Running & Resuming Lightflow Workflows (run_lightflows)
Authoring new workflows? Read create_lightflows instead.
Fast-Path Rules
- Read only
SKILL.md, then run start directly: do not read
lightflow.yaml, actions.py, or README.md first. The CLI compiles the
manifest and prints any gate's Instructions, Payload Schema, and the
exact Resume with: command. --lightflow=<path> accepts a manifest file
or its directory.
- Skip redundant
status calls & chain cleanup: when start or resume
exits 0 (Lightflow completed successfully!), do not run status. If
asked to clean up afterwards, chain start ... && cleanup ... (&& stops
naturally at an EXIT_CODE=2 gate).
1. Commands
python3 -m lightflow is equivalent to lightflow when the console script is
not on PATH. Runs remember their manifest, so status, resume, visualize,
and cleanup need only --log_id; if the manifest file moved, pass
--lightflow=<new path> once and it is re-recorded.
lightflow start --lightflow=<dir_or_manifest> --log_id=<run_id> [--payload='{...}' | --payload=@file.json]
lightflow start ... --dry_run # only when asked to preview; ends with a Summary: line and a 💡 --payload seed hint
# Resolve a paused gate once its Instructions are satisfied (APPROVE sets approved=true itself)
lightflow resume --log_id=<id> --stage=<gate_stage> --resolution=APPROVE --payload='{...}'
lightflow resume --log_id=<id> --stage=<gate_stage> --resolution=REJECT --comment="..." # runs rollback_action; dependents are blocked
# After fixing a failed stage: re-arms only failed stages, keeps completed work
lightflow resume --log_id=<id> [--payload='{...}']
lightflow status --log_id=<id> # one line per stage + any paused gate's Instructions, Schema, resume command; --verbose adds payload + stamp log
lightflow list # every saved run: log ID, lightflow, state, last activity, manifest
lightflow visualize --log_id=<id> --output=/tmp/viz.html
lightflow cleanup --log_id=<id> # deletes the run's state only; workflow artifacts on disk are untouched
2. Exit Codes & Governance
0 COMPLETED: done; report the stage outputs printed to stdout.
2 SUSPENDED at an operator_action: follow the printed
Instructions, then resume with a payload matching the Payload Schema.
--resolution=APPROVE validates --payload against the gate's
json_schema; on a validation error the gate stays paused, so fix the
payload and re-run (status reprints the schema in a new conversation).
1 FAILED or REJECTED: the footer names the root cause and the exact
resume command. Fix the cause, then resume — never start --force,
which discards completed stages and is only for rerunning a completed run
from scratch. A rejected gate (🛑) is terminal unless deliberately
re-opened: resume --stage=<gate> --resolution=APPROVE --payload='{...}'
decides again in one call; a bare resume --stage=<gate> only re-opens it.
status exits like the run: 0 completed · 1 failed, rejected, or
interrupted · 2 paused · 3 no saved state · 4 running in another
process (wait; don't resume) · 5 waiting: a polling_policy stage
yielded before its condition was met, nothing is broken, resume once it
holds. Use --verbose only when you need the payload, stamp log, or Mermaid
diagram.
1---2name: run-lightflows3description: Executes, inspects, and resumes existing Lightflow DAG workflows via CLI (`lightflow`, or the equivalent `python3 -m lightflow`). Use when asked to run, dry-run, check status, visualize, resolve an `operator_action` human-in-the-loop checkpoint (`EXIT_CODE=2`), or recover a failed Lightflow run without authoring a new workflow. Run `start` directly without pre-reading the manifest or `actions.py`.4metadata:5 source: https://skillmd.com/skills/google/run-lightflows6---78# Running & Resuming Lightflow Workflows (`run_lightflows`)910> **Authoring new workflows?** Read `create_lightflows` instead.1112## Fast-Path Rules13141. **Read only `SKILL.md`, then run `start` directly**: do **not** read15 `lightflow.yaml`, `actions.py`, or `README.md` first. The CLI compiles the16 manifest and prints any gate's `Instructions`, `Payload Schema`, and the17 exact `Resume with:` command. `--lightflow=<path>` accepts a manifest file18 or its directory.192. **Skip redundant `status` calls & chain cleanup**: when `start` or `resume`20 exits `0` (`Lightflow completed successfully!`), do **not** run `status`. If21 asked to clean up afterwards, chain `start ... && cleanup ...` (`&&` stops22 naturally at an `EXIT_CODE=2` gate).2324## 1. Commands2526`python3 -m lightflow` is equivalent to `lightflow` when the console script is27not on `PATH`. Runs remember their manifest, so `status`, `resume`, `visualize`,28and `cleanup` need only `--log_id`; if the manifest file moved, pass29`--lightflow=<new path>` once and it is re-recorded.3031```bash32lightflow start --lightflow=<dir_or_manifest> --log_id=<run_id> [--payload='{...}' | --payload=@file.json]33lightflow start ... --dry_run # only when asked to preview; ends with a Summary: line and a 💡 --payload seed hint3435# Resolve a paused gate once its Instructions are satisfied (APPROVE sets approved=true itself)36lightflow resume --log_id=<id> --stage=<gate_stage> --resolution=APPROVE --payload='{...}'37lightflow resume --log_id=<id> --stage=<gate_stage> --resolution=REJECT --comment="..." # runs rollback_action; dependents are blocked3839# After fixing a failed stage: re-arms only failed stages, keeps completed work40lightflow resume --log_id=<id> [--payload='{...}']4142lightflow status --log_id=<id> # one line per stage + any paused gate's Instructions, Schema, resume command; --verbose adds payload + stamp log43lightflow list # every saved run: log ID, lightflow, state, last activity, manifest44lightflow visualize --log_id=<id> --output=/tmp/viz.html45lightflow cleanup --log_id=<id> # deletes the run's state only; workflow artifacts on disk are untouched46```4748## 2. Exit Codes & Governance4950- **`0` COMPLETED**: done; report the stage outputs printed to `stdout`.51- **`2` SUSPENDED at an `operator_action`**: follow the printed52 `Instructions`, then `resume` with a payload matching the `Payload Schema`.53 `--resolution=APPROVE` validates `--payload` against the gate's54 `json_schema`; on a validation error the gate stays paused, so fix the55 payload and re-run (`status` reprints the schema in a new conversation).56- **`1` FAILED or REJECTED**: the footer names the root cause and the exact57 `resume` command. Fix the cause, then `resume` — **never `start --force`**,58 which discards completed stages and is only for rerunning a *completed* run59 from scratch. A rejected gate (`🛑`) is terminal unless deliberately60 re-opened: `resume --stage=<gate> --resolution=APPROVE --payload='{...}'`61 decides again in one call; a bare `resume --stage=<gate>` only re-opens it.62- **`status` exits like the run**: `0` completed · `1` failed, rejected, or63 interrupted · `2` paused · `3` no saved state · `4` running in another64 process (wait; don't `resume`) · `5` waiting: a `polling_policy` stage65 yielded before its condition was met, nothing is broken, `resume` once it66 holds. Use `--verbose` only when you need the payload, stamp log, or Mermaid67 diagram.