(cli-reference)=

# CLI reference

This page lists all of the available options and subcommands for the {ref}`Nextflow CLI <cli-page>`.

(cli-options)=

## 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} 23.10.0
  :::
: 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](https://en.wikipedia.org/wiki/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

(cli-auth)=

### `auth`

:::{versionadded} 25.10.0
:::

Manage Seqera Platform authentication.

**Usage**

```console
$ 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.
: The following options are available:

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

```console
$ nextflow auth login
```

Authenticate with an Enterprise installation:

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

View current authentication status:

```console
$ nextflow auth status
```

Configure Seqera settings:

```console
$ nextflow auth config
```

Remove authentication:

```console
$ nextflow auth logout
```

(cli-clean)=

### `clean`

Clean up *cache* and *work* directories.

**Usage**

```console
$ 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`:

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

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

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

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

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

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

(cli-clone)=

### `clone`

Clone a remote project into a folder.

**Usage**

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

```console
$ nextflow clone nextflow-io/hello
nextflow-io/hello cloned to: hello
```

Clone a specific revision of a pipeline.

```console
$ nextflow clone nextflow-io/hello -r v1.1
nextflow-io/hello cloned to: hello
```

(cli-config)=

### `config`

Print the resolved pipeline configuration.

**Usage**

```console
$ 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 {ref}`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`
: :::{versionadded} 25.12.0-edge
  :::
: Project revision. Can be a git branch, tag, or commit SHA number.

`-a, -show-profiles`
: Show all configuration profiles.

`-sort`
: Sort config attributes.

`-value`
: :::{versionadded} 23.10.0
  :::
: 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.

```console
$ nextflow config

docker {
    enabled = true
}

process {
    executor = 'local'
}
```

Print out the config using a flat notation.

```console
$ nextflow config -flat

docker.enabled = true
process.executor = 'local'
```

Print out the config using the Java properties notation.

```console
$ nextflow config -properties

docker.enabled = true
process.executor = local
```

Print out the value of a specific configuration property.

```console
$ nextflow config -value process.executor
local
```

Print out all profiles from the project's configuration.

```console
$ nextflow config -show-profiles

docker {
    enabled = true
}

profiles {
    standard {
        process {
            executor = 'local'
        }
    }
    cloud {
        process {
            executor = 'cirrus'
            container = 'cbcrg/imagex'
        }
    }
}
```

(cli-console)=

### `console`

Launch the Nextflow interactive console.

**Usage**

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

```console
$ nextflow console
```

(cli-drop)=

### `drop`

Delete the local copy of a project.

**Usage**

```console
$ 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`
: :::{versionadded} 25.12.0-edge
:::
: Project revision to drop. Can be a git branch, tag, or commit SHA number.

**Examples**

Drop the `nextflow-io/hello` project.

```console
$ nextflow drop nextflow-io/hello
```

Forcefully drop the `nextflow-io/hello` pipeline, ignoring any local changes.

```console
$ nextflow drop nextflow-io/hello -f
```

(cli-fs)=

### `fs`

Perform basic filesystem operations.

**Usage**

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

```console
$ nextflow fs list <directory>
```

Print the contents of a file to standard output.

```console
$ nextflow fs cat <file>
```

Copy a file or directory.

```console
$ nextflow fs cp <source> <target>
```

Move a file or directory.

```console
$ nextflow fs mv <source> <target>
```

Delete a file or directory.

```console
$ nextflow fs rm <path>
```

:::{versionadded} 23.10.0
:::

Print file or directory attributes.

```console
$ nextflow fs stat <path>
```

### `help`

Print the top-level help or specific help for a command.

**Usage**

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

```console
$ 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**

```console
$ 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:

```console
$ 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:

```console
$ 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]
```

(cli-inspect)=

### `inspect`

:::{versionadded} 23.10.0
:::

Inspect process settings in a pipeline project. Currently only supports the `container` directive.

**Usage**

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

```console
$ nextflow inspect nextflow-io/hello
```

Specify parameters as with the `run` command:

```console
$ nextflow inspect main.nf --alpha 1 --beta hello
```

(cli-kuberun)=

### `kuberun`

Launch a Nextflow pipeline on a Kubernetes cluster.

**Usage**

```console
$ 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 {ref}`k8s-page` for more information.

