Add -help-json flag for machine-readable CLI help

[ewels]

Why

Coding agents and tooling increasingly drive the Nextflow CLI, but the only machine interface to it today is the rendered -help text. Scraping that output is brittle: it's formatted for humans, wraps to the terminal width, and changes layout without notice. An LLM (or any tool) wanting to know "what flags does nextflow run take, and what type is each one?" has to parse prose.

This adds a structured, stable contract for that question. It's a direct port of the idea in nf-core/tools#4310, which added --help-json to the nf-core CLI for the same reason — so agents can discover the CLI reliably one command at a time, rather than pulling the whole tree into context or guessing from help text.

The design follows the same principles as the nf-core PR:

• Progressive disclosure. nextflow -help-json returns the global options plus an index of every command; drilling into a command (nextflow run -help-json) returns that command's full option/argument detail. Agents navigate down rather than loading everything at once.
• Introspection, not parsing. A small CliSchema class reads the JCommander @Parameter / @Parameters annotations directly — the same source of truth that drives -help — so the JSON can't drift from the real CLI.
• Discoverable. A one-line tip on the main -help screen points tools and agents at the flag.

The flag is marked as a help-style option, so it works even when required arguments are missing (just like -help).

What it looks like

nextflow -help-json — global options + a name/description index of every command:

{
  "name": "nextflow",
  "path": "nextflow",
  "usage": "nextflow [options] COMMAND [arg...]",
  "params": [ ... 11 global options ... ],
  "subcommands": {
    "run":    { "help": "Execute a pipeline project" },
    "config": { "help": "Print a project configuration" },
    "lineage":{ "help": "Explore workflows lineage metadata", "aliases": ["li"] },
    "...":    {}
  }
}

nextflow info -help-json — a single command's full detail:

{
  "name": "info",
  "path": "nextflow info",
  "usage": "nextflow info [options] [args...]",
  "params": [
    { "name": "args",     "kind": "argument", "type": "List",    "help": "project name" },
    { "name": "detailed", "kind": "option",   "type": "boolean", "opts": ["-d"], "help": "Show detailed information", "is_flag": true },
    { "name": "format",   "kind": "option",   "type": "String",  "opts": ["-o"], "help": "Output format, either: text (default), json, yaml" },
    { "name": "checkForUpdates", "kind": "option", "type": "boolean", "opts": ["-u", "-check-updates"], "help": "Check for remote updates", "is_flag": true }
  ],
  "help": "Print project and system runtime information"
}

Notes

• Hidden options and the universal meta flags (-h, -help, -help-json) are excluded from the reported parameters, matching what -help shows.
• Nextflow's command tree is flat (unlike nf-core's nested groups), so the root index lists all commands in one level. Group-style commands that dispatch their own internal sub-commands (e.g. lineage, plugin) report their own options; their sub-commands aren't yet indexed — a reasonable follow-up.
• New unit tests in CliSchemaTest cover the root schema, a command schema, and alias surfacing. Existing LauncherTest tests still pass.

🤖 Generated with Claude Code

[netlify]

✅ Deploy Preview for nextflow-docs-staging ready!

Name	Link
🔨 Latest commit	5faaca1
🔍 Latest deploy log	https://app.netlify.com/projects/nextflow-docs-staging/deploys/6a22f14c5a75df000880dd70
😎 Deploy Preview	https://deploy-preview-7198--nextflow-docs-staging.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.