---
title: Command line interface
description: Use the Nextflow CLI to manage and execute pipelines from local files or remote repositories.
toc_max_heading_level: 3
---

# 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][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.
:::

## 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][cli-run] for more information.

#### Local pipelines

Run a pipeline from your local filesystem:

```bash
nextflow run main.nf
```

#### Remote pipelines

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

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

```bash
nextflow run https://github.com/nextflow-io/hello
```

#### Private repositories

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

```bash
nextflow run organization/private-repo -user my-username
```

Alternatively, configure Git authentication. See [Git configuration][git-page] for more information.

#### Non-GitHub providers

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

```bash
nextflow run organization/repo -hub bitbucket
```

#### Revision selection

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

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

<AddedInVersion version="26.04" />

Nextflow downloads and stores each explicitly requested Git branch, tag, or commit ID in a separate directory path, enabling you to run multiple revisions of the same pipeline simultaneously. Downloaded revisions are stored in a subdirectory of the local project: `$NXF_ASSETS/.repos/<org>/<repo>/clones/<commitId>`.

:::tip
Use tags or commit IDs instead of branches for reproducible pipeline runs. Branch references change as development progresses over time.
:::

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

```bash
nextflow run main.nf --input data.csv --output results
```

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

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

Parameters without values are set to `true`:

```bash
nextflow run main.nf --verbose  # params.verbose = true
```

:::warning
Quote parameters containing wildcards to prevent shell expansion:

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

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

```bash
nextflow run main.nf -params-file params.json
```

**Parameter precedence**

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

1. Script parameters (`params.foo = 'default'`)
2. Configuration parameters (see [Parameters][config-params] for more information)
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:

```bash
nextflow kuberun nextflow-io/hello
```

See [kuberun][cli-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:

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

```bash
nextflow info hello
```

This prints an output similar to the following:

```bash
project name: nextflow-io/hello
repository  : https://github.com/nextflow-io/hello
local path  : $HOME/.nextflow/assets/.repos/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 revisions are 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:

```bash
nextflow pull nextflow-io/hello
```

You can specify a particular revision to download:

```bash
nextflow pull nextflow-io/hello -r mybranch
```

See [pull][cli-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. Specify `-l` option lists all repository files instead of showing script contents:

```bash
nextflow view nextflow-io/hello
nextflow view nextflow-io/hello -l
```

See [view][cli-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:

```bash
nextflow clone nextflow-io/hello my-hello
```

See [clone][cli-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:

```bash
nextflow drop nextflow-io/hello
```

See [drop][cli-drop] for more information.

## Module management

<AddedInVersion version="26.04" />

The `module` command allows you to discover, install, and run modules through a centralized module registry. See [Using modules][using-modules-page] and the [`module`][cli-module] command reference for more information.

## Configuration and validation

Configuration and validation options and commands help you control and verify pipeline settings. Configuration options supplement pipeline configuration at runtime, while validation commands inspect how Nextflow interprets your configuration files, process definitions, and scripts.

Use these to customize pipeline configuration, debug configuration issues, verify settings, and catch issues before execution.

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

```bash
nextflow -c my.config run nextflow-io/hello
```

See [Configuration][config-page] 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:

```bash
nextflow -C my.config run nextflow-io/hello
```

See [Configuration][config-page] for more information.

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

```bash
nextflow config
nextflow config nextflow-io/hello
```

See [config][cli-config] for more information.

### Process inspection

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:

```bash
nextflow inspect nextflow-io/hello
nextflow inspect nextflow-io/hello -format json
```

See [inspect][cli-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:

```bash
nextflow lint main.nf
```

See [lint][cli-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:

```bash
nextflow log
nextflow log dreamy_euler
nextflow log last -f name,status,duration
```

See [log][cli-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:

```bash
nextflow clean -n
nextflow clean dreamy_euler -f
```

See [clean][cli-clean] for more information.

### Data lineage

<AddedInVersion version="25.04" />

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

```bash
nextflow lineage
```

See [Getting started with data lineage][data-lineage-page] to get started and [lineage][cli-lineage] for more information.

## Seqera Platform

[Seqera Platform](https://seqera.io) 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

<AddedInVersion version="25.10" />

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:

```bash
nextflow auth login
```

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

```bash
nextflow auth status
nextflow auth config
nextflow auth logout
```

See [auth][cli-auth] for more information.

### Platform workflow submission

<AddedInVersion version="25.10" />

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:

```bash
nextflow launch nextflow-io/hello
```

See [launch][cli-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:

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

```bash
nextflow fs ls '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 rm s3://my-bucket/data/file.txt
```

See [fs][cli-fs] for more information.

### Plugins

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

See [plugin][cli-plugin] for more information.

**Plugin creation**

<AddedInVersion version="25.04" />

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

```bash
nextflow plugin create
```

**Plugin installation**

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

```bash
nextflow plugin install my-plugin
```

**Plugin execution**

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

```bash
nextflow plugin my-plugin:hello --alpha --beta
```

See individual plugin documentation for plugin specific commands.

### Secrets

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:

```bash
nextflow secrets list
nextflow secrets set AWS_ACCESS_KEY_ID
nextflow secrets delete AWS_ACCESS_KEY_ID
```

See [secrets][cli-secrets] for more information.

### Nextflow updates

The `self-update` command updates Nextflow to a newer version.  It downloads and installs the latest release or a specific version. By default, it updates to the latest stable release:

```bash
nextflow self-update
```

Specify a version or use the `NXF_EDGE` environment variable for development releases:

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

```bash
nextflow help run
```

### Version information

The `-v` and `-version` options print Nextflow version information.

Use `-v` for minimal output showing version and build number:

```bash
nextflow -v
```

You will see output similar to the following:

```console
nextflow version 24.04.0.5917
```

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

```bash
nextflow -version
```

You will see output similar to the following:

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

[cli-auth]: ./reference/cli/auth
[cli-clean]: ./reference/cli/clean
[cli-clone]: ./reference/cli/clone
[cli-config]: ./reference/cli/config
[cli-drop]: ./reference/cli/drop
[cli-fs]: ./reference/cli/fs
[cli-inspect]: ./reference/cli/inspect
[cli-kuberun]: ./reference/cli/kuberun
[cli-launch]: ./reference/cli/launch
[cli-lineage]: ./reference/cli/lineage
[cli-lint]: ./reference/cli/lint
[cli-log]: ./reference/cli/log
[cli-module]: ./reference/cli/module
[cli-module-install]: ./reference/cli/module#module-install
[cli-module-list]: ./reference/cli/module#module-list
[cli-module-view]: ./reference/cli/module#module-view
[cli-module-run]: ./reference/cli/module#module-run
[cli-module-spec]: ./reference/cli/module#module-spec
[cli-module-validate]: ./reference/cli/module#module-validate
[cli-module-remove]: ./reference/cli/module#module-remove
[cli-module-publish]: ./reference/cli/module#module-publish
[cli-module-search]: ./reference/cli/module#module-search
[cli-params]: ./cli#pipeline-parameters
[cli-plugin]: ./reference/cli/plugin
[cli-pull]: ./reference/cli/pull
[cli-reference]: ./reference/cli
[cli-run]: ./reference/cli/run
[cli-secrets]: ./reference/cli/secrets
[cli-view]: ./reference/cli/view
[config-constants]: ./config#constants-and-functions
[config-env-vars]: ./reference/env-vars
[config-page]: ./config
[config-params]: ./config#parameters
[data-lineage-page]: ./tutorials/data-lineage
[git-page]: ./git
[using-modules-page]: ./modules/using-modules
