Command line interface

Nextflow provides a robust command line interface (CLI) for the management and execution of pipelines. This page explains the key concepts and common usage patterns for the CLI.

For the complete reference of all commands, subcommands, and options, see CLI reference.

Note

Nextflow uses two types of command line flags:

  • Nextflow options use a single dash (e.g., -log) and modify Nextflow’s behavior.

  • Pipeline parameters use a double dash (e.g., --input) and are passed to your pipeline script.

Options

Nextflow options control how Nextflow itself operates. Use them to configure execution behavior, manage logging, override configurations, and get information about Nextflow.

Soft configuration override

The -c option adds your configuration on top of the defaults and merges them together.

Use this when you want to override specific settings while keeping other defaults intact. Multiple configuration files can be specified as a comma separated list.

$ nextflow -c my.config run nextflow-io/hello

See Configuration for more information.

Hard configuration override

The -C option replaces all default configuration with your custom configuration files. Multiple configuration files can be specified as a comma separated list.

Use this when you want to ensure no default configurations interfere with your custom settings. Unlike -c which merges configurations, -C ensures only your specified file is used.

$ nextflow -C my.config run nextflow-io/hello

See Configuration for more information.

Background execution

The -bg option launches Nextflow as a background process and frees your terminal for other work.

Use this for long-running pipelines when you need to continue using your terminal or want to disconnect without stopping execution. It works like nohup, allowing you to close your terminal without stopping the pipeline.

$ nextflow -bg run nextflow-io/hello

Quiet mode

The -q option suppresses the Nextflow banner and execution progress output.

Use this to keep your terminal output clean. It hides the ASCII banner and task progress but doesn’t affect pipeline println statements or error messages.

$ nextflow -q run nextflow-io/hello

Custom log file path

The -log option directs Nextflow logs to a specific file instead of the default .nextflow.log.

Use this for organizing logs by project, integrating with logging systems, or storing logs in centralized locations.

$ nextflow -log /var/log/nextflow.log run nextflow-io/hello

Syslog integration

The -syslog option sends logs to a Syslog server for centralized log management.

Use this to aggregate Nextflow logs with other system logs to enable centralized monitoring and analysis.

$ nextflow -syslog localhost:1234 run nextflow-io/hello

JVM properties

The -D option sets Java system properties that control the JVM running Nextflow.

Use this for configuring memory, encoding, or other Java-level behavior. You can specify multiple properties by using -D multiple times.

$ nextflow -Dfile.encoding=UTF-8 run nextflow-io/hello

See Environment variables for more information.

Help display

The -h option shows available commands and global options.

Use this to discover available commands or refresh your memory about command syntax.

$ nextflow -h

Version information

The -v and -version options prints Nextflow version information.

Use -v for minimal output showing version and build number.

$ nextflow -v
nextflow version 24.04.0.5917

Use -version for detailed output showing creation date, citation, and website.

$ nextflow -version
N E X T F L O W
version 24.04.0 build 5917
created 03-05-2024 15:07 UTC
cite doi:10.1038/nbt.3820
http://nextflow.io

Pipeline execution

Pipeline execution is the core function of Nextflow. These commands run Nextflow workflows, either from local files or remote Git repositories. Nextflow handles downloading, caching, and executing pipelines with minimal user intervention.

Launching a project

The run command executes pipeline scripts from local files or remote repositories. It automatically manages repository downloads, caching, and execution, supporting various Git providers and authentication methods.

See run for more information.

Local pipelines

Run a pipeline from your local filesystem:

$ nextflow run main.nf

Remote pipelines

Use the format <organization>/<repository> to run a pipeline from directly from Git repositories:

$ nextflow run nextflow-io/hello

Nextflow automatically:

  1. Downloads the repository to $HOME/.nextflow/assets/

  2. Caches it for future runs

  3. Executes the main script

If you omit the organization, Nextflow searches cached pipelines first, then attempts to download from the NXF_ORG organization (default: nextflow-io).

You can also use full repository URLs:

$ nextflow run https://github.com/nextflow-io/hello

Private repositories

Use the -user option to add credentials for private repositories:

$ nextflow run organization/private-repo -user my-username

Alternatively, configure Git authentication. See Git configuration for more information.

Non-GitHub providers

Use the -hub option specify Bitbucket, GitLab, or other Git providers:

$ nextflow run organization/repo -hub bitbucket

Revision selection

Use the -r option to specify Git branches, tags, or commits:

$ nextflow run nextflow-io/hello -r v1.1
$ nextflow run nextflow-io/hello -r dev-branch
$ nextflow run nextflow-io/hello -r a3f5c8e

Pipeline parameters

Pipeline parameters are values defined with params in your script. Override them on the command line using the -- prefix to customize pipeline behavior without modifying code.

$ nextflow run main.nf --input data.csv --output results

Parameter names support automatic conversion between kebab-case and camelCase:

