From 9ffc222cd0b606138b24ad3f9907ec91e2f47232 Mon Sep 17 00:00:00 2001 From: Christopher Hakkaart Date: Fri, 31 Oct 2025 09:58:34 +1300 Subject: [PATCH 01/13] Testing restructure idea Signed-off-by: Christopher Hakkaart --- docs/cli.md | 32 +++++++++++++++++--------------- 1 file changed, 17 insertions(+), 15 deletions(-) diff --git a/docs/cli.md b/docs/cli.md index 160c04d500..ec46c86ecd 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -14,37 +14,39 @@ Nextflow options use a single dash prefix, e.g. `-resume`. Do not confuse with d ### Hard configuration override -Use the specified configuration file(s) overriding any defaults. +Use the `-C` option to replace all settings in default configuration files with those from a specified file: ```console -$ nextflow -C my.config COMMAND [arg...] +$ nextflow -C COMMAND [arg...] ``` -The `-C` option is used to override *all* settings specified in the default config file. For soft override, please refer the `-c` option. +This option is useful when you require complete control over the configuration and want to override all default Nextflow configuration file settings. Unlike `-c`, which merges configurations, `-C` performs a complete override and ensures **only** your custom configuration is applied. -- Override **any** default configuration with a custom configuration file: +**Example:** - ```console - $ nextflow -C my.config run nextflow-io/hello - ``` +Override **any** default configuration with a custom configuration file: + +```console +nextflow -C my.config run nextflow-io/hello +``` ### JVM properties -Set JVM properties. +Use the `-D` option to set custom Java system properties and configure or fine-tune the JVM instance used by Nextflow: ```console -$ nextflow -Dkey=value COMMAND [arg...] +$ nextflow -D= COMMAND [arg...] ``` -This option allows the definition of custom Java system properties that can be used to properly configure or fine tuning the JVM instance used by the Nextflow runtime. +This option is useful for setting encoding, memory parameters, or other Java-level properties. You can specify multiple properties by using the `-D` option multiple times. For other JVM-level options, see {ref}`config-env-vars`. -For specifying other JVM level options, please refer to the {ref}`config-env-vars` section. +**Example:** -- Add JVM properties to the invoked pipeline: +Add JVM properties to the invoked pipeline: - ```console - $ nextflow -Dfile.encoding=UTF-8 run nextflow-io/hello - ``` +```console +nextflow -Dfile.encoding=UTF-8 run nextflow-io/hello +``` ### Execution as a background job From 82183f108cf5c1ed86e3467e1919157bb40b310e Mon Sep 17 00:00:00 2001 From: Christopher Hakkaart Date: Fri, 31 Oct 2025 10:02:42 +1300 Subject: [PATCH 02/13] Update intro Signed-off-by: Christopher Hakkaart --- docs/cli.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/cli.md b/docs/cli.md index ec46c86ecd..4bc99a8387 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -2,12 +2,12 @@ # Command line -Nextflow provides a robust command line interface (CLI) for the management and execution of pipelines. +Nextflow provides a robust command line interface (CLI) for executing and managing computational pipelines. -Simply run `nextflow` with no options or `nextflow -h` to see the list of available top-level options and commands. See {ref}`cli-reference` for the full list of subcommands with examples. +To view available options and commands, run `nextflow -h`. For complete documentation of all commands and subcommands with usage examples, see {ref}`cli-reference`. :::{note} -Nextflow options use a single dash prefix, e.g. `-resume`. Do not confuse with double dash notation, e.g. `--resume`, which is instead used for {ref}`Pipeline parameters `. +Nextflow options use a single dash prefix (e.g., `-resume`), while pipeline parameters use a double dash prefix (e.g., `--resume`). See {ref}`Pipeline parameters ` for more information. ::: ## Basic usage From c541d89890ccc8437a275b2387e05129e13ea436 Mon Sep 17 00:00:00 2001 From: Christopher Hakkaart Date: Fri, 31 Oct 2025 13:40:15 +1300 Subject: [PATCH 03/13] Minor language revisions Signed-off-by: Christopher Hakkaart --- docs/cli.md | 32 ++++++++++++++------------------ 1 file changed, 14 insertions(+), 18 deletions(-) diff --git a/docs/cli.md b/docs/cli.md index 4bc99a8387..291fb28c36 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -4,7 +4,7 @@ Nextflow provides a robust command line interface (CLI) for executing and managing computational pipelines. -To view available options and commands, run `nextflow -h`. For complete documentation of all commands and subcommands with usage examples, see {ref}`cli-reference`. +To view available options and commands, run `nextflow -h`. For complete documentation of all commands and subcommands, see {ref}`cli-reference`. :::{note} Nextflow options use a single dash prefix (e.g., `-resume`), while pipeline parameters use a double dash prefix (e.g., `--resume`). See {ref}`Pipeline parameters ` for more information. @@ -14,20 +14,18 @@ Nextflow options use a single dash prefix (e.g., `-resume`), while pipeline para ### Hard configuration override -Use the `-C` option to replace all settings in default configuration files with those from a specified file: +Use the `-C` option to replace all settings in default Nextflow configuration files with those from a specified file: ```console $ nextflow -C COMMAND [arg...] ``` -This option is useful when you require complete control over the configuration and want to override all default Nextflow configuration file settings. Unlike `-c`, which merges configurations, `-C` performs a complete override and ensures **only** your custom configuration is applied. +The `-C` option is useful when you require complete control over the configuration and want to override all default Nextflow configuration file settings. Unlike `-c`, which merges configurations, `-C` performs a complete override and ensures only your custom configuration is applied. -**Example:** - -Override **any** default configuration with a custom configuration file: +For example, to override the default configuration with a custom configuration file: ```console -nextflow -C my.config run nextflow-io/hello +$ nextflow -C my.config run nextflow-io/hello ``` ### JVM properties @@ -38,31 +36,29 @@ Use the `-D` option to set custom Java system properties and configure or fine-t $ nextflow -D= COMMAND [arg...] ``` -This option is useful for setting encoding, memory parameters, or other Java-level properties. You can specify multiple properties by using the `-D` option multiple times. For other JVM-level options, see {ref}`config-env-vars`. - -**Example:** +The `-D` option is useful for setting encoding, memory parameters, or other Java-level properties. You can specify multiple properties by using the `-D` option multiple times. For other JVM-level options, see {ref}`config-env-vars`. -Add JVM properties to the invoked pipeline: +For example, to add JVM properties to the invoked pipeline: ```console -nextflow -Dfile.encoding=UTF-8 run nextflow-io/hello +$ nextflow -Dfile.encoding=UTF-8 run nextflow-io/hello ``` ### Execution as a background job -Execute `nextflow` in the background. +Use the `-bg` option to execute a Nextflow run in the background: ```console $ nextflow -bg COMMAND [arg...] ``` -The `-bg` option is used to invoke the nextflow execution in the background and allows the user to continue interacting with the terminal. This option is similar to `nohup` in behavior. +The `-bg` invokes the Nextflow run in the background and allows the user to continue interacting with the terminal. This option is similar to `nohup` in behavior. -- Invoke any execution as a background job: +For example, invoke a run as a background job: - ```console - $ nextflow -bg run nextflow-io/hello - ``` +```console +$ nextflow -bg run nextflow-io/hello +``` ### Soft configuration override From 9bcab02469283206e7ba10dd7b2c36079ea4d0a8 Mon Sep 17 00:00:00 2001 From: Christopher Hakkaart Date: Fri, 31 Oct 2025 15:01:07 +1300 Subject: [PATCH 04/13] Convert to concept based language Signed-off-by: Christopher Hakkaart --- docs/cli.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/cli.md b/docs/cli.md index 291fb28c36..1a857d2520 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -1,8 +1,8 @@ (cli-page)= -# Command line +# Command line interface -Nextflow provides a robust command line interface (CLI) for executing and managing computational pipelines. +The Nextflow command line interface (CLI) is the main way to execute and manage pipelines. To view available options and commands, run `nextflow -h`. For complete documentation of all commands and subcommands, see {ref}`cli-reference`. @@ -14,7 +14,7 @@ Nextflow options use a single dash prefix (e.g., `-resume`), while pipeline para ### Hard configuration override -Use the `-C` option to replace all settings in default Nextflow configuration files with those from a specified file: +The `-C` option replaces all default Nextflow configuration files with those from a specified configuration file: ```console $ nextflow -C COMMAND [arg...] @@ -30,15 +30,15 @@ $ nextflow -C my.config run nextflow-io/hello ### JVM properties -Use the `-D` option to set custom Java system properties and configure or fine-tune the JVM instance used by Nextflow: +The `-D` option sets Java system properties that control the JVM instance running Nextflow: ```console $ nextflow -D= COMMAND [arg...] ``` -The `-D` option is useful for setting encoding, memory parameters, or other Java-level properties. You can specify multiple properties by using the `-D` option multiple times. For other JVM-level options, see {ref}`config-env-vars`. +JVM properties configure Java behavior such as encoding, memory parameters, and other system-level settings. Multiple properties can be specified through repeated `-D` options. See {ref}`config-env-vars` for additional JVM configuration. -For example, to add JVM properties to the invoked pipeline: +For example, to add JVM properties to a pipeline run: ```console $ nextflow -Dfile.encoding=UTF-8 run nextflow-io/hello @@ -46,15 +46,15 @@ $ nextflow -Dfile.encoding=UTF-8 run nextflow-io/hello ### Execution as a background job -Use the `-bg` option to execute a Nextflow run in the background: +The `-bg` option runs Nextflow pipelines as background processes: ```console $ nextflow -bg COMMAND [arg...] ``` -The `-bg` invokes the Nextflow run in the background and allows the user to continue interacting with the terminal. This option is similar to `nohup` in behavior. +Background execution detaches the pipeline from the terminal session, similar to `nohup`, allowing continued terminal interaction while the pipeline runs. -For example, invoke a run as a background job: +For example, to invoke a run as a background job: ```console $ nextflow -bg run nextflow-io/hello From 8ce13705dc9a28c506a61d7e39969183811db955 Mon Sep 17 00:00:00 2001 From: Christopher Hakkaart Date: Mon, 3 Nov 2025 16:56:35 +1300 Subject: [PATCH 05/13] Revise entire page with new layout Signed-off-by: Christopher Hakkaart --- docs/cli.md | 563 ++++++++++++++++++++++++++++-------------- docs/reference/cli.md | 14 ++ 2 files changed, 386 insertions(+), 191 deletions(-) diff --git a/docs/cli.md b/docs/cli.md index 1a857d2520..f01656d42c 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -2,383 +2,564 @@ # Command line interface -The Nextflow command line interface (CLI) is the main way to execute and manage pipelines. +The Nextflow command line interface (CLI) is how you interact with Nextflow to run pipelines, manage projects, inspect configurations, and maintain your workflow environment. This page explains the key concepts and common usage patterns for the CLI. -To view available options and commands, run `nextflow -h`. For complete documentation of all commands and subcommands, see {ref}`cli-reference`. +For a complete technical reference of all options, see {ref}`cli-reference`. :::{note} -Nextflow options use a single dash prefix (e.g., `-resume`), while pipeline parameters use a double dash prefix (e.g., `--resume`). See {ref}`Pipeline parameters ` for more information. +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. ::: -## Basic usage +## Options + +Nextflow options are modifiers that control how Nextflow itself operates. Use them to configure execution behavior, manage logging, override configurations, or get information about Nextflow. ### Hard configuration override -The `-C` option replaces all default Nextflow configuration files with those from a specified configuration file: +The `-C` option replaces all default configuration with your custom configuration file, ensuring complete control over settings. + +Use this when you need absolute control and want to ensure no default configurations interfere with your custom settings. Unlike `-c` which merges configurations, `-C` ensures only your specified file is used. ```console -$ nextflow -C COMMAND [arg...] +$ nextflow -C my.config run nextflow-io/hello ``` -The `-C` option is useful when you require complete control over the configuration and want to override all default Nextflow configuration file settings. Unlike `-c`, which merges configurations, `-C` performs a complete override and ensures only your custom configuration is applied. +See {ref}`config-page` for more about configuration files. + +### Soft configuration override -For example, to override the default configuration with a custom configuration file: +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. You can specify `-c` multiple times to layer configurations, with later files taking precedence over earlier ones. ```console -$ nextflow -C my.config run nextflow-io/hello +$ nextflow -c my.config run nextflow-io/hello ``` -### JVM properties +See {ref}`config-page` for more about configuration files. + +### Background execution + +The `-bg` option runs Nextflow as a background process and frees your terminal for other work. -The `-D` option sets Java system properties that control the JVM instance running Nextflow: +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. Outputs are saved to `.nextflow.log` by default. ```console -$ nextflow -D= COMMAND [arg...] +$ nextflow -bg run nextflow-io/hello ``` -JVM properties configure Java behavior such as encoding, memory parameters, and other system-level settings. Multiple properties can be specified through repeated `-D` options. See {ref}`config-env-vars` for additional JVM configuration. +### Quiet mode + +The `-q` option suppresses the Nextflow banner and execution progress output. -For example, to add JVM properties to a pipeline run: +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. ```console -$ nextflow -Dfile.encoding=UTF-8 run nextflow-io/hello +$ nextflow -q run nextflow-io/hello ``` -### Execution as a background job +### Custom log file path -The `-bg` option runs Nextflow pipelines as background processes: +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. ```console -$ nextflow -bg COMMAND [arg...] +$ nextflow -log /var/log/nextflow.log run nextflow-io/hello ``` -Background execution detaches the pipeline from the terminal session, similar to `nohup`, allowing continued terminal interaction while the pipeline runs. +### Syslog integration + +The `-syslog` option sends logs to a [Syslog](https://en.wikipedia.org/wiki/Syslog) server for centralized log management. -For example, to invoke a run as a background job: +Use this to aggregate Nextflow logs with other system logs to enable centralized monitoring and analysis. ```console -$ nextflow -bg run nextflow-io/hello +$ nextflow -syslog localhost:1234 run nextflow-io/hello ``` -### Soft configuration override +### JVM properties + +The `-D` option sets Java system properties that control the JVM running Nextflow. -Add the specified file to configuration set. +Use this for configuring memory, encoding, or other Java-level behavior. You can specify multiple properties by using `-D` multiple times. ```console -$ nextflow -c nxf.config COMMAND [arg...] +$ nextflow -Dfile.encoding=UTF-8 run nextflow-io/hello ``` -The `-c` option is used to append a new configuration to the default configuration. The `-c` option allows us to update the config in an additive manner. For **hard override**, refer to the `-C` option. - -- Update *some* fields of the default config for any pipeline: +See {ref}`config-env-vars` for additional JVM configuration options. - ```console - $ nextflow -c nxf.config run nextflow-io/hello - ``` +### Help display -### Help +The `-h` option shows available commands and global options. -Print the help message. +Use this to discover available commands or refresh your memory about command syntax. ```console $ nextflow -h ``` -The `-h` option prints out the overview of the CLI interface and enumerates the top-level *options* and *commands*. +### Version information -### Execution logs +The `-v` and `-version` options show Nextflow version details. + +Use `-v` for brief output showing version and build number. + +```console +$ nextflow -v +nextflow version 24.04.0.5917 +``` -Sets the path of the nextflow log file. +Use `-version` for detailed information including creation date, citation, and website. ```console -$ nextflow -log custom.log COMMAND [arg...] +$ 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 ``` -The `-log` option takes a path of the new log file which will be used instead of the default `.nextflow.log` or to save logs files to another directory. +## Pipeline execution -- Save all execution logs to the custom `/var/log/nextflow.log` file: +Pipeline execution is the core function of Nextflow. These commands run workflow scripts, either from local files or remote Git repositories. Nextflow handles downloading, caching, and executing pipelines with minimal user intervention. - ```console - $ nextflow -log /var/log/nextflow.log run nextflow-io/hello - ``` +### Launching a project -### Quiet execution +The `run` command executes pipeline scripts. This is the primary command for running Nextflow workflows. It handles both local scripts and remote repositories seamlessly. -Disable the printing of information to the terminal. +Use this command whenever you need to execute a pipeline. It automatically manages repository downloads, caching, and execution, supporting various Git providers and authentication methods. + +**Local execution** + +Run a pipeline script from your local filesystem: ```console -$ nextflow -q COMMAND [arg...] +$ nextflow run main.nf ``` -The `-q` option suppresses the banner and process-related info, and exits once the execution is completed. Please note that it does not affect any explicit print statement within a pipeline. +**Remote execution** + +Nextflow executes pipelines directly from Git repositories without manual downloading. Use the format `/`: + +```console +$ nextflow run nextflow-io/hello +``` -- Invoke the pipeline execution without the banner and pipeline information: +Nextflow automatically: - ```console - $ nextflow -q run nextflow-io/hello - ``` +1. Downloads the repository to `$HOME/.nextflow/assets/` +2. Caches it for future runs +3. Executes the main script -### Logging to a syslog server +If you omit the owner, Nextflow searches cached pipelines first, then attempts to download from the `NXF_ORG` organization (default: `nextflow-io`). -Send logs to [Syslog](https://en.wikipedia.org/wiki/Syslog) server endpoint. +You can also use full repository URLs: ```console -$ nextflow -syslog localhost:1234 COMMAND [arg...] +$ nextflow run https://github.com/nextflow-io/hello ``` -The `-syslog` option is used to send logs to a Syslog logging server at the specified endpoint. +**Private repositories** + +For private repositories, use the `-user` option to provide credentials: -- Send the logs to a Syslog server at specific endpoint: +```console +$ nextflow run owner/private-repo -user myusername +``` - ```console - $ nextflow -syslog localhost:1234 run nextflow-io/hello - ``` +Alternatively, configure Git authentication. See {ref}`Git configuration `. -### Version +**Non-GitHub providers** -Print the Nextflow version information. +Use the `-hub` option for Bitbucket, GitLab, or other Git providers: ```console -$ nextflow -v +$ nextflow run owner/repo -hub bitbucket ``` -The `-v` option prints out information about Nextflow, such as the version and build. The `-version` option, in addition, prints out the citation reference and official website. +**Revision selection** -- The short version: +Execute specific Git branches, tags, or commits with the `-r` option. This is essential for running specific pipeline versions, testing development branches, and ensuring reproducibility by pinning to specific commits. - ```console - $ nextflow -v - nextflow version 20.07.1.5412 - ``` +```console +$ nextflow run nextflow-io/hello -r v1.1 +$ nextflow run nextflow-io/hello -r dev-branch +$ nextflow run nextflow-io/hello -r a3f5c8e +``` -- The full version info with citation and website link: +(cli-params)= - ```console - $ nextflow -version - 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 - ``` +**Pipeline parameters** -## Running pipelines +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. -The main purpose of the Nextflow CLI is to run Nextflow pipelines with the `run` command. Nextflow can execute a local script (e.g. `./main.nf`) or a remote project (e.g. `github.com/nextflow-io/hello`). +```console +$ nextflow run main.nf --input data.csv --output results +``` -### Launching a remote project +Parameter names support automatic conversion between kebab-case and camelCase: -To launch the execution of a pipeline project, hosted in a remote code repository, you simply need to specify its qualified name or the repository URL after the `run` command. The qualified name is formed by two parts: the `owner` name and the `repository` name separated by a `/` character. +```console +$ nextflow run main.nf --input-file data.csv # Becomes params.inputFile +``` -If a Nextflow project is hosted on GitHub, for example `http://github.com/nextflow-io/hello`, it can be executed by entering the following command in your shell terminal: +Parameters without values are set to `true`: -```bash -nextflow run nextflow-io/hello +```console +$ nextflow run main.nf --verbose # params.verbose = true ``` -or using the project URL: +:::{warning} +Quote parameters containing wildcards to prevent shell expansion: -```bash -nextflow run http://github.com/nextflow-io/hello +```console +$ nextflow run main.nf --files "*.fasta" ``` +::: -If the project is found, it will be automatically downloaded to the Nextflow home directory (`$HOME/.nextflow` by default) and cached for subsequent runs. +**Parameter files** -:::{note} -You must use the `-hub` option to specify the hosting service if your project is hosted on a service other than GitHub, e.g. `-hub bitbucket`. However, the `-hub` option is not required if you use the project URL. -::: +For complex parameter sets, use a YAML or JSON file with `-params-file`. This is cleaner than long command lines. -If the `owner` is omitted, Nextflow will search your cached pipelines for a pipeline that matches the name specified. If no pipeline is found, Nextflow will try to download it using the `organization` name defined by the `NXF_ORG` environment variable (`nextflow-io` by default). +```yaml +# params.yml +input: data.csv +output: results/ +min_quality: 20 +``` -:::{tip} -To access a private repository, specify the access credentials using the `-user` command line option. Then follow the interactive prompts to enter your password. Alternatively, define your private repository access credentials using Git. See {ref}`Git configuration ` for more information. -::: +```console +$ 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 {ref}`config-params`) +3. Parameter files (`-params-file`) +4. Command line parameters (`--foo bar`) + +### Kubernetes execution -### Using a specific revision +The `kuberun` command executes pipelines entirely within a Kubernetes cluster. This experimental feature runs the Nextflow driver itself inside Kubernetes. -Any Git branch, tag, or commit of a project repository can be used when launching a pipeline by specifying the `-r` option: +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. ```console -$ nextflow run nextflow-io/hello -r mybranch +$ nextflow kuberun nextflow-io/hello ``` -or +See {ref}`cli-kuberun` for configuration details. + +## 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. ```console -$ nextflow run nextflow-io/hello -r v1.1 +$ nextflow list ``` -These commands will execute two different project revisions based on the given Git branch/tag/commit. +### Showing project information -(cli-params)= +The `info` command displays detailed metadata about a downloaded project, including its repository location, local path, main script, and available revisions. -### Pipeline parameters +Use this to understand a project's structure, see available versions, or verify which revision is currently checked out. -Pipeline scripts can define *parameters* that can be overridden on the command line. +```console +$ 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 `*`) -Parameters can be declared in the main script: +### Pulling or updating projects -```nextflow -params.alpha = 'default script value' +The `pull` command downloads a pipeline or updates an existing one to the latest version from its Git repository. -workflow { - println "alpha = ${params.alpha}" -} +Use this to manually download pipelines before running them, update cached pipelines, or download pipelines for offline use. You can specify a particular revision to download. + +```console +$ nextflow pull nextflow-io/hello +$ nextflow pull nextflow-io/hello -r mybranch ``` -Or in a config file: +See {ref}`cli-pull` for configuration options. + +### Viewing project code + +The `view` command displays the contents of a pipeline's main script or lists all files in the repository. -```groovy -params { - alpha = 'default config value' -} +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. + +```console +$ nextflow view nextflow-io/hello +$ nextflow view nextflow-io/hello -l ``` -The above parameter can be specified on the command line as `--alpha`: +See {ref}`cli-view` for configuration options. + +### 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 in detail. If you omit the target directory it uses the pipeline name. ```console -$ nextflow run main.nf --alpha Hello +$ nextflow clone nextflow-io/hello my-hello ``` -:::{note} -Parameters that are specified on the command line without a value are set to `true`. -::: +See {ref}`cli-clone` for configuration options. -:::{note} -Parameters that are specified on the command line in kebab case (e.g., `--alpha-beta`) are automatically converted to camel case (e.g., `--alphaBeta`). Because of this, a parameter defined as `alphaBeta` in the pipeline script can be specified on the command line as `--alphaBeta` or `--alpha-beta`. -::: +### Deleting cached projects -:::{warning} -When a command line parameter includes one or more glob characters, i.e. wildcards like `*` or `?`, the parameter value must be enclosed in quotes to prevent Bash expansion and preserve the glob characters. For example: +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. ```console -$ nextflow run --files "*.fasta" +$ nextflow drop nextflow-io/hello ``` -::: -Parameters specified on the command line can be also specified in a params file using the `-params-file` option. +See {ref}`cli-drop` for configuration options. + +## 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 potential problems early. + +### Configuration inspection + +The `config` command prints the resolved configuration for a pipeline to show how all configuration files merge together into the final effective settings. + +Use this to debug configuration issues, verify which settings will be applied, understand configuration precedence, or inspect specific configuration properties. ```console -$ nextflow run main.nf -params-file pipeline_params.yml +$ nextflow config +$ nextflow config nextflow-io/hello ``` -The `-params-file` option loads parameters for your Nextflow pipeline from a JSON or YAML file. Parameters defined in the file are equivalent to specifying them directly on the command line. For example, instead of specifying parameters on the command line: +See {ref}`cli-config` for configuration options. + +### Process inspection + +The `inspect` command displays detailed settings for processes in a pipeline, including directives, resources, and container images. + +Use this to verify process configurations before running, understand resource allocations, or check which containers will be used. This shows CPU, memory, containers, process directives, and executor settings for each process. ```console -$ nextflow run main.nf --alpha 1 --beta two +$ nextflow inspect main.nf ``` -Parameters can be represented in YAML format: +See {ref}`cli-inspect` for configuration options. -```yaml -alpha: 1 -beta: 'two' +### Script validation + +The `lint` command checks Nextflow scripts and configuration files for common issues and syntax violations. + +Use this during development to maintain code quality, catch syntax errors, identify deprecated features, spot style inconsistencies, and find potential bugs before execution. + +```console +$ nextflow lint main.nf ``` -Or in JSON format: +See {ref}`cli-lint` for configuration options. + +## 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, including run names, timestamps, and customizable output fields. -```json -{ - "alpha": 1, - "beta": "two" -} +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. + +```console +$ nextflow log +$ nextflow log dreamy_euler +$ nextflow log last -f name,status,duration ``` -:::{note} -Parameter values in the params file can reference the following {ref}`built-in variables `: `baseDir`, `projectDir`, `launchDir`. -::: +See {ref}`cli-log` for configuration options. + +### 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. + +```console +$ nextflow clean -n +$ nextflow clean dreamy_euler -f +``` -Parameters are applied in the following order (from lowest to highest priority): +See {ref}`cli-clean` for configuration options. -1. Parameters defined in pipeline scripts (e.g. `main.nf`) -2. Parameters defined in {ref}`config files ` -3. Parameters specified in a params file (`-params-file`) -4. Parameters specified on the command line (`--something value`) +### Data lineage -## Managing projects +The `lineage` command explores data lineage and provenance for workflow executions and tracks relationships between inputs, outputs, and processing steps. -Nextflow seamlessly integrates with popular Git providers, including [BitBucket](http://bitbucket.org/), [GitHub](http://github.com), and [GitLab](http://gitlab.com) for managing Nextflow pipelines as version-controlled Git repositories. +Use this feature to understand input/output relationships between tasks, trace data flow through the pipeline, or establish file provenance. Lineage tracking must be enabled in configuration. -The following commands allow you to perform basic operations to manage your projects. +```console +$ nextflow lineage +``` + +See {ref}`data-lineage-page` to get started and {ref}`cli-lineage` for configuration options. -### Listing available projects +### Secret management -The `list` command allows you to list all the projects you have downloaded in your computer. For example: +The `secrets` command manages secure pipeline secrets. -```bash -nextflow list +Use this to store credentials securely, reference them in pipelines without exposing values, and manage sensitive data centrally across your organization. + +```console +$ nextflow secrets list +$ nextflow secrets set AWS_ACCESS_KEY_ID +$ nextflow secrets delete AWS_ACCESS_KEY_ID ``` -This prints a list similar to the following: +See {ref}`cli-secrets` for configuration options. + +## Platform integration + +Platform integration commands connect Nextflow with [Seqera Platform](https://seqera.io) for workflow management, monitoring, and collaboration. The Platform provides centralized execution management, monitoring dashboards, and secure credential storage. + +Use these commands when working with Seqera Platform to authenticate, launch workflows, or manage secrets. + +### Platform authentication + +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. +```console +$ nextflow auth login ``` -cbcrg/ampa-nf -cbcrg/piper-nf -nextflow-io/hello -nextflow-io/examples + +Additional authentication operations include checking login status, viewing configuration details, and logging out: + +```console +$ nextflow auth status +$ nextflow auth config +$ nextflow auth logout ``` -### Showing project information +See {ref}`cli-auth` for configuration options. + +### Platform workflow submission -By using the `info` command you can show information from a downloaded project. For example: +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. ```console -$ nextflow info hello -project name: nextflow-io/hello -repository : http://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] +$ nextflow launch nextflow-io/hello ``` -Starting from the top it shows: the project name; the Git repository URL; the local directory where the project has been downloaded; the script that is executed when launched; the list of available revisions i.e. branches and tags. Tags are marked with a `[t]` on the right and the checked-out revision is marked with a `*` on the left. +See {ref}`cli-launch` for configuration options. + +## System utilities -### Pulling or updating a project +System utilities provide administrative and development tools for managing Nextflow itself, interacting with remote filesystems, working with plugins, and debugging. -The `pull` command allows you to download a project from a GitHub repository or to update it if that repository has already been downloaded. For example: +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 development tool 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. ```console -$ nextflow pull nextflow-io/hello +$ nextflow console ``` -Alternatively, you can use the repository URL as the name of the project to pull: +### Remote filesystem operations + +The `fs` command performs filesystem operations on remote storage systems supported by Nextflow, including 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. Operations include listing, copying, moving, and deleting files. ```console -$ nextflow pull https://github.com/nextflow-io/hello +$ nextflow fs list s3://my-bucket/data/ +$ nextflow fs cp s3://source/file.txt s3://dest/ +$ nextflow fs delete s3://bucket/old-data/ ``` -Downloaded pipeline projects are stored in your directory `$HOME/.nextflow/assets` directory. +### Plugins -### Viewing the project code +The `plugin` command creates plugins, installs them, and executes plugin-specific operations. -The `view` command shows the content of the pipeline script you have pulled. For example: +Create a new plugin scaffold for development: ```console -$ nextflow view nextflow-io/hello +$ nextflow plugin create ``` -By adding the `-l` option to the example above it will list the content of the repository. +Install a plugin to extend Nextflow's functionality: -### Cloning a project into a directory +```console +$ nextflow plugin install my-plugin +``` -The `clone` command allows you to copy a Nextflow pipeline project to a directory of your choice. For example: +Execute plugin-specific commands using the format `plugin-name:command`: ```console -$ nextflow clone nextflow-io/hello target-dir +$ nextflow plugin my-plugin:hello --alpha --beta ``` -If the destination directory is omitted the specified project is cloned to a directory with the same name as the pipeline base name (e.g. `hello`) in the current directory. +See {ref}`using-plugins-page` and {ref}`cli-plugin` for more information. See individual plugin documentation for plugin specific commands. -The `clone` command can be used to inspect or modify the source code of a pipeline project. You can eventually commit and push back your changes by using the usual Git/GitHub workflow. +### Nextflow updates -### Deleting a project +The `self-update` command updates Nextflow to a newer version. It downloads and installs the latest release or a specific version. -Downloaded pipelines can be deleted by using the `drop` command, as shown below: +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. -```bash -nextflow drop nextflow-io/hello +```console +$ 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. + +```console +$ nextflow help run +$ nextflow help clean +``` \ No newline at end of file diff --git a/docs/reference/cli.md b/docs/reference/cli.md index c30afa4963..aff63d7233 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -233,6 +233,8 @@ 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. @@ -280,6 +282,8 @@ $ nextflow clone nextflow-io/hello -r v1.1 nextflow-io/hello cloned to: hello ``` +(cli-config)= + ### `config` Print the resolved pipeline configuration. @@ -412,6 +416,8 @@ Launch the `console` GUI. $ nextflow console ``` +(cli-drop)= + ### `drop` Delete the local copy of a project. @@ -659,6 +665,8 @@ 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. @@ -934,6 +942,8 @@ Lint and format all files in the current directory (and subdirectories) and use $ nextflow lint -format -spaces 2 . ``` +(cli-list)= + ### `list` List all downloaded projects. @@ -1119,6 +1129,8 @@ $ nextflow plugin [options] : Execute a plugin-specific command. +(cli-pull)= + ### `pull` Download or update a project. @@ -1520,6 +1532,8 @@ 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). From 23de8daeeafafe355212a3a697e8e0b7d5b4cea9 Mon Sep 17 00:00:00 2001 From: Christopher Hakkaart Date: Tue, 4 Nov 2025 10:09:15 +1300 Subject: [PATCH 06/13] Revise text Signed-off-by: Christopher Hakkaart --- docs/cli.md | 72 ++++++++++++++++++++++--------------------- docs/reference/cli.md | 2 ++ 2 files changed, 39 insertions(+), 35 deletions(-) diff --git a/docs/cli.md b/docs/cli.md index f01656d42c..6ebe479c87 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -2,9 +2,9 @@ # Command line interface -The Nextflow command line interface (CLI) is how you interact with Nextflow to run pipelines, manage projects, inspect configurations, and maintain your workflow environment. This page explains the key concepts and common usage patterns for the CLI. +The Nextflow command-line interface (CLI) is how you interact with Nextflow to run pipelines, manage projects, inspect configurations, and maintain your workflow environment. This page explains the key concepts and common usage patterns for the CLI. -For a complete technical reference of all options, see {ref}`cli-reference`. +For the complete reference of all commands, subcommands, and options, see {ref}`cli-reference`. :::{note} Nextflow uses two types of command-line flags: @@ -15,37 +15,37 @@ Nextflow uses two types of command-line flags: ## Options -Nextflow options are modifiers that control how Nextflow itself operates. Use them to configure execution behavior, manage logging, override configurations, or get information about Nextflow. +Nextflow options are modifiers that control how Nextflow itself operates. Use them to configure execution behavior, manage logging, override configurations, and get information about Nextflow. ### Hard configuration override The `-C` option replaces all default configuration with your custom configuration file, ensuring complete control over settings. -Use this when you need absolute control and want to ensure no default configurations interfere with your custom settings. Unlike `-c` which merges configurations, `-C` ensures only your specified file is used. - ```console $ nextflow -C my.config run nextflow-io/hello ``` -See {ref}`config-page` for more about configuration files. +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. + +See {ref}`config-page` for more information. ### 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. You can specify `-c` multiple times to layer configurations, with later files taking precedence over earlier ones. - ```console $ nextflow -c my.config run nextflow-io/hello ``` -See {ref}`config-page` for more about configuration files. +Use this when you want to override specific settings while keeping other defaults intact. You can specify `-c` multiple times to layer configurations, with later files taking precedence over earlier ones. + +See {ref}`config-page` for more information. ### Background execution -The `-bg` option runs Nextflow as a background process and frees your terminal for other work. +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. Outputs are saved to `.nextflow.log` by default. +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. ```console $ nextflow -bg run nextflow-io/hello @@ -91,7 +91,7 @@ Use this for configuring memory, encoding, or other Java-level behavior. You can $ nextflow -Dfile.encoding=UTF-8 run nextflow-io/hello ``` -See {ref}`config-env-vars` for additional JVM configuration options. +See {ref}`config-env-vars` for more information. ### Help display @@ -105,16 +105,16 @@ $ nextflow -h ### Version information -The `-v` and `-version` options show Nextflow version details. +The `-v` and `-version` options prints Nextflow version information. -Use `-v` for brief output showing version and build number. +Use `-v` for minimal output showing version and build number. ```console $ nextflow -v nextflow version 24.04.0.5917 ``` -Use `-version` for detailed information including creation date, citation, and website. +Use `-version` for detailed output showing creation date, citation, and website. ```console $ nextflow -version @@ -127,15 +127,15 @@ http://nextflow.io ## Pipeline execution -Pipeline execution is the core function of Nextflow. These commands run workflow scripts, either from local files or remote Git repositories. Nextflow handles downloading, caching, and executing pipelines with minimal user intervention. +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. This is the primary command for running Nextflow workflows. It handles both local scripts and remote repositories seamlessly. +The `run` command executes pipeline scripts. This is the primary command for running Nextflow. It handles both local scripts and remote repositories seamlessly. Use this command whenever you need to execute a pipeline. It automatically manages repository downloads, caching, and execution, supporting various Git providers and authentication methods. -**Local execution** +**Local pipelines** Run a pipeline script from your local filesystem: @@ -143,7 +143,7 @@ Run a pipeline script from your local filesystem: $ nextflow run main.nf ``` -**Remote execution** +**Remote pipelines** Nextflow executes pipelines directly from Git repositories without manual downloading. Use the format `/`: @@ -173,7 +173,7 @@ For private repositories, use the `-user` option to provide credentials: $ nextflow run owner/private-repo -user myusername ``` -Alternatively, configure Git authentication. See {ref}`Git configuration `. +Alternatively, configure Git authentication. See {ref}`Git configuration ` for more information. **Non-GitHub providers** @@ -257,7 +257,7 @@ Use this when you want both the Nextflow driver and tasks running in Kubernetes. $ nextflow kuberun nextflow-io/hello ``` -See {ref}`cli-kuberun` for configuration details. +See {ref}`cli-kuberun` for more information. ## Project management @@ -311,7 +311,7 @@ $ nextflow pull nextflow-io/hello $ nextflow pull nextflow-io/hello -r mybranch ``` -See {ref}`cli-pull` for configuration options. +See {ref}`cli-pull` for more information. ### Viewing project code @@ -324,7 +324,7 @@ $ nextflow view nextflow-io/hello $ nextflow view nextflow-io/hello -l ``` -See {ref}`cli-view` for configuration options. +See {ref}`cli-view` for more information. ### Cloning projects locally @@ -336,7 +336,7 @@ Use this when you want to modify an existing pipeline, create a derivative pipel $ nextflow clone nextflow-io/hello my-hello ``` -See {ref}`cli-clone` for configuration options. +See {ref}`cli-clone` for more information. ### Deleting cached projects @@ -348,7 +348,7 @@ Use this to free disk space by removing pipelines you no longer need. The projec $ nextflow drop nextflow-io/hello ``` -See {ref}`cli-drop` for configuration options. +See {ref}`cli-drop` for more information. ## Configuration and validation @@ -367,7 +367,7 @@ $ nextflow config $ nextflow config nextflow-io/hello ``` -See {ref}`cli-config` for configuration options. +See {ref}`cli-config` for more information. ### Process inspection @@ -379,7 +379,7 @@ Use this to verify process configurations before running, understand resource al $ nextflow inspect main.nf ``` -See {ref}`cli-inspect` for configuration options. +See {ref}`cli-inspect` for more information. ### Script validation @@ -391,7 +391,7 @@ Use this during development to maintain code quality, catch syntax errors, ident $ nextflow lint main.nf ``` -See {ref}`cli-lint` for configuration options. +See {ref}`cli-lint` for more information. ## Execution history @@ -411,7 +411,7 @@ $ nextflow log dreamy_euler $ nextflow log last -f name,status,duration ``` -See {ref}`cli-log` for configuration options. +See {ref}`cli-log` for more information. ### Work directory cleanup @@ -424,7 +424,7 @@ $ nextflow clean -n $ nextflow clean dreamy_euler -f ``` -See {ref}`cli-clean` for configuration options. +See {ref}`cli-clean` for more information. ### Data lineage @@ -436,7 +436,7 @@ Use this feature to understand input/output relationships between tasks, trace d $ nextflow lineage ``` -See {ref}`data-lineage-page` to get started and {ref}`cli-lineage` for configuration options. +See {ref}`data-lineage-page` to get started and {ref}`cli-lineage` for more information. ### Secret management @@ -450,7 +450,7 @@ $ nextflow secrets set AWS_ACCESS_KEY_ID $ nextflow secrets delete AWS_ACCESS_KEY_ID ``` -See {ref}`cli-secrets` for configuration options. +See {ref}`cli-secrets` for more information. ## Platform integration @@ -458,7 +458,7 @@ Platform integration commands connect Nextflow with [Seqera Platform](https://se Use these commands when working with Seqera Platform to authenticate, launch workflows, or manage secrets. -### Platform authentication +### Seqera Platform authentication The `auth` command manages authentication credentials for Seqera Platform, saving access tokens for API interactions. @@ -476,7 +476,7 @@ $ nextflow auth config $ nextflow auth logout ``` -See {ref}`cli-auth` for configuration options. +See {ref}`cli-auth` for more information. ### Platform workflow submission @@ -488,7 +488,7 @@ Use this to leverage Platform's cloud resources, monitoring capabilities, and ex $ nextflow launch nextflow-io/hello ``` -See {ref}`cli-launch` for configuration options. +See {ref}`cli-launch` for more information. ## System utilities @@ -518,6 +518,8 @@ $ nextflow fs cp s3://source/file.txt s3://dest/ $ nextflow fs delete s3://bucket/old-data/ ``` +See {ref}`cli-fs` for more information. + ### Plugins The `plugin` command creates plugins, installs them, and executes plugin-specific operations. diff --git a/docs/reference/cli.md b/docs/reference/cli.md index aff63d7233..097c77b9e9 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -454,6 +454,8 @@ Forcefully drop the `nextflow-io/hello` pipeline, ignoring any local changes. $ nextflow drop nextflow-io/hello -f ``` +(cli-fs)= + ### `fs` Perform basic filesystem operations. From 057b40c505630eb5f13c90d2b102272b260c0c21 Mon Sep 17 00:00:00 2001 From: Christopher Hakkaart Date: Tue, 4 Nov 2025 12:57:13 +1300 Subject: [PATCH 07/13] Review CLI page Signed-off-by: Christopher Hakkaart --- docs/cli.md | 156 ++++++++++++++++++++++++++++++++-------------------- 1 file changed, 97 insertions(+), 59 deletions(-) diff --git a/docs/cli.md b/docs/cli.md index 6ebe479c87..54f165aebd 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -2,12 +2,12 @@ # Command line interface -The Nextflow command-line interface (CLI) is how you interact with Nextflow to run pipelines, manage projects, inspect configurations, and maintain your workflow environment. This page explains the key concepts and common usage patterns for the CLI. +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 {ref}`cli-reference`. :::{note} -Nextflow uses two types of command-line flags: +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. @@ -15,30 +15,30 @@ Nextflow uses two types of command-line flags: ## Options -Nextflow options are modifiers that control how Nextflow itself operates. Use them to configure execution behavior, manage logging, override configurations, and get information about Nextflow. +Nextflow options control how Nextflow itself operates. Use them to configure execution behavior, manage logging, override configurations, and get information about Nextflow. -### Hard configuration override +### Soft configuration override -The `-C` option replaces all default configuration with your custom configuration file, ensuring complete control over settings. +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. ```console -$ nextflow -C my.config run nextflow-io/hello +$ nextflow -c my.config run nextflow-io/hello ``` -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. - See {ref}`config-page` for more information. -### Soft configuration override +### Hard configuration override -The `-c` option adds your configuration on top of the defaults and merges them together. +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. ```console -$ nextflow -c my.config run nextflow-io/hello +$ nextflow -C my.config run nextflow-io/hello ``` -Use this when you want to override specific settings while keeping other defaults intact. You can specify `-c` multiple times to layer configurations, with later files taking precedence over earlier ones. - See {ref}`config-page` for more information. ### Background execution @@ -93,6 +93,10 @@ $ nextflow -Dfile.encoding=UTF-8 run nextflow-io/hello See {ref}`config-env-vars` for more information. +### Debug + +-remote-debug + ### Help display The `-h` option shows available commands and global options. @@ -131,13 +135,13 @@ Pipeline execution is the core function of Nextflow. These commands run Nextflow ### Launching a project -The `run` command executes pipeline scripts. This is the primary command for running Nextflow. It handles both local scripts and remote repositories seamlessly. +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. -Use this command whenever you need to execute a pipeline. It automatically manages repository downloads, caching, and execution, supporting various Git providers and authentication methods. +See {ref}`cli-run` for more information. **Local pipelines** -Run a pipeline script from your local filesystem: +Run a pipeline from your local filesystem: ```console $ nextflow run main.nf @@ -145,7 +149,7 @@ $ nextflow run main.nf **Remote pipelines** -Nextflow executes pipelines directly from Git repositories without manual downloading. Use the format `/`: +Run a pipeline from directly from Git repositories without manual downloading. Use the format `/`: ```console $ nextflow run nextflow-io/hello @@ -167,17 +171,17 @@ $ nextflow run https://github.com/nextflow-io/hello **Private repositories** -For private repositories, use the `-user` option to provide credentials: +Add credentials for private repositories with the `-user` option: ```console -$ nextflow run owner/private-repo -user myusername +$ nextflow run owner/private-repo -user my-username ``` Alternatively, configure Git authentication. See {ref}`Git configuration ` for more information. **Non-GitHub providers** -Use the `-hub` option for Bitbucket, GitLab, or other Git providers: +Specify Bitbucket, GitLab, or other Git providers with the `-hub` option: ```console $ nextflow run owner/repo -hub bitbucket @@ -185,7 +189,7 @@ $ nextflow run owner/repo -hub bitbucket **Revision selection** -Execute specific Git branches, tags, or commits with the `-r` option. This is essential for running specific pipeline versions, testing development branches, and ensuring reproducibility by pinning to specific commits. +Specify Git branches, tags, or commits with the `-r` option: ```console $ nextflow run nextflow-io/hello -r v1.1 @@ -225,13 +229,14 @@ $ nextflow run main.nf --files "*.fasta" **Parameter files** -For complex parameter sets, use a YAML or JSON file with `-params-file`. This is cleaner than long command lines. +For complex parameter sets, use YAML or JSON files with `-params-file`. This is cleaner than long command lines. -```yaml -# params.yml -input: data.csv -output: results/ -min_quality: 20 +```json +{ + "input": "data.csv", + "output": "results/", + "min_quality": 20 +} ``` ```console @@ -304,10 +309,15 @@ This shows: 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. You can specify a particular revision to download. +Use this to manually download pipelines before running them, update cached pipelines, or download pipelines for offline use. ```console $ nextflow pull nextflow-io/hello +``` + +You can specify a particular revision to download. + +```console $ nextflow pull nextflow-io/hello -r mybranch ``` @@ -330,7 +340,7 @@ See {ref}`cli-view` for more information. 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 in detail. If you omit the target directory it uses the pipeline name. +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. ```console $ nextflow clone nextflow-io/hello my-hello @@ -350,15 +360,29 @@ $ nextflow drop nextflow-io/hello See {ref}`cli-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. + +```console +$ nextflow secrets list +$ nextflow secrets set AWS_ACCESS_KEY_ID +$ nextflow secrets delete AWS_ACCESS_KEY_ID +``` + +See {ref}`cli-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 potential problems early. +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 to show how all configuration files merge together into the final effective settings. +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. @@ -371,21 +395,25 @@ See {ref}`cli-config` for more information. ### Process inspection -The `inspect` command displays detailed settings for processes in a pipeline, including directives, resources, and container images. +:::{versionadded} 23.09.0-edge +::: -Use this to verify process configurations before running, understand resource allocations, or check which containers will be used. This shows CPU, memory, containers, process directives, and executor settings for each process. +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. ```console -$ nextflow inspect main.nf +$ nextflow inspect nextflow-io/hello +$ nextflow inspect nextflow-io/hello -format json ``` See {ref}`cli-inspect` for more information. ### Script validation -The `lint` command checks Nextflow scripts and configuration files for common issues and syntax violations. +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 during development to maintain code quality, catch syntax errors, identify deprecated features, spot style inconsistencies, and find potential bugs before execution. +Use this to catch syntax errors before execution, enforce consistent code formatting, or validate entire directories of Nextflow code. ```console $ nextflow lint main.nf @@ -401,7 +429,7 @@ Use these commands to review past executions, free disk space, troubleshoot fail ### Execution logs -The `log` command displays execution history and details about past pipeline runs, including run names, timestamps, and customizable output fields. +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. @@ -428,9 +456,15 @@ See {ref}`cli-clean` for more information. ### Data lineage +:::{versionadded} 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 feature to understand input/output relationships between tasks, trace data flow through the pipeline, or establish file provenance. Lineage tracking must be enabled in configuration. +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. ```console $ nextflow lineage @@ -438,20 +472,6 @@ $ nextflow lineage See {ref}`data-lineage-page` to get started and {ref}`cli-lineage` 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. - -```console -$ nextflow secrets list -$ nextflow secrets set AWS_ACCESS_KEY_ID -$ nextflow secrets delete AWS_ACCESS_KEY_ID -``` - -See {ref}`cli-secrets` for more information. - ## Platform integration Platform integration commands connect Nextflow with [Seqera Platform](https://seqera.io) for workflow management, monitoring, and collaboration. The Platform provides centralized execution management, monitoring dashboards, and secure credential storage. @@ -460,6 +480,9 @@ Use these commands when working with Seqera Platform to authenticate, launch wor ### Seqera Platform authentication +:::{versionadded} 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. @@ -480,6 +503,9 @@ See {ref}`cli-auth` for more information. ### Platform workflow submission +:::{versionadded} 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. @@ -500,7 +526,7 @@ Use these commands for system administration, development, and testing. The `console` command launches an interactive Groovy console with Nextflow's execution context loaded. -Use this development tool 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. +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. ```console $ nextflow console @@ -508,14 +534,15 @@ $ nextflow console ### Remote filesystem operations -The `fs` command performs filesystem operations on remote storage systems supported by Nextflow, including S3, Google Cloud Storage, and Azure Blob Storage. +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. Operations include listing, copying, moving, and deleting files. +Use this to manage remote data, test cloud storage access, or perform bulk file operations without additional tools. ```console $ nextflow fs list s3://my-bucket/data/ -$ nextflow fs cp s3://source/file.txt s3://dest/ -$ nextflow fs delete s3://bucket/old-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 {ref}`cli-fs` for more information. @@ -524,25 +551,36 @@ See {ref}`cli-fs` for more information. The `plugin` command creates plugins, installs them, and executes plugin-specific operations. +See {ref}`cli-plugin` for more information. + +**Plugin creation** + +:::{versionadded} 25.04.0 +::: + Create a new plugin scaffold for development: ```console $ nextflow plugin create ``` +**Plugin installation** + Install a plugin to extend Nextflow's functionality: ```console $ nextflow plugin install my-plugin ``` +**Plugin execution** + Execute plugin-specific commands using the format `plugin-name:command`: ```console $ nextflow plugin my-plugin:hello --alpha --beta ``` -See {ref}`using-plugins-page` and {ref}`cli-plugin` for more information. See individual plugin documentation for plugin specific commands. +See individual plugin documentation for plugin specific commands. ### Nextflow updates @@ -564,4 +602,4 @@ Use this to learn about command-specific options, refresh your memory about synt ```console $ nextflow help run $ nextflow help clean -``` \ No newline at end of file +``` From 8e6742769a64a696c792ed526e649dda8eb12247 Mon Sep 17 00:00:00 2001 From: Christopher Hakkaart Date: Tue, 4 Nov 2025 12:58:02 +1300 Subject: [PATCH 08/13] Remove bug Signed-off-by: Christopher Hakkaart --- docs/cli.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/cli.md b/docs/cli.md index 54f165aebd..ab0e7d6e41 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -93,10 +93,6 @@ $ nextflow -Dfile.encoding=UTF-8 run nextflow-io/hello See {ref}`config-env-vars` for more information. -### Debug - --remote-debug - ### Help display The `-h` option shows available commands and global options. From 5ee4925c2266d6c9d5a2d3f2638ee321da09322b Mon Sep 17 00:00:00 2001 From: Christopher Hakkaart Date: Tue, 4 Nov 2025 13:21:08 +1300 Subject: [PATCH 09/13] Try different language Signed-off-by: Christopher Hakkaart --- docs/cli.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/cli.md b/docs/cli.md index ab0e7d6e41..fc4d0d3298 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -145,7 +145,7 @@ $ nextflow run main.nf **Remote pipelines** -Run a pipeline from directly from Git repositories without manual downloading. Use the format `/`: +Use the format `/` to run a pipeline from directly from Git repositories: ```console $ nextflow run nextflow-io/hello @@ -167,7 +167,7 @@ $ nextflow run https://github.com/nextflow-io/hello **Private repositories** -Add credentials for private repositories with the `-user` option: +Use the `-user` option to add credentials for private repositories: ```console $ nextflow run owner/private-repo -user my-username @@ -177,7 +177,7 @@ Alternatively, configure Git authentication. See {ref}`Git configuration Date: Tue, 4 Nov 2025 16:07:58 +1300 Subject: [PATCH 10/13] Fix language Signed-off-by: Christopher Hakkaart --- docs/cli.md | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/docs/cli.md b/docs/cli.md index fc4d0d3298..5dc19b2abe 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -8,7 +8,6 @@ For the complete reference of all commands, subcommands, and options, see {ref}` :::{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. ::: @@ -145,7 +144,7 @@ $ nextflow run main.nf **Remote pipelines** -Use the format `/` to run a pipeline from directly from Git repositories: +Use the format `/` to run a pipeline from directly from Git repositories: ```console $ nextflow run nextflow-io/hello @@ -157,7 +156,7 @@ Nextflow automatically: 2. Caches it for future runs 3. Executes the main script -If you omit the owner, Nextflow searches cached pipelines first, then attempts to download from the `NXF_ORG` organization (default: `nextflow-io`). +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: @@ -170,7 +169,7 @@ $ nextflow run https://github.com/nextflow-io/hello Use the `-user` option to add credentials for private repositories: ```console -$ nextflow run owner/private-repo -user my-username +$ nextflow run organization/private-repo -user my-username ``` Alternatively, configure Git authentication. See {ref}`Git configuration ` for more information. @@ -180,7 +179,7 @@ Alternatively, configure Git authentication. See {ref}`Git configuration Date: Wed, 5 Nov 2025 16:41:05 -0600 Subject: [PATCH 11/13] Remove top-level options reference Signed-off-by: Ben Sherman --- docs/cli.md | 158 ++++++++++++------------------------------ docs/reference/cli.md | 18 ++--- 2 files changed, 56 insertions(+), 120 deletions(-) diff --git a/docs/cli.md b/docs/cli.md index 5dc19b2abe..7ddb67f459 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -12,118 +12,6 @@ Nextflow uses two types of command line flags: - 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. - -```console -$ nextflow -c my.config run nextflow-io/hello -``` - -See {ref}`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. - -```console -$ nextflow -C my.config run nextflow-io/hello -``` - -See {ref}`config-page` 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. - -```console -$ 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. - -```console -$ 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. - -```console -$ nextflow -log /var/log/nextflow.log run nextflow-io/hello -``` - -### Syslog integration - -The `-syslog` option sends logs to a [Syslog](https://en.wikipedia.org/wiki/Syslog) server for centralized log management. - -Use this to aggregate Nextflow logs with other system logs to enable centralized monitoring and analysis. - -```console -$ 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. - -```console -$ nextflow -Dfile.encoding=UTF-8 run nextflow-io/hello -``` - -See {ref}`config-env-vars` 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. - -```console -$ nextflow -h -``` - -### Version information - -The `-v` and `-version` options prints Nextflow version information. - -Use `-v` for minimal output showing version and build number. - -```console -$ nextflow -v -nextflow version 24.04.0.5917 -``` - -Use `-version` for detailed output showing creation date, citation, and website. - -```console -$ 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. @@ -388,6 +276,30 @@ $ nextflow config nextflow-io/hello See {ref}`cli-config` for more information. +### 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. + +```console +$ nextflow -c my.config run nextflow-io/hello +``` + +See {ref}`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. + +```console +$ nextflow -C my.config run nextflow-io/hello +``` + +See {ref}`config-page` for more information. + ### Process inspection :::{versionadded} 23.09.0-edge @@ -598,3 +510,25 @@ Use this to learn about command-specific options, refresh your memory about synt $ nextflow help run $ nextflow help clean ``` + +### Version information + +The `-v` and `-version` options print Nextflow version information. + +Use `-v` for minimal output showing version and build number. + +```console +$ nextflow -v +nextflow version 24.04.0.5917 +``` + +Use `-version` for detailed output showing creation date, citation, and website. + +```console +$ 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 +``` diff --git a/docs/reference/cli.md b/docs/reference/cli.md index 097c77b9e9..323e6af8df 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -16,10 +16,11 @@ Available options: : Comma-separated list of configuration files which are used as the configuration set. Any other default configuration files are ignored. `-D` -: Set JVM properties. +: Set JVM properties (e.g. `-Dfile.encoding=UTF-8`). Equivalent to the `NXF_JVM_ARGS` environment variable. `-bg` -: Execute nextflow in background. +: 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. @@ -27,22 +28,23 @@ Available options: `-d, -dockerize` : :::{deprecated} 23.09.0-edge ::: -: Launch nextflow via Docker (experimental). +: Launch Nextflow via Docker (experimental). `-h` -: Print this help. +: Print available commands and options. `-log` -: Set nextflow log file path. +: Set Nextflow log file path (default: `.nextflow.log`). `-q, -quiet` -: Do not print information messages. +: Do not print the Nextflow banner and execution progress to the console. +: Does not affect messages printed by the pipeline or error messages. `-remote-debug` : Enable JVM interactive remote debugging (experimental). `-syslog` -: Send logs to syslog server (e.g. localhost:514). +: 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`. @@ -56,7 +58,7 @@ Available options: ### `auth` -:::{versionadded} 25.09.0-edge +:::{versionadded} 25.10.0 ::: Manage Seqera Platform authentication. From 87f4d3e104fcfd257f7f2635e46b497590beeca7 Mon Sep 17 00:00:00 2001 From: Christopher Hakkaart Date: Thu, 6 Nov 2025 16:05:03 +1300 Subject: [PATCH 12/13] Minor revisions Signed-off-by: Christopher Hakkaart --- docs/cli.md | 35 +++++++++++++++++------------------ 1 file changed, 17 insertions(+), 18 deletions(-) diff --git a/docs/cli.md b/docs/cli.md index 7ddb67f459..f3e80b21e4 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -210,7 +210,7 @@ See {ref}`cli-pull` for more information. 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. +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. ```console $ nextflow view nextflow-io/hello @@ -259,22 +259,9 @@ See {ref}`cli-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. +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 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. - -```console -$ nextflow config -$ nextflow config nextflow-io/hello -``` - -See {ref}`cli-config` for more information. +Use these to customize pipeline configuration, debug configuration issues, verify settings, and catch issues before execution. ### Soft configuration override @@ -300,6 +287,19 @@ $ nextflow -C my.config run nextflow-io/hello See {ref}`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. + +```console +$ nextflow config +$ nextflow config nextflow-io/hello +``` + +See {ref}`cli-config` for more information. + ### Process inspection :::{versionadded} 23.09.0-edge @@ -493,7 +493,7 @@ See individual plugin documentation for plugin specific commands. 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. +Use this to upgrade Nextflow, switch versions, or install edge releases. By default, it updates to the latest stable release. Specify a particular version or use the `NXF_EDGE` environment variable for development releases. ```console $ nextflow self-update @@ -508,7 +508,6 @@ Use this to learn about command-specific options, refresh your memory about synt ```console $ nextflow help run -$ nextflow help clean ``` ### Version information From c252b956a199df021e2e42079b05ba11a5021ce4 Mon Sep 17 00:00:00 2001 From: Ben Sherman Date: Thu, 6 Nov 2025 08:22:35 -0600 Subject: [PATCH 13/13] update version callouts Signed-off-by: Ben Sherman --- docs/cli.md | 2 +- docs/reference/cli.md | 22 ++++++++-------------- 2 files changed, 9 insertions(+), 15 deletions(-) diff --git a/docs/cli.md b/docs/cli.md index f3e80b21e4..d8d3d94cc7 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -302,7 +302,7 @@ See {ref}`cli-config` for more information. ### Process inspection -:::{versionadded} 23.09.0-edge +:::{versionadded} 23.10.0 ::: The `inspect` command analyzes process settings in a pipeline without executing it. It outputs container information in JSON or Nextflow configuration format. diff --git a/docs/reference/cli.md b/docs/reference/cli.md index 323e6af8df..188c22779b 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -26,7 +26,7 @@ Available options: : Comma-separated list of configuration files which are added to the configuration set. `-d, -dockerize` -: :::{deprecated} 23.09.0-edge +: :::{deprecated} 23.10.0 ::: : Launch Nextflow via Docker (experimental). @@ -321,7 +321,7 @@ The `config` command is used for printing the project's configuration i.e. the ` : Sort config attributes. `-value` -: :::{versionadded} 23.08.0-edge +: :::{versionadded} 23.10.0 ::: : Print the value of a config option, or fail if the option is not defined. @@ -620,7 +620,7 @@ $ nextflow info nextflow-io/hello ### `inspect` -:::{versionadded} 23.09.0-edge +:::{versionadded} 23.10.0 ::: Inspect process settings in a pipeline project. Currently only supports the `container` directive. @@ -730,22 +730,18 @@ The `kuberun` command supports the following options from [`run`](#run): The following new options are also available: `-head-cpus` -: :::{versionadded} 22.01.0-edge - ::: : Specify number of CPUs requested for the Nextflow pod. `-head-image` -: :::{versionadded} 22.07.1-edge +: :::{versionadded} 22.10.0 ::: : Specify the container image for the Nextflow driver pod. `-head-memory` -: :::{versionadded} 22.01.0-edge - ::: : Specify amount of memory requested for the Nextflow pod. `-head-prescript` -: :::{versionadded} 22.05.0-edge +: :::{versionadded} 22.10.0 ::: : Specify script to be run before the Nextflow pod starts. @@ -1238,12 +1234,12 @@ The `run` command is used to execute a local pipeline script or remote pipeline : Prevent the cancellation of child jobs on execution termination `-dsl1` -: :::{deprecated} 23.09.0-edge +: :::{deprecated} 23.10.0 ::: : Execute the workflow using DSL1 syntax. `-dsl2` -: :::{deprecated} 23.09.0-edge +: :::{deprecated} 23.10.0 ::: : Execute the workflow using DSL2 syntax. @@ -1278,8 +1274,6 @@ The `run` command is used to execute a local pipeline script or remote pipeline : Library extension path. `-main-script` (`main.nf`) -: :::{versionadded} 20.09.1-edge - ::: : The script file to be executed when launching a project directory or repository. `-name` @@ -1300,7 +1294,7 @@ The `run` command is used to execute a local pipeline script or remote pipeline : Comma separated list of plugin ids to be applied in the pipeline execution. `-preview` -: :::{versionadded} 22.06.0-edge +: :::{versionadded} 22.10.0 ::: : Run the workflow script skipping the execution of all processes.