The last mile: run & doctor

The single most common place a new user stalls is the gap between generating a workflow and having it running. The classic path — validate → generate → cylc install → cylc play — is four tools, two of them Cylc’s, and the crucial handoff (the workflow id Cylc assigns at install) is never named in the quick start. run and doctor close that gap.

The last mile. run collapses Validate → Play into one command; doctor checks the node first; —dummy rehearses the graph without real binaries.

nwp-compose run — one command to the finish line

nwp-compose run forecast.yaml

run performs, in order, aborting at the first failure with a message that names the failed step:

1. validate — the same schema + graph + physics gate as nwp-compose validate, including the unphysical-block (a CFL-violating config is refused here, not silently run).
2. generate — render the Cylc bundle into an output directory.
3. cylc install — and capture the concrete workflow id Cylc prints (e.g. forecast/run1).
4. cylc play — start it, echoing the id prominently so every later cylc command is obvious.

✓ validate   forecast.yaml — schema + graph + physics OK
✓ generate   → ./out/ (flow.cylc, manifest.json, 8 components)
✓ install    → forecast/run1
✓ play       forecast/run1 is now running

  Watch it:   cylc tui forecast/run1
  Stop it:    cylc stop forecast/run1

Flags

Flag	Effect
--dry-run	Stop after generate; print the workflow id it would use and the exact cylc commands. Writes the bundle, runs no Cylc.
--dummy	Exercise the graph without real binaries (cylc play --mode=dummy --main-loop dummy_bridge). Finishes in seconds.
--no-play	Validate, generate, and install — but do not play. Hands you the id to play yourself.
-o, --output <dir>	Where to generate the bundle (default a temp/./out-style dir).

It shells out to Cylc — by design

run does not reimplement Cylc; it calls cylc install and cylc play and parses their output. This honors the project’s “stay Cylc-native” discipline. If cylc is not on PATH, run stops after generate with a clear message and the exact commands to run once Cylc is available — it never pretends to have done something it didn’t.

nwp-compose doctor — preflight before you commit a long job

nwp-compose doctor                 # check the environment
nwp-compose doctor forecast.yaml   # also check this workflow's component prerequisites

doctor turns the silent “validate passed but the run died at task 1” failure mode into an explicit, actionable report. Each check is green (✓), yellow (!, advisory), or red (✗, blocking), and every non-green line prints the exact remediation:

Check	Looks for
Python	interpreter ≥ 3.12
Cylc	cylc on PATH at the expected 8.6.4
Virtualenv	an editable install that actually resolves to this checkout
Run dir	write access + free space on ~/cylc-run (honors CYLC_RUN_DIR)
Cache dir	write access on the $XDG_CACHE_HOME-aware cache
GUI port	the local GUI port is free (retries ephemeral if not)
Home quota	headroom for a Cylc venv / run dirs
Plugins	discovered plugin components and any name collisions
Prerequisites	per-component requires: executables and env vars (with a workflow argument)

nwp-compose doctor
  ✓ python      3.12.4 (>= 3.12)
  ✓ cylc        8.6.4 on PATH
  ✓ venv        editable install → /home/aria/nwp-compose
  ! run dir     ~/cylc-run on a 2% -free home filesystem
                → set CYLC_RUN_DIR=/scratch/$USER/cylc-run
  ✗ ungrib      requires `wgrib2` (not found on PATH)
                → module load wgrib2  (or add it to your environment)

  1 blocking, 1 advisory. Fix the blocking item before `nwp-compose run`.

doctor exits non-zero if any check is red, so it composes in scripts and CI as a gate.

How they fit together

doctor   → is this NODE ready?          (prerequisites, paths, quota)
validate → is this WORKFLOW correct?    (schema, graph, physics)
run      → make it RUN                   (generate → install → play, id surfaced)

The recommended first-time sequence on any new node is doctor, then run --dummy, then run.

Next

• Quick start — the short path.
• Warning catalog — what validate/run block and why.
• Unprivileged on shared HPC — the environment overrides doctor recommends.