gmlst scheme¶

Manage scheme catalogs, downloads, updates, and local custom schemes.

list¶

List schemes from cached catalogs, local custom schemes, or remote providers.

Usage¶

gmlst scheme list [OPTIONS]

Options¶

Option	Description	Default
`-p, --provider [pubmlst\\|pasteur\\|enterobase\\|cgmlst\\|local\\|all]`	Filter by provider.	`all`
`-t, --type [mlst\\|cgmlst\\|wgmlst\\|all]`	Filter by scheme type.	`all`
`-n, --name TEXT`	Filter by scheme name.	-
`-f, --format [text\\|table\\|csv\\|tsv\\|json]`	Output format.	`table`
`-a, --available`	Show remotely available schemes, not only cached ones.	`False`
`--cache-dir PATH`	Override the scheme cache directory.	-
`-h, --help`	Show the help message and exit.	-

Examples¶

gmlst scheme list
gmlst scheme list -p pubmlst -t mlst
gmlst scheme list -p local
gmlst scheme list --available -f json

Notes¶

Table output adapts to the terminal and is the normal human-readable view.
--available refreshes the view toward provider catalogs so you can inspect schemes that are not yet downloaded locally.
Listings are filtered through gmlst/data/blocked_schemes.json, which hides blocked scheme_name values by provider.

download¶

Download one scheme into the local cache.

Usage¶

gmlst scheme download [OPTIONS]

Options¶

Option	Description	Default
`-s, --scheme TEXT`	Scheme name to download. Required.	-
`--force`	Re-download even if the scheme is already cached.	`False`
`-q, --quiet`	Reduce console output.	`False`
`--download-tool [auto\\|aria2c\\|curl\\|wget\\|httpx\\|requests]`	Download backend.	`auto`
`-x, --connections INTEGER`	Number of parallel download connections.	-
`--token TEXT`	Authentication token when the provider supports it.	-
`--cache-dir PATH`	Override the scheme cache directory.	-
`-h, --help`	Show the help message and exit.	-

Examples¶

gmlst scheme download -s saureus_1
gmlst scheme download -s ecoli_1 --download-tool aria2c -x 16
gmlst scheme download -s saureus_1 --force

Notes¶

Use --download-tool to pick the transfer backend explicitly, or leave it on auto to let gmlst choose.
-x, --connections is most useful for providers that fetch many locus files.
Blocked schemes are rejected before download.

update-fingerprints¶

Builds the local species fingerprint database used by typing auto-detection. Downloads one MLST scheme (7 housekeeping genes) per unique organism and sketches them into compact k-mer fingerprints (~1 MB total).

MLST-only: Fingerprints use MLST schemes exclusively. cgMLST schemes (2000+ loci) are deliberately excluded — they take minutes to download vs seconds for MLST, with no improvement in species-level discrimination. See fingerprint database docs for rationale.

Usage¶

# Build all fingerprints (downloads missing schemes)
gmlst scheme update-fingerprints [-y] [-x N]

# Build for specific organisms only
gmlst scheme update-fingerprints -o "Bordetella pertussis,Staphylococcus aureus"

Options¶

Option	Description	Default
`-y, --yes`	Skip confirmation when overwriting existing database.	`False`
`-o, --organisms TEXT`	Comma-separated organisms (substring match).	all
`-x, --connections INTEGER`	Concurrent downloads per scheme. Lower = gentler.	`4`
`--cache-dir PATH`	Override cache directory.	auto

How it works¶

Groups all catalog schemes by organism name
For each organism, selects the smallest MLST scheme (skips if none available)
Downloads the scheme if not cached (rate-limit tolerant)
Sketches housekeeping gene sequences (k=21, sample every 7th k-mer, cap 5000/species)
Saves as zlib-compressed JSON (~1 MB for 170+ species)

Detection lookup order¶

When typing omits -s/-n, the fingerprint database is resolved in this order:

<cache>/species_fingerprints.json.gz (user-built, freshest)
gmlst/data/species_fingerprints.json.gz (bundled with package)
Interactive prompt to build now (TTY only)

Notes¶

PubMLST requires an API key for post-2024 data: gmlst config set GMLST_PUBMLST_API_KEY <key>
Rate-limited servers may cause some downloads to fail; re-run to retry (cached schemes skip instantly)
See fingerprint database coverage for the full species list

update¶

Refresh one cached scheme or refresh provider catalogs.

Usage¶

gmlst scheme update [OPTIONS]

Options¶

Option	Description	Default
`-s, --scheme TEXT`	Scheme name to update.	-
`-a, --all`	Update all cached schemes.	`False`
`-f, --force`	Force catalog or scheme refresh.	`False`
`--token TEXT`	Authentication token when the provider supports it.	-
`--download-tool [auto\\|aria2c\\|curl\\|wget\\|httpx\\|requests]`	Download backend.	`auto`
`-x, --connections INTEGER`	Number of parallel download connections.	-
`--cache-dir PATH`	Override the scheme cache directory.	-
`-h, --help`	Show the help message and exit.	-

