Skip to content
Docs menu

Headless output with --json

Drive venom commands from CI, editors and other agents with --json, which prints one JSON document on stdout per command.

View .md

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.