Module System Implementation

docs/cli.md

@@ -262,7 +262,136 @@ $ nextflow secrets set AWS_ACCESS_KEY_ID
 $ nextflow secrets delete AWS_ACCESS_KEY_ID
 ```
 
-See {ref}`cli-secrets` for more information. 
+See {ref}`cli-secrets` for more information.
+
+## Module management
+
+:::{versionadded} 26.04.0
+:::
+
+Module management commands enable working with reusable, registry-based modules. The Nextflow module system allows you to install, run, search, and publish standardized modules from registries, eliminating duplicate work and spreading improvements throughout the community.
+
+Use these commands to discover modules in registries, install them into your project, run them directly without creating a workflow, and publish your own modules for others to use.
+
+### Installing modules
+
+The `module install` command downloads modules from a registry and makes them available in your workflow. Modules are stored locally in the `modules/` directory and version information is tracked in `nextflow_spec.json`.
+
+Use this to add reusable modules to your pipeline, manage module versions, or update modules to newer versions.
+
+```console
+$ nextflow module install nf-core/fastqc
+$ nextflow module install nf-core/fastqc -version 1.0.0
+```
+
+After installation, module will be available in `modules/@nf-core/fastqc` and included in `nextflow_spec.json` 
+
+Use the `-force` flag to reinstall a module even if local modifications exist.
+
+See {ref}`cli-module-install` for more information.
+
+### Running modules directly
+
+The `module run` command executes a module directly from the registry without requiring a wrapper workflow. This provides immediate access to module functionality for ad-hoc tasks or testing.
+
+Use this to quickly run a module, test module functionality, or execute one-off data processing tasks.
+
+```console
+$ nextflow module run nf-core/fastqc --input 'data/*.fastq.gz'
+$ nextflow module run nf-core/fastqc --input 'data/*.fastq.gz' -version 1.0.0
+```
+
+The command accepts all standard Nextflow execution options (`-profile`, `-resume`, etc.):
+
+```console
+$ nextflow module run nf-core/salmon \
+    --reads reads.fq \
+    --index salmon_index \
+    -profile docker \
+    -resume
+```
+
+See {ref}`cli-module-run` for more information.
+
+### Listing modules
+
+The `module list` command displays all modules currently installed in your project, showing their versions and integrity status.
+
+Use this to review installed modules, check module versions, or detect local modifications.
+
+```console
+$ nextflow module list
+$ nextflow module list -json
+```
+
+The output shows each module's name, installed version, and whether it has been modified locally. Use `-json` for machine-readable output suitable for scripting.
+
+See {ref}`cli-module-list` for more information.
+
+### Searching for modules
+
+The `module search` command queries the module registry to discover available modules by keyword or name.
+
+Use this to find modules for specific tasks, explore available tools, or discover community contributions.
+
+```console
+$ nextflow module search alignment
+$ nextflow module search "quality control" -limit 10
+$ nextflow module search bwa -json
+```
+
+Results include module names, versions, descriptions, and download statistics. Use `-limit` to control the number of results and `-json` for programmatic access.
+
+See {ref}`cli-module-search` for more information.
+
+### Viewing module information
+
+The `module info` command displays detailed metadata and usage information for a specific module from the registry.
+
+Use this to understand module requirements, view input/output specifications, see available tools, or generate usage templates before installing or running a module.
+
+```console
+$ nextflow module info nf-core/fastqc
+$ nextflow module info nf-core/fastqc -version 1.0.0
+$ nextflow module info nf-core/fastqc -json
+```
+
+The output includes the module's version, description, authors, keywords, tools, input/output channels, and a generated usage template showing how to run the module. Use `-json` for machine-readable output suitable for programmatic access.
+
+See {ref}`cli-module-info` for more information.
+
+### Removing modules
+
+The `module remove` command deletes modules from your project, removing local files and configuration entries.
+
+Use this to clean up unused modules, free disk space, or remove deprecated modules from your pipeline.
+
+```console
+$ nextflow module remove nf-core/fastqc
+$ nextflow module remove nf-core/fastqc -keep-config
+$ nextflow module remove nf-core/fastqc -keep-files
+```
+
+By default, both local files and configuration entries are removed. Use `-keep-config` to preserve version information in `nextflow_spec.json`, or `-keep-files` to remove only the configuration entry while keeping local files.
+
+See {ref}`cli-module-remove` for more information.
+
+### Publishing modules
+
+The `module publish` command uploads modules to a registry, making them available for others to install and use.
+
+Use this to share your modules with the community, contribute to module libraries, or distribute modules within your organization.
+
+```console
+$ nextflow module publish myorg/my-module
+$ nextflow module publish myorg/my-module -dry-run
+```
+
+Publishing requires authentication via the `NXF_REGISTRY_TOKEN` environment variable or `registry.apiKey` in the Nextflow configuration. The module must include `main.nf`, `meta.yaml`, and `README.md` files.
+
+Use `-dry-run` to validate your module structure without uploading.
+
+See {ref}`cli-module-publish` for more information.
 
 ## Configuration and validation
 

docs/reference/cli.md

@@ -1125,6 +1125,215 @@ $ nextflow log tiny_leavitt -F 'process =~ /split_letters/'
 work/1f/f1ea9158fb23b53d5083953121d6b6
 ```
 
