add documentation and tests

Signed-off-by: jorgee <jorge.ejarque@seqera.io>

Author: jorgee

docs/cli.md

@@ -262,7 +262,120 @@ $ 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.
+
+### 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.auth` 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,187 @@ $ 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-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]`
+
+: Publish a module to the registry, making it available for others to install.
+: Requires authentication via `NXF_REGISTRY_TOKEN` environment variable or `registry.auth` 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

@@ -55,9 +55,11 @@ dependencies {
     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.20.1'
 
     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/module/ModuleInstall.groovy

@@ -26,9 +26,12 @@ import nextflow.config.ModulesConfig
 import nextflow.config.RegistryConfig
 import nextflow.exception.AbortOperationException
 import nextflow.module.ModuleReference
+import nextflow.module.ModuleRegistryClient
 import nextflow.module.ModuleResolver
 import nextflow.pipeline.PipelineSpec
+import nextflow.util.TestOnly
 
+import java.nio.file.Path
 import java.nio.file.Paths
 
 /**
@@ -50,6 +53,12 @@ class ModuleInstall extends CmdBase {
     @Parameter(description = "[scope/name]", required = true)
     List<String> args
 
+    @TestOnly
+    protected Path root
+
+    @TestOnly
+    protected ModuleRegistryClient client
+
     @Override
     String getName() {
         return 'install'
@@ -66,21 +75,19 @@ class ModuleInstall extends CmdBase {
         def reference = ModuleReference.parse(moduleRef)
 
         // Get config
-        def baseDir = Paths.get('.').toAbsolutePath().normalize()
+        def baseDir = root ?: Paths.get('.').toAbsolutePath().normalize()
         def config = new ConfigBuilder()
                 .setOptions(launcher.options)
                 .setBaseDir(baseDir)
                 .build()
-        def registryConfig = config.navigate('registry') as RegistryConfig
+        final registryConfig = config.navigate('registry') as RegistryConfig
 
-        //TODO: Decide final location of modules currently in nextflow_spec.json.
-        // Alternative: Use nextflow config. It requires to implement nextflow.config updater features
-        // def modulesConfig = config.navigate('modules') as ModulesConfig
-        def specFile = new PipelineSpec(baseDir)
-        def modulesConfig = new ModulesConfig(specFile.getModules())
+        // Get modules versions from nextflow_spec.json.
+        final specFile = new PipelineSpec(baseDir)
+        final modulesConfig = new ModulesConfig(specFile.getModules())
 
         // Create resolver and install
-        def resolver = new ModuleResolver(baseDir, modulesConfig, registryConfig)
+        def resolver = new ModuleResolver(baseDir, client ?: new ModuleRegistryClient(registryConfig), modulesConfig)
 
         try {
             def installedMainFile = resolver.installModule(reference, version, force)