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`

Comma-separated list of configuration files which are used as the configuration set. Any other default configuration files are ignored.

`-D`

Set JVM properties (e.g. -Dfile.encoding=UTF-8). Equivalent to the NXF_JVM_ARGS environment variable.

`-bg`

Execute Nextflow in background.

Allows you to close your terminal without terminating the pipeline run.

`-c, -config`

Comma-separated list of configuration files which are added to the configuration set.

`-d, -dockerize`

Deprecated in version 23.10

Launch Nextflow via Docker (experimental).

`-h`

Print available commands and options.

`-log`

Set Nextflow log file path (default: .nextflow.log). Must be a local path.

`-q, -quiet`

Do not print the Nextflow banner and execution progress to the console.

Does not affect error messages.

`-remote-debug`

Enable JVM interactive remote debugging (experimental).

`-syslog`

Send logs to a 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

`auth`

Added in version 25.10

Manage Seqera Platform authentication.

Usage

$ nextflow auth <subcommand> [options]

Description

The auth command provides authentication and configuration management for Seqera. For Seqera Cloud, it uses an OAuth2 authentication flow to generate and save a Personal Access Token (PAT) locally. For Seqera Enterprise installations, it uses direct PAT authentication. Credentials are saved to ~/.nextflow/seqera-auth.config. An includeConfig statement is automatically added to ~/.nextflow/config or the configuration file set using $NXF_HOME.

Options

`-h, -help`

Prints the command usage information.

Subcommands

`login`

Authenticates with Seqera and saves credentials. Sets Seqera primary compute environment, monitoring, and workspace.

Available options:

`-u, -url`

Specifies your Seqera API endpoint (default: https://api.cloud.seqera.io)

`logout`

Removes Seqera authentication and revokes the Seqera Cloud access token (if applicable).

`config`

Sets Seqera primary compute environment, monitoring, and workspace.

`status`

Shows Seqera authentication status and configuration.

Examples

Authenticate with Seqera Cloud:

$ nextflow auth login

Authenticate with an Enterprise installation:

$ nextflow auth login -u https://tower.example.com/api

View current authentication status:

$ nextflow auth status

Configure Seqera settings:

$ nextflow auth config

Remove authentication:

$ nextflow auth logout

`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 or bitbucket.

`-r` (`master`)

Revision to clone. It can be a git branch, tag, or commit SHA 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, see 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.

`-r, -revision`

Added in version 26.04

Project revision. Can be a git branch, tag, or commit SHA number.

`-a, -show-profiles`

Show all configuration profiles.

`-sort`

Sort config attributes.

`-value`

Added in version 23.10

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.

`-r, -revision`

Added in version 26.04

Project revision to drop. Can be a git branch, tag, or commit SHA number.

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>

Added in version 23.10

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, or yaml.

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/.repos/nextflow-io/hello
  main script : main.nf
  revisions   :
  * master (default)
    mybranch
    testing
  * v1.1 [t]
    v1.2 [t]

`inspect`

Added in version 23.10

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 or config.

