atb-cli

A command-line tool for querying the AllTheBacteria genomics database (~3.2M bacterial genomes), searching AMR/stress/virulence genes, finding closest genomes via sketch distances, and downloading genome assemblies.

Single binary, no dependencies.

Supported platforms: Linux, macOS, Windows (amd64 and arm64)

atb-cli was designed and architected by Thanh Le Viet in his personal capacity, using his own Claude account. The implementation was developed with coding assistance from Claude (Anthropic), an AI assistant that helped with code generation, testing, and documentation under human direction and review. Thanks to hackathon participants Jane Hawkey, Ahmed M Moustafa, Martin Hunt, and Zamin Iqbal for their input and feedback.

Table of Contents

• Download
• Install
• Quick Start
• Updating
• Usage Examples
• Query genomes by species
• Filter by geography and platform
• Use a TOML filter file
• Get sample details
• Download genome assemblies
• Summary statistics
• Query AMR genes
• Query MLST
• Find closest genomes (sketch)
• Browse and download ATB files from OSF
• Fetch the database
• Configuration
• LLM Integration (MCP)
• Output Formats
• Available Columns
• Performance
• Building
• Data Sources
• License

Download

Pre-built binaries for all platforms:

Platform	Architecture	File
Linux	x86_64 (amd64)	atb-cli_<version>_linux_amd64.tar.gz
Linux	ARM64	atb-cli_<version>_linux_arm64.tar.gz
macOS	Intel (amd64)	atb-cli_<version>_darwin_amd64.tar.gz
macOS	Apple Silicon (arm64)	atb-cli_<version>_darwin_arm64.tar.gz
Windows	x86_64 (amd64)	atb-cli_<version>_windows_amd64.zip
Windows	ARM64	atb-cli_<version>_windows_arm64.zip

Latest release: github.com/allthebacteria/atb-cli/releases/latest

Download the file for your platform, extract, and place the atb binary (or atb.exe on Windows) somewhere in your PATH.

Install

One-line install (Linux/macOS):

curl -fsSL https://raw.githubusercontent.com/allthebacteria/atb-cli/main/install.sh | bash

This detects your OS and architecture, downloads the latest release, and installs to ~/.local/bin. It will add the directory to your PATH automatically if needed.

# Install a specific version
curl -fsSL https://raw.githubusercontent.com/allthebacteria/atb-cli/main/install.sh | ATB_VERSION=v0.1.0 bash

# Install the binary to a custom directory
curl -fsSL https://raw.githubusercontent.com/allthebacteria/atb-cli/main/install.sh | ATB_INSTALL_DIR=/usr/local/bin bash

The env var goes after the pipe so it applies to bash, not curl. Writing ATB_INSTALL_DIR=/path curl ... | bash looks plausible but only sets the variable for the curl process — the install script run by bash never sees it.

Heads up — pick a data directory before fetching. ATB_INSTALL_DIR only controls where the atb binary lands, not where the database goes. A default atb fetch pulls the core parquet tables (~600 MB) and builds the per-genus AMR indexes, which expand to ~35 GB on disk. Add another ~4.2 GB if you run atb sketch fetch. By default everything goes to ~/.local/share/atb/data, which is often on a small home volume. To put it elsewhere, either pass --data-dir per command or set it once:

```bash atb config set general.data_dir /path/to/large/volume

or, ad hoc:

atb fetch --data-dir /path/to/large/volume ```

If you don't need AMR queries, you can skip that table to save the ~35 GB. atb fetch will prompt before downloading amrfinderplus.parquet; answer n to skip just that table and continue with the rest. To bypass the prompt non-interactively, either pre-select tables or pass --yes:

```bash

Skip AMR explicitly (non-interactive)

atb fetch --tables assembly.parquet,assembly_stats.parquet,checkm2.parquet,sylph.parquet,run.parquet,mlst.parquet

Or accept the AMR download without prompting

atb fetch --yes ```

Windows: Download the .zip from the Download table above, extract, and add atb.exe to your PATH.

Other methods:

# Go install (requires Go 1.23+)
go install github.com/allthebacteria/atb-cli/cmd/atb@latest

# From source
git clone https://github.com/allthebacteria/atb-cli.git
cd atb-cli
make build    # binary at ./bin/atb

Quick Start

# 1. Download the database (~540 MB core tables)
atb fetch

# 2. Query
atb query --species "Escherichia coli" --hq-only --limit 10

