# JSON output

Parse `--json`, never the human renderer. Human output and piped tab-separated output may change in any minor version. The shapes on this page are part of the 1.0 stability promise unless marked otherwise: within 1.x, fields may be added, and existing fields keep their meaning. Ignore fields you do not recognize.

| Command                                                                                                     | `--json` prints                                     |
| ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
| `wb run`, `wb resume`, `wb attach`                                                                          | The event stream, NDJSON.                           |
| Detached `wb run`, `wb resume`                                                                              | One launch receipt.                                 |
| `wb wait`                                                                                                   | One result.                                         |
| `wb send`, `wb answer`                                                                                      | One receipt.                                        |
| `wb smoke`                                                                                                  | One line per package.                               |
| `wb ps`                                                                                                     | One run record per NDJSON line.                     |
| `wb view`, `wb build`, `wb outcome`, `wb clean`, `wb status`, `wb project`, `wb studio`, `wb worker status` | One document. Not covered by the stability promise. |

## Event stream

`wb run --json`, `wb resume --json`, and `wb attach --json` write one complete event per line, `protocol: 0`. The envelope and every event type are on [Event protocol](/docs/standard/events).

```sh
wb run project-core --task "Review this migration" --json
```

Once a run has started, a failure is a `run.failed` event on stdout with a non-zero exit. A failure before it starts prints `error: <message>` on stderr and emits no events.

## Launch receipts

Detached `wb run --json` and `wb resume --json`:

```json
{
    "session_id": "wb_...",
    "run_id": "wb_...",
    "input_id": "...",
    "after_sequence": 0
}
```

A resume may also include `receipt`.

## `wb wait --json`

One object.

| Field              | Presence        | Meaning                                                                                                           |
| ------------------ | --------------- | ----------------------------------------------------------------------------------------------------------------- |
| `session_id`       | always          | The session.                                                                                                      |
| `run_id`           | always          | The run observed.                                                                                                 |
| `state`            | always          | `starting`, `running`, `idle`, `turn_completed`, `completed`, `failed`, `cancelled`, `needs_input`, or `timeout`. |
| `sequence`         | always          | The boundary's event sequence. Pass it as `--after` next time.                                                    |
| `final`            | always          | The final response of the turn or run.                                                                            |
| `usage`            | always          | Usage since `--after`, `kind: "delta"`.                                                                           |
| `usage_total`      | always          | Usage for the run so far, `kind: "total"`.                                                                        |
| `pending_requests` | always          | Each `{id, kind, sequence, details}`; `kind` is `permission`, `question`, or `authentication`.                    |
| `outcome_id`       | when it applies | The run's outcome.                                                                                                |
| `error`            | when it applies | Why the run failed.                                                                                               |
| `interrupted`      | when it applies | The wait itself was interrupted.                                                                                  |
| `repository`       | when it applies | Repository provenance of a `--repo` run.                                                                          |
| `delivery`         | when it applies | Repository delivery state.                                                                                        |
| `run_state`        | when it applies | The run's own state.                                                                                              |
| `authoring`        | when it applies | For `wb create`: package selectors and paths, changed files, and evidence path.                                   |

`usage` and `usage_total` carry the token counts and `cost_usd` the runner reported.

## `wb send --json` and `wb answer --json`

On success:

```json
{
    "session_id": "wb_...",
    "run_id": "wb_...",
    "input_id": "...",
    "after_sequence": 42
}
```

with an optional `receipt`:

| Field         | Meaning                                                                                                                        |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `version`     | `1`.                                                                                                                           |
| `id`          | The control request.                                                                                                           |
| `kind`        | `send`, `steer`, `follow_up`, `permission`, `question`, `cancel_turn`, `cancel`, `close`, `attach_client`, or `detach_client`. |
| `outcome`     | `accepted` or `rejected`.                                                                                                      |
| `resolved_at` | When it resolved, ISO 8601.                                                                                                    |
| `disposition` | Optional: `attached`, `detached`, `delivered`, `queued`, `cancelled`, `already_idle`, `cancellation_requested`, or `closed`.   |
| `error`       | Optional `{code, message}`.                                                                                                    |

A failure prints `{"error":{"code":...,"message":...}}`, or `{"receipt":...,"error":...}` when the run rejected the input.

## `wb smoke --json`

One NDJSON line per package:

| Field                  | Meaning                                                                                   |
| ---------------------- | ----------------------------------------------------------------------------------------- |
| `status`               | `ready`, `needs-auth`, or `failed`.                                                       |
| `workbench`, `version` | The package.                                                                              |
| `runtime`              | The runtime checked.                                                                      |
| `runner`               | Optional. The runner.                                                                     |
| `tools`                | The tools checked.                                                                        |
| `authentication`       | Optional. `{ready, model, provider?, route?, authenticated_providers, connect_command?}`. |
| `requirements`         | Optional. `{checked, applied, unchecked}`.                                                |
| `workspaces`           | The workspace bindings.                                                                   |
| `docker_engine`        | Optional. The host Docker engine check.                                                   |
| `warnings`             | Warnings.                                                                                 |
| `error`                | Optional. `{code, message}`, where `code` is `authentication_required` or `smoke_failed`. |

A source that cannot be resolved prints `error: <message>` on stderr with no JSON line.

## Other machine output

- `wb ps --json` includes `state`, `needs_input`, pending requests, and `project` (a display name or `null`).
- `wb project list --json` returns `name`, `slug`, `counts`, and `created_at` for each project.
- `wb studio --json` and `wb studio status --json` contain `running`, `url`, `image`, `image_id`, and `open_url` when the browser was not opened.
- `wb clean --json` returns one versioned report with the policy, eligible and protected resources, reconciled runs, byte counts, and the applied result.
- `wb push` prints a machine record of `push`, `org/slug`, `version`, and `digest` when piped.
- `wb image push` prints `pushed<TAB><ref>` when piped.
- `wb connect` prints `ready`, `saved`, `removed`, or `absent`, then runtime, runner, and provider, tab separated, when piped.

These are not covered by the stability promise.