Headless output with --json
Drive venom commands from CI, editors and other agents with --json, which prints one JSON document on stdout per command.
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.
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
Newer commands print one line in this shape:
{"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
| 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
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.