CLI reference

Generated from code

This page is produced by scripts/gen_cli_reference.py, which introspects the live Click application. It is regenerated on every CLI change and CI asserts it is current — so it cannot drift from the actual commands. Do not edit by hand.

The commands below are introspected from the installed package. Invoke any command with -h/--help for full help.

components

Inspect available component types (core + plugins).

Sub-commands: list

components list

List core + discovered plugin components (source + sandbox status).

Flag / arg	Kind	Type	Required	Default	Description
--json	option	boolean	no		Emit machine-readable JSON instead of the human table.

diff

Show what changes in the generated workflow between two workflow.yaml.

Flag / arg	Kind	Type	Required	Default	Description
YAML_A	argument	file	no
YAML_B	argument	file	no
--from-gist	option	text	no		Fetch the LEFT-side workflow.yaml from a public GitHub Gist URL and diff against the local YAML path passed as the (one) remaining positional arg. Two-gist diff is not supported in v0. (Phase 8 §2C, decision D2.)
--no-cache	option	boolean	no		When —from-gist is set, bypass the local cache and re-fetch.
--format	option	choice	no	unified	Output format: a unified text diff, or a JSON {added, removed} structure.
--context, -n	option	integer	no	3	Lines of unified-diff context.

doctor

Unprivileged preflight: probe the host this tool will run on.

Flag / arg	Kind	Type	Required	Default	Description
WORKFLOW_YAML	argument	file	no
--json	option	boolean	no		Emit a machine-readable JSON object on stdout (human table -> stderr).
--cylc-run-dir	option	path	no		Override the cylc-run dir to check (default: $CYLC_RUN_DIR or ~/cylc-run).
--min-free-gb	option	float	no	2.0	Minimum free-space threshold (GB) for yellow/red space checks.
--port	option	integer	no	8765	GUI port to probe for availability (mirrors gui --port).
--no-color	option	boolean	no		Suppress ANSI colour; useful for log files and CI.

generate

Render a workflow.yaml into a runnable Cylc 8 workflow.

Flag / arg	Kind	Type	Required	Default	Description
WORKFLOW_YAML	argument	file	yes
--output, -o	option	directory	no		Output directory. Required unless —dry-run.
--dry-run	option	boolean	no		Render to stdout instead of writing to —output. (Plan §4.2.)
--engine	option	choice	no	cylc	Execution engine. Only cylc is implemented; flag exists for future-proofing.
--no-warnings	option	boolean	no		Suppress non-fatal soft-warnings (W1–W3) printed to stderr.
--mode	option	choice	no	live	Cylc run mode the rendered flow is intended for. ‘dummy’ adds a top-of-file banner reminding the operator to cylc play --main-loop dummy_bridge (per [[project-phase-2-6-cleanup]] memory; OC-1). Does not change the rendered graph — Cylc’s own --mode=dummy is set at play time. The banner is plain text and inert to cylc.

gui

Open the nwp-compose read/operate GUI.

Flag / arg	Kind	Type	Required	Default	Description
--port	option	integer	no	8765	Port for local mode. Falls back to 8000-9000 on collision.
--local	option	boolean	no		Force local mode even if config.yaml declares a hosted_url.
--url	option	text	no		Open this exact URL (overrides config + local mode).
--print-url	option	boolean	no		Print only the bare URL on stdout and exit, without booting a server or opening a browser. Use for shell pipelines like URL=$(nwp-compose gui --print-url). For SSH tunneling, use --no-browser instead (boots the server, prints the announce line).
--no-browser	option	boolean	no		Boot the server, print the URL, but do NOT open the browser.
--cylc-run-dir	option	path	no		Override the cylc-run directory (default: ~/cylc-run).
--config	option	path	no		Override the config file path (default: ~/.nwp-compose/config.yaml).

import-cron

Assisted migration from a personal bash/cron NWP setup into a starter workflow.yaml.

Flag / arg	Kind	Type	Required	Default	Description
--cron, -c	option	text	no	Sentinel.UNSET	A crontab line or schedule (the hour field drives the cycling cadence), e.g. ‘0 0,6,12,18 * * *’.
--script, -s	option	file	no	Sentinel.UNSET	A driver bash script to scan for model executables.
--output, -o	option	file	no	imported-workflow.yaml	Starter workflow.yaml to write.
--report	option	file	no		Migration report path (default: <output>.MIGRATION.md).
--force	option	boolean	no		Overwrite the output/report if they exist.
--validate-after	option	boolean	no		Run nwp-compose validate on the generated starter and report the result.

migrate

Upgrade a workflow.yaml to the current schema version with a visible diff.