`-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 hello

`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`

Specify number of CPUs requested for the Nextflow pod.

`-head-image`

Specify the container image for the Nextflow driver pod.

`-head-memory`

Specify amount of memory requested for the Nextflow pod.

`-head-prescript`

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. For example, my-pvc:/mnt/path.

Examples

Execute a pipeline into a Kubernetes cluster:

$ nextflow kuberun nextflow-io/hello

`launch`

Added in version 25.10

Launch a workflow in Seqera Platform.

Usage

$ nextflow launch [options] [project]

Description

The launch command launches a pipeline run in Seqera Platform. To log in and configure the execution environment, use the auth command.

Options

`-compute-env`

The compute environment for workflow execution.

`-c, -config`

A configuration file to add to the configuration set.

`-entry`

The entry workflow to be executed.

`-h, -help`

Prints command usage information.

`-latest`

Whether to pull the latest changes before execution.

`-name`

A mnemonic name to assign to the run.

`-main-script`

The script file to execute when launching a project directory or repository. Should be a path relative to the project root. For example, -main-script subproject/main.nf.

`-params-file`

A JSON or YAML file to load parameters from.

`-profile`

A configuration profile.

`-resume`

Whether to resume an execution using cached results from a previous run.

`-r, -revision`

The project revision to run. Can be a git branch, tag, or commit hash.

`-stub-run, -stub`

Whether to replace scripts with command stubs when executing the run.

`-user-secret`

Added in version 26.04

Name of user secret to use in the pipeline. Can be specified multiple times.

`-w, -work-dir`

The directory where intermediate result files are stored.

`-workspace`

The Seqera Platform workspace name.

`-workspace-secret`

Added in version 26.04

Name of workspace secret to use in the pipeline. Can be specified multiple times.

Examples

Execute a pipeline in Seqera Platform:

$ nextflow launch nextflow-io/hello

`lineage`

Added in version 25.04

warning

Experimental: may change in a future release.

Inspect lineage metadata for Nextflow runs.

Usage

$ nextflow lineage SUBCOMMAND [arg ..]

Description

The lineage command is used to inspect lineage metadata.

See Getting started with data lineage to learn how to get started with data lineage.

Options

`-h, -help`

Print the command usage.

Subcommands

`check <lid>`

Validate the checksum of output lineage record.

`diff <lid-1> <lid-2>`

Display a git-style diff between two lineage records.

`find <field-1>=<value-1> [<field-2>=<value-2> ...]`

Find all lineage records that match the given field values.

`list`

List the Nextflow runs with lineage enabled, printing the corresponding lineage ID (LID) for each run.

`render <lid> [path]`

Render the lineage graph for a lineage record as an HTML file (default output path: ./lineage.html).

The lineage record should be of type FileOutput, TaskRun, or WorkflowRun.

`view <lid>`

View a lineage record.

`lint`

Lint Nextflow scripts and config files.

Usage

$ nextflow lint [options] [paths]

Description

The lint command parses and analyzes the given Nextflow scripts and config files, formats them if specified, and prints any errors. Directories are recursively scanned for scripts and config files to lint.

Options

`-exclude`

File pattern to exclude from linting (default: .git, .lineage, .nextflow, .nf-test, nf-test.config, work).

Can be specified multiple times.

`-files-from`

Added in version 26.04

Read list of paths to lint from a text file. Use - to read from standard input.

`-format`

Format scripts and config files that have no errors.

`-o, -output`

Output mode for reporting errors: full, extended, concise, json, markdown (default: full).

`-project-dir`

Added in version 26.04

Path to project directory (default: '.'). Used to locate project-level assets such as the lib directory and modules directory.

`-sort-declarations`

Sort script declarations in Nextflow scripts (default: false).

`-spaces`

Number of spaces to indent (default: 4).

`-tabs`

Indent with tabs (default: false).

Examples

Lint a specific file:

$ nextflow lint main.nf

Lint all files in the current directory (and subdirectories) with concise output:

$ nextflow lint -o concise .

Lint and format all files in the current directory (and subdirectories) and use two spaces per indent:

$ nextflow lint -format -spaces 2 .

note

Formatting code with the lint command in Nextflow 25.10 or later may make your code incompatible with previous versions of Nextflow. If you need your code to remain compatible with versions prior to 25.10, run the formatter with Nextflow 25.04:

NXF_VER=25.04.8 nextflow lint -format .

`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.

The same fields as the trace.fields option can be specified here, as well as stdout and stderr. The trace fields %cpu and %mem must be specified as pcpu and pmem, respectively.

Use the -l option to see the complete list of available fields.

`-F, -filter`

Filter log entries by a custom expression, e.g. process =~ /hello.*/ && 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'

split_letters       0       1f/f1ea91       112ms
convert_to_upper    0       bf/334115       144ms
convert_to_upper    0       a3/06521d       139ms

Filter fields from the execution log of a process based on a criteria:

$ nextflow log tiny_leavitt -F 'process =~ /split_letters/'

work/1f/f1ea9158fb23b53d5083953121d6b6

`logfile`

Added in version 26.05.0-edge

Print the contents of a Nextflow log file, with optional level filtering and follow mode.

Usage

$ nextflow logfile [options] [run_name | session_id | path]

Description

The logfile command prints the contents of a .nextflow.log file written by Nextflow during a pipeline run. The argument can be:

A run name (e.g. kickass_rutherford) -- resolved via the local execution history and matched to the corresponding .nextflow.log[.N] file in the current directory by session id.
A session id (or unique prefix), or the literal last for the most recent run.
A direct path to a log file (e.g. .nextflow.log.4 or an absolute path).

If no argument is given, the most recent run is used.

