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'

{"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

{"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.

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 | | bob capture-tasks | -f json | Open tasks of one note with block IDs and status names | Unversioned (ok, no schema_version) | Capture | | bob capture-templates list | -f json | Saved-template shelf entries | schema_version: 1 | Capture | | bob capture-templates save | -f json | Saved definition plus shelf position | schema_version: 1 | Capture | | bob capture-templates show | -f json | One saved definition | schema_version: 1 | Capture | | bob capture-templates delete | -f json | Removed entries plus remaining count | schema_version: 1 | Capture | | bob capture-templates clear | -f json | Cleared count | schema_version: 1 | Capture |

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: [].

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 owns actions, candidate eligibility, and error behavior.

Plan, readiness, freshness, and stats¶

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.

Tasks, reconciliation, and queries¶

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¶

Other structured formats¶

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

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
• Capture syntax for the tokens these envelopes describe.
• CLI reference for the exact flags of every command.
• Configuration and environment for the BOB_* names that select vaults, adapters, and plugin roots used above.