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 retry / cancel are destructive verbs that refuse 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, page with --limit / --cursor.
stackbone runs get <id>	Inspect a single run (status, trigger, timing).
stackbone runs retry <id>	Start a fresh durable run from a run's original input. Requires --yes.
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, with no run of its own 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 produced it. The full vocabulary is manual, webhook, cron, event, job, workflow, chat and eval: workflow is a durable workflow run, chat an agent chat turn, cron a recurring schedule, job a one-shot dispatched job, and eval a case executed by the eval engine (see stackbone eval).

stackbone runs list

List recent durable runs for the installation (workflow runs and agent turns). 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).
--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.

9b1c7f42-3f6a-4a71-9c2e-8d4f0b6a1e33  done        workflow 2026-06-01T10:00:00Z

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.

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 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 retry

Start a fresh durable run from the original run's input. retry starts a new durable run rather than resuming the old one in place. It is destructive, so it requires --yes.

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

Human mode prints Retried run <id> → new run <newId> (running).

JSON payload: the freshly-started run.

{
  "schema_version": 1,
  "run": { "id": "3a5e01d8-7c44-4d2b-b0f1-6e9a2c7d5b10", "status": "running" /* ... */ },
}

stackbone runs cancel

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

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 (retry / cancel without --yes) · 1 generic (e.g. invalid --status). See exit codes.