Operate Runs with the CLI

Start, inspect, stream, steer, resolve, control, branch, truncate, and delete durable workflow state safely.

Before you begin

Select the namespace and obtain authority for the exact Agent, session, and Run actions you need. Keep stable Agent, session, Run, promise, and event identifiers from accepted responses. Use authoritative workflow state instead of analytics when deciding whether to mutate a Run.

Steps

1. Start work with a caller-stable event id:

constal runs start support customer-42 --data @message.json \
  --deliver live --event-id message-20260822-1 --output json

2. Inspect with runs session, runs workflow, runs get, runs detail, or runs journal. Page only with the cursor returned by the selected endpoint.
3. Follow committed frames with constal runs stream support customer-42 --run <run-id>. Disconnecting does not cancel execution.
4. List and resolve durable waits with runs waits and runs resolve --value @decision.json --event-id ....
5. Apply steer, pause, resume, cancel, or interrupt to the exact Run. Advanced policy, rebind, truncate, and branch controls take reviewed JSON through --body @file.
6. Delete an entire session only with runs delete-session; it is asynchronous and is not a shortcut for cancelling one Run. Follow progress with runs deletion.

Verify

Refresh runs workflow after every control and retain its receipt. Confirm event actor, mode, accepted binding or Policy snapshot, and resulting status. When a request outcome is uncertain, reuse the same --event-id rather than issuing a fresh mutation.

Next steps

Read Create durable work with the SDK, Run controls, and the generated Runs command reference.