Usage

This section assumes you’ve installed Nextclade CLI, it’s available in your system path as nextclade and has executable permissions. If not, please refer to installation section for more information.

Refer to the help prompt for usage of Nextclade by running it without any arguments or with --help:

nextclade
nextclade --help

Note that Nextclade CLI has subcommands. Each subcommand has its own help prompt:

nextclade run --help
nextclade dataset list --help
nextclade dataset get --help

Quick start

  1. Download a SARS-CoV-2 dataset:

    nextclade dataset get --name 'nextstrain/sars-cov-2/wuhan-hu-1/orfs' --output-dir 'data/sars-cov-2'

    Observe downloaded dataset files in the directory data/sars-cov-2/

    💡️ This command will download the latest SARS-CoV-2 dataset. You should run it periodically to update the dataset, in order to get the latest features, including the most up-to-date clade assignment. Find out more in the Nextclade datasets section.

  2. Run using the downloaded dataset and its example sequences (data/sars-cov-2/sequences.fasta):

    nextclade run \
   --input-dataset data/sars-cov-2 \
   --output-all=output/ \
   data/sars-cov-2/sequences.fasta

    Try to provide your own data instead of data/sars-cov-2/sequences.fasta.

    For more controls, specify input files explicitly and/or add more flags for output files:

    nextclade run \
   --verbose \
   --include-reference \
   --in-order \
   --input-dataset=data/sars-cov-2 \
   --input-ref=data/sars-cov-2/reference.fasta \
   --input-annotation=data/sars-cov-2/genome_annotation.gff3 \
   --cds-selection=E,M,N,ORF1a,ORF1b,ORF3a,ORF6,ORF7a,ORF7b,ORF8,ORF9b,S \
   --input-tree=data/sars-cov-2/tree.json \
   --input-pathogen-json=data/sars-cov-2/pathogen.json \
   --output-fasta=output/nextclade.aligned.fasta.gz \
   --output-json=output/nextclade.json \
   --output-ndjson=output/nextclade.ndjson \
   --output-csv=output/nextclade.csv \
   --output-tsv=output/nextclade.tsv \
   --output-tree=output/nextclade.auspice.json \
   --output-tree-nwk=output/nextclade.tree.nwk \
   --output-translations=output/nextclade_CDS_{cds}.translation.fasta.zst \
   data/sars-cov-2/sequences.fasta \
   my_sequences1.fasta.gz \
   my_sequences2.fasta.xz

    Add the --verbose flag to show more information in the console. Add --include-reference flag to also write gap-stripped reference sequence and reference peptides into outputs. Add --in-order to preserve the same order of results in output files as in input fasta (has runtime performance cost).

    The --input-dataset argument can be combined with individual --input* args. In this case, individual args override the corresponding files in the dataset.

    If --output-all is used, you can set --output-basename to control filenames and --output-selection=all,fasta,json,ndjson,csv,tsv,tree,translations,insertions,errors to control which files are emitted.

    There are more advanced arguments to control alignment and other parts of the algorithm. Refer to nextclade run --help for more details.

    You can learn more about input and output files in sections: Input files, Output files and Nextclade datasets. Read the built-in help (nextclade --help) for a detailed description of each subcommand and each flag.

  3. Find the output files in the output/ directory:

  • nextclade.aligned.fasta - aligned input sequences

  • nextclade_cds_<cds_name>.translation.fasta - aligned peptides corresponding to each coding sequence (CDS)

  • nextclade.tsv - results of the analysis in TSV format

  • nextclade.csv - same results, but in CSV format

  • nextclade.json - detailed results of the analysis in JSON format

  • nextclade.ndjson - detailed results of the analysis in newline-delimited JSON format

  • nextclade.auspice.json - same as input tree, but with the input sequences placed onto it and in Auspice v2 JSON format

  • nextclade.tree.nwk - same as input tree, but with the input sequences placed onto it and in Newick format

JSON Schemas

Nextclade can generate JSON Schema definitions for its JSON-based file formats to help with validation, code generation, and integration in downstream applications.

# Generate schemas for all formats
nextclade schema write --output schemas/

# Generate schema for specific format
nextclade schema write --for output-json --output schemas/output-json.schema.json

# Read help for more options
nextclade schema write --help

For comprehensive documentation, usage examples, and integration guides, see the JSON Schema documentation.

What’s next?

Congratulations, You have learned how to use Nextclade CLI!

Going further, you might want to learn about the science behind the Nextclade internals in the Algorithm section. The required input data is described in Input files section. And produced files are described in Output files section. The datasets are described in more details in the Nextclade datasets section.

For a more convenient online tool, check out Nextclade Web.

Nextclade is an open-source project. We welcome ideas and contributions. Head to our GitHub repository if you want report a bug, suggest a feature, or contribute code.