# JSON outputs

This page is the command-level lookup for machine-readable output. Each row names the command, the flag that selects the shape, what the envelope carries, the schema version the command actually prints (or explicitly unversioned when the JSON carries no version), and the contract that owns the semantics. Generated CLI pages own the exact flags; contracts own the behavior.

Fixture prerequisites match the other reference pages: run the examples from this checkout's `bob` in an isolated `HOME`/`XDG_*` tree, a synthetic vault, `BOB_NOW=2026-10-20 12:00:00`, `TZ=UTC`, and `BOB_REF_JOBS_KICK=off`. Network, clipboard, sync, and hook execution are stubbed or avoided. Stored file versions are not command versions: freshness stored state and the review journal carry their own numbers, and only the `schema_version` printed on stdout counts below.

## Framing

JSON reports print to stdout. Warnings, progress, and hook chatter print to stderr so a JSON pipe stays parseable. Usage errors exit 2.

Success and failure envelopes are per command family. Commands do not share one `ok` / `error` / `schema_version` shape:

- Versioned helpers such as `capture-parse`, `plan`, `freshness`, and most `ref` commands print `ok: true` plus a payload on success. Many of those success envelopes carry `schema_version`.
- Capture-helper error envelopes are often `{"ok":false,"error":"…"}` and need not repeat the success `schema_version`.
- `bob capture -f json` is unversioned (`ok`, no `schema_version`).
- `bob vault-sync status -j` prints the status record directly, with no `ok` and no `schema_version`.
- A failing command may print JSON, a human message on stderr, or both; see that command's contract.

The `bob capture-parse` envelope below is a verbatim captured line from the isolated fixture. The `bob plan` illustration after it is a shortened excerpt of the schema-2 keys from a synthetic vault with no daily note yet; `…` marks omitted nested numbers.

```
bob capture-parse -f json -- 'Buy milk @dev'
```

Output

```
{"ok":true,"schema_version":1,"input":"Buy milk @dev","body":"Buy milk","mode":"task","route":"dev","section":null,"block_id":null,"needs":[],"spans":[{"start":9,"end":13,"kind":"route"}],"diagnostics":[]}
```

```
bob plan -f json -b /path/to/synthetic-vault
```

Output (excerpt)

```
{"ok":true,"schema_version":2,"date":"2026-10-20","daily_file":"2026/20261020.md","status":"ok","caps":{"max_themes":…,"max_links":…,"max_next":…,"max_pending":…,"max_ready":…,"strict":false},"today":{"count":0},"today_tasks":[],"themes":{"count":0,"cap":…,"over":false},"links":{"count":0,"cap":…,"over":false},"next":{"count":0,"cap":…,"over":false},"pending":{"count":0,"cap":…,"over":false},"theme_names":[],"entries":[],"warnings":[]}
```

## Capture and protocol helpers

`bob capture` writes the vault. Most `capture-*` helpers are read-only previews, pickers, and discovery calls for the Mac app and editors. `capture-task-id` and `capture-pomodoro-name` write by default (`-d` / `--dry-run` plans without writing). `capture-templates save`, `delete`, and `clear` mutate the saved-template shelf; `list` and `show` are read-only.

