Skip to content

Getting Started

This guide walks you through the complete setup, from installation to running mlst with your freshly updated database.

Step 1: Install mlstdb

conda create -n mlst -c bioconda mlst
conda activate mlst
pip install mlstdb

Verify the installation:

mlstdb --version

Step 2: Register with the databases

Before downloading any schemes, you need to register your credentials with PubMLST and/or Pasteur. This is a one-time setup. Your credentials are saved locally and reused for future updates.

Two methods are available — choose the one that suits your setup:

BIGSdb v1.53.0 (PubMLST since May 2026) supports personal API keys — a simpler alternative to OAuth with no browser step required.

mlstdb connect --db pubmlst --api-key

You will be prompted to paste your API key (generate one from your PubMLST profile page under API keys). The key is saved to ~/.config/mlstdb/api_keys.

Where do I get my API key?

See the Connect guide for step-by-step instructions.

Option B: OAuth (required for Pasteur or older BIGSdb instances)

mlstdb connect --db pubmlst
mlstdb connect --db pasteur

Each connect command will:

  1. Ask for your Client ID (24 characters) and Client Secret (42 characters)
  2. Open an authorisation URL — visit it in your browser
  3. Ask you to paste the verification code from the website
  4. Save all tokens securely to ~/.config/mlstdb/

Where do I get my Client ID and Client Secret?

See the Connect guide for step-by-step instructions on registering with PubMLST and Pasteur.

Info

If you've already connected before, mlstdb connect will test your existing credentials and skip re-registration if they're still valid.

Step 3: Download MLST schemes

mlstdb update

This will:

  • Read the built-in curated list of ~170 MLST schemes from both PubMLST and Pasteur
  • Download allele sequences (.tfa files) and ST profiles (.txt files) for each scheme
  • Save everything to a pubmlst/ directory
  • Build a BLAST database in blast/

First run may take a while

Downloading hundreds of schemes involves many API calls. You can speed things up with --threads 4 or download specific schemes by providing a custom input file. See the Update guide for details.

If the download is interrupted, use --resume to pick up where you left off:

mlstdb update --resume

Step 4: Verify with mlst

Once the update is complete, test your new database:

mlst --blastdb blast/mlst.fa --datadir pubmlst your_assembly.fasta

Replace your_assembly.fasta with the path to any bacterial genome assembly.

What was created?

After a successful update, your directory should look like this:

pubmlst/
├── klebsiella/
│   ├── klebsiella.txt          # ST profiles
│   ├── klebsiella_info.json    # Scheme metadata
│   ├── gapA.tfa                # Allele sequences
│   ├── infB.tfa
│   └── ...
├── listeria/
│   └── ...
└── ...

blast/
├── mlst.fa                     # Combined allele sequences
├── mlst.fa.ndb                 # BLAST index files
├── mlst.fa.nhr
└── ...

Each scheme gets its own subdirectory containing:

  • Profile file (<scheme>.txt) : maps ST numbers to allele combinations
  • Allele files (<locus>.tfa) : FASTA sequences for each locus
  • Metadata (<scheme>_info.json) : source database, download date, locus count

Keeping your database up to date

Schemes change over time as new STs and alleles are added. To update your database, simply run:

mlstdb update

This will re-download all schemes and rebuild the BLAST database. Use --resume if you want to skip schemes that have already been downloaded.

Next Steps