CLI reference
The commands below are introspected from the installed package. Invoke any
command with -h/--help for full help.
components
Section titled “components”Inspect available component types (core + plugins).
Sub-commands: list
components list
Section titled “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. |
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
Section titled “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
Section titled “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. |
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
Section titled “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 | A crontab line or schedule (the hour field drives the cycling cadence), e.g. ‘0 0,6,12,18 * * *’. | |
--script, -s |
option | file | no | 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
Section titled “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 = 1). |
namelist
Section titled “namelist”Interactively configure a component’s namelist (templated or BYO).
| Flag / arg | Kind | Type | Required | Default | Description |
|---|---|---|---|---|---|
-c, --component |
option | text | yes | Component type to configure (wrf, real, or geogrid in this build). | |
--mode |
option | choice | yes | 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). |
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. |
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
Section titled “schema”Introspect the component schema (GUI exporter, etc.).
Sub-commands: widgets
schema widgets
Section titled “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
Section titled “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
Section titled “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). |