| Command | Flag | Shape | Version | Contract |
| --- | --- | --- | --- | --- |
| `bob capture` | `-f json` | One result per item: routing, task line, placement, plus batch `captures`, `warnings`, `plan_budget`, `pomodoro_blocks`, `task_blocks`, `open_notes`, and `pull_in` | Unversioned (`ok`, no `schema_version`) | [Capture](<https://bobs-org.github.io/capture/index.md>) |
| `bob capture-parse` | `-f json` | Per-item `mode`, spans, diagnostics, and `needs` for incomplete input | `schema_version: 1` | [Capture](<https://bobs-org.github.io/capture/index.md>) |
| `bob capture-complete` | `-f json` | Completion context plus candidates and replacement ranges | `schema_version: 1` | [Capture](<https://bobs-org.github.io/capture/index.md>) |
| `bob capture-pomodoro-name` | `-f json` | Name write (or `-d` plan) for one open Pomodoro | `schema_version: 1` | [Capture](<https://bobs-org.github.io/capture/index.md>) |
| `bob capture-pomodoros` | `-f json` | Ledger entries for the day plus `warnings` | `schema_version: 1` | [Pomodoro homes](<https://bobs-org.github.io/pomodoro-homes/index.md>) |
| `bob capture-related` | `-f json` | Candidate matches, UTF-8 draft anchors, verified actions, and already-linked tasks; `--query` adds scores | `schema_version: 1` | [Capture](<https://bobs-org.github.io/capture/#bob-capture-related>) |
| `bob capture-rewrite` | `-f json` | `input`, rewritten `text`, `changed`, `cursor`, `rule`, and `edits` | `schema_version: 1` | [Capture](<https://bobs-org.github.io/capture/index.md>) |
| `bob capture-sections` | `-f json` | `route`, `count`, and non-`Tasks` `sections` | Unversioned (`ok`, no `schema_version`) | [Capture](<https://bobs-org.github.io/capture/index.md>) |
| `bob capture-targets` | `-f json` | `bob_dir`, `count`, and route `targets` | Unversioned (`ok`, no `schema_version`) | [Capture](<https://bobs-org.github.io/capture/index.md>) |
| `bob capture-task-id` | `-f json` | ID write (or `-d` plan) plus `note_path` and picker `*_replacement` strings | `schema_version: 1` | [Capture](<https://bobs-org.github.io/capture/index.md>) |

For `bob capture-complete` in `relation_label` context, visible catalog rows include `label`, normalized `key`, `count`, `replacement`, and optional `inverse`. A typed row is first and includes `typed: true`, `existing`, and `hidden`; when the typed key exists, it also includes `count` and uses the catalog spelling. Hidden labels are omitted from the visible rows, but an exact typed hidden label remains available with `hidden: true`. The response includes `hidden_count` for this context. | `bob capture-task-sections` | `-f json` | ALL-CAPS child sections of one task | `schema_version: 1` | [Capture](<https://bobs-org.github.io/capture/index.md>) | | `bob capture-tasks` | `-f json` | Open tasks of one note with block IDs and status names | Unversioned (`ok`, no `schema_version`) | [Capture](<https://bobs-org.github.io/capture/index.md>) | | `bob capture-templates list` | `-f json` | Saved-template shelf entries | `schema_version: 1` | [Capture](<https://bobs-org.github.io/capture/#saved-templates>) | | `bob capture-templates save` | `-f json` | Saved definition plus shelf position | `schema_version: 1` | [Capture](<https://bobs-org.github.io/capture/#saved-templates>) | | `bob capture-templates show` | `-f json` | One saved definition | `schema_version: 1` | [Capture](<https://bobs-org.github.io/capture/#saved-templates>) | | `bob capture-templates delete` | `-f json` | Removed entries plus remaining count | `schema_version: 1` | [Capture](<https://bobs-org.github.io/capture/#saved-templates>) | | `bob capture-templates clear` | `-f json` | Cleared count | `schema_version: 1` | [Capture](<https://bobs-org.github.io/capture/#saved-templates>) |

### Similar-task draft results

`bob capture-related -f json -- DRAFT` returns one `items` entry per task-creating draft item. `index` is the item's 0-based position in the full draft, including items that do not create tasks. Templates and drafts without new tasks return `items: []`.

| Field | Wire representation |
| --- | --- |
| `range` | Half-open `{start, end}` UTF-8 byte offsets for the item in the submitted draft |
| `route_range` | The item's own destination-token range; omitted when absent |
| `discard_range` | Range for removing the item and adjacent separator; omitted when the item has authored children |
| `marker_at` | UTF-8 byte offset for inserting an action marker |
| `matches[].matched_ranges` | Array of half-open `[start, end]` UTF-8 byte pairs in that match's clean `title` |
| `matches[].band` | `same_title`, `possible_duplicate`, `similar`, `closed_duplicate`, or `hold` |
| `matches[].actions`, `matches[].default_action` | Available actions and the recommended default; clients apply draft edits only after user selection |
| `matches[].replacements` | Present for targets with block IDs; ID-less targets use `requires_block_id` and `block_id_suggestions` |
| `linked` | Keys already referenced by the item, with their link kind |

A candidate appears under only the item with its highest match score; ties go to the earliest eligible item. Tasks explicitly linked by any task-creating item are excluded from every item's matches. Non-exact matches need at least two distinct meaningful terms. A `hold` row is below the display threshold; clients use it only to retain an already-visible suggestion while wording changes. Bob can return it even if the client has never displayed it. Draft results omit scores. `--query TEXT` is a separate calibration shape with scores and without draft anchors or actions.

`route_range` and `discard_range` use the same object shape as `range`. Draft offsets are valid only for the exact submitted text; match offsets index the returned `title`. End offsets are exclusive. The full [capture-related contract](<https://bobs-org.github.io/capture/#bob-capture-related>) owns actions, candidate eligibility, and error behavior.

## Plan, readiness, freshness, and stats

| Command | Flag | Shape | Version | Contract |
| --- | --- | --- | --- | --- |
| `bob plan` | `-f json` | Date, status, caps, Today entries, lane counts, and `warnings` | `schema_version: 2` | [Plan](<https://bobs-org.github.io/plan/index.md>) |
| `bob ready` | `-f json` | Per-note Ready lane against `max_ready_per_note` | `schema_version: 1` | [Plan](<https://bobs-org.github.io/plan/index.md>) |
| `bob freshness` and `bob freshness list` | `-f json` | Review queue report | `schema_version: 14` | [Freshness](<https://bobs-org.github.io/freshness/index.md>) |
| `bob freshness seed` | `-f json` | Seed dry-run report: stamped counts, buckets, skipped | `schema_version: 14` | [Freshness](<https://bobs-org.github.io/freshness/index.md>) |
| `bob stats overview` | `-f json` | Weekly glance report | `schema_version: 1` | [Stats](<https://bobs-org.github.io/stats/index.md>) |
| `bob stats show` | `-f json` | One or more metric details | `schema_version: 1` | [Stats](<https://bobs-org.github.io/stats/index.md>) |
| `bob stats metrics` | `-f json` | Metric id, kind, and definition catalog | `schema_version: 1` | [Stats](<https://bobs-org.github.io/stats/index.md>) |

Do not copy the freshness `14` onto stored files: it is the command envelope version. The freshness contract owns the stored review state.

`summary.headline.display` is the formatted headline; optional `suffix` is its display suffix, and optional `stat` identifies the calculation. For `net`, `value` sums complete, non-null daily values, excluding provisional today. With at least one such value, `stat` and `suffix` are both `"total"`; otherwise `value` is `null`, `display` is `"–"`, and both fields are omitted. When present, the net delta says `shrinking`, `growing`, or `flat` from the total's sign. Other numeric headlines use daily medians; ratios pool numerators and denominators, and booleans count met days over days with data. The envelope remains schema 1; see [Stats summaries](<https://bobs-org.github.io/stats/#ranges-grouping-summaries-display>).

## Tasks, reconciliation, and queries

| Command | Flag | Shape | Version | Contract |
| --- | --- | --- | --- | --- |
| `bob task move` | `-f json` | Move plan and repaired-link report | `schema_version: 1` | [Task move](<https://bobs-org.github.io/task-move/index.md>) |
| `bob task reconcile` (aliases `task-status-hooks`, `mark-next-tasks`) | `-f json` | Sync result: marked, cleared, blocked, dependency, and reference changes | Unversioned (serialized sync result, no `schema_version`) | [Task Status Hooks](<https://bobs-org.github.io/task-status-hooks/index.md>) |
| `bob task reroll` (alias `randomize`) | `-f json` | Re-roll plan and per-task outcomes | `schema_version: 1` | [Randomize](<https://bobs-org.github.io/randomize/index.md>) |
| `bob query` | `-f json` (default is `paths`) | `engine`, `query_kind`, `format`, `paths`, `result`, and `warnings` | Unversioned (no `schema_version`) | [Bob query](<https://bobs-org.github.io/dataview/index.md>) |
| `bob articles format` | `-f json` | Article plans | `schema_version: 1` | [Articles](<https://bobs-org.github.io/articles/index.md>) |
| `bob articles list` | `-f json` | Article notes needing work | `schema_version: 1` | [Articles](<https://bobs-org.github.io/articles/index.md>) |
| `bob articles outline` | `-f json` | Section outline of one note | `schema_version: 1` | [Articles](<https://bobs-org.github.io/articles/index.md>) |

`bob task archive`, `bob projects`, and `bob nightly` are human-only in this checkout: they expose no `--format json` or `--json` flag.

## References, jobs, Keep, plugins, and status

| Command | Flag | Shape | Version | Contract |
| --- | --- | --- | --- | --- |
| `bob ref find` | `-f json` | Library verdicts and title candidates | `schema_version: 1` (`REF_SCHEMA_VERSION`) | [Reference library](<https://bobs-org.github.io/ref/index.md>) |
| `bob ref list` | `-f json` | Notes by reading state with dates and parents | `schema_version: 1` (`REF_SCHEMA_VERSION`) | [Reference library](<https://bobs-org.github.io/ref/index.md>) |
| `bob ref show` | `-f json` | One note: reading state, dates, annotation pointers, and an additive `sections` list (omitted when the region has none; `schema_version` stays 1) | `schema_version: 1` (`REF_SCHEMA_VERSION`) | [Reference library](<https://bobs-org.github.io/ref/index.md>) |
| `bob ref scan` | `-f json` | Scan report: `mode`, `write_pdfs`, `hook`, `intake`, `summary` (with `held`), `notes` (with `marker_write`, including `restored` when a stale save was restored), `failures`, `intake_only`, `queued`, `held`. Every writing scan that holds the writer lock also writes that exact line to `<state>/bob-cli/ref/last-scan.json` and (macOS) posts `org.bobs.bob.ref.scan-finished`. `--intake-only` files queued `xlib/` PDFs and audio only (no annotation pass); `ok` is then also false when a writing drain leaves `queued` nonempty. Hard failures use the error envelope (`error.code` / `hint` / `paths`) instead of `summary`/`notes`/`failures`, with no `held` field. | `schema_version: 1` (`REF_SCHEMA_VERSION`) | [JSON output](<https://bobs-org.github.io/highlights-ref-sync/#json-output>) |
| `bob ref today` | `-f json` | Pulls one reference's reading task into a Pomodoro (`mode` `dry_run` or `write`; `-d` plans without writing). Success carries `changed`, `ref`, `task`, `pomodoros`, and `capture`. This is not a listing of today's references. | `schema_version: 1` (`REF_SCHEMA_VERSION`) | [bob ref today](<https://bobs-org.github.io/ref/#bob-ref-today>) |
| `bob ref rename` | `-f json` | Rename plan and rewritten-link report | `schema_version: 1` (`REF_SCHEMA_VERSION`) | [Reference library](<https://bobs-org.github.io/ref/index.md>) |
| `bob ref migrate-tasks` | `-f json` | Migration plan for open ref tasks | `schema_version: 1` (`REF_SCHEMA_VERSION`) | [Reference library](<https://bobs-org.github.io/ref/index.md>) |
| `bob ref migrate-zorg` | `-f json` | Zorg-record migration plan | `schema_version: 1` (`REF_SCHEMA_VERSION`) | [Reference library](<https://bobs-org.github.io/ref/index.md>) |
| `bob ref jobs list` | `-f json` | Queued background jobs plus a `summary` | `schema_version: 1` | [Ref jobs](<https://bobs-org.github.io/ref-jobs/index.md>) |
| `bob ref jobs run` | Human only | Clips pending jobs through the shared ingest | No JSON flag | [Ref jobs](<https://bobs-org.github.io/ref-jobs/index.md>) |
| `bob gkeep` and `bob gkeep list` | `-f json` (default is `table`) | Keep inbox notes with counts and error hints | `schema_version: 1` | [Bob Gkeep](<https://bobs-org.github.io/gkeep/index.md>) |
| `bob gkeep doctor` | `-f json` | Adapter and credential diagnosis | `schema_version: 1` | [Bob Gkeep](<https://bobs-org.github.io/gkeep/index.md>) |
| `bob gkeep migrate-markers` | `-f json` | Marker-removal plan | `schema_version: 1` | [Bob Gkeep](<https://bobs-org.github.io/gkeep/index.md>) |
| `bob gkeep migrate-tasks` | `-f json` | Link-repair plan for open tasks | `schema_version: 1` | [Bob Gkeep](<https://bobs-org.github.io/gkeep/index.md>) |
| `bob gkeep pull` | `-f json` | Inbox import report | `schema_version: 1` | [Bob Gkeep](<https://bobs-org.github.io/gkeep/index.md>) |
| `bob plugins` and `bob plugins list` | `-f json` (default is `table`) | Repo plugins with version, sync, and vault state | Unversioned (`ok`, no `schema_version`) | [Bob Plugins](<https://bobs-org.github.io/plugins/index.md>) |
| `bob plugins sync` | `-f json` | Copied, skipped, and unchanged files with backups | Unversioned (`ok`, no `schema_version`) | [Bob Plugins](<https://bobs-org.github.io/plugins/index.md>) |
| `bob vault-sync status` | `--json` / `-j` | Direct `StatusRecord`: `last_attempt_at`, `last_success_at`, `local_sha`, `remote_sha`, `files_committed`, `push_retries`, `duration_ms`, `conflicts`, `interrupted_merge_recovered`, `aborted_merge_head`, `halted_merge_head`, `interrupted_fast_forward_recovered`, `last_error` | Unversioned (no `ok`, no `schema_version`) | [Vault Git sync](<https://bobs-org.github.io/vault-git-sync/index.md>) |
| `bob completion status` | `--json` / `-j` | Protocol, executable, and per-shell install state | `schema_version: 1`, `protocol: 1` | [Completion](<https://bobs-org.github.io/completion/index.md>) |

## Other structured formats

These are public but are not JSON. They use their own flags on the same commands.

| Format | Command and flag | Shape |
| --- | --- | --- |
| CSV | `bob stats overview -f csv`, `bob stats show -f csv` | Same report rows as JSON, comma-separated |
| TSV | `bob ref migrate-tasks -f tsv` | Migration plan rows for spreadsheets |
| Table | `bob plugins -f table`, `bob gkeep -f table` | Human tables; the default for those two families |
| Markdown | `bob query -f markdown`, `bob ref find -f markdown`, `bob ref list -f markdown`, `bob ref show -f markdown` | Rendered notes output |
| Paths | `bob query` default (`-f paths`) | Newline-separated vault paths |

Hidden adapters (Keep, web-clip, Dataview internals) and on-disk state files (`.bob/`, `templates.json`, the Stats review journal, ref job spool files) are not public command outputs even when they contain JSON.

## Related

- [Your first Bob day](<https://bobs-org.github.io/start/first-bob-day/index.md>)
- [Capture syntax](<https://bobs-org.github.io/reference/capture-syntax/index.md>) for the tokens these envelopes describe.
- [CLI reference](<https://bobs-org.github.io/reference/cli/index.md>) for the exact flags of every command.
- [Configuration and environment](<https://bobs-org.github.io/reference/configuration/index.md>) for the `BOB_*` names that select vaults, adapters, and plugin roots used above.