Flag / arg	Kind	Type	Required	Default	Description
WORKFLOW_YAML	argument	file	yes
--write, -w	option	boolean	no		Overwrite the file in place (after backing it up to <file>.bak). Default is dry-run: show the diff, write nothing.
--force	option	boolean	no		Permit clobbering an existing <file>.bak when writing.
--to	option	integer	no		Target schema version (default: current = 0).

namelist

Interactively configure a component’s namelist (templated or BYO).

Flag / arg	Kind	Type	Required	Default	Description
-c, --component	option	text	yes	Sentinel.UNSET	Component type to configure (wrf, real, or geogrid in this build).
--mode	option	choice	yes	Sentinel.UNSET	templated: prompt schema params + preview render. byo: dry-run patch your own namelist’s cycle keys.
--byo-file	option	file	no		BYO mode: path to your existing namelist file (required for —mode byo).
--dry-run	option	boolean	no		Preview only — write no files and exit 0.
-o, --output	option	file	no		Templated mode: workflow.yaml to create/update (default ./workflow.yaml).
--force	option	boolean	no		Templated mode: overwrite —output if it already exists.
--no-warnings	option	boolean	no		Templated mode: suppress soft warnings (does not suppress the W-7..W-10 unphysical block).

new

Scaffold a starter workflow.yaml from a known-good template or a gist URL.

Flag / arg	Kind	Type	Required	Default	Description
--template	option	text	no		Template to scaffold (run nwp-compose new --template ? for the list).
--from-gist	option	text	no		Fetch a workflow.yaml from a public GitHub Gist URL (supports the #filename selector for multi-file gists). Mutually exclusive with —template. (Phase 8 §2C.)
--no-cache	option	boolean	no		When —from-gist is set, bypass the local cache and re-fetch.
--output, -o	option	file	no		Destination YAML file. Defaults to ./<template>.yaml or ./workflow.yaml.
--force	option	boolean	no		Overwrite the destination file if it already exists.

run

Validate, generate, install, and play a workflow.yaml in one command.

Flag / arg	Kind	Type	Required	Default	Description
WORKFLOW_YAML	argument	file	yes
--output, -o	option	directory	no		Output directory for generate. Defaults to ./out/ beside the YAML.
--dummy	option	boolean	no		Generate with —mode=dummy, then play with —mode=dummy —main-loop dummy_bridge. Exercises the graph without real binaries (aliases cluster platforms to localhost background so the dummy play runs on a box without SLURM).
--dry-run	option	boolean	no		Stop after generate; print the workflow id and the exact cylc commands that WOULD run. No install, no scheduler.
--no-play	option	boolean	no		Run validate + generate + cylc install, but stop before cylc play.
--no-warnings	option	boolean	no		Pass —no-warnings through to validate + generate (suppresses W1–W6).

schema

Introspect the component schema (GUI exporter, etc.).

Sub-commands: widgets

schema widgets

Emit per-component GUI form-field descriptors as JSON.

Flag / arg	Kind	Type	Required	Default	Description
--component, -c	option	text	no		Export only this component_type (default: all components).
--output, -o	option	file	no		Write JSON to this path instead of stdout.
--indent	option	integer	no	2	JSON indent (use 0 for compact single-line output).

tutorial

Guided, exitable walkthrough that builds a valid workflow.yaml.

Flag / arg	Kind	Type	Required	Default	Description
--output, -o	option	file	no	tutorial-workflow.yaml	Destination YAML. Written ONLY at the final confirm step.
--force	option	boolean	no		Overwrite the destination file if it already exists.
--non-interactive	option	boolean	no		Run the full arc with defaults — no prompts, no network. CI-safe.
--replay	option	file	no		Load an existing YAML and replay the tutorial against its choices as defaults. Mutually exclusive with —non-interactive.
--engine	option	choice	no	mpas	Which NWP path to walk (selects the lesson + starting template).
--chapter	option	integer range	no		Jump straight to one chapter (1–6), print it, and exit.

validate

Validate a workflow.yaml against the schema and graph rules.

Flag / arg	Kind	Type	Required	Default	Description
WORKFLOW_YAML	argument	file	no
--from-gist	option	text	no		Fetch a workflow.yaml from a public GitHub Gist URL and validate in place — never writes to disk. Mutually exclusive with the positional workflow_yaml argument. (Phase 8 §2C.)
--no-cache	option	boolean	no		When —from-gist is set, bypass the local cache and re-fetch.
--cylc	option	boolean	no		After schema validation, render to a tempdir and run cylc validate.
--no-warnings	option	boolean	no		Suppress non-fatal soft-warnings (W1–W6).