$ nextflow run main.nf --input-file data.csv  # Becomes params.inputFile

Parameters without values are set to true:

$ nextflow run main.nf --verbose  # params.verbose = true

Warning

Quote parameters containing wildcards to prevent shell expansion:

$ nextflow run main.nf --files "*.fasta"

Parameter files

For complex parameter sets, use YAML or JSON files with -params-file. This is cleaner than long command lines.

{
  "input": "data.csv",
  "output": "results/",
  "min_quality": 20
}

$ nextflow run main.nf -params-file params.yml

Parameter precedence

Nextflow applies parameters defined in multiple places in the following order (lowest to highest priority):

  1. Pipeline script defaults (params.foo = 'default')

  2. Configuration files (see Parameters)

  3. Parameter files (-params-file)

  4. Command line parameters (--foo bar)

Kubernetes execution

The kuberun command executes pipelines entirely within a Kubernetes cluster. This experimental feature runs the Nextflow driver itself inside Kubernetes.

Use this when you want both the Nextflow driver and tasks running in Kubernetes. This differs from using the Kubernetes executor with run, where only tasks run in Kubernetes while the driver runs externally.

$ nextflow kuberun nextflow-io/hello

See kuberun for more information.

Project management

Project management commands interact with Git-hosted pipelines. Nextflow integrates with Git providers (e.g., GitHub, GitLab, and Bitbucket) to treat pipelines as versioned projects and maintains a local cache in $HOME/.nextflow/assets/.

Use these commands to explore available pipelines, inspect their code, maintain your cache, and clone projects.

Listing downloaded projects

The list command shows all pipelines currently downloaded to your local cache. This helps you track which projects are available offline and manage your cache directory. Pipelines are stored in $HOME/.nextflow/assets/ by default.

$ nextflow list

Showing project information

The info command displays detailed metadata about a downloaded project, including its repository location, local path, main script, and available revisions.

Use this to understand a project’s structure, see available versions, or verify which revision is currently checked out.

$ nextflow info hello
project name: nextflow-io/hello
repository  : https://github.com/nextflow-io/hello
local path  : $HOME/.nextflow/assets/nextflow-io/hello
main script : main.nf
revisions   :
* master (default)
  mybranch
  v1.1 [t]
  v1.2 [t]

This shows:

  • The full project name and repository URL

  • Where it’s cached locally

  • Which script runs by default

  • Available revisions (branches and tags marked with [t])

  • Which revision is currently checked out (marked with *)

Pulling or updating projects

The pull command downloads a pipeline or updates an existing one to the latest version from its Git repository.

Use this to manually download pipelines before running them, update cached pipelines, or download pipelines for offline use.

$ nextflow pull nextflow-io/hello

You can specify a particular revision to download.

$ nextflow pull nextflow-io/hello -r mybranch

See pull for more information.

Viewing project code

The view command displays the contents of a pipeline’s main script or lists all files in the repository.

Use this to quickly inspect pipeline code without opening files or explore the project structure. The -l option lists all repository files instead of showing script contents.

$ nextflow view nextflow-io/hello
$ nextflow view nextflow-io/hello -l

See view for more information.

Cloning projects locally

The clone command copies a pipeline from the cache to a local directory and creates a full Git repository you can modify.

Use this when you want to modify an existing pipeline, create a derivative pipeline, or study a pipeline’s structure. If you omit the target directory it uses the pipeline name.

$ nextflow clone nextflow-io/hello my-hello

See clone for more information.

Deleting cached projects

The drop command removes a downloaded pipeline from the local cache.

Use this to free disk space by removing pipelines you no longer need. The project is deleted from $HOME/.nextflow/assets/. The next run will download it again if needed.

$ nextflow drop nextflow-io/hello

See drop for more information.

Secret management

The secrets command manages secure pipeline secrets.

Use this to store credentials securely, reference them in pipelines without exposing values, and manage sensitive data centrally across your organization.

$ nextflow secrets list
$ nextflow secrets set AWS_ACCESS_KEY_ID
$ nextflow secrets delete AWS_ACCESS_KEY_ID

See secrets for more information.

Configuration and validation

Configuration and validation commands help you understand and verify pipeline settings before execution. These commands inspect how Nextflow interprets your configuration files, process definitions, and scripts.

Use these commands during development to debug configuration issues, verify settings, and catch issues.

Configuration inspection

The config command prints the resolved configuration for a pipeline.

Use this to debug configuration issues, verify which settings will be applied, understand configuration precedence, or inspect specific configuration properties.

$ nextflow config
$ nextflow config nextflow-io/hello

See config for more information.

Process inspection

New in version 23.09.0-edge.

The inspect command analyzes process settings in a pipeline without executing it. It outputs container information in JSON or Nextflow configuration format.

Use this to determine which container images will be used by each process before running the pipeline.

