JSON contract

Every verb — capabilities included — emits the same envelope. Pass --json, or pipe the output, to get it instead of the human summary.

The seven keys

{
  "ok": true,
  "tool_version": "0.0.5",
  "data": [],
  "meta": {},
  "warnings": [],
  "commands": [],
  "errors": []
}

Key	Type	Meaning
`ok`	bool	Did the operation succeed? Tracks the exit code (`true` for exit 0).
`tool_version`	string	The `rf` version that produced the envelope.
`data`	array \| null	The result rows on success — an array even for a single object (read `data[0]`), empty `[]` when there are no results. `null` when `ok` is `false`.
`meta`	object	Request metadata — see below.
`warnings`	array	One entry per recovered miss: `{ code, files, msg }`, where `files` lists the paths that warning covers. The warning codes are listed under `rf capabilities`.
`commands`	array	Paste-ready `rg` commands that reproduce each recovery, so any result can be confirmed independently.
`errors`	array	One entry per error: `{ code, message, exit_code, remediation }`, plus nullable `did_you_mean` and `path`. Empty when `ok` is `true`. Note `errors` use `message`; `warnings` use `msg`.

The meta block

"meta": {
  "verb": "content",
  "request_id": "…",
  "ts_iso": "…",
  "contract_version": "2",
  "data_hash": "…",
  "elapsed_ms": 0
}

contract_version — the value to branch on. It bumps on any breaking change to this envelope. It is currently 2. It is a JSON string ("2") in both meta and the capabilities contract’s data[0].contract_version — compare it as a string, not a number.
request_id and data_hash are content-addressed. With a fixed SOURCE_DATE_EPOCH and identical inputs, the whole envelope is byte-identical across runs.
elapsed_ms is wall-clock timing. SOURCE_DATE_EPOCH pins it to 0 so a determinism check can compare the whole envelope.
Verbs add their own counts to meta (for example matched_files, default_matched_files, hidden_by_filters on content).

data shapes

content rows are { file, surfaced_by }; see content. find rows are { file, stage, fix }; see find. capabilities returns the whole contract as data[0].

Determinism

SOURCE_DATE_EPOCH=0 rf content token . --json | sha256sum
SOURCE_DATE_EPOCH=0 rf content token . --json | sha256sum   # same hash

Set NO_COLOR to strip ANSI styling from the human render. The authoritative, machine-readable version of everything on this page is rf capabilities --json.