Skip to content

Command line

pip install "plasticdb[cli]"

plasticdb proteins list --plastic PET --format fasta > pet.fasta
plasticdb download dataset --release 2026.50 -o data/
plasticdb jobs submit annotate-genome genome.fna --wait -o hits.tsv
plasticdb cite --release 2026.50

plasticdb (also python -m plasticdb) is a thin layer over the SDK: each command is one Client call. Without the cli extra the script says which extra to install. This page's command tree and exit-code table are generated from the tool itself.

Output

  • Data goes to stdout; messages, progress and warnings go to stderr.
  • --format picks tsv, csv, json, jsonl or (for sequences) fasta. Lists default to tsv, single records to json.
  • -o FILE writes to a file, and the extension picks the format when --format is not given (.tsv, .csv, .json, .jsonl, .fasta, and .bib, .ris, .nwk where they apply). Downloads take a file or a directory.
  • TSV is one line per record: lists are joined with ;, nested objects are JSON, and tabs and newlines inside values become spaces.
  • --limit/-n caps a list. A closed pipe (| head) is not an error.

No prompts

The tool never asks for anything unless you pass --interactive, and only auth login ever asks.

Global options and filters

--release, --api-key, --base-url, --cache-dir, -q/--quiet and -v/--verbose (-vv logs every request and retry) work before or after the subcommand. Their environment variables are PLASTICDB_RELEASE, PLASTICDB_API_KEY, PLASTICDB_BASE_URL, PLASTICDB_CACHE_DIR and PLASTICDB_CONFIG_DIR.

Filter options are the SDK's filter names (--plastic, --include-subtypes, --polarity, --min-year, --class, ...), generated from its types, so plasticdb proteins list --help lists exactly what client.proteins.list() takes.

Authentication

pbpaste | plasticdb auth login       # or: plasticdb auth login --interactive
plasticdb auth status                # which key, and where it came from
plasticdb auth logout

auth login checks the key with the server and saves it to $XDG_CONFIG_HOME/plasticdb/config.json (~/.config/plasticdb/; %APPDATA%\plasticdb on Windows; $PLASTICDB_CONFIG_DIR overrides it), mode 0600 in a 0700 directory. The key is read from stdin, or from --key (which leaves it in your shell history), and is never echoed. Precedence: --api-key, then PLASTICDB_API_KEY, then the file. Only jobs needs a key.

Downloads and jobs

download dataset without a release saves the live database's ZIP. With --release, -o is a directory and receives every artefact the release published (Parquet tables, reference databases, MANIFEST.json), each checked against its SHA-256.

jobs submit prints the job id. With --wait it also writes the results: -o hits.tsv saves the server's results file (with provenance lines), and --format writes the typed results instead. Each job parameter is an option named after its SDK keyword (--evalue, --target-polymers, --genus-column, ...); the build-tree filters are the /microorganisms filters. An input of - is read from stdin. Job types are kebab-case: annotate-gene, annotate-genome, compare-genomes, annotate-list, pathway-analysis, hmm-screen, build-tree.

Exit codes

Stable, so pipelines can branch on them.