Options

`-f, -follow`

Continuously print new lines as the file grows (similar to tail -f). Stop with Ctrl+C.

`-h, -help`

Print the command usage.

`-keep-ansi`

Preserve any ANSI escape sequences found inside log content. By default these are stripped so the output is clean text.

`-l, -level <LEVEL>`

Minimum log level to print: TRACE, DEBUG, INFO, WARN, or ERROR. Case-insensitive. When set, only entries at this level or higher are printed. Multi-line entries (e.g. stack traces) inherit the level of their parent entry. No filtering is applied by default.

`-n, -lines <N>`

Print only the last N log entries. Counts entries (one or more lines each), not raw lines.

`-no-pager`

Do not pipe the output through a pager. By default, when standard output is a terminal, the output is piped through $NXF_PAGER, falling back to $PAGER, falling back to less -FR. A bare less invocation is augmented with -FR so colors render. Short outputs exit without entering the pager. Pager is automatically disabled with -f/-follow.

`-no-ansi`

Disable colored output. By default, when the output destination is a terminal:

Every line is prefixed with a coloured 2-character level indicator.
TRACE and DEBUG entries are dimmed.
DEBUG, INFO, WARN and ERROR entries are syntax-highlighted to make them easier to read.

Styling is auto-disabled when output goes to a non-terminal destination (file or pipe with -no-pager) or when the NO_COLOR environment variable is set.

Examples

Print the log of the most recent run:

$ nextflow logfile

Print the log of a specific run, looked up by name:

$ nextflow logfile kickass_rutherford

Print a specific log file directly:

$ nextflow logfile .nextflow.log.4

Show only warnings and errors from the most recent run:

$ nextflow logfile -level WARN

Show the last 10 entries of an ongoing run and continue streaming new lines:

$ nextflow logfile -n 10 -f

`module`

Added in version 26.04

Manage Nextflow modules.

Usage

$ nextflow module <subcommand> [options]

Description

The module command provides a comprehensive system for managing registry-based modules. It enables installing modules from registries, running them directly, searching for available modules, and publishing your own modules to a registry.

Subcommands

`create [namespace/name]`

Create a new module with a basic main.nf, meta.yml, and README.md.

`install [options] [namespace/name]`

Install a module from the registry into your project. Downloaded modules are stored in the modules/ directory. The .module-info file is created in the module directory to store additional information of the installed module.

The following options are available:

`-version`

Specify the module version to install (e.g., 1.0.0). If not specified, installs the latest version.

`-force`

Force reinstall even if the module exists locally with modifications. Without this flag, Nextflow prevents overwriting locally modified modules.

`list [options]`

List all modules currently installed in your project. Shows each module's name, version, and integrity status (whether it has been modified locally).

The following options are available:

`-o, -output` (`table`)

Output mode for list results. Options: table (default), json.

`publish [options] [namespace/name | path]`

Publish a module to the registry, making it available for others to install. The argument can be either a namespace/name reference (for an already-installed module) or a local directory path containing the module files. Requires authentication via the NXF_REGISTRY_TOKEN environment variable or the registry.apiKey config option. The module directory must contain main.nf, meta.yml, and README.md.

The following options are available:

`-dry-run`

Validate the module structure and metadata without uploading to the registry. Useful for testing before publishing.

`-registry`

