opschain runs cancel

Included from Basic tier

opschain runs cancel <run-id> [--reason <text>]

Cancels a run — a change or a workflow run, by id. Against a server the change verb is tried first and a not-found falls through to the workflow-run verb (the API v2 ChangeService.CancelChange, then WorkflowRunService.CancelWorkflowRun); locally the repository's run is cancelled in the local store, and a --local run still attached in another terminal observes that cancel, aborts its executing step and finalises cancelled (exit code 3 in the attached terminal). The command returns as soon as the cancel is accepted — the run then winds down and finalises as cancelled (watch it with runs show). The wind-down frees the run's capacity in both states: an executing step's runner is directed to abort at its next lease renewal (the CANCEL directive, so within OPSCHAIN_RUNNER_RENEW_INTERVAL), releasing its lease, and a queued step that never dispatched leaves the fleet queue — nested runs a cancelled workflow spawned included.

Cancelling kills the run; to hold a server run between steps and release it later, use runs pause and runs resume instead.

Flags

Flag	Meaning
--reason <text>	Server only: the operator's reason (max 1000 characters), recorded on the cancel audit event and appended to each cancelled step's audit trail (cancelled via API: <reason>) — visible on the cancelled activity's events. The CLI refuses an overlong reason before sending; the server's own named violation is surfaced verbatim otherwise.

Output

cancelled run 0199c81e-…

Exit codes

Code	Meaning
0	Cancel accepted.
1	The cancel failed — unknown id, the server's refusal (e.g. an already-finalised run), or a transport error.
2	Usage error (--reason over 1000 characters, or on a local target, included).

See also

• opschain docs cli/runs-pause / opschain docs cli/runs-resume — hold a run without killing it.
• opschain docs cli/runs-retry — run a cancelled or failed run again.
• opschain docs cli/runs-show — watch the cancel land.