If you don't have the parquet files yet:

# Download core tables from OSF (~540MB)
./bin/atb fetch

# Or download all tables including ENA metadata (~4.3 GB)
./bin/atb fetch --all

Updating

atb checks for new versions in the background (once every 24 hours). If a newer release is found, you'll see a notice on every run until you upgrade:

  A new version of atb is available: v0.9.0 (current: v0.8.0)

  What's new:
    feat: find closest ATB genomes via sketch distances
    ...

  Release: https://github.com/allthebacteria/atb-cli/releases/tag/v0.9.0

  Run 'atb update' to upgrade.

To update:

# Interactive update (asks for confirmation)
atb update

# Non-interactive (for scripts/CI)
atb update --force

The updater downloads the correct binary for your OS/architecture from GitHub Releases and replaces the current binary in place.

Usage Examples

Query genomes by species

# Get 10 high-quality E. coli genomes
atb query --species "Escherichia coli" --hq-only --limit 10

# With quality filters
atb query --species "Escherichia coli" \
  --hq-only \
  --min-completeness 99.5 \
  --max-contamination 0.5 \
  --min-n50 200000 \
  --sort-by N50 --sort-desc \
  --limit 20

# Select specific columns
atb query --species "Escherichia coli" --hq-only --limit 5 \
  --columns sample_accession,sylph_species,N50,Completeness_General,aws_url

# Search by genus
atb query --genus Salmonella --hq-only --limit 20

# Wildcard species search
atb query --species-like "Streptococcus%" --hq-only --limit 10

Filter by geography and platform (requires ENA tables)

# Salmonella from the UK, Illumina only
atb query --species "Salmonella enterica" \
  --country "United Kingdom" \
  --platform "ILLUMINA" \
  --limit 20

# Genomes collected between 2020-2023
atb query --species "Escherichia coli" \
  --collection-date-from 2020-01-01 \
  --collection-date-to 2023-12-31 \
  --limit 50

Use a TOML filter file (reproducible queries)

# Create a filter file
cat > my_query.toml <<'EOF'
[filter]
species = "Escherichia coli"
hq_only = true
min_completeness = 99.0
max_contamination = 2.0
min_n50 = 100000

[output]
columns = ["sample_accession", "sylph_species", "N50", "Completeness_General", "aws_url"]
sort_by = "N50"
sort_desc = true
limit = 100
format = "tsv"
output = "ecoli_results.tsv"
EOF

# Run the query
atb query --filter my_query.toml

# CLI flags override TOML values
atb query --filter my_query.toml --limit 10

Get sample details

atb info SAMD00000355

Output:

=== Assembly ===
  sample_accession:   SAMD00000355
  sylph_species:      Streptococcus pyogenes
  hq_filter:          PASS
  dataset:            661k
  aws_url:            https://allthebacteria-assemblies.s3.eu-west-2.amazonaws.com/SAMD00000355.fa.gz

=== Assembly Stats ===
  total_length: 1868526
  N50:          148451

=== CheckM2 Quality ===
  completeness_general:  99.06
  contamination:         0.03

=== MLST ===
  scheme:    ecoli_achtman_4
  ST:        131
  status:    PERFECT
  score:     100
  alleles:   adk(53);fumC(40);gyrB(47);icd(13);mdh(36);purA(28);recA(29)

=== ENA Metadata ===
  country:             Japan:Aichi
  collection_date:     1994
  instrument_platform: ILLUMINA

Download genome assemblies

# Query, then download
atb query --species "Klebsiella pneumoniae" --hq-only --limit 10 \
  --columns sample_accession,aws_url --format csv -o results.csv
atb download --from results.csv --output-dir ./genomes

# Pipe query directly to download
atb query --species "Escherichia coli" --hq-only --limit 5 \
  --columns sample_accession,aws_url --format csv | \
  atb download --from - --output-dir ./ecoli_genomes

# Preview what would be downloaded
atb download --from results.csv --dry-run

# Download from a URL list
atb download --urls my_urls.txt --output-dir ./genomes --parallel 8

# Download a single file
atb download --url https://allthebacteria-assemblies.s3.eu-west-2.amazonaws.com/SAMD00000355.fa.gz \
  --output-dir ./genomes

Summary statistics

# Default summary of the full database
atb summarise

# Group by species (top 20)
atb summarise --by sylph_species --top 20