Specify the registry to publish the module (default: https://registry.nextflow.io)

`remove [options] [namespace/name]`

Remove a module from your project. By default, removes both local files and configuration entries. Use options to control what gets removed.

The following options are available:

`-force`

Force removal even if the module has no .module-info file (i.e. not installed from a registry) or has local modifications.

`-keep-files`

Remove the .module-info but keep local files in the modules/ directory.

`run [options] [namespace/name | path] [--<input_name> <input-value>]`

Execute a module directly. Can be a remote module (namespace/name) or a local module path (beginning with ./, ../, or /). Automatically downloads the module if not already installed.

Accepts all standard Nextflow run options. For example, -profile, -resume, and -c. Command-line params (i.e., --<input_name>) are inferred from the module's declared inputs.

The following additional options are available:

`-version`

Specify the module version to run (e.g., 1.0.0). If not specified, uses the latest version.

`search [options] [query]`

Search for modules in the registry by keyword or name. Returns modules matching the query with their names, versions, descriptions, and download statistics.

The following options are available:

`-limit`

Maximum number of results to return (default: varies by registry).

`-o, -output` (`simple`)

Output mode for search results. Options: simple (default), json.

`spec [options] <namespace/name or path>`

Generate the meta.yml for a local module from the source code (main.nf).

The generated file includes TODO placeholders for fields that were not specified.

If a spec file already exists, it is incorporated into the new file.

The following options are available:

`view [options] [namespace/name]`

Display detailed information about a module from the registry. Shows module name, version, description, and other metadata, as well as example usage.

The following options are available:

`-version`

Specify the module version to query (e.g., 1.0.0). If not specified, displays information for the latest version.

`-o, -output` (`text`)

Output mode for info results. Options: text (default), json.

`-namespace <namespace>`

Module namespace, used to construct the module name. Required when the argument is a path; ignored when it is a module name.

`-version <version>`

Module version string (e.g. 1.0.0). Defaults to TODO: Add version.

`-description <text>`

Short description of what the module does. Defaults to TODO: Add description.

`-license <identifier>`

SPDX license identifier (e.g. MIT, Apache-2.0). Defaults to TODO: Add license (e.g., MIT).

`-author <name>`

Module author. Can be specified multiple times, once per author. Defaults to [TODO: Add author].

`-dry-run`

Print the generated spec to stdout without writing any file.

`validate [options] <scope/name or path>`

Validate a module before publishing to the registry.

Verifies that all required files are present (main.nf, meta.yml, README.md) and that the module spec contains all required fields (name, version, description, license).

Examples

Install the latest module version:

$ nextflow module install nf-core/fastqc

Display installed modules in formatted table:

$ nextflow module list

Validate module structure without publishing:

$ nextflow module publish myorg/my-module -dry-run

Publish module to nextflow registry:

$ export NXF_REGISTRY_TOKEN=your-token
$ nextflow module publish myorg/my-module

Display information for latest module version:

$ nextflow module view nf-core/fastqc

Display information for specific version:

$ nextflow module view nf-core/fastqc -version 1.0.0

Create a module:

$ nextflow module create

Remove module completely:

$ nextflow module remove nf-core/fastqc

Run a remote module:

$ nextflow module run nf-core/fastqc \
    --input 'data/*.fastq.gz'

Run a remote module with specific version and run options:

$ nextflow module run nf-core/fastqc \
    -version 1.0.0 \
    --input 'data/*.fastq.gz' \
    -with-conda \
    -resume

Run a local module:

$ nextflow module run ./modules/nf-core/fastqc/main.nf \
      --input 'data/*.fastq.gz'

Search for alignment-related modules:

$ nextflow module search alignment

Generate spec for local module by name:

$ nextflow module spec nf-core/fastqc

Generate spec for local module by path (namespace required):

$ nextflow module spec -namespace nf-core ./modules/my-module

Provide additional fields to avoid TODO placeholders:

$ nextflow module spec \
    -namespace nf-core \
    -version 1.0.0 \
    -description "Quality control of raw sequencing reads" \
    -license MIT \
    -author "@drpatelh" \
    -author "@joseespinosa" \
    ./modules/nf-core/fastqc

Validate module by name:

$ nextflow module validate myorg/my-module

Validate module by path:

$ nextflow module validate ./modules/myorg/my-module

`plugin`

Manage plugins and run plugin-specific commands:

$ nextflow plugin <subcommand> [options]

Subcommands

`create`

Added in version 25.04

Create a plugin scaffold using the Nextflow plugin template. See Creating a plugin for more information.

`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

`-a, -all`

Update all downloaded projects.

`-d, -deep`

Deprecated in version 26.04

Ignored for new multi-revision asset management strategy. Still used in legacy assets.

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 or bitbucket

`-migrate`

Added in version 26.04

Update the project asset to new multi-revision strategy.

`-r, -revision`

Project revision to run. Can be a git branch, tag, or commit SHA number.

When passing a git tag or branch, the workflow.revision and workflow.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`

Deprecated in version 26.04

Ignored for new multi-revision asset management strategy. Still used in legacy assets.

Create a shallow clone of the specified depth.

`-disable-jobs-cancellation`

Prevent the cancellation of child jobs on execution termination

`-dsl1`

Deprecated in version 23.10

Execute the workflow using DSL1 syntax.

`-dsl2`

Deprecated in version 23.10

Execute the workflow using DSL2 syntax.

`-dump-channels`

Dump channels for debugging purpose. Optionally accepts a comma-separated list of channel tags to filter which channels are printed.

`-dump-hashes`

Dump task hash keys for debugging purposes.

Added in version 23.10

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 in version 24.10

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 or bitbucket

`-latest`

Pull latest changes before run.

`-lib`

Library extension path.

`-main-script` (`main.nf`)

The script file to execute when launching a project directory or repository. Should be a path relative to the project root. For example, -main-script subproject/main.nf.

The project nextflow.config is always read from the project root regardless of the main script location.

`-name`

Assign a mnemonic name to the a pipeline run.

`-offline`

Do not check for remote project updates.

`-o, -output-dir` (`results`)

Added in version 24.10

Directory where workflow outputs are stored.

#####-output-format

Added in version 26.04

Output format for printing workflow outputs. Options: text (default), json, none.

`-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`

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`

Project revision to run. Can be a git branch, tag, or commit SHA number.

When passing a git tag or branch, the workflow.revision and workflow.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

The default format was changed from dot to html.

`-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 named docker 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, see Reports:

$ 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

See Pipeline parameters for more information about writing custom parameters files.

`secrets`

Manage pipeline secrets.

Usage

$ nextflow secrets <subcommand> [options]

Options

`-h, -help`

Print the command usage.

Subcommands

`list`

List secrets available in the current store.

`get <secret>`

Retrieve a secret value.

`set <secret> <value>`

Create or update a secret.

`delete <secret>`

Delete a secret.

Examples

Set a secret:

$ nextflow secrets set FOO "Hello world"

List secrets:

$ nextflow secrets list

Get a secret:

$ nextflow secrets get FOO

Delete a secret:

$ nextflow secrets delete FOO

`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.

`-r, -revision`

Added in version 26.04

Project revision. Can be a git branch, tag, or commit SHA number.

Examples

Viewing the contents of a downloaded pipeline:

$ nextflow view nextflow-io/hello

== content of file: .nextflow/assets/.repos/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/.repos/nextflow-io/hello
.git
.gitignore
LICENSE
README.md
main.nf
nextflow.config

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
}

Help

Company

Options​

-C​

-D​

-bg​

-c, -config​

-d, -dockerize​

-h​

-log​

-q, -quiet​

-remote-debug​

-syslog​

-trace​

-v, -version​

Commands​

auth​

Usage​

Description​

Options​

-h, -help​

Subcommands​

login​

-u, -url​

logout​

config​

status​

Examples​

clean​

Usage​

Description​

Options​

-after​

-before​

-but​

-n, -dry-run​

-f, -force​

-h, -help​

-k, -keep-logs​

-q, -quiet​

Examples​

clone​

Usage​

Description​

Options​

-d, -deep​

-h, -help​

-hub (github)​

-r (master)​

-user​

Examples​

config​

Usage​

Description​

Options​

-flat​

-h, -help​

-profile​

-properties​

-r, -revision​

-a, -show-profiles​

-sort​

-value​

Examples​

console​

Usage​

Description​

Options​

Examples​

drop​

Usage​

Description​

Options​

-f​

-h, -help​

-r, -revision​

Examples​

fs​

Usage​

Description​

Options

`-C`

`-D`

`-bg`

`-c, -config`

`-d, -dockerize`

`-h`

`-log`

`-q, -quiet`

`-remote-debug`

`-syslog`

`-trace`

`-v, -version`

Commands

`auth`

Usage

Description

Options

`-h, -help`

Subcommands

`login`

`-u, -url`

`logout`

`config`

`status`

Examples

`clean`

Usage

Description

Options

`-after`

`-before`

`-but`

`-n, -dry-run`

`-f, -force`

`-h, -help`

`-k, -keep-logs`

`-q, -quiet`

Examples

`clone`

Usage

Description

Options

`-d, -deep`

`-h, -help`

`-hub` (`github`)

`-r` (`master`)

`-user`

Examples

`config`

Usage

Description

Options

`-flat`

`-h, -help`

`-profile`

`-properties`

`-r, -revision`

`-a, -show-profiles`

`-sort`

`-value`

Examples

`console`

Usage

Description

Options

Examples

`drop`

Usage

Description

Options

`-f`

`-h, -help`

`-r, -revision`

Examples

`fs`

Usage

Description

Options

`-h, -help`