**Options**

The `kuberun` command supports the following options from [`run`](#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`
: :::{versionadded} 22.10.0
  :::
: Specify the container image for the Nextflow driver pod.

`-head-memory`
: Specify amount of memory requested for the Nextflow pod.

`-head-prescript`
: :::{versionadded} 22.10.0
  :::
: 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.

```console
$ nextflow kuberun nextflow-io/hello
```

(cli-launch)=

### `launch`

:::{versionadded} 25.10.0
:::

Launch a workflow in [Seqera Platform](https://seqera.io/platform/).

**Usage**

```console
$ 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`](#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, e.g. `-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`
: :::{versionadded} 26.04.0
  :::
: 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`
: :::{versionadded} 26.04.0
  :::
: Name of workspace secret to use in the pipeline.
: Can be specified multiple times.

**Examples**

Execute a pipeline in Seqera Platform.

```console
$ nextflow launch nextflow-io/hello
```

(cli-lineage)=

### `lineage`

:::{versionadded} 25.04.0
:::

:::{warning} *Experimental: may change in a future release.*
:::

Inspect lineage metadata for Nextflow runs.

**Usage**

```console
$ nextflow lineage SUBCOMMAND [arg ..]
```

**Description**

The `lineage` command is used to inspect lineage metadata.

See the {ref}`data-lineage-page` guide 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.

(cli-lint)=

### `lint`

Lint Nextflow scripts and config files.

**Usage**

```console
$ 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`
: :::{versionadded} 26.04.0
  :::
: 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`
: :::{versionadded} 26.04.0
  :::
: 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.

```console
$ nextflow lint main.nf
```

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

```console
$ nextflow lint -o concise .
```

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

```console
$ 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:

```bash
NXF_VER=25.04.8 nextflow lint -format .
```
:::

(cli-list)=

### `list`

List all downloaded projects.

**Usage**

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

```console
$ nextflow list

nextflow-io/hello
nextflow-hub/fastqc
```

(cli-log)=

### `log`

Print the execution history and log information.

**Usage**

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

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

```console
$ nextflow log -quiet

focused_payne
tiny_leavitt
boring_euler
```

List the execution entries *only* a specific execution.

```console
$ nextflow log tiny_leavitt

work/1f/f1ea9158fb23b53d5083953121d6b6
work/bf/334115deec60929dc18edf0010032a
work/a3/06521d75da296d4dd7f4f8caaddad8
```

List the execution entries *after* a specific execution.

```console
$ nextflow log -after tiny_leavitt

work/92/c1a9cd9a96e0531d81ca69f5dc3bb7
work/3f/70944c7a549b6221e1ccc7b4b21b62
work/0e/2ebdba85f76f6068b21a1bcbf10cab
```

List the execution entries *before* a specific execution.

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

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

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

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

work/1f/f1ea9158fb23b53d5083953121d6b6
```

(cli-module)=

### `module`

:::{versionadded} 26.04.0
:::

Manage Nextflow modules.

**Usage**

```console
$ 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**

(cli-module-create)=

`create [namespace/name]`

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

(cli-module-install)=

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

(cli-module-list)=

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

(cli-module-publish)=

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

(cli-module-remove)=

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

(cli-module-run)=

`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, including `-profile`, `-resume`, `-c`, etc. 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.

(cli-module-search)=

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

(cli-module-spec)=

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

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

(cli-module-validate)=

`validate [options] <namespace/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).

(cli-module-view)=

`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 format. Options: `text` (default), `json`.

**Examples**

Search for modules related to "alignment":

```console
$ nextflow module search alignment
```

View information for a module:

```console
$ nextflow module view nf-core/fastqc
```

Install a module:

```console
$ nextflow module install nf-core/fastqc
```

List installed modules:

```console
$ nextflow module list
```

Run a module:

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

Run a local module:

```console
$ nextflow module run ./modules/local/fastqc/main.nf \
    --input 'data/*.fastq.gz' \
    -with-docker
```

Remove a module:

```console
$ nextflow module remove nf-core/fastqc
```

Create a module with a given name:

```console
$ nextflow module create myorg/my-module
```

Generate a spec for a local module:

```console
$ nextflow module spec -namespace myorg ./modules/myorg/my-module
```

Validate a local module:

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

Publish a module to the Nextflow registry:

```console
$ export NXF_REGISTRY_TOKEN=<token>
$ nextflow module publish myorg/my-module
```

(cli-plugin)=

### `plugin`

Manage plugins and run plugin-specific commands.

```console
$ nextflow plugin <subcommand> [options]
```

`create`

: :::{versionadded} 25.04.0
  :::
: Create a plugin scaffold using the [Nextflow plugin template](https://github.com/nextflow-io/nf-plugin-template/). See {ref}`gradle-plugin-create` 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.

(cli-pull)=

### `pull`

Download or update a project.

**Usage**

```console
$ 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} 25.12.0-edge
  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`
:::{versionadded} 25.12.0-edge
  :::
: 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.

```console
$ nextflow pull nextflow-io/hello

Checking nextflow-io/hello ...
done - revision: 96eb04d6a4 [master]
```

Pull the latest revision for all downloaded projects.

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

```console
$ nextflow pull nextflow-io/hello -r v1.1

Checking nextflow-io/hello ...
checkout-out at AnyObjectId[1c3e9e7404127514d69369cd87f8036830f5cf64] - revision: 1c3e9e7404 [v1.1]
```

(cli-run)=

### `run`

Execute a pipeline.

**Usage**

```console
$ 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} 25.12.0-edge
  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} 23.10.0
  :::
: Execute the workflow using DSL1 syntax.

`-dsl2`
: :::{deprecated} 23.10.0
  :::
: Execute the workflow using DSL2 syntax.

`-dump-channels`
: Dump channels for debugging purpose.
: Optionally accepts a comma-separated list of tags to filter output to only channels with a matching tag.

`-dump-hashes`
: Dump task hash keys for debugging purposes.
: :::{versionadded} 23.10.0
  You can use `-dump-hashes json` to dump the task hash keys as JSON for easier post-processing. See the {ref}`caching and resuming tips <cache-compare-hashes>` for more details.
  :::

`-e.<key>=<value>`
: Add the specified variable to execution environment.

`-entry`
: :::{deprecated} 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` 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, e.g. `-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`)
: :::{versionadded} 24.10.0
  :::
: Directory where workflow outputs are stored.

`-output-format`
: :::{versionadded} 26.04.0
  :::
: 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`
: :::{versionadded} 22.10.0
  :::
: 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.
: :::{versionchanged} 23.10.0
  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](https://seqera.io/) (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.

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

  ```console
  $ nextflow run main.nf -profile docker
  ```

- Execute a pipeline and generate the summary HTML report. For more information on the metrics, please refer the {ref}`tracing-page` section:

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

  ```console
  $ nextflow run nextflow-io/hello -qs 4
  ```

- Invoke the pipeline with a specific workflow as the entry-point.

  ```console
  $ nextflow run main.nf -entry workflow_A
  ```

- Execute a pipeline with integrated monitoring in [Seqera Platform](https://seqera.io).

  ```console
  $ nextflow run nextflow-io/hello -with-tower
  ```

- Execute a pipeline with a custom parameters file (YAML or JSON).

  ```console
  $ nextflow run main.nf -params-file pipeline_params.yml
  ```

  See {ref}`cli-params` for more information about writing custom parameters files.

(cli-secrets)=

### `secrets`

Manage {ref}`pipeline secrets <secrets-page>`.

**Usage**

```console
$ 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:

```console
$ nextflow secrets set FOO "Hello world"
```

List secrets:

```console
$ nextflow secrets list
```

Get a secret:

```console
$ nextflow secrets get FOO
```

Delete a secret:

```console
$ nextflow secrets delete FOO
```

### `self-update`

Update the nextflow runtime to the latest available version.

**Usage**

```console
$ nextflow self-update
```

**Description**

The `self-update` command directs the `nextflow` CLI to update itself to the latest stable release.

**Examples**

Update Nextflow:

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

(cli-view)=

### `view`

View a project's script file(s).

**Usage**

```console
$ 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`
: :::{versionadded} 25.12.0-edge
  :::
: Project revision. Can be a git branch, tag, or commit SHA number.

**Examples**

View the contents of a downloaded pipeline:

```console
$ 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:

```console
$ 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:

```console
$ 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
}
```
