kevin/ma

Fork 0

Files

Kevin Trogant 97cc9058d3 add nextflow d30e48d

2026-04-29 23:01:54 +02:00

44 KiB

Raw Blame History

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

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

$ 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

(cli-clean)=

`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

(cli-clone)=

`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

(cli-config)=

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

$ 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'
        }
    }
}

(cli-console)=

`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

(cli-drop)=

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

$ nextflow drop nextflow-io/hello

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

$ nextflow drop nextflow-io/hello -f

(cli-fs)=

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

:::{versionadded} 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 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]

(cli-inspect)=

`inspect`

:::{versionadded} 23.10.0 :::

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

(cli-kuberun)=

`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 {ref}k8s-page 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: :::{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.

$ nextflow kuberun nextflow-io/hello

(cli-launch)=

`launch`

:::{versionadded} 25.10.0 :::

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

$ 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

$ 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

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

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

:::

(cli-list)=

`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

(cli-log)=

`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

(cli-module)=

`module`

:::{versionadded} 26.04.0 :::

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

(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":

$ nextflow module search alignment

View information for a module:

$ nextflow module view nf-core/fastqc

Install a module:

$ nextflow module install nf-core/fastqc

List installed modules:

$ nextflow module list

Run a module:

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

$ nextflow module remove nf-core/fastqc

Create a module with a given name:

$ nextflow module create myorg/my-module

Generate a spec for a local module:

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

Validate a local module:

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

Publish a module to the Nextflow registry:

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

(cli-plugin)=

`plugin`

Manage plugins and run plugin-specific commands.

$ nextflow plugin <subcommand> [options]

create: :::{versionadded} 25.04.0 :::; Create a plugin scaffold using the Nextflow 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

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

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

(cli-run)=

`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} 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 (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, please refer the {ref}tracing-page 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
```
See {ref}cli-params for more information about writing custom parameters files.

(cli-secrets)=

`secrets`

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

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

(cli-view)=

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

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

44 KiB Raw Blame History

CLI reference

Options

Commands

auth

clean

clone

config

console

drop

fs

help

info

inspect

kuberun

launch

lineage

lint

list

log

module

plugin

pull

run

secrets

self-update

view

44 KiB

Raw Blame History

`auth`

`clean`

`clone`

`config`

`console`

`drop`

`fs`

`help`

`info`

`inspect`

`kuberun`

`launch`

`lineage`

`lint`

`list`

`log`

`module`

`plugin`

`pull`

`run`

`secrets`

`self-update`

`view`