Workbenches is an open standard. Read why
Docs JSON output

CLI reference

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.

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:

{
    "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:

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