---
title: Headless output with --json
description: Drive venom commands from CI, editors and other agents with --json, which prints one JSON document on stdout per command.
section: reference
order: 140
audience: [builder, agent, user]
sources: [docs/headless.md, cli/src/json-output.ts]
features: [reference.doc-headless]
---

Every `venom` subcommand that prints a result takes `--json` and prints one JSON document on stdout. Progress and diagnostics stay on stderr, so a script can parse stdout directly.

```bash
venom workflow list --json | jq '.workflows[].name'
venom inbox list --json | jq '.items | length'
```

The exit code does not change with `--json`: 0 success, 1 failure, 2 usage error.

## The shared shape {#shape}

Newer commands print one line in this shape:

```json
{"ok":true,"workflows":[{"name":"review","file":".venom/workflows/review.ts"}]}
{"ok":false,"error":{"code":"workflow_not_found","message":"no workflow nope"}}
```

Branch on `ok`, then on `error.code`.

## Per command {#commands}

| Command | `--json` output |
|---|---|
| `venom workflow list`, `run <name>` | Shared shape: `{ok, workflows:[{name, file}]}`, `{ok, name, status, result}`. Errors `usage`, `workflow_not_found`, `workflow_failed`. |
| `venom inbox list/show/approve/reject/redirect/take-over` | Shared shape: `{ok, items:[...]}`, `{ok, item}`, `{ok, id, action, message?}`. Errors `usage`, `not_found`. |
| `venom workspace new/switch/diff/merge/apply/pr/rm` | Shared shape. Failures `merge_failed`, `apply_failed`, `workspace_error`. `venom workspace list` keeps its older shape, a JSON array. |
| `venom export <session>` | Shared shape: `{ok, session, format, items, scrubbed, path}`; with `--out -` the text is in `text`. Errors `usage`, `ambiguous_session`, `session_not_found`. |
| `venom export-traces` | Shared shape: `{ok, dir, scanned, kept, manifest}`. |
| `venom session export/share/unshare/replay` | Shared shape. `replay` prints the turn model: `{ok, source, v: 1, session, lanes, turns, events, sideCalls, totals}`. |
| `venom review`, `triage`, `replay` | `venom.review/v1`, `venom.triage/v1`, the replay plan or outcome. |
| `venom usage`, `routes` | The orchestrator's usage and `/v1/routing` reports. |
| `venom cost` | `{type: "cost", source: "cloud" or "local", window, today, last_7_days, month, totals, daily, by_gear, by_model, by_role, by_day, by_session, by_task, notes}`. |
| `venom provenance <sha>`, `record`, `key` | Verification of the receipt chain; the recorded receipt; the key id. |
| `venom revert <intent>` | Shared shape: the plan of commits to revert, and with `--apply` the branch and test result. Errors `no_commits`, `conflict`, `revert_failed`. |
| `venom forecast "<task>"` | Shared shape: `{ok, object: "venom.forecast", task, history, gears:[...]}`. |
| `venom tour [path]` | `{ok, file, model, requests, spentUsd, maxUsd, complete, markdown?}`; with `--dry-run` the plan and estimate. |
| `venom bisect "<test>"` | Shared shape: `{ok, good, bad, steps, culprit?, explanation?}`. Errors `usage`, `bisect_failed`. |
| `venom explain <path>` | Shared shape: `{ok, path, hash, text, cached}`. Errors `usage`, `explain_failed`. |
| `venom doctor`, `audit verify`, `schedule list`, `memory list/sync`, `plugin list`, `models status/list`, `config` | Their own documented reports. |

Older commands keep the shapes they shipped with; new commands use the shared one.

## Over HTTP {#server}

The same actions are reachable over `venom serve`: for example `GET /v1/workflows?cwd=` lists a workspace's workflow scripts, next to `GET /v1/saved-sessions` and `GET /v1/schedules`. The generated reference is at `/docs/api/harness-server`.

## Related

- [Error codes](/docs/reference/errors.md)
- [Evidence bundles](/docs/reference/evidence-bundle.md)