Examples¶

gmlst scheme update
gmlst scheme update -s saureus_1
gmlst scheme update -a --force

Notes¶

Without -s, scheme update refreshes provider catalogs.
-a, --all updates all cached schemes.
-s and -a are mutually exclusive. Use one or the other.
--force is the way to refresh catalogs or cached schemes even when local metadata looks current.
Blocked schemes are rejected before update.

show¶

Display detailed metadata for one scheme, or fall back to a list view.

Usage¶

gmlst scheme show [OPTIONS]

Options¶

Option	Description	Default
`-s, --scheme TEXT`	Scheme name to inspect.	-
`-f, --format [text\\|table\\|csv\\|tsv\\|json]`	Output format.	`table`
`--cache-dir PATH`	Override the scheme cache directory.	-
`-h, --help`	Show the help message and exit.	-

Examples¶

gmlst scheme show -s saureus_1
gmlst scheme show -s saureus_1 -f json
gmlst scheme show

Notes¶

With -s, this command shows one scheme in detail, including fields such as downloaded_at, updated_at, and n_profiles when that metadata is available.
Without -s, it prints guidance and falls back to list-style output so you still get a useful catalog view.

create¶

Create a local custom scheme from extracted novel allele data.

Usage¶

gmlst scheme create [OPTIONS]

Options¶

Option	Description	Default
`-t, --type [mlst]`	Scheme type to create. Required.	-
`-s, --source TEXT`	Source public scheme used as the base. Required.	-
`--data-dir, --datadir DIRECTORY`	Directory containing extracted novel data. Required.	-
`--desc TEXT`	Free-text description for the new custom scheme.	-
`--cache-dir PATH`	Override the scheme cache directory.	-
`-h, --help`	Show the help message and exit.	-

Examples¶

gmlst scheme create -t mlst -s saureus_1 --data-dir novel_data
gmlst scheme create -t mlst -s saureus_1 --data-dir novel_data --desc "Lab collection 2024"

Notes¶

The custom scheme is named automatically as custom_1, custom_2, and so on.
Creation merges the original public scheme content with the extracted novel alleles and profiles, so the result stays typeable against both old and newly discovered data.

update-custom¶

Extend an existing local custom scheme with new novel allele data.

Usage¶

gmlst scheme update-custom [OPTIONS]

Options¶

Option	Description	Default
`-s, --scheme TEXT`	Local custom scheme to update. Required.	-
`--data-dir, --datadir DIRECTORY`	Directory containing extracted novel data. Required.	-
`--cache-dir PATH`	Override the scheme cache directory.	-
`-h, --help`	Show the help message and exit.	-

Examples¶

gmlst scheme update-custom -s custom_1 --data-dir more_novel_data

Notes¶

This command only works with local custom schemes.
New allele and profile numbering continues from the existing custom scheme instead of restarting from n1 or N1.

export¶

Export a cached scheme in MST-friendly or original profile format.

Usage¶

gmlst scheme export [OPTIONS]

Options¶

Option	Description	Default
`-s, --scheme TEXT`	Scheme name to export. Required.	-
`--format [grapetree\\|original]`	Export format. Required.	-
`-o, --output PATH`	Output file path. Required.	-
`--cache-dir PATH`	Override the scheme cache directory.	-
`-h, --help`	Show the help message and exit.	-

Examples¶

gmlst scheme export -s custom_1 --format grapetree -o mst.tsv
gmlst scheme export -s saureus_1 --format original -o saureus_1.txt

Notes¶

grapetree writes a TSV profile table with an ST-style first column that is compatible with GrapeTree workflows.
original writes a copy of the scheme's original profile file.

Provider endpoint environment variables¶

These variables let you point the scheme commands at alternate BIGSdb endpoints or register a private BIGSdb provider.

Variable	Purpose
`GMLST_PUBMLST_BASE_URL`	Override the PubMLST BIGSdb API base URL.
`GMLST_PASTEUR_BASE_URL`	Override the Pasteur BIGSdb API base URL.
`GMLST_PRIVATE_BIGSDB_URL`	Register a private BIGSdb instance as an additional provider.
`GMLST_PRIVATE_BIGSDB_NAME`	Set the provider key used for the private BIGSdb instance.
`GMLST_PRIVATE_BIGSDB_LABEL`	Set the display label shown for the private BIGSdb provider.

Example:

export GMLST_PUBMLST_BASE_URL="http://127.0.0.1:8000/api/db"
gmlst scheme list -p pubmlst

export GMLST_PRIVATE_BIGSDB_URL="http://127.0.0.1:9000/api/db"
export GMLST_PRIVATE_BIGSDB_NAME="labdb"
gmlst scheme list -p labdb