# Summarise a previous query result
atb query --genus Salmonella --hq-only --limit 100 \
  --columns sample_accession,sylph_species,hq_filter,dataset -o salmonella.tsv
atb summarise --from salmonella.tsv

# Pipe query to summarise
atb query --species "Escherichia coli" --hq-only --limit 200 \
  --columns sample_accession,sylph_species,dataset --format csv | \
  atb summarise --from -

Query AMR genes

AMR data comes from AMRFinderPlus v4.2.5 results run across all ATB genomes. All AMR, stress, and virulence data is in amrfinderplus.parquet (~58.5M rows, ~1.18 GB), downloaded automatically by atb fetch and partitioned by genus for fast queries.

# Get all AMR gene hits for E. coli (high-quality genomes only)
atb amr --species "Escherichia coli" --hq-only --limit 100

# Filter by drug class
atb amr --species "Escherichia coli" --hq-only --class "BETA-LACTAM"

# Wildcard gene search (all beta-lactamase genes)
atb amr --species "Escherichia coli" --gene "bla%"

# Compare resistance across multiple species
atb amr --species "Escherichia coli,Klebsiella pneumoniae" --class "BETA-LACTAM"

# Find a gene across ALL genera (no species filter needed)
atb amr --gene "blaCTX-M-15" --limit 100

# Filter by ENA metadata -- country, platform, or collection date
# (requires ena_20250506.parquet: run 'atb fetch --tables ena_20250506.parquet')
# Any ENA filter implies --with-ena, so country/collection_date/instrument_platform
# are appended to the output automatically.
atb amr --species "Escherichia coli" --class "BETA-LACTAM" \
  --country "United Kingdom" --platform ILLUMINA --limit 50
atb amr --species "Salmonella enterica" --gene "blaCTX-M-15" \
  --collection-date-from 2022-01-01

# Add ENA columns to the output without filtering
# (requires ena_20250506.parquet). Without --with-ena the ENA table is not read,
# so default AMR queries stay in the millisecond tier.
atb amr --species "Escherichia coli" --class "BETA-LACTAM" --with-ena --limit 50

# Search by drug class across all genera
atb amr --class "CARBAPENEM" --limit 50

# Filter by detection quality
atb amr --species "Escherichia coli" --min-coverage 95 --min-identity 98

# Query stress response genes
atb amr --species "Escherichia coli" --type stress

# Query virulence factors
atb amr --species "Escherichia coli" --type virulence

# Query all three categories at once
atb amr --species "Escherichia coli" --type all

# Output to file (CSV)
atb amr --species "Klebsiella pneumoniae" --hq-only --format csv -o kpn_amr.csv

# Auto-gzip when -o ends in .gz; format inferred from filename (.csv.gz -> CSV)
atb amr --species "Escherichia coli" --hq-only -o ecoli_amr.tsv.gz

# Restrict to a specific list of samples (comma-separated)
atb amr --samples SAMD00093868,SAMEA104470147 --type all

# Or read accessions from a file (one per line, '#' comments allowed)
atb amr --sample-file my_isolates.txt --class "BETA-LACTAM"

# Download matching assemblies directly
atb amr --species "Escherichia coli" --class "BETA-LACTAM" --hq-only --download -d ./genomes

# Preview what would be downloaded (no actual download)
atb amr --species "Klebsiella pneumoniae" --gene "blaCTX-M-15" --download --dry-run

# Cap number of assemblies to download
atb amr --species "Escherichia coli" --gene "bla%" --download --max-samples 20 -d ./bla_genomes

--species accepts comma-separated values for multi-species comparison. When omitted, --gene or --class is required to search across all genera.

The --download flag downloads the FASTA assembly for each unique sample in the results. Query output is always printed first. Use --dry-run to preview URLs without downloading, and --max-samples to cap the number of assemblies.

AMR output preserves the AMRFinderPlus v4.2.5 TSV header verbatim, so all 26 columns are present in the original case and ordering: Name, Protein id, Contig id, Start, Stop, Strand, Element symbol, Element name, Scope, Type, Subtype, Class, Subclass, Method, Target length, Reference sequence length, % Coverage of reference, % Identity to reference, Alignment length, Closest reference accession, Closest reference name, HMM accession, HMM description, Hierarchy node, genus, species.

With --with-ena (or any ENA filter), three extra columns are appended: country, collection_date, instrument_platform.

Query MLST (Multi-Locus Sequence Typing)

MLST