opschain runs show

Included from Basic tier

opschain runs show <run-id> [--events]

Shows one run: a header block and the step tree. The id picks the family — a change is tried first and a not-found falls through to the workflow-run endpoint. Against a server, either family's show document carries its steps as included resources, rebuilt as a tree with children ordered by step sequence — a change's step resources, a workflow run's workflow_*_step resources.

Flags

Flag	Meaning
--events	Append the run's audit events as a TIME TYPE STEP ACTOR MESSAGE table, oldest first. Local runs, and server runs of both families, read over the API v2 EventService.ListEvents: a change uses the for_change_id scope (the change's own events plus its steps'), a workflow run the for_workflow_run_id scope (the run's own events plus its workflow steps'), with step sources resolved to their full paths.

Output

Run:       0199c81e-…
Kind:      change
Action:    web:deploy
Target:    demo/dev/web
Status:    success
Created:   2026-10-14T03:10:41Z
Started:   2026-10-14T03:10:44Z
Finished:  2026-10-14T03:12:26Z
Duration:  1m42s

✔ deploy — success (1m42s)
├─ ✔ build — success (58.0s)
└─ ✔ release — success (44.0s)

• A Commit: line appears when the run recorded one.

• Each step line is a status glyph (· pending, ◦ queued, ▶ running, ⏸ waiting, ✔ success, − skipped, ✖ error, ⊘ cancelled, ⊗ aborted, ‼ system_error), the step name, the status (omitted while pending) and the elapsed/total duration.

• A step that failed prints the reason the server recorded on the line under it, inside its tree column, introduced by ↳ — for a workflow change step whose nested change was refused at creation that is the API's own refusal (an invalid action file's validation error, an unknown or missing required input), for an executed step the failure or infrastructure cause (exit status 2, a lost runner, a timeout):

  ├─ ‼ provision-site — system_error (0.2s)
  │  ↳ declarative action file .opschain/actions/hosted/provision.yaml is invalid: output key "output_originIp" must match ^[a-z0-9_]{1,50}$

  The same text is the step resource's last_error_message (opschain docs resources/step); nothing prints for a step that never failed.

• Durations are anchored to the newest recorded event, not the wall clock, so the output is stable for a stored run.

• -o json|yaml prints the run detail (header, steps and, with --events, the events) as one machine document — the shape the gate verbs' step-id lookup reads (status_code: waiting). A workflow run's step carries nested_run_id, the run it spawned (a change step's change, a workflow step's nested workflow run): the id to pass to opschain runs artifacts or opschain runs logs for that step's work, since a workflow run holds no artifacts of its own on a server. Omitted for steps that spawn nothing. A failed step carries last_error_message, the reason printed under it in text mode, verbatim; omitted for steps that never failed.

• The header's inputs object is the run's recorded typed inputs exactly as the server serializes them (supplied values and evaluated defaults; a secret-typed value is ******, the stored value being a vault reference, never a raw secret) — the same object GET /api/workflow_runs/<id> and GET /api/changes/<id> carry. Omitted when the run recorded no inputs.

• While the server reports the run waiting on runner capacity (steps queued with no online, non-draining runner serving their queue/group), the machine document's header carries waiting_on_runner_capacity: true; the flag clears the moment a matching runner connects. Follow mode on opschain runs create prints the same fact once as queued — no online runner currently serves this run.

Exit codes

Code	Meaning
0	Shown.
1	The run was not found or the read failed.
2	Usage error.

See also

• opschain docs cli/runs-list — the index this drills into.
• opschain docs cli/runs-converged — the property/settings view a change recorded.
• opschain learn 3.1 — reading a run's record, step by step.