---
title: 'runs'
description: 'List, inspect, retry and cancel the durable execution runs of a running agent installation'
position: 15
---

# 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](/docs/cli/reference/conventions#target-resolution).
> `list` is [cursor-paginated](/docs/cli/reference/conventions#pagination), and
> `retry` / `cancel` are
> [destructive verbs](/docs/cli/reference/conventions#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](/docs/sdk/workflows/overview).

| Command                                                | Purpose                                                                     |
| ------------------------------------------------------ | --------------------------------------------------------------------------- |
| [`stackbone runs list`](#stackbone-runs-list)          | List recent runs. Filter with `--status`, page with `--limit` / `--cursor`. |
| [`stackbone runs get <id>`](#stackbone-runs-get)       | Inspect a single run (status, trigger, timing).                             |
| [`stackbone runs retry <id>`](#stackbone-runs-retry)   | Start a fresh durable run from a run's original input. Requires `--yes`.    |
| [`stackbone runs cancel <id>`](#stackbone-runs-cancel) | 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](/docs/sdk/workflows/serial-execution) 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](/docs/cli/reference/hitl).
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`](/docs/cli/reference/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.

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

**JSON payload**

```jsonc
{
  "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`).

```jsonc
{
  "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>`](/docs/cli/reference/logs).

## 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`.

```bash
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.

```jsonc
{
  "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`.

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

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

**JSON payload:** the updated run.

```jsonc
{
  "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](/docs/cli/reference/conventions#exit-codes).