Quick start

This is the fast path for someone who already knows what they want. New to the concepts? Take the guided tutorial instead — it teaches the why at each step.

The one-command path

nwp-compose new --template bahamas-mpas-rap -o my_run.yaml
nwp-compose run my_run.yaml

nwp-compose run chains validate → generate → cylc install → cylc play, stops at the first failure with a message that names the step, and prints the concrete Cylc workflow id it started (for example my_run/run1) so you never have to guess it. Add --dry-run to stop after generate and see exactly what it would run, or --dummy to exercise the graph without real binaries.

Run the preflight first on a new node

nwp-compose doctor

checks Python/Cylc versions, venv health, write access and free space on your run and cache dirs, and per-component prerequisite executables — turning a silent runtime failure into an actionable message before you commit a six-hour job.

The explicit path (what run does for you)

If you prefer to drive each step yourself — or you want to understand what run wraps:

1. Scaffold a starter from the template gallery:

   nwp-compose new --template bahamas-mpas-rap -o my_run.yaml

2. Validate the schema, the component graph, and the physics (CFL, decomposition):

   nwp-compose validate my_run.yaml          # add --cylc to also run `cylc validate`

   A physically unsafe configuration (e.g. a CFL-violating time step) is blocked, not merely warned — see the warning catalog.

3. Generate the runnable bundle into ./out/:

   nwp-compose generate my_run.yaml -o ./out/

   This writes flow.cylc, manifest.json, the component task scripts, the runtime lib, and the rendered namelists. Use --dry-run to print flow.cylc to stdout and write nothing — the trust loop for the schema.

4. Install with Cylc. This is the step that assigns the workflow id:

   cylc install ./out/
   # INSTALLED my_run/run1 from ./out      ← "my_run/run1" is your <workflow_id>

5. Play it:

   cylc play my_run/run1
   # exercise the graph without real binaries:
   cylc play --mode=dummy --main-loop dummy_bridge my_run/run1

The workflow id is what Cylc prints, not your output directory

./out/ is the source directory you generated. The workflow id is what cylc install prints (my_run/run1) and is what every later cylc command takes. nwp-compose run captures and echoes this for you so the two never get confused.

See what changed, safely upgrade

nwp-compose diff baseline.yaml tweaked.yaml   # diff at the rendered flow.cylc level
nwp-compose migrate my_run.yaml               # dry-run upgrade; --write to apply with a .bak

Next

• Tutorial: your first forecast — the guided version.
• The last mile: run & doctor — the full reference for these two commands.
• Interactive namelist configuration — tune parameters with units and validation, or bring your own namelist.