CLI reference
This page lists all of the available options and subcommands for the Nextflow CLI.
Options
The top-level options are meant to be invoked in relation to the core Nextflow application and are applied to all commands. For options specific to any command, refer the CLI Commands section.
Available options:
-C
Use the specified configuration file(s) overriding any defaults.
-D
Set JVM properties.
-bg
Execute nextflow in background.
-c, -config
Add the specified file to configuration set.
-d, -dockerize
Deprecated since version 23.09.0-edge.
Launch nextflow via Docker (experimental).
-h
Print this help.
-log
Set nextflow log file path.
-q, -quiet
Do not print information messages.
-remote-debug
Enable JVM interactive remote debugging (experimental).
-syslog
Send logs to syslog server (e.g. localhost:514).
-trace
Enable trace level logging for the specified packages. Multiple packages can be provided separating them with a comma, e.g.
-trace nextflow,io.seqera
.-v, -version
Print the program version.
Commands
clean
Clean up cache and work directories.
Usage
$ nextflow clean [run_name|session_id] [options]
Description
Upon invocation within a directory, nextflow
creates a project specific .nextflow.log
file, .nextflow
cache directory as well as a work
directory. The clean
command is designed to facilitate removal of these files from previous executions. A list of run names and session ids can be generated by invoking nextflow log -q
.
If no run name or session id is provided, it will clean the latest run.
Options
-after
Clean up runs executed after the specified one.
-before
Clean up runs executed before the specified one.
-but
Clean up all runs except the specified one.
-n, -dry-run
Print names of files to be removed without deleting them.
-f, -force
Force clean command.
-h, -help
Print the command usage.
-k, -keep-logs
Removes only temporary files but retains execution log entries and metadata.
-q, -quiet
Do not print names of files removed.
Examples
Dry run to remove work directories for the run name boring_euler
:
$ nextflow clean boring_euler -n
Would remove work/92/c1a9cd9a96e0531d81ca69f5dc3bb7
Would remove work/3f/70944c7a549b6221e1ccc7b4b21b62
Would remove work/0e/2ebdba85f76f6068b21a1bcbf10cab
Remove work directories for the run name boring_euler
.
$ nextflow clean boring_euler -f
Removed work/92/c1a9cd9a96e0531d81ca69f5dc3bb7
Removed work/3f/70944c7a549b6221e1ccc7b4b21b62
Removed work/0e/2ebdba85f76f6068b21a1bcbf10cab
Remove the execution entries except for a specific execution.
$ nextflow clean -but tiny_leavitt -f
Removed work/1f/f1ea9158fb23b53d5083953121d6b6
Removed work/bf/334115deec60929dc18edf0010032a
Removed work/a3/06521d75da296d4dd7f4f8caaddad8
Dry run to remove the execution data before a specific execution.
$ nextflow clean -before tiny_leavitt -n
Would remove work/5d/ad76f7b7ab3500cf616814ef644b61
Would remove work/c4/69a82b080a477612ba8d8e4c27b579
Would remove work/be/a4fa2aa38f76fd324958c81c2e4603
Would remove work/54/39116773891c47a91e3c1733aad4de
Dry run to remove the execution data after a specific execution.
$ nextflow clean -after focused_payne -n
Would remove work/1f/f1ea9158fb23b53d5083953121d6b6
Would remove work/bf/334115deec60929dc18edf0010032a
Would remove work/a3/06521d75da296d4dd7f4f8caaddad8
Dry run to remove the temporary execution data for a specific execution, while keeping the log files.
$ nextflow clean -keep-logs tiny_leavitt -n
Would remove temp files from work/1f/f1ea9158fb23b53d5083953121d6b6
Would remove temp files from work/bf/334115deec60929dc18edf0010032a
Would remove temp files from work/a3/06521d75da296d4dd7f4f8caaddad8
clone
Clone a remote project into a folder.
Usage
$ nextflow clone [options] [project]
Description
The clone
command downloads a pipeline from a Git-hosting platform into the current directory and modifies it accordingly. For downloading a pipeline into the global cache ~/.nextflow/assets
, please refer to the nextflow pull
command.
Options
-d, -deep
Create a shallow clone of the specified depth.
-h, -help
Print the command usage.
-hub
(github
)Service hub where the project is hosted. Options:
gitlab
orbitbucket
.-r
(master
)Revision to clone - It can be a git branch, tag, or revision number.
-user
Private repository user name.
Examples
Clone the latest revision of a pipeline.
$ nextflow clone nextflow-io/hello
nextflow-io/hello cloned to: hello
Clone a specific revision of a pipeline.
$ nextflow clone nextflow-io/hello -r v1.1
nextflow-io/hello cloned to: hello
config
Print the resolved pipeline configuration.
Usage
$ nextflow config [options] [project name or path]
Description
The config
command is used for printing the project’s configuration i.e. the nextflow.config
and is especially useful for understanding the resolved profiles and parameters that Nextflow will use run a pipeline. For in-depth information, please refer the Config profiles section.
Options
-flat
Print config using flat notation.
-h, -help
Print the command usage.
-profile
Choose a configuration profile.
-properties
Print config using Java properties notation.
-a, -show-profiles
Show all configuration profiles.
-sort
Sort config attributes.
-value
New in version 23.08.0-edge.
Print the value of a config option, or fail if the option is not defined.
Examples
Print out the inferred config using a the default group key-value notation.
$ nextflow config
docker {
enabled = true
}
process {
executor = 'local'
}
Print out the config using a flat notation.
$ nextflow config -flat
docker.enabled = true
process.executor = 'local'
Print out the config using the Java properties notation.
$ nextflow config -properties
docker.enabled = true
process.executor = local
Print out the value of a specific configuration property.
$ nextflow config -value process.executor
local
Print out all profiles from the project’s configuration.
$ nextflow config -show-profiles
docker {
enabled = true
}
profiles {
standard {
process {
executor = 'local'
}
}
cloud {
process {
executor = 'cirrus'
container = 'cbcrg/imagex'
}
}
}
console
Launch the Nextflow interactive console.
Usage
$ nextflow console
Description
The console
command provides a Graphical User Interface (GUI) and an interactive REPL (Read-Eval-Print-Loop) for quick experimentation.
Options
None available
Examples
Launch the console
GUI.
$ nextflow console
drop
Delete the local copy of a project.
Usage
$ nextflow drop [options] [project]
Description
The drop
command is used to remove the projects which have been downloaded into the global cache. Please refer the list
command for generating a list of downloaded pipelines.
Options
-f
Delete the repository without taking care of local changes.
-h, -help
Print the command usage.
Examples
Drop the nextflow-io/hello
project.
$ nextflow drop nextflow-io/hello
Forcefully drop the nextflow-io/hello
pipeline, ignoring any local changes.
$ nextflow drop nextflow-io/hello -f
fs
Perform basic filesystem operations.
Usage
$ nextflow fs [subcommands]
Description
The fs
command is used to perform filesystem operations like copy, move, delete, list directory, etc. Like the file()
method, it can work with local files, remote URLs, and remote object storage. Storage credentials can be provided through the same manner as launching a pipeline (Nextflow config, environment vars, etc).
Options
-h, -help
Print the command usage.
Examples
List a directory.
$ nextflow fs list <directory>
Print the contents of a file to standard output.
$ nextflow fs cat <file>
Copy a file or directory.
$ nextflow fs cp <source> <target>
Move a file or directory.
$ nextflow fs mv <source> <target>
Delete a file or directory.
$ nextflow fs rm <path>
New in version 23.10.0.
Print file or directory attributes.
$ nextflow fs stat <path>
help
Print the top-level help or specific help for a command.
Usage
$ nextflow help [options] [command]
Description
The help
command prints out the overview of the CLI interface and enumerates the top-level options and commands. Note that this command is equivalent to simply invoking nextflow
at the command line.
Options
-h, -help
Print the command usage.
Examples
Invoke the help
option for the drop
command.
$ nextflow help drop
Delete the local copy of a project
Usage: drop [options] name of the project to drop
Options:
-f
Delete the repository without taking care of local changes
Default: false
-h, -help
Print the command usage
Default: false
info
Print project or system runtime information.
Usage
$ nextflow info [options] [project]
Description
The info
command prints out the nextflow runtime information about the hardware as well as the software versions of the Nextflow version and build, operating system, and Groovy and Java runtime. It can also be used to display information about a specific project.
If no run name or session id is provided, it will clean the latest run.
Options
-u, -check-updates
Check for remote updates.
-d
Show detailed information.
-h, -help
Print the command usage.
-o
(text
)Output format, either
text
,json
oryaml
.
Examples
Display Nextflow runtime and system info:
$ nextflow info
Version: 20.07.1 build 5412
Created: 24-07-2020 15:18 UTC (20:48 IDT)
System: Mac OS X 10.15.6
Runtime: Groovy 2.5.11 on OpenJDK 64-Bit Server VM 1.8.0_192-b01
Encoding: UTF-8 (UTF-8)
Display information about a specific project:
$ nextflow info nextflow-io/hello
project name: nextflow-io/hello
repository : https://github.com/nextflow-io/hello
local path : /Users/evanfloden/.nextflow/assets/nextflow-io/hello
main script : main.nf
revisions :
* master (default)
mybranch
testing
v1.1 [t]
v1.2 [t]
inspect
New in version 23.09.0-edge.
Inspect process settings in a pipeline project. Currently only supports the container
directive.
Usage
$ nextflow inspect [options] [project]
Description
The inspect
command allows you to determine the container for each process in a pipeline without running the pipeline. It prints to stdout a listing of containers for each process, formatted either as JSON or Nextflow configuration.
Options
-concretize
Build the container images resolved by the inspect command.
-format
(json
)Inspect output format. Can be
json
orconfig
.-i, -ignore-errors
Ignore errors while inspecting the pipeline.
-params-file
Load script parameters from a JSON/YAML file.
-profile
Use the given configuration profile(s).
-r, revision
Revision of the project to inspect (either a git branch, tag or commit SHA number).
Examples
Get the list of containers used by a pipeline.
$ nextflow inspect nextflow-io/hello
Specify parameters as with the run
command:
$ nextflow inspect main.nf --alpha 1 --beta foo
kuberun
Launch a Nextflow pipeline on a Kubernetes cluster.
Usage
$ nextflow kuberun [options] [project]
Description
The kuberun
command builds upon the run
command and offers a deep integration with the Kubernetes execution environment. This command deploys the Nextflow runtime as a Kubernetes pod and assumes that you’ve already installed the kubectl
CLI. The kuberun
command does not allow the execution of local Nextflow scripts. See Kubernetes for more information.
Options
The kuberun
command supports the following options from run
:
-cache
-disable-jobs-cancellation
-dsl1
-dsl2
-dump-channels
-dump-hashes
-e.<key>=<value>
-entry
-h, -help
-hub
-latest
-main-script
-name
-offline
-params-file
-plugins
-preview
-process.<key>=<value>
-profile
-qs, -queue-size
-resume
-r, -revision
-stub, -stub-run
-user
-with-conda
-with-dag
-N, -with-notification
-with-report
-with-spack
-with-timeline
-with-tower
-with-trace
-with-wave
-with-weblog
-without-spack
-without-wave
-w, -work-dir
The following new options are also available:
-head-cpus
New in version 22.01.0-edge.
Specify number of CPUs requested for the Nextflow pod.
-head-image
New in version 22.07.1-edge.
Specify the container image for the Nextflow driver pod.
-head-memory
New in version 22.01.0-edge.
Specify amount of memory requested for the Nextflow pod.
-head-prescript
New in version 22.05.0-edge.
Specify script to be run before the Nextflow pod starts.
-n, -namespace
Specify the K8s namespace to use.
-remoteConfig
Add the specified file from the K8s cluster to configuration set.
-remoteProfile
Choose a configuration profile in the remoteConfig.
-v, -volume-mount
Volume claim mounts, e.g.
my-pvc:/mnt/path
.
Examples
Execute a pipeline into a Kubernetes cluster.
$ nextflow kuberun nextflow-io/hello
list
List all downloaded projects.
Usage
$ nextflow list [options]
Description
The list
commands prints a list of the projects which are already downloaded into the global cache ~/.nextflow/assets
.
Options
-h, -help
Print the command usage.
Examples
List the downloaded pipelines.
$ nextflow list
nextflow-io/hello
nextflow-hub/fastqc
log
Print the execution history and log information.
Usage
$ nextflow log [options] [run_name | session_id]
Description
The log
command is used to query the execution metadata associated with pipelines executed by Nextflow. The list of executed pipelines can be generated by running nextflow log
. Instead of run name, it’s also possible to use a session id. Moreover, this command contains multiple options to facilitate the queries and is especially useful while debugging a pipeline and while inspecting pipeline execution metadata.
Options
-after
Show log entries for runs executed after the specified one.
-before
Show log entries for runs executed before the specified one.
-but
Show log entries for runs executed but the specified one.
-f, -fields
Comma-separated list of fields to include in the printed log. Use the
-l
option to see the list of available fields.-F, -filter
Filter log entries by a custom expression, e.g.
process =~ /foo.*/ && status == 'COMPLETED'
.-h, -help
Print the command usage.
-l, -list-fields
Show all available fields.
-quiet
Show only run names.
-s
Character used to separate column values.
-t, -template
Text template used to each record in the log.
Examples
Listing the execution logs of previous invocations of all pipelines in a project.
$ nextflow log
TIMESTAMP DURATION RUN NAME STATUS REVISION ID SESSION ID COMMAND
2020-10-07 11:52:24 2.1s focused_payne OK 96eb04d6a4 af6adaaa-ad4f-48a2-9f6a-b121e789adf5 nextflow run nextflow-io/hello -r master
2020-10-07 11:53:00 3.1s tiny_leavitt OK e3b475a61b 4d3b95c5-4385-42b6-b430-c865a70d56a4 nextflow run ./tutorial.nf
2020-10-07 11:53:29 2.5s boring_euler OK e3b475a61b a6276975-7173-4208-ae09-ab9d6dce8737 nextflow run tutorial.nf
Listing only the run names of the execution logs of all pipelines invocations in a project.
$ nextflow log -quiet
focused_payne
tiny_leavitt
boring_euler
List the execution entries only a specific execution.
$ nextflow log tiny_leavitt
work/1f/f1ea9158fb23b53d5083953121d6b6
work/bf/334115deec60929dc18edf0010032a
work/a3/06521d75da296d4dd7f4f8caaddad8
List the execution entries after a specific execution.
$ nextflow log -after tiny_leavitt
work/92/c1a9cd9a96e0531d81ca69f5dc3bb7
work/3f/70944c7a549b6221e1ccc7b4b21b62
work/0e/2ebdba85f76f6068b21a1bcbf10cab
List the execution entries before a specific execution.
$ nextflow log -before tiny_leavitt
work/5d/ad76f7b7ab3500cf616814ef644b61
work/c4/69a82b080a477612ba8d8e4c27b579
work/be/a4fa2aa38f76fd324958c81c2e4603
work/54/39116773891c47a91e3c1733aad4de
List the execution entries except for a specific execution.
$ nextflow log -but tiny_leavitt
work/5d/ad76f7b7ab3500cf616814ef644b61
work/c4/69a82b080a477612ba8d8e4c27b579
work/be/a4fa2aa38f76fd324958c81c2e4603
work/54/39116773891c47a91e3c1733aad4de
Filter specific fields from the execution log of a process.
$ nextflow log tiny_leavitt -f 'process,exit,hash,duration'
splitLetters 0 1f/f1ea91 112ms
convertToUpper 0 bf/334115 144ms
convertToUpper 0 a3/06521d 139ms
Filter fields from the execution log of a process based on a criteria.
$ nextflow log tiny_leavitt -F 'process =~ /splitLetters/'
work/1f/f1ea9158fb23b53d5083953121d6b6
plugin
Manage plugins and run plugin-specific commands.
$ nextflow plugin <subcommand> [options]
The plugin
command provides several subcommands for managing and using plugins:
install <plugin[@version],..>
Install a plugin. Multiple plugins can be specified as a comma-separated list. Each plugin id consists of a name and optional version separated by a
@
.<plugin>:<subcommand> [options]
Execute a plugin-specific command.
pull
Download or update a project.
Usage
$ nextflow pull [options] [project]
Description
The pull
command downloads a pipeline from a Git-hosting platform into the global cache ~/.nextflow/assets
and modifies it accordingly. For downloading a pipeline into a local directory, please refer to the nextflow clone
command.
Options
-all
Update all downloaded projects.
-d, -deep
Create a shallow clone of the specified depth.
-h, -help
Print the command usage.
-hub
(github
)Service hub where the project is hosted. Options:
gitlab
orbitbucket
-r, -revision
Revision of the project to run (either a git branch, tag or commit hash).
When passing a git tag or branch, the
workflow.revision
andworkflow.commitId
fields are populated. When passing only the commit hash,workflow.revision
is not defined.-user
Private repository user name.
Examples
Download a new pipeline or pull the latest revision for a specific project.
$ nextflow pull nextflow-io/hello
Checking nextflow-io/hello ...
done - revision: 96eb04d6a4 [master]
Pull the latest revision for all downloaded projects.
$ nextflow pull -all
Checking nextflow-io/hello ...
done - revision: 96eb04d6a4 [master]
Checking nextflow-hub/fastqc ...
done - revision: 087659b18e [master]
Download a specific revision of a new project or pull the latest revision for a specific project.
$ nextflow pull nextflow-io/hello -r v1.1
Checking nextflow-io/hello ...
checkout-out at AnyObjectId[1c3e9e7404127514d69369cd87f8036830f5cf64] - revision: 1c3e9e7404 [v1.1]
run
Execute a pipeline.
Usage
$ nextflow run [options] [project]
Description
The run
command is used to execute a local pipeline script or remote pipeline project.
Options
-E
Exports all current system environment.
-ansi-log
Enable/disable ANSI console logging.
-bucket-dir
Remote bucket where intermediate result files are stored. When running a hybrid workflow,
-bucket-dir
and-work-dir
should define separate work directories for remote tasks and local tasks, respectively.-cache
Enable/disable processes caching.
-d, -deep
Create a shallow clone of the specified depth.
-disable-jobs-cancellation
Prevent the cancellation of child jobs on execution termination
-dsl1
Deprecated since version 23.09.0-edge.
Execute the workflow using DSL1 syntax.
-dsl2
Deprecated since version 23.09.0-edge.
Execute the workflow using DSL2 syntax.
-dump-channels
Dump channels for debugging purpose.
-dump-hashes
Dump task hash keys for debugging purposes.
New in version 23.10.0: You can use
-dump-hashes json
to dump the task hash keys as JSON for easier post-processing. See the caching and resuming tips for more details.-e.<key>=<value>
Add the specified variable to execution environment.
-entry
Deprecated since version 24.10.0: Use params in the entry workflow to call different workflows from the command line.
Entry workflow to be executed.
-h, -help
Print the command usage.
-hub
(github
)Service hub where the project is hosted. Options:
gitlab
orbitbucket
-latest
Pull latest changes before run.
-lib
Library extension path.
-main-script
(main.nf
)New in version 20.09.1-edge.
The script file to be executed when launching a project directory or repository.
-name
Assign a mnemonic name to the a pipeline run.
-offline
Do not check for remote project updates.
-o, -output-dir
(results
)New in version 24.10.0.
Directory where workflow outputs are stored.
-params-file
Load script parameters from a JSON/YAML file.
-plugins
Comma separated list of plugin ids to be applied in the pipeline execution.
-preview
New in version 22.06.0-edge.
Run the workflow script skipping the execution of all processes.
-process.<key>=<value>
Set process config options.
-profile
Choose a configuration profile.
-qs, -queue-size
Max number of processes that can be executed in parallel by each executor.
-resume
Execute the script using the cached results, useful to continue executions that was stopped by an error.
-r, -revision
Revision of the project to run (either a git branch, tag or commit hash).
When passing a git tag or branch, the
workflow.revision
andworkflow.commitId
fields are populated. When passing only the commit hash,workflow.revision
is not defined.-stub-run, -stub
Execute the workflow replacing process scripts with command stubs
-test
Test a script function with the name specified.
-user
Private repository user name.
-with-apptainer
Enable process execution in an Apptainer container.
-with-charliecloud
Enable process execution in a Charliecloud container.
-with-cloudcache
Enable the use of the Cloud cache plugin for storing cache metadata to an object storage bucket.
-with-conda
Use the specified Conda environment package or file (must end with
.yml
or.yaml
)-with-dag
(dag-<timestamp>.html
)Create pipeline DAG file.
Changed in version 23.10.0: The default format was changed from
dot
tohtml
.-with-docker
Enable process execution in a Docker container.
-N, -with-notification
Send a notification email on workflow completion to the specified recipients.
-with-podman
Enable process execution in a Podman container.
-with-report
(report-<timestamp>.html
)Create workflow execution HTML report.
-with-singularity
Enable process execution in a Singularity container.
-with-spack
Use the specified Spack environment package or file (must end with
.yaml
)-with-timeline
(timeline-<timestamp>.html
)Create workflow execution timeline.
-with-tower
(https://api.cloud.seqera.io
)Monitor workflow execution with Seqera Platform (formerly Tower Cloud).
-with-trace
(trace-<timestamp>.txt
)Create workflow execution trace file.
-with-wave
(https://wave.seqera.io
)Enable the use of Wave containers.
-with-weblog
(http://localhost
)Send workflow status messages via HTTP to target URL.
-without-conda
Disable process execution with Conda.
-without-docker
Disable process execution with Docker.
-without-podman
Disable process execution in a Podman container.
-without-spack
Disable process execution with Spack.
-without-wave
Disable the use of Wave containers.
-w, -work-dir
(work
)Directory where intermediate result files are stored.
Examples
Run a specific revision of a remote pipeline.
$ nextflow run nextflow-io/hello -r v1.1 N E X T F L O W ~ version 20.07.1 Launching `nextflow-io/hello` [grave_cajal] - revision: 1c3e9e7404 [v1.1]
Choose a
profile
for running the project. Assumes that a profile nameddocker
has already been defined in the config file.$ nextflow run main.nf -profile docker
Execute a pipeline and generate the summary HTML report. For more information on the metrics, please refer the Reports section:
$ nextflow run main.nf -with-report
Execute a pipeline with a custom queue size. By default, the queue size is the number of available CPUs.
$ nextflow run nextflow-io/hello -qs 4
Invoke the pipeline with a specific workflow as the entry-point.
$ nextflow run main.nf -entry workflow_A
Execute a pipeline with integrated monitoring in Seqera Platform.
$ nextflow run nextflow-io/hello -with-tower
Execute a pipeline with a custom parameters file (YAML or JSON).
$ nextflow run main.nf -params-file pipeline_params.yml
For example, the following params file in YAML format:
alpha: 1 beta: 'foo'
Or in JSON format:
{ "alpha": 1, "beta": "foo" }
Is equivalent to the following command line:
$ nextflow run main.nf --alpha 1 --beta foo
The parameters specified with this mechanism are merged with the resolved configuration (base configuration and profiles). The values provided via a params file overwrite those of the same name in the Nextflow configuration file.
self-update
Update the nextflow runtime to the latest available version.
Usage
$ nextflow self-update
Description
The self-update
command directs the nextflow
CLI to update itself to the latest stable release.
Examples
Update Nextflow.
$ nextflow self-update
N E X T F L O W
version 20.07.1 build 5412
created 24-07-2020 15:18 UTC (20:48 IDT)
cite doi:10.1038/nbt.3820
http://nextflow.io
Nextflow installation completed. Please note:
- the executable file `nextflow` has been created in the folder: /usr/local/bin
view
View a project’s script file(s).
Usage
$ nextflow view [options] [project]
Description
The view
command is used to inspect the pipelines that are already stored in the global nextflow cache. For downloading a pipeline into the global cache ~/.nextflow/assets
, refer to the pull
command.
Options
-h, -help
Print the command usage.
-l
List repository content.
-q
Hide header line.
Examples
Viewing the contents of a downloaded pipeline.
$ nextflow view nextflow-io/hello
== content of file: .nextflow/assets/nextflow-io/hello/main.nf
#!/usr/bin/env nextflow
process sayHello {
input:
val x
output:
stdout
script:
"""
echo '$x world!'
"""
}
workflow {
Channel.of('Bonjour', 'Ciao', 'Hello', 'Hola') | sayHello | view
}
List the folder structure of the downloaded pipeline:
$ nextflow view -l nextflow-io/hello
== content of path: .nextflow/assets/nextflow-io/hello
LICENSE
README.md
nextflow.config
.gitignore
circle.yml
foo.nf
.git
.travis.yml
main.nf
View the contents of a downloaded pipeline without omitting the header:
$ nextflow view -q nextflow-io/hello
#!/usr/bin/env nextflow
process sayHello {
input:
val x
output:
stdout
script:
"""
echo '$x world!'
"""
}
workflow {
Channel.of('Bonjour', 'Ciao', 'Hello', 'Hola') | sayHello | view
}