Code Meaning
0 success
1 any other error
2 bad command line, option or parameter value (also a server 422)
3 no such record, it was withdrawn or merged, or a job's files expired
4 no API key, an invalid one, or not allowed
5 rate limited (429) beyond the retry budget
6 release unknown, unavailable, or unable to answer this
7 the job failed on the server
8 timed out (a request, a sequence search's 15 s, or --timeout waiting for a job)
9 server unreachable or failing (5xx): retry later
130 interrupted (Ctrl-C)

Reference

Global options

Accepted before or after the subcommand.

Option Meaning Default
--version Print the version and exit.
--release Pin every read to a dataset release (env PLASTICDB_RELEASE).
--api-key API key (env PLASTICDB_API_KEY, else plasticdb auth login's).
--base-url API base URL (env PLASTICDB_BASE_URL).
--cache-dir Keep pinned answers and release files here (env PLASTICDB_CACHE_DIR).
--quiet, -q Only errors on stderr.
--verbose, -v More detail on stderr (-vv: every request and retry).
--interactive Allow prompts (only auth login ever asks).

Commands

Full-text search across every record type (live only).

Option Meaning Default
Q What to search for.
--grouped, --no-grouped The top hits per record type (JSON) instead of one ranking.
--limit, -n At most this many records.
--format Output format (default tsv, or the -o file's extension).
--output, -o Write the data here instead of stdout.

plasticdb stats

Summary statistics of the live database.

Option Meaning Default
--view Which statistics. summary
--evidence-scope Which organisms count: credited by an organism or an enzyme assay (default), by an organism assay, or only through an enzyme (enzyme_only: summary only).
--format Output format (default json, or the -o file's extension).
--output, -o Write the data here instead of stdout.

plasticdb changes

Records updated, merged or removed since a time (live only).

Option Meaning Default
--since ISO 8601 time (the previous run's as_of).
--entity-type Only this record type.
--limit, -n At most this many records.
--format Output format (default tsv, or the -o file's extension).
--output, -o Write the data here instead of stdout.

plasticdb cite

How to cite the data: the dataset release (--release, else the current one) and paper.

Option Meaning Default
--format text (default), bibtex or json.
--output, -o Write here instead of stdout.

plasticdb provenance

The release, its source, and the server's and this tool's versions (record with results).

Option Meaning Default
--format Output format (default json, or the -o file's extension).
--output, -o Write the data here instead of stdout.

plasticdb version

This tool's version (and with --server, the server's).

Option Meaning Default
--server, --no-server Also ask the server for its version.
--format Output format (default text, or the -o file's extension).
--output, -o Write the data here instead of stdout.

plasticdb proteins

Wild-type proteins and engineered variants.

plasticdb proteins list

Proteins matching the filters (positive evidence unless --polarity says otherwise).

Option Meaning Default
--limit, -n At most this many records.
--format Output format (default tsv, or the -o file's extension).
--output, -o Write the data here instead of stdout.
--q, --query Free-text search.
--name Name contains.
--plasticdb-id
--accession
--plastic Plastic name or abbreviation (e.g. PET).
--include-subtypes, --no-include-subtypes Include the plastic's subtypes.
--microorganism Microorganism tax-id, accession or name.
--lineage Lineage contains (any rank).
--year Evidence published in this year.
--min-year Evidence published in or after this year.
--max-year Evidence published in or before this year.
--substrate-form Substrate form (film, powder, ...).
--evidence-method How degradation was shown.
--include-negative, --no-include-negative Also list records with only negative results.
--polarity Evidence outcome (default positive).
--activity-class
--min-kcat
--max-km
--min-kcat-km
--min-vmax
--has-structure, --no-has-structure Only records with (or without) a structure.
--has-sequence, --no-has-sequence Only records with (or without) a sequence.
--ec-number
--min-tm
--max-tm
--origin-type
--origin-environment
--kind Wild types, engineered variants or both.
--include-sequenceless, --no-include-sequenceless
--include-sequence, --no-include-sequence Add each protein's sequence to the rows.
--sort-by Sort key.
--sort-order Sort direction.
--updated-since Changed at or after this ISO 8601 time.
plasticdb proteins get

One protein (or the engineered variant an accession names).

Option Meaning Default
ACCESSION Accession (PB…).
--format Output format (default json, or the -o file's extension).
--output, -o Write the data here instead of stdout.
--view
--include-sequenceless, --no-include-sequenceless
--follow-merges, --no-follow-merges
plasticdb proteins fasta

One protein's FASTA record with the server's annotated header (pinnable).

Option Meaning Default
REF Accession or numeric id.
--output, -o Write here instead of stdout.
plasticdb proteins structure

The primary structure's PDB coordinates (live only; see download structure).

Option Meaning Default
REF Accession or numeric id.
--output, -o Write here instead of stdout.
plasticdb proteins variants

The engineered variants of one wild-type protein, with sequences.

Option Meaning Default
ACCESSION Parent accession.
--limit, -n At most this many records.
--format Output format (default tsv, or the -o file's extension).
--output, -o Write the data here instead of stdout.
--include-sequenceless, --no-include-sequenceless
plasticdb proteins lineage

A wild-type protein with every variant engineered from it (live only).

Option Meaning Default
ACCESSION Parent accession.
--format Output format (default json, or the -o file's extension).
--output, -o Write the data here instead of stdout.

plasticdb variants

Engineered variants.

plasticdb variants list

Engineered variants matching the filters.

Option Meaning Default
--limit, -n At most this many records.
--format Output format (default tsv, or the -o file's extension).
--output, -o Write the data here instead of stdout.
--q, --query Free-text search.
--name Name contains.
--accession
--plastic Plastic name or abbreviation (e.g. PET).
--include-subtypes, --no-include-subtypes Include the plastic's subtypes.
--microorganism Microorganism tax-id, accession or name.
--lineage Lineage contains (any rank).
--year Evidence published in this year.
--min-year Evidence published in or after this year.
--max-year Evidence published in or before this year.
--substrate-form Substrate form (film, powder, ...).
--evidence-method How degradation was shown.
--include-negative, --no-include-negative Also list records with only negative results.
--polarity Evidence outcome (default positive).
--activity-class
--min-kcat
--max-km
--min-kcat-km
--min-vmax
--has-structure, --no-has-structure Only records with (or without) a structure.
--has-sequence, --no-has-sequence Only records with (or without) a sequence.
--ec-number
--min-tm
--max-tm
--origin-type
--origin-environment
--include-sequenceless, --no-include-sequenceless
--include-sequence, --no-include-sequence Add each protein's sequence to the rows.
--sort-by Sort key.
--sort-order Sort direction.
--updated-since Changed at or after this ISO 8601 time.
plasticdb variants get

One variant (live only).

Option Meaning Default
REF Accession or numeric id.
--format Output format (default json, or the -o file's extension).
--output, -o Write the data here instead of stdout.
--include-sequenceless, --no-include-sequenceless
--follow-merges, --no-follow-merges
plasticdb variants fasta

One variant's FASTA record (pinnable).

Option Meaning Default
REF Accession or numeric id.
--output, -o Write here instead of stdout.
plasticdb variants structure

A variant's structure coordinates (live only).

Option Meaning Default
REF Accession or numeric id.
--output, -o Write here instead of stdout.
plasticdb variants of

The variants of one parent protein, with sequences.

Option Meaning Default
PARENT Parent accession.
--limit, -n At most this many records.
--format Output format (default tsv, or the -o file's extension).
--output, -o Write the data here instead of stdout.

plasticdb microorganisms

Microorganisms with evidence of acting on plastics.

plasticdb microorganisms list

Microorganisms matching the filters (positive evidence unless --polarity says).

Option Meaning Default
--limit, -n At most this many records.
--format Output format (default tsv, or the -o file's extension).
--output, -o Write the data here instead of stdout.
--q, --query Free-text search.
--name Name contains.
--plastic Plastic name or abbreviation (e.g. PET).
--include-subtypes, --no-include-subtypes Include the plastic's subtypes.
--plastic-id Plastic id.
--tax-id
--year Evidence published in this year.
--min-year Evidence published in or after this year.
--max-year Evidence published in or before this year.
--temp-class
--environment
--location
--lineage Lineage contains (any rank).
--domain
--kingdom
--phylum
--class Taxonomic class.
--order
--family
--genus
--evidence-method How degradation was shown.
--substrate-form Substrate form (film, powder, ...).
--sole-carbon-source
--aerobicity
--include-negative, --no-include-negative Also list records with only negative results.
--polarity Evidence outcome (default positive).
--evidence-scope Count enzyme assays, organism assays, or both.
--sort-by Sort key.
--sort-order Sort direction.
--updated-since Changed at or after this ISO 8601 time.
plasticdb microorganisms get

One microorganism.

Option Meaning Default
REF NCBI tax-id or PlasticDB accession.
--format Output format (default json, or the -o file's extension).
--output, -o Write the data here instead of stdout.
--evidence-scope Count enzyme assays, organism assays, or both.
--follow-merges, --no-follow-merges
plasticdb microorganisms names

Every microorganism's id and name (live only).

Option Meaning Default
--format Output format (default tsv, or the -o file's extension).
--output, -o Write the data here instead of stdout.
plasticdb microorganisms taxonomy

Aggregate statistics for one taxon (live only).

Option Meaning Default
RANK genus, family, order, class, phylum, …
NAME The taxon, e.g. Pseudomonas.
--format Output format (default json, or the -o file's extension).
--output, -o Write the data here instead of stdout.

plasticdb plastics

The plastic vocabulary.

plasticdb plastics list

Plastics matching the filters.

Option Meaning Default
--limit, -n At most this many records.
--format Output format (default tsv, or the -o file's extension).
--output, -o Write the data here instead of stdout.
--q, --query Free-text search.
--name Name contains.
--cas-number
--plastic-id Plastic id.
--polymer-class
--parent-id
--has-evidence, --no-has-evidence
--evidence-scope Count enzyme assays, organism assays, or both.
--sort-by Sort key.
--sort-order Sort direction.
--updated-since Changed at or after this ISO 8601 time.
plasticdb plastics get

One plastic with a page each of its microorganisms and proteins.

Option Meaning Default
PLASTIC_ID Plastic id.
--format Output format (default json, or the -o file's extension).
--output, -o Write the data here instead of stdout.
--microorganism-limit
--microorganism-offset
--microorganism-sort-by
--microorganism-sort-order
--microorganism-polarity
--protein-limit
--protein-offset
--protein-sort-by
--protein-sort-order
--protein-polarity
--evidence-scope Count enzyme assays, organism assays, or both.
plasticdb plastics names

Every plastic's id and name (live only).

Option Meaning Default
--format Output format (default tsv, or the -o file's extension).
--output, -o Write the data here instead of stdout.

plasticdb papers

The literature behind the evidence.

plasticdb papers list

Papers matching the filters.

Option Meaning Default
--limit, -n At most this many records.
--format Output format (default tsv, or the -o file's extension).
--output, -o Write the data here instead of stdout.
--q, --query Free-text search.
--year Evidence published in this year.
--min-year Evidence published in or after this year.
--max-year Evidence published in or before this year.
--doi Paper DOI.
--journal
--authors
--country
--plastic Plastic name or abbreviation (e.g. PET).
--include-subtypes, --no-include-subtypes Include the plastic's subtypes.
--microorganism Microorganism tax-id, accession or name.
--protein Protein accession.
--evidence-method How degradation was shown.
--polarity Evidence outcome (default positive).
--has-quantitative, --no-has-quantitative Only records with (or without) a measured value.
--sort-by Sort key.
--sort-order Sort direction.
--updated-since Changed at or after this ISO 8601 time.
plasticdb papers get

One paper with the organisms, proteins and variants it reports.

Option Meaning Default
PAPER_ID Paper id.
--format Output format (default json, or the -o file's extension).
--output, -o Write the data here instead of stdout.
plasticdb papers footprint

Every record one paper contributed (live only).

Option Meaning Default
PAPER_ID Paper id.
--format Output format (default json, or the -o file's extension).
--output, -o Write the data here instead of stdout.
plasticdb papers export

Citations as BibTeX or RIS: one paper, or every paper matching the filters.

Option Meaning Default
PAPER_ID (optional) One paper; omit to export every match.
--format bibtex (default) or ris.
--output, -o Write here instead of stdout.
--q, --query Free-text search.
--year Evidence published in this year.
--min-year Evidence published in or after this year.
--max-year Evidence published in or before this year.
--doi Paper DOI.
--journal
--authors
--country
--plastic Plastic name or abbreviation (e.g. PET).
--include-subtypes, --no-include-subtypes Include the plastic's subtypes.
--microorganism Microorganism tax-id, accession or name.
--protein Protein accession.
--evidence-method How degradation was shown.
--polarity Evidence outcome (default positive).
--has-quantitative, --no-has-quantitative Only records with (or without) a measured value.
--updated-since Changed at or after this ISO 8601 time.

plasticdb evidence

The evidence spine (interaction -> experiment -> observation) and the material tables.

plasticdb evidence interactions

A protein's interactions with their experiments and observations.

Option Meaning Default
PROTEIN Protein accession.
--level One row per interaction, experiment or observation (tsv/csv). interaction
--limit, -n At most this many records.
--format Output format (default tsv, or the -o file's extension).
--output, -o Write the data here instead of stdout.
--evidence-level all, direct (assayed on it) or indirect (via its organism or enzyme); direct and indirect need --protein or --microorganism.
--include-sequenceless, --no-include-sequenceless
plasticdb evidence interaction-records

Every interaction as a flat record (the whole evidence spine, one table per level).

Option Meaning Default
--limit, -n At most this many records.
--format Output format (default tsv, or the -o file's extension).
--output, -o Write the data here instead of stdout.
--plastic Plastic name or abbreviation (e.g. PET).
--include-subtypes, --no-include-subtypes Include the plastic's subtypes.
--plastic-id Plastic id.
--microorganism Microorganism tax-id, accession or name.
--protein Protein accession.
--evidence-level all, direct (assayed on it) or indirect (via its organism or enzyme); direct and indirect need --protein or --microorganism.
--paper-id Paper id.
--doi Paper DOI.
--polarity Evidence outcome (default positive).
--evidence-method How degradation was shown.
--substrate-form Substrate form (film, powder, ...).
--measurement-type What was measured (e.g. weight_loss).
--has-quantitative, --no-has-quantitative Only records with (or without) a measured value.
plasticdb evidence interaction

One interaction record.

Option Meaning Default
INTERACTION_ID
--format Output format (default json, or the -o file's extension).
--output, -o Write the data here instead of stdout.
plasticdb evidence experiments

Experiments (assays with their conditions) as flat records.

Option Meaning Default
--limit, -n At most this many records.
--format Output format (default tsv, or the -o file's extension).
--output, -o Write the data here instead of stdout.
--plastic Plastic name or abbreviation (e.g. PET).
--include-subtypes, --no-include-subtypes Include the plastic's subtypes.
--plastic-id Plastic id.
--microorganism Microorganism tax-id, accession or name.
--protein Protein accession.
--evidence-level all, direct (assayed on it) or indirect (via its organism or enzyme); direct and indirect need --protein or --microorganism.
--paper-id Paper id.
--doi Paper DOI.
--polarity Evidence outcome (default positive).
--evidence-method How degradation was shown.
--substrate-form Substrate form (film, powder, ...).
--measurement-type What was measured (e.g. weight_loss).
--has-quantitative, --no-has-quantitative Only records with (or without) a measured value.
--interaction-id Only this interaction's records.
plasticdb evidence experiment

One experiment record.

Option Meaning Default
EXPERIMENT_ID
--format Output format (default json, or the -o file's extension).
--output, -o Write the data here instead of stdout.
plasticdb evidence observations

Measured values as flat records.

Option Meaning Default
--limit, -n At most this many records.
--format Output format (default tsv, or the -o file's extension).
--output, -o Write the data here instead of stdout.
--plastic Plastic name or abbreviation (e.g. PET).
--include-subtypes, --no-include-subtypes Include the plastic's subtypes.
--plastic-id Plastic id.
--microorganism Microorganism tax-id, accession or name.
--protein Protein accession.
--evidence-level all, direct (assayed on it) or indirect (via its organism or enzyme); direct and indirect need --protein or --microorganism.
--paper-id Paper id.
--doi Paper DOI.
--polarity Evidence outcome (default positive).
--evidence-method How degradation was shown.
--substrate-form Substrate form (film, powder, ...).
--measurement-type What was measured (e.g. weight_loss).
--has-quantitative, --no-has-quantitative Only records with (or without) a measured value.
--interaction-id Only this interaction's records.
--experiment-id Only this experiment's observations.
plasticdb evidence observation

One observation record.

Option Meaning Default
OBSERVATION_ID
--format Output format (default json, or the -o file's extension).
--output, -o Write the data here instead of stdout.
plasticdb evidence kinetics

Kinetic parameters of a protein and its variants.

Option Meaning Default
PROTEIN Protein accession.
--limit, -n At most this many records.
--format Output format (default tsv, or the -o file's extension).
--output, -o Write the data here instead of stdout.
plasticdb evidence properties

Stability and activity properties of a protein and its variants.

Option Meaning Default
PROTEIN Protein accession.
--limit, -n At most this many records.
--format Output format (default tsv, or the -o file's extension).
--output, -o Write the data here instead of stdout.
plasticdb evidence binding-assays

Binding (adsorption) assays.

Option Meaning Default
--limit, -n At most this many records.
--format Output format (default tsv, or the -o file's extension).
--output, -o Write the data here instead of stdout.
--protein Protein accession.
--protein-id
--protein-variant-id
--paper-id Paper id.
--doi Paper DOI.
--plastic Plastic name or abbreviation (e.g. PET).
--plastic-id Plastic id.
--include-subtypes, --no-include-subtypes Include the plastic's subtypes.
plasticdb evidence binding-assay

One binding assay.

Option Meaning Default
ASSAY_ID
--format Output format (default json, or the -o file's extension).
--output, -o Write the data here instead of stdout.
plasticdb evidence constructs

Expressed constructs, with their sequences.

Option Meaning Default
--limit, -n At most this many records.
--format Output format (default tsv, or the -o file's extension).
--output, -o Write the data here instead of stdout.
--protein Protein accession.
--protein-id
--protein-variant-id
--paper-id Paper id.
--doi Paper DOI.
plasticdb evidence construct

One construct.

Option Meaning Default
CONSTRUCT_ID
--format Output format (default json, or the -o file's extension).
--output, -o Write the data here instead of stdout.
plasticdb evidence preparations

Prepared materials (expression host, purification, tags).

Option Meaning Default
--limit, -n At most this many records.
--format Output format (default tsv, or the -o file's extension).
--output, -o Write the data here instead of stdout.
--protein Protein accession.
--protein-id
--protein-variant-id
--paper-id Paper id.
--doi Paper DOI.
plasticdb evidence preparation

One preparation.

Option Meaning Default
PREPARATION_ID
--format Output format (default json, or the -o file's extension).
--output, -o Write the data here instead of stdout.

plasticdb pathways

Curated degradation pathways.

plasticdb pathways list

Every pathway.

Option Meaning Default
--limit, -n At most this many records.
--format Output format (default tsv, or the -o file's extension).
--output, -o Write the data here instead of stdout.
plasticdb pathways get

One pathway with its ordered reaction steps.

Option Meaning Default
PATHWAY_ID
--format Output format (default json, or the -o file's extension).
--output, -o Write the data here instead of stdout.
plasticdb pathways for-plastic

Every pathway that degrades one plastic.

Option Meaning Default
PLASTIC_ID
--format Output format (default json, or the -o file's extension).
--output, -o Write the data here instead of stdout.
plasticdb pathways graph

A plastic's pathways as a graph of compounds and reactions.

Option Meaning Default
PLASTIC_ID
--pathway-id Only this pathway.
--format Output format (default json, or the -o file's extension).
--output, -o Write the data here instead of stdout.

plasticdb releases

Dataset releases: the named, citable versions of the data.

plasticdb releases list

Every completed release, newest first.

Option Meaning Default
--limit, -n At most this many records.
--format Output format (default tsv, or the -o file's extension).
--output, -o Write the data here instead of stdout.
plasticdb releases current

The release the server is serving now.

Option Meaning Default
--format Output format (default json, or the -o file's extension).
--output, -o Write the data here instead of stdout.
plasticdb releases get

One release with its artefacts.

Option Meaning Default
VERSION e.g. 2026.50
--format Output format (default json, or the -o file's extension).
--output, -o Write the data here instead of stdout.
plasticdb releases status

Whether a release is being cut right now.

Option Meaning Default
--format Output format (default json, or the -o file's extension).
--output, -o Write the data here instead of stdout.

plasticdb download

Files: filtered tables, the whole dataset, and a release's checksummed artefacts.

plasticdb download table

One table as the server publishes it (a pinned release: that release's table).

Option Meaning Default
TABLE Which table.
--format csv (default), json, or fasta (proteins).
--output, -o A file, or a directory to save the server's file name in. .
--q, --query Free-text search.
--name Name contains.
--plasticdb-id
--accession
--plastic Plastic name or abbreviation (e.g. PET).
--include-subtypes, --no-include-subtypes Include the plastic's subtypes.
--microorganism Microorganism tax-id, accession or name.
--lineage Lineage contains (any rank).
--year Evidence published in this year.
--min-year Evidence published in or after this year.
--max-year Evidence published in or before this year.
--substrate-form Substrate form (film, powder, ...).
--evidence-method How degradation was shown.
--include-negative, --no-include-negative Also list records with only negative results.
--polarity Evidence outcome (default positive).
--activity-class
--min-kcat
--max-km
--min-kcat-km
--min-vmax
--has-structure, --no-has-structure Only records with (or without) a structure.
--has-sequence, --no-has-sequence Only records with (or without) a sequence.
--ec-number
--min-tm
--max-tm
--origin-type
--origin-environment
--kind Wild types, engineered variants or both.
--plastic-id Plastic id.
--tax-id
--temp-class
--environment
--location
--domain
--kingdom
--phylum
--class Taxonomic class.
--order
--family
--genus
--sole-carbon-source
--aerobicity
--evidence-scope Count enzyme assays, organism assays, or both.
--cas-number
--polymer-class
--parent-id
--has-evidence, --no-has-evidence
--doi Paper DOI.
--journal
--authors
--country
--protein Protein accession.
--has-quantitative, --no-has-quantitative Only records with (or without) a measured value.
--parent-protein-id
--parent-plasticdb-id
--variant-type
--engineering-method
plasticdb download dataset

Every public record. With --release: every artefact that release published, verified.

Option Meaning Default
--output, -o A file, or a directory to save the server's file name in. .
--format zip (default: CSVs, README, licence) or json.
--max-wait Seconds to wait while the server builds the ZIP.
plasticdb download artefact

One artefact of a release (the pinned or current one), verified against its SHA-256.

Option Meaning Default
FILE Path in the release, e.g. parquet/proteins.parquet
--output, -o A file, or a directory to save the server's file name in. .
plasticdb download manifest

A release's MANIFEST.json (every artefact with its SHA-256, size and licence).

Option Meaning Default
--output, -o Write here instead of stdout.
--format Output format (default json, or the -o file's extension).
plasticdb download structure

One structure's coordinates as a release published them (gzipped PDB), verified.

Option Meaning Default
STRUCTURE_ID Structure id (a record's structures[].id).
--output, -o A file, or a directory to save the server's file name in. .

plasticdb jobs

Run PlasticDB's analyses (needs an API key).

plasticdb jobs submit

Submit a job. Prints its id; with --wait, its results (or -o saves the results file).

Option Meaning Default
TYPE The analysis.
INPUTS (optional) Input file(s): FASTA (plain or gzip) or a taxa table; - reads stdin. compare-genomes takes 2-20, build-tree none.
--wait, --no-wait Wait for the job, then write its results.
--timeout With --wait: give up after this many seconds.
--format With --wait: the results as tsv (default), csv, json, jsonl or newick (build-tree). Without --format, -o saves the server's results file.
--output, -o Write here instead of stdout.
--idempotency-key Name this submission (1-255 printable ASCII characters). Resubmitting with the same key within 24 hours returns the first job instead of a duplicate (default: a new UUID, reused on the client's own retries).
--blast-type For annotate-gene, annotate-genome, compare-genomes, pathway-analysis.
--organism-type For annotate-gene, annotate-genome, compare-genomes.
--evalue For annotate-gene, annotate-genome, compare-genomes, pathway-analysis, hmm-screen.
--pident For annotate-gene, annotate-genome, compare-genomes, pathway-analysis.
--include-variants, --no-include-variants For annotate-gene, annotate-genome, compare-genomes.
--min-qcov For annotate-gene, annotate-genome, compare-genomes.
--min-scov For annotate-gene, annotate-genome, compare-genomes.
--min-bitscore For annotate-gene, annotate-genome, compare-genomes.
--genus-column For annotate-list.
--species-column For annotate-list.
--field-separator For annotate-list.
--target-plastic For pathway-analysis.
--min-step-identity For pathway-analysis.
--max-step-evalue For pathway-analysis.
--min-reference-coverage For pathway-analysis.
--min-query-coverage For pathway-analysis.
--target-polymers For hmm-screen.
--threshold-mode For hmm-screen.
--label A genome's name in the results, one per input, in order (compare-genomes).
--microorganism-ids Organism ids (repeat the option).
--q, --query Free-text search.
--name Name contains.
--plastic Plastic name or abbreviation (e.g. PET).
--plastic-id Plastic id.
--include-subtypes, --no-include-subtypes Include the plastic's subtypes.
--tax-id
--temp-class
--environment
--location
--year Evidence published in this year.
--min-year Evidence published in or after this year.
--max-year Evidence published in or before this year.
--lineage Lineage contains (any rank).
--domain
--kingdom
--phylum
--class Taxonomic class.
--order
--family
--genus
--evidence-method How degradation was shown.
--substrate-form Substrate form (film, powder, ...).
--include-negative, --no-include-negative Also list records with only negative results.
--polarity Evidence outcome (default positive).
--evidence-scope Count enzyme assays, organism assays, or both.
--sole-carbon-source
--aerobicity
--updated-since Changed at or after this ISO 8601 time.
plasticdb jobs status

A job's status, parameters and provenance.

Option Meaning Default
JOB Job id, or a share link.
--format Output format (default json, or the -o file's extension).
--output, -o Write the data here instead of stdout.
plasticdb jobs wait

Wait for a job to finish (exit 7 if it fails, 8 on --timeout); print its record.

Option Meaning Default
JOB Job id, or a share link.
--timeout Give up after this many seconds.
--poll-interval First poll interval, seconds. 2.0
--format Output format (default json, or the -o file's extension).
--output, -o Write the data here instead of stdout.
plasticdb jobs results

A finished job's results, typed (every stored hit; see jobs download for the file).

Option Meaning Default
JOB Job id, or a share link.
--format tsv (default), csv, json, jsonl, or newick (build-tree; its default).
--comparison, --no-comparison compare-genomes: the genome x plastic matrix instead of hits.
--output, -o Write here instead of stdout.
plasticdb jobs download

The server's results file (TSV with provenance lines; a ZIP for compare-genomes).

Option Meaning Default
JOB Job id, or a share link.
--output, -o A file, or a directory to save the server's file name in. .
--scov Minimum subject coverage (0 = off).
--qcov Minimum query coverage.
--bitscore Minimum bitscore.
--all-hits, --no-all-hits Every hit, not the default view.
plasticdb jobs share

Create a read-only link to a job's results. The link is shown once: keep it.

Option Meaning Default
JOB Job id, or a share link.
--expires-in-days 1-365; default: as long as the job.
--format text (the URL, default) or json.
--output, -o Write here instead of stdout.
plasticdb jobs shares

A job's share links (never their tokens).

Option Meaning Default
JOB Job id, or a share link.
--format Output format (default tsv, or the -o file's extension).
--output, -o Write the data here instead of stdout.
plasticdb jobs unshare

Revoke a share link.

Option Meaning Default
JOB Job id, or a share link.
SHARE_ID
plasticdb jobs list

Your jobs, newest first.

Option Meaning Default
--limit, -n At most this many records.
--format Output format (default tsv, or the -o file's extension).
--output, -o Write the data here instead of stdout.
plasticdb jobs search-sequence

Search one sequence now (synchronous DIAMOND; no job). --format json adds provenance.

Option Meaning Default
SEQUENCE Residues, a one-record FASTA file, or - for stdin.
--format Output format (default tsv, or the -o file's extension).
--output, -o Write the data here instead of stdout.
--blast-type
--evalue
--pident
--include-variants, --no-include-variants

plasticdb auth

Store, check or remove your API key.

plasticdb auth login

Save an API key to the config file (0600). Reads it from --key, else stdin.

Option Meaning Default
--key The key (visible in your shell history and process list: prefer stdin).
--verify, --no-verify Check the key with the server first. True
plasticdb auth logout

Remove the stored API key.

plasticdb auth status

Which API key is in use and where it comes from (exit 4 when there is none).

Option Meaning Default
--verify, --no-verify Also check the key with the server.
--format Output format (default text, or the -o file's extension).
--output, -o Write the data here instead of stdout.