JSON Output Contract¶
Bullpen commands that support --output json are intended for scripts, agents, and dashboards. This page defines the shared JSON contract used by command-reference pages.
Successful Output¶
Non-streaming commands emit a single JSON document to stdout and then exit. The top-level value is normally an object envelope with command-specific fields. Some older commands may emit an array or a narrower object; command pages document the representative top-level keys for automation.
Streaming commands, such as websocket watches, emit one JSON document per event line. Consumers should parse each line independently.
Error Envelope¶
When JSON mode can handle an error before process exit, the CLI emits a single JSON object. Consumers should accept this shape:
| key | type | nullable | notes |
|---|---|---|---|
error |
string | no | Short human-readable failure summary |
caused_by |
array |
yes | Error chain when available |
hint |
string | yes | Recovery guidance when available |
recovery_command |
string | yes | Suggested bullpen ... command without internal sentinel wrappers |
Legacy commands may emit only {"error": "..."}. Treat missing optional keys as null.
Numeric Fields¶
Decimal values that represent token amounts, prices, rates, and balances may be serialized as strings to preserve precision. Examples include CLOB prices such as midpoint, Hyperliquid fields such as mark_px, and Solana token amounts. Consumers should parse numeric-as-string fields with decimal-safe libraries instead of binary floating point.
Integers used for counts, timestamps, and small indexes may be JSON numbers. When precision matters, prefer the type documented on the command page.
Schema Version¶
Commands may include schema_version at the top level. When present, it is an integer version for that command's JSON shape.
Commands that do not emit schema_version inherit contract version 1. Consumers should default absent schema_version to 1 and tolerate additional fields.
SIGPIPE Safety¶
JSON output is safe to pipe into tools such as head, jq, and shell pipelines. If the downstream reader closes the pipe early, Bullpen treats SIGPIPE or broken-pipe writes as a normal pipe termination and exits without printing a Rust panic or backtrace.
Stability¶
Patch releases may add optional or nullable fields and may add values to existing string enums. They should not remove documented fields, rename documented fields, or change documented field types.
Minor releases may add required fields, increment schema_version, or introduce a new envelope for a command when the old shape remains documented during migration.
Major releases may remove fields, rename fields, or change field types. Command pages and this contract should be updated in the same release.
Consumer Guidance¶
Treat unknown fields as non-breaking. Treat absent optional fields as null. For strict automation, validate the exact command path in the target Bullpen version and pin the CLI version used by production jobs.