JSON Mode

Bowerbird’s machine-readable options are command-specific. Use --output json only where that command’s --help lists it, and use --json input only on commands that explicitly accept a JSON payload. They are not universal global flags.

For commands that can prompt or open a picker, add the global --non-interactive flag when you need a hard no-prompt guarantee:

bwrb --non-interactive new task --json '{"name":"Fix login","priority":"high"}'
bwrb --non-interactive edit "My Task" --json '{"status":"settled"}'

Logical actor provenance

Schemas opt into runner provenance with { "value": "$ACTOR" }. Establish the identity once for the CLI process:

BWRB_ACTOR='codex:session-17' bwrb new attestation \
  --json '{"name":"CI passed","outcome":"passed"}'
bwrb --actor 'orchestrator:reviewer-2' new attestation \
  --json '{"name":"Independent review","outcome":"passed"}'

The explicit root option wins over the environment. If neither exists, $ACTOR becomes unknown; Bowerbird never guesses Alice from an OS account, Git identity, or hostname. Actor values are provenance, not permission.

JSON output shapes

Check the command reference before choosing a parser. Bowerbird emits one complete JSON value, but success shapes differ by workflow:

Workflow	Success shape
list [filters] --output json	Raw array of note objects with _path, _name, and frontmatter
list [filters] --receipt --output json	Query receipt with selectors/settings, counts, truncated, and data rows
list --count --output json	Raw { "count": number } object
list --name ... --output json	{ "success": true, "data": [...] }
list --fuzzy ... --output json	{ "success": true, "data": [...] }, including scores and match metadata
list --body ... --matches --output json	Match report with success, data, totalMatches, and truncated
list --lineage ... --output json	Raw { "target", "nodes", "warnings" } object
new --fork ... --output json	{ "success": true, "path", "id", "forked_from", "warnings" }
lineage adopt ... --output json	{ "success": true, "mode", "child", "parent", "changes", "warnings", "body_invariance" }

Guarded note writers use numeric top-level error codes. If edit, fork, or adoption observes newer note bytes, exit code 2 includes data.reason: "note-modified-concurrently", data.retryable: true, the vault-relative data.path, and data.attempts. JSON edit makes up to three total attempts (the initial attempt plus at most two retries) before returning that error.

Normal list output is intentionally a raw array:

bwrb list task --output json | jq -r '.[] | ._path'

The opt-in receipt adds query metadata and limit accounting without changing the default array contract. It is incompatible with --count, --open, lineage, and name/fuzzy/detailed-match modes.

Name and fuzzy resolution use a success envelope:

bwrb list --name "My Note" --output json --picker none | jq -r '.data[0].path'
bwrb list --fuzzy "My Nte" --output json | jq '.data[] | {path, score}'

Lineage output is a raw graph object, not a data envelope:

bwrb list --lineage "Briefs/Launch Brief" --output json | jq '.nodes[]'

Adoption output uses a success envelope because it describes a planned or applied mutation. Preview is the default; require mode == "dry-run", review the paths and changes, and then rerun with --execute. Generated preview IDs are provisional. Both body_invariance.child.unchanged and body_invariance.parent.unchanged should be true.

JSON input

new and edit accept frontmatter payloads directly:

bwrb new task --json '{"name":"Fix login","priority":"high"}'
bwrb edit "My Task" --json '{"status":"settled"}'

Other management commands accept JSON only where their help documents it, such as config edit <key> --json <value> and selected template/dashboard workflows. Run bwrb <command> --help; do not infer --json support from another command.

bwrb new --json reports filename safety metadata when relevant: nameTransformed appears when a requested name is normalized, and pathLengthWarning appears for relative paths longer than 200 characters. Paths longer than 260 characters are rejected.

Errors and exits

Machine-readable failures normally use a structured error object such as:

{
  "success": false,
  "error": "No matches for query",
  "code": 1
}

The process exit code remains authoritative. Consumers should tolerate added fields and should not assume that every successful command uses the same envelope merely because errors share a common shape.

Audit JSON is report-only: it never applies fixes or deletes. For delete-eligible findings, issue metadata may include a recommendation under meta.recommendation.

See Also

• AI integration
• bwrb list
• Targeting Model