nextstrain buildď
Runs a pathogen build in a Nextstrain runtime.
The build directory should contain a Snakefile, which will be run with snakemake.
You need at least one runtime available to run a build. You can test if the Docker, Conda, ambient, or AWS Batch runtimes are properly supported on your computer by running:
nextstrain check-setup
The nextstrain build command is designed to cleanly separate the Nextstrain build interface from provisioning a runtime environment, so that running builds is as easy as possible. It also lets us more seamlessly make runtime changes in the future as desired or necessary.
usage: nextstrain build [options] <directory> [...]
nextstrain build --help
Positional Argumentsď
- <directory>
Path to pathogen build directory
- ...
Additional arguments to pass to the executed program
Default: []
Named Argumentsď
- --help, -h
Show a brief help message of common options and exit
- --detach
Run the build in the background, detached from your terminal. Re-attach later using âattach. Currently only supported when also using âaws-batch.
Default: False
- --attach
Re-attach to a âdetachâed build to view output and download results. Currently only supported when also using âaws-batch.
- --cpus
Number of CPUs/cores/threads/jobs to utilize at once. Limits containerized (Docker, AWS Batch) builds to this amount. Informs Snakemakeâs resource scheduler when applicable. Informs the AWS Batch instance size selection. By default, no constraints are placed on how many CPUs are used by a build; builds may use all that are available if theyâre able to.
- --memory
Amount of memory to make available to the build. Units of b, kb, mb, gb, kib, mib, gib are supported. Limits containerized (Docker, AWS Batch) builds to this amount. Informs Snakemakeâs resource scheduler when applicable. Informs the AWS Batch instance size selection.
- --download
Only download new or modified files matching <pattern> from the remote build. Shell-style advanced globbing is supported, but be sure to escape wildcards or quote the whole pattern so your shell doesnât expand them. May be passed more than once. Currently only supported when also using âaws-batch. Default is to download every new or modified file.
Besides basic glob features like single-part wildcards (*), character classes ([âŚ]), and brace expansion ({âŚ, âŚ}), several advanced globbing features are also supported: multi-part wildcards (**), extended globbing (@(âŚ), +(âŚ), etc.), and negation (!âŚ).
Default: True
- --no-download
Do not download any files from the remote build when it completes. Currently only supported when also using âaws-batch.
Default: True
- --no-logs
Do not show the log messages of the remote build. Currently only supported when also using âaws-batch. Default is to show all log messages, even when attaching to a completed build.
Default: True
runtime selection optionsď
Select the Nextstrain runtime to use, if the default is not suitable.
- --docker
Run commands inside a container image using Docker. (default)
- --conda
Run commands with access to a fully-managed Conda environment.
- --singularity
Run commands inside a container image using Singularity.
- --ambient
Run commands in the ambient environment, outside of any container image.
- --aws-batch
Run commands remotely on AWS Batch inside the Nextstrain container image.
runtime optionsď
Options shared by all runtimes.
- --env
Set the environment variable <name> to the value in the current environment (i.e. pass it thru) or to the given <value>. May be specified more than once. Overrides any variables of the same name set via âenvdir. When this option or âenvdir is given, the default behaviour of automatically passing thru several âwell-knownâ variables is disabled. The âwell-knownâ variables are AUGUR_RECURSION_LIMIT, AUGUR_MINIFY_JSON, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN, ID3C_URL, ID3C_USERNAME, ID3C_PASSWORD, RETHINK_HOST, and RETHINK_AUTH_KEY. Pass those variables explicitly via âenv or âenvdir if you need them in combination with other variables.
Default: []
- --envdir
Set environment variables from the envdir at <path>. May be specified more than once. An envdir is a directory containing files describing environment variables. Each filename is used as the variable name. The first line of the contents of each file is used as the variable value. When this option or âenv is given, the default behaviour of automatically passing thru several âwell-knownâ variables is disabled. See the description of âenv for more details.
Default: []
development optionsď
These should generally be unnecessary unless youâre developing Nextstrain.
- --image
Container image name to use for the Nextstrain runtime (default: ânextstrain/baseâ for Docker and AWS Batch, docker://nextstrain/base for Singularity)
Default: ânextstrain/baseâ
- --exec
Program to run inside the runtime
Default: âsnakemakeâ
development options for âdockerď
- --augur
Replace the imageâs copy of augur with a local copy
- --auspice
Replace the imageâs copy of auspice with a local copy
- --fauna
Replace the imageâs copy of fauna with a local copy
- --sacra
Replace the imageâs copy of sacra with a local copy
- --docker-arg
Additional arguments to pass to docker run
Default: []
development options for âaws-batchď
See <https://docs.nextstrain.org/projects/cli/page/aws-batch> for more information.
- --aws-batch-job
Name of the AWS Batch job definition to use
Default: ânextstrain-jobâ
- --aws-batch-queue
Name of the AWS Batch job queue to use
Default: ânextstrain-job-queueâ
- --aws-batch-s3-bucket
Name of the AWS S3 bucket to use as shared storage
Default: ânextstrain-jobsâ
- --aws-batch-cpus
Number of vCPUs to request for job
- --aws-batch-memory
Amount of memory in MiB to request for job