+(cli-module)=
+
+### `module`
+
+:::{versionadded} 26.04.0
+:::
+
+Manage Nextflow modules from registries.
+
+**Usage**
+
+```console
+$ nextflow module <subcommand> [options]
+```
+
+**Description**
+
+The `module` command provides a comprehensive system for managing reusable, registry-based modules. It enables installing modules from registries, running them directly, searching for available modules, and publishing your own modules for community use.
+
+**Subcommands**
+
+(cli-module-install)=
+
+`install [options] [scope/name]`
+
+: Install a module from the registry into your project.
+: Downloaded modules are stored in the `modules/` directory and version information is tracked in `nextflow_spec.json`.
+: The following options are available:
+
+  `-version`
+  : Specify the module version to install (e.g., `1.0.0`). If not specified, installs the latest version.
+
+  `-force`
+  : Force reinstall even if the module exists locally with modifications. Without this flag, Nextflow prevents overwriting locally modified modules.
+
+: **Examples:**
+
+  ```console
+  # Install latest version
+  $ nextflow module install nf-core/fastqc
+
+  # Install specific version
+  $ nextflow module install nf-core/fastqc -version 1.0.0
+
+  # Force reinstall over local modifications
+  $ nextflow module install nf-core/fastqc -force
+  ```
+
+(cli-module-run)=
+
+`run [options] [scope/name] [--<input_name> <input-value>]`
+
+: Execute a module directly from the registry without creating a wrapper workflow.
+: Automatically downloads the module if not already installed. Accepts all standard Nextflow run options.
+: The following options are available:
+
+  `-version`
+  : Specify the module version to run (e.g., `1.0.0`). If not specified, uses the latest version.
+
+  All standard `run` command options
+  : The `module run` command extends the `run` command and accepts all its options, including `-profile`, `-resume`, `-c`, etc.
+
+: **Examples:**
+
+  ```console
+  # Run module with inputs
+  $ nextflow module run nf-core/fastqc --input 'data/*.fastq.gz'
+
+  # Run specific version with Nextflow options
+  $ nextflow module run nf-core/fastqc \
+      --input 'data/*.fastq.gz' \
+      -version 1.0.0 \
+      -profile docker \
+      -resume
+  ```
+
+(cli-module-list)=
+
+`list [options]`
+
+: List all modules currently installed in your project.
+: Shows module names, versions, and integrity status (whether they've been modified locally).
+: The following options are available:
+
+  `-json`
+  : Output results in JSON format for programmatic processing.
+
+: **Examples:**
+
+  ```console
+  # Display installed modules in formatted table
+  $ nextflow module list
+
+  # Output as JSON
+  $ nextflow module list -json
+  ```
+
+(cli-module-search)=
+
+`search [options] [query]`
+
+: Search for modules in the registry by keyword or name.
+: Returns modules matching the query with their names, versions, descriptions, and download statistics.
+: The following options are available:
+
+  `-limit`
+  : Maximum number of results to return (default: varies by registry).
+
+  `-json`
+  : Output results in JSON format for programmatic processing.
+
+: **Examples:**
+
+  ```console
+  # Search for alignment-related modules
+  $ nextflow module search alignment
+
+  # Search with limited results
+  $ nextflow module search "quality control" -limit 10
+
+  # Get results as JSON
+  $ nextflow module search bwa -json
+  ```
+
+(cli-module-info)=
+
+`info [options] [scope/name]`
+
+: Display detailed information about a module from the registry.
+: Shows module metadata, version, description, authors, keywords, tools, input/output specifications, and generates a usage template.
+: The following options are available:
+
+  `-version`
+  : Specify the module version to query (e.g., `1.0.0`). If not specified, displays information for the latest version.
+
+  `-json`
+  : Output results in JSON format for programmatic processing.
+
+: **Examples:**
+
+  ```console
+  # Display information for latest version
+  $ nextflow module info nf-core/fastqc
+
+  # Display information for specific version
+  $ nextflow module info nf-core/fastqc -version 1.0.0
+
+  # Get results as JSON
+  $ nextflow module info nf-core/fastqc -json
+  ```
+
+(cli-module-remove)=
+
+`remove [options] [scope/name]`
+
+: Remove a module from your project.
+: By default, removes both local files and configuration entries. Use options to control what gets removed.
+: The following options are available:
+
+  `-keep-config`
+  : Keep the version entry in `nextflow_spec.json` but delete local files from the `modules/` directory.
+
+  `-keep-files`
+  : Remove the version entry from `nextflow_spec.json` but keep local files in the `modules/` directory.
+
+: **Examples:**
+
+  ```console
+  # Remove module completely
+  $ nextflow module remove nf-core/fastqc
+
+  # Delete files but keep version config
+  $ nextflow module remove nf-core/fastqc -keep-config
+
+  # Remove from config but keep local files
+  $ nextflow module remove nf-core/fastqc -keep-files
+  ```
+
+(cli-module-publish)=
+
+`publish [options] [scope/name | path]`
+
+: Publish a module to the registry, making it available for others to install.
+: The argument can be either a `scope/name` reference (for an already-installed module) or a local directory path containing the module files.
+: Requires authentication via `NXF_REGISTRY_TOKEN` environment variable or `registry.apiKey` configuration.
+: The module directory must contain `main.nf`, `meta.yaml`, and `README.md`.
+: The following options are available:
+
+  `-dry-run`
+  : Validate the module structure and metadata without uploading to the registry. Useful for testing before publishing.
+
+  `-registry`
+  : Specify the registry to publish the module (default: `https://registry.nextflow.io`)
+
+: **Examples:**
+
+  ```console
+  # Validate module structure without publishing
+  $ nextflow module publish myorg/my-module -dry-run
+
+  # Publish to nextflow registry
+  $ export NXF_REGISTRY_TOKEN=your-token
+  $ nextflow module publish myorg/my-module
+
+  # Publish to a custom registry
+  $ export NXF_REGISTRY_TOKEN=your-token
+  $ nextflow module publish myorg/my-module -registry 'https://custom.registry.com'
+  ```
+
 (cli-plugin)=
 
 ### `plugin`

modules/nextflow/build.gradle

@@ -70,9 +70,12 @@ dependencies {
     api 'dev.failsafe:failsafe:3.1.0'
     api 'io.seqera:lib-trace:0.1.0'
     api 'com.fasterxml.woodstox:woodstox-core:7.1.1'
+    api 'org.apache.commons:commons-compress:1.27.1'  // For tar.gz extraction
+    api 'io.seqera:npr-api:0.21.4-SNAPSHOT'
 
     testImplementation 'org.subethamail:subethasmtp:3.1.7'
     testImplementation (project(':nf-lineage'))
+    testImplementation 'org.wiremock:wiremock:3.13.1'
     // test configuration
     testFixturesApi ("org.apache.groovy:groovy-test:4.0.30") { exclude group: 'org.apache.groovy' }
     testFixturesApi ("org.objenesis:objenesis:3.4")

modules/nextflow/src/main/groovy/nextflow/cli/CmdBase.groovy

@@ -26,9 +26,14 @@ import com.beust.jcommander.Parameter
 abstract class CmdBase implements Runnable {
 
     private Launcher launcher
+    private List<String> unknownOptions
 
     abstract String getName()
 
+    protected List<String> getUnknownOptions(){ return this.unknownOptions }
+
+    void setUnknownOptions(List<String> options){ this.unknownOptions = options }
+
     Launcher getLauncher() { launcher }
 
     void setLauncher( Launcher value ) { this.launcher = value }