Command-line interface for the SAURUS Staphylococcus aureus genomic surveillance database.
Query 139,299 S. aureus genomes from your terminal. Filter by lineage, resistance cassette, capsule serotype, country, source, host, or collection year. Export clean accession lists ready for datasets download genome accession.
All data is bundled inside this image. No downloads, API keys, or network access are required after docker pull.
The image contains:
datasets command-line tool, so you can fetch genome assemblies without installing anything on your hostIf you already have a Python environment, pip install saurus-cli is faster. Use the Docker image when you want zero host dependencies, reproducible execution, or a self-contained pipeline step.
Pull the image:
docker pull bbeckleyhub/saurus-cli:latest
Verify it works:
docker run --rm bbeckleyhub/saurus-cli:latest --version
Run a real query:
docker run --rm bbeckleyhub/saurus-cli:latest --lineage USA300 --count
Expected output: 8657
0.1.0 — first public releaselatest — always points to the most recent stable releasePin to a specific version in production. Use latest only for exploration.
Count USA300 genomes globally:
docker run --rm bbeckleyhub/saurus-cli:latest --lineage USA300 --count
Count USA100 bloodstream isolates in the USA:
docker run --rm bbeckleyhub/saurus-cli:latest --lineage USA100 --country USA --source blood --count
Export matching genomes to your host directory:
docker run --rm -v "$PWD:/work" bbeckleyhub/saurus-cli:latest \
--lineage USA300 --country USA --source blood \
--format tsv,accession -o usa300_blood
This writes two files to the current directory on your host:
usa300_blood.tsv — full metadata tableusa300_blood.txt — plain accession listFilter by resistance gene content:
docker run --rm bbeckleyhub/saurus-cli:latest --amr mecA,tetM --count
Filter by geography and time range:
docker run --rm bbeckleyhub/saurus-cli:latest \
--lineage EMRSA-15 --country "United Kingdom" --year 2015-2023 --count
Show the full example gallery:
docker run --rm bbeckleyhub/saurus-cli:latest --examples
Show author, affiliation, and citation information:
docker run --rm bbeckleyhub/saurus-cli:latest --about
Pipe accessions directly into NCBI datasets, all inside the container:
docker run --rm bbeckleyhub/saurus-cli:latest --lineage USA300 --quiet | \
datasets download genome accession --inputfile /dev/stdin --filename usa300.zip
Or write the accessions to the host and pipe from the host:
docker run --rm bbeckleyhub/saurus-cli:latest --lineage USA300 --quiet > accessions.txt
datasets download genome accession --inputfile accessions.txt --filename usa300.zip
The second form requires datasets on the host. The first does not.
To explore the container:
docker run --rm -it --entrypoint sh bbeckleyhub/saurus-cli:latest
Then run any command:
saurus --examples
saurus --about
saurus --lineage USA300 --count
Exit with exit or Ctrl+D.
The full data bundle is at /usr/local/share/saurus/data/ inside the container. To inspect or extract the raw tables:
docker run --rm --entrypoint sh bbeckleyhub/saurus-cli:latest \
-c "ls -la /usr/local/share/saurus/data/"
You will see eight subdirectories:
agr capsule gene_annotation metadata mlst mrsa sccmec spa
All files are gzipped TSVs, readable with zcat or pandas. Example:
docker run --rm --entrypoint sh bbeckleyhub/saurus-cli:latest \
-c "zcat /usr/local/share/saurus/data/mrsa/mrsa_all.tsv.gz | head -5"
Typing filters:
--st <ST> MLST Sequence Type (e.g., 5, 398)
--cc <CC> Clonal Complex (e.g., 398, CC398)
--spa <TYPE> spa Type (e.g., t002)
--sccmec <TYPE> SCCmec Type (e.g., II, IV)
--agr <TYPE> agr Type (e.g., I, II)
--capsule <TYPE> Capsule Serotype (e.g., 5, 8)
Phenotype:
--mrsa Filter only MRSA isolates
--mssa Filter only MSSA isolates
Epidemiological metadata:
--country <NAME> Country of origin (e.g., USA, Ghana, Denmark)
--source <NAME> Isolation source (e.g., blood, nasal)
--host <NAME> Host species (e.g., "Homo sapiens")
--year <YEAR> Collection year or range (e.g., 2019, 2015-2023)
Gene content:
--amr <GENES> AMR genes, comma-separated (e.g., mecA,tetM)
--vfdb <GENES> Virulence genes, comma-separated
--plasmid <REPLICONS> Plasmid replicons, comma-separated
--any Match ANY of the given genes (default: ALL)
Output:
--format <FORMATS> Comma-separated: accession, tsv, csv, json
--output, -o <PATH> Output base path (extension added per format)
--count Print only the number of matches
--quiet, -q Suppress banner and footer
--debug Show row counts after each filter
Shortcuts:
--lineage <NAME> Pre-defined lineage signature
--config <FILE> JSON config file
--examples Print example gallery and exit
--about Print author and citation and exit
--version Print version and exit
--help Print full help and exit
USA100 ST5 t002 SCCmec II agr II capsule 5
USA300 ST8 t008 SCCmec IV agr I capsule 5
USA400 ST1 t128 SCCmec IV agr III capsule 8
USA500 ST8 t064 SCCmec IV agr I capsule 5
USA700 ST72 t324 SCCmec IV agr I capsule 5
USA800 ST5 t688 SCCmec IV agr II capsule 5
EMRSA-15 ST22 t032 SCCmec IV agr I capsule 5
EMRSA-16 ST36 t018 SCCmec II agr III capsule 8
Bengal Bay ST772 t657 SCCmec V agr II capsule 5
ST152 ST152 SCCmec V agr III capsule 5
Any flag passed alongside --lineage overrides the corresponding signature component.
Save a query as JSON for reuse across runs and institutions:
{
"lineage": "USA100",
"country": "United States",
"source": "blood",
"mrsa": true,
"year": "2020-2025",
"format": "tsv,accession",
"output": "usa100_blood_2020_2025"
}
Run it:
docker run --rm -v "$PWD:/work" bbeckleyhub/saurus-cli:latest \
--config usa100_blood_2020_2025.json
Both output files are written to your host's current directory.
SAURUS (Staphylococcus aureus Unified Resource for Universal Surveillance) is a free, open genomic resource that consolidates eleven typing, gene-annotation, and epidemiological modules for the entire public S. aureus repository behind a single queryable interface.
The web version runs in your browser at https://saurus-db.org/
SAURUS-CLI is the terminal companion, with the same dataset, the same modules, and the same accession-first output.
SAURUS-CLI is the second release in the ARGUS initiative, a family of open genomic surveillance tools covering the WHO priority ESKAPE pathogens.
ARGUS umbrella: https://argus-db.org/
If you use SAURUS-CLI in your research, please cite:
Beckley B. SAURUS-CLI: a reproducible command-line interface for typing-based genome retrieval in Staphylococcus aureus. BMC Bioinformatics [under review]. 2026.
Underlying typing pipeline:
Beckley B, Amarh V. StaphScope: a species-optimized computational pipeline for rapid and accessible Staphylococcus aureus genotyping and surveillance. BMC Genomics. 2026;27(1):261. doi:10.1186/s12864-026-12609-x
Source gene annotation dataset:
Shelenkov A, Slavokhotova A, Yunusova M, et al. Genomic typing, antimicrobial resistance gene, virulence factor and plasmid replicon database for the important pathogenic bacteria Staphylococcus aureus. BMC Genom Data. 2025;26(1):65. doi:10.1186/s12863-025-01363-w
MIT License. See https://github.com/bbeckley-hub/saurus-cli/blob/main/LICENSE
Bug reports and feature requests: https://github.com/bbeckley-hub/saurus/issues
Email: [email protected]
Content type
Image
Digest
sha256:fd8058a14…
Size
129.2 MB
Last updated
about 22 hours ago
docker pull bbeckleyhub/saurus-cli