stackbone runs

stackbone runs targets a running agent installation. With no --agent it runs against the local-dev installation linked to the current project, so stackbone dev must be running. See target resolution. list is cursor-paginated, and cancel is a destructive verb that refuses to run without --yes.

Inspect and control the durable execution runs of the targeted installation. A run is one durable invocation: a workflow run started from a trigger, or an agent chat turn. The durable engine executes it, so it can pause and resume across processes. See Workflows → durable runs.

Command	Purpose
`stackbone runs list`	List recent runs. Filter with `--status` / `--trigger` / `--tag`, page with `--limit` / `--cursor`.
`stackbone runs get <id>`	Inspect a single run (status, trigger, timing).
`stackbone runs cancel <id>`	Cancel a running run (marks it `interrupted`). Requires `--yes`.

A run id is a uuid, and every verb below takes the id exactly as stackbone runs list printed it.

Run status

A run's status is running, done, failed, interrupted, or waiting (a serial workflow trigger queued behind an active run: the row is there so you can see the queue, and it carries no startedAt or durationMs because nothing has executed yet). interrupted covers both a run you cancelled and a durable run that is parked awaiting a human decision: a workflow that called requestApproval() and is waiting on the approvals inbox. A parked run moves back from interrupted to running after you answer the approval, so interrupted is not always terminal.

Run trigger

A run's trigger tells you what started it. The full vocabulary is manual, webhook, cron, event, job, workflow, chat, eval, platform and unknown.

Trigger	What started the run
`manual`	`POST /api/workflows/:name/start`: Studio, the API or `stackbone workflows start`.
`cron`	A workflow schedule.
`event`	A Connect trigger link. `triggerRef` holds the link's id.
`workflow`	A parent workflow calling `startWorkflow` or `startWorkflowAndWait`.
`chat`	An agent chat turn, or a turn of a streaming workflow chat.
`platform`	The box itself: RAG ingest of an upload, auto-map suggestions, eval judges.
`eval`	A case executed by the eval engine (see `stackbone eval`).
`job`	A one-shot dispatched job.
`unknown`	No start gate recorded one.

A resumed run keeps the trigger it started with. triggerRef is null for every trigger except event. Workflow runs recorded before this vocabulary existed keep workflow, whatever started them.

Trigger link

A run a Connect trigger link started, or resumed, also carries triggerLink: the link's id, its connector and trigger ids, whether it started or resumed the run, and the names the box's connector catalog gives them.

"triggerLink": {
  "subscriptionId": "3f2a9c1e-5b7d-4e8a-9c0f-1a2b3c4d5e6f",
  "connector": "gmail",
  "trigger": "gmail_new_email_received",
  "outcome": "started",
  "connectorDisplayName": "Gmail",
  "triggerDisplayName": "New Email",
  "connectorLogoUrl": "https://..."
}

triggerLink is null for a run no link started, and for one whose link was deleted. The names and the logo are absent when the box's catalog does not list the connector, so a reader falls back to the ids. Because it reads the delivery that woke the run, a resumed run carries the link even though its trigger is the one it started with.

stackbone runs list

List recent durable runs for the installation (workflow runs and agent turns), newest first. Cursor-paginated.

Flag	Type	Description
`--agent`	string	Installation id to target. Defaults to the local-dev install.
`--status`	string	Filter by status: `running`, `done`, `failed`, `interrupted`, `waiting` (a serial workflow trigger queued behind an active run).
`--trigger`	string	Filter by trigger, any value from Run trigger.
`--tag`	string	Filter by a run tag, `key:value` split on the first colon: `channel:voice`, `room:call-a:b`. Exact and case-sensitive.
`--cursor`	string	Opaque cursor from a previous page (`nextCursor` / `prevCursor`).
`--limit`	string	Maximum number of runs to return (1–100).

Human mode prints one row per run: id, status, trigger, creation timestamp, and for a run a trigger link started or resumed, the connector and trigger names.

9b1c7f42-3f6a-4a71-9c2e-8d4f0b6a1e33  done        workflow 2026-06-01T10:00:00Z
4c8d2e17-9a0b-4f3c-8e6d-7b5a1c2d3e4f  done        event    2026-06-01T10:05:00Z  Gmail · New Email

JSON payload

{
  "schema_version": 1,
  "items": [
    {
      "id": "9b1c7f42-3f6a-4a71-9c2e-8d4f0b6a1e33",
      "status": "done",
      "trigger": "workflow",
      "createdAt": "2026-06-01T10:00:00Z",
      // ...the rest of the run record, same fields as `runs get`
    },
  ],
  "nextCursor": "eyJ..." /* or null */,
  "prevCursor": null /* or null */,
}

stackbone runs get

Inspect a single run by id. You get its status, trigger and timing. A run a trigger link started or resumed adds a link line with the connector and trigger names and whether the link started or resumed it:

trigger   event
link      Gmail · New Email (started)

Flag	Type	Description
`--agent`	string	Installation id to target. Defaults to the local-dev install.

JSON payload run is the full run record. Alongside the fields below it carries triggerRef, triggerLink, traceId, isPlayground, entityName, entityKind, input, output, error and the per-turn token counters (inputTokens, outputTokens, cacheReadTokens, cacheWriteTokens, totalTokens).

{
  "schema_version": 1,
  "run": {
    "id": "9b1c7f42-3f6a-4a71-9c2e-8d4f0b6a1e33",
    "status": "done",
    "trigger": "workflow",
    "createdAt": "2026-06-01T10:00:00Z",
    "startedAt": "2026-06-01T10:00:01Z",
    "finishedAt": "2026-06-01T10:00:02Z",
    "durationMs": 1234,
  },
}

To follow a run's logs live, use stackbone logs tail --run <id>.

stackbone runs cancel

Cancel a running run. Its status becomes interrupted. Destructive, so it requires --yes.

You can cancel only a running run. Cancelling a run in any other status fails with run_not_running and exits 1.

stackbone runs cancel 9b1c7f42-3f6a-4a71-9c2e-8d4f0b6a1e33 --yes

Human mode prints Cancelled run <id> (interrupted).

JSON payload: the updated run.

{
  "schema_version": 1,
  "run": { "id": "9b1c7f42-3f6a-4a71-9c2e-8d4f0b6a1e33", "status": "interrupted" /* ... */ },
}

Exit codes: 0 ok · 3 no target (no project and no --agent, or stackbone dev is not running) · 4 not found (unknown run, or a targeted box with no registered deployment) · 5 permission (cancel without --yes) · 1 generic (an invalid --status or --limit, or a cancel on a run that is not running). See exit codes.