$ nextflow inspect nextflow-io/hello
$ nextflow inspect nextflow-io/hello -format json

See inspect for more information.

Script validation

The lint command analyzes Nextflow scripts and configuration files for syntax errors and code issues. It can also automatically format your code to maintain consistent style across your project.

Use this to catch syntax errors before execution, enforce consistent code formatting, or validate entire directories of Nextflow code.

$ nextflow lint main.nf

See lint for more information.

Execution history

Execution history and maintenance commands manage past runs and clean up cached files. Nextflow maintains metadata about all executions and stores intermediate files in work directories.

Use these commands to review past executions, free disk space, troubleshoot failures, or explore data lineage.

Execution logs

The log command displays execution history and details about past pipeline runs, such as run names, timestamps, and customizable output fields.

Use this to find run names for resuming, review execution history, or debug failed runs. The command shows recent executions by default, with options to view specific runs or customize output fields.

$ nextflow log
$ nextflow log dreamy_euler
$ nextflow log last -f name,status,duration

See log for more information.

Work directory cleanup

The clean command removes work directories and cached intermediate files from past executions.

Use this to free disk space, clean up failed or test runs, or maintain your work directory. Use -n to perform a dry run and show what would be deleted. Use -f to delete files.

$ nextflow clean -n
$ nextflow clean dreamy_euler -f

See clean for more information.

Data lineage

New in version 25.04.0.

Warning

Experimental: may change in a future release.

The lineage command explores data lineage and provenance for workflow executions and tracks relationships between inputs, outputs, and processing steps.

Use this to understand input/output relationships between tasks, trace data flow through the pipeline, or establish file provenance. Lineage tracking must be enabled in configuration.

$ nextflow lineage

See Getting started with data lineage to get started and lineage for more information.

Seqera Platform

Seqera Platform is a comprehensive workflow orchestration platform that extends Nextflow with features for workflow management, monitoring, and collaboration.

Use these commands to authenticate with Seqera Platform and launch workflows directly to the Platform’s managed infrastructure.

Platform authentication

New in version 25.10.0.

The auth command manages authentication credentials for Seqera Platform, saving access tokens for API interactions.

Use this to log in or out of the Platform, establishing or removing your authentication credentials.

$ nextflow auth login

Additional authentication operations include checking login status, viewing configuration details, and logging out:

$ nextflow auth status
$ nextflow auth config
$ nextflow auth logout

See auth for more information.

Platform workflow submission

New in version 25.10.0.

The launch command submits a workflow to run on Seqera Platform’s infrastructure instead of your local machine.

Use this to leverage Platform’s cloud resources, monitoring capabilities, and execution management. The Platform handles resource provisioning, execution monitoring, and result storage.

$ nextflow launch nextflow-io/hello

See launch for more information.

System utilities

System utilities provide administrative and development tools for managing Nextflow itself, interacting with remote filesystems, working with plugins, and debugging.

Use these commands for system administration, development, and testing.

Interactive console

The console command launches an interactive Groovy console with Nextflow’s execution context loaded.

Use this to test Nextflow DSL code interactively, debug expressions, explore Nextflow’s APIs, or experiment with syntax. It opens a GUI or REPL depending on your environment.

$ nextflow console

Remote filesystem operations

The fs command performs filesystem operations on remote storage systems supported by Nextflow, such as S3, Google Cloud Storage, and Azure Blob Storage.

Use this to manage remote data, test cloud storage access, or perform bulk file operations without additional tools.

$ nextflow fs list s3://my-bucket/data/
$ nextflow fs cat s3://my-bucket/data/file.txt
$ nextflow fs cp s3://my-bucket/data/file.txt s3://dest/
$ nextflow fs delete s3://my-bucket/data/file.txt

See fs for more information.

Plugins

The plugin command creates plugins, installs them, and executes plugin-specific operations.

See plugin for more information.

Plugin creation

New in version 25.04.0.

Use the create subcommand to create a new plugin scaffold for development:

$ nextflow plugin create

Plugin installation

Use the install subcommand to install a plugin and extend Nextflow functionality:

$ nextflow plugin install my-plugin

Plugin execution

Use the the format plugin-name:command to execute plugin-specific commands:

$ nextflow plugin my-plugin:hello --alpha --beta

See individual plugin documentation for plugin specific commands.

Nextflow updates

The self-update command updates Nextflow to a newer version. It downloads and installs the latest release or a specific version.

Use this to upgrade Nextflow, switch versions, or install edge releases. By default, it updates to the latest stable release. You can specify a particular version or use the NXF_EDGE environment variable for development releases.

$ nextflow self-update
$ NXF_EDGE=1 nextflow self-update

Command help

The help command displays detailed usage information for any Nextflow command.

Use this to learn about command-specific options, refresh your memory about syntax, or discover available features for a particular command.

$ nextflow help run
$ nextflow help clean