JSON Contract and Error Envelope

JSON Contract & Error Envelope

--json is a versioned API contract, not pretty-printing. Tools and agents can depend on it.

Envelope

Every JSON payload includes:

Field	Meaning
command	The command that produced the result (search, show, version, …)
ok	true on success, false on error
schema_version	Integer; bumped on contract changes

Plus command-specific fields (e.g. hits, total, query, nodes, edges).

Success example (search)

{
  "command": "search",
  "query": "parse config",
  "kind": "all",
  "total": 7,
  "ok": true,
  "schema_version": 1,
  "hits": [
    {
      "grain": "symbol",
      "name": "parseConfig",
      "symbol_kind": "function",
      "signature": "function parseConfig(env: Record<string, string>): Config {",
      "path": "src/config.ts",
      "role": "impl",
      "exported": true,
      "start_line": 4,
      "end_line": 6,
      "snippet": "export function parseConfig(env: Record<string, string>): Config {\n  …\n}\n",
      "score": 0.7383,
      "why": "exact name match",
      "risk_level": "low",
      "graph": {}
    }
  ]
}

Error envelope

On failure, ok is false and an error object carries a stable code and a message:

{"command":"symbol","error":{"code":"NOT_FOUND","message":"symbol not found: DoesNotExist"},"ok":false,"schema_version":1}

The code is a stable identifier (e.g. NOT_FOUND, NOT_INITIALIZED, STORE_ERROR) suitable for branching; the message is human-facing. Some errors also carry a hint. The process exit code maps to the error class — see Exit Codes.

Freshness block

Graph/index payloads include a freshness object so agents can decide whether to reindex:

"freshness": {"indexed_head":"c3035af…","dirty":false,"last_indexed_at":"2026-06-07T12:31:18Z","stale":false}

Stability

• Additive changes (new fields) do not bump schema_version.
• Breaking changes bump schema_version.
• Results to stdout; diagnostics to stderr.

Related

Output Modes · Exit Codes · Using Columbus with Your Agent