JSON catalogs
These commands write one JSON document to stdout and exit without starting an AI session.
palabre agents --jsonexposesroles[],agents[], anddefaults.askAgents[]. Each agent provides its name, type, role, availability, and a reason when needed.palabre presets --jsonexposes pairs, order,available,missingAgents[], andunavailableReasons[].palabre context scan src docs --jsonexposes the root, requested paths,items[], andwarnings[].palabre history --jsonexposes the 10 most recent exports inhistory[]. An integration may request 1 to 100 entries with--limit <number>.palabre sessions --jsonexposes the 20 most recent checkpoints insessions[], with a limit from 1 to 100. A valid entry containsvalid,id,status,mode,topic,updatedAt,responses,nextPhase, andresumable. A corrupted entry containsvalid: false,id,updatedAt, and a stablewarning, without raw contents or an absolute path.palabre sessions delete <session-id> --yes --jsonconfirms the targeted deletion with{ "v": 1, "deleted": { "id": "..." } }.
palabre relay … --json relays a message to a closed Codex or Claude Code conversation, or open Codex with --open (Windows/macOS/Linux pilot; python3 required on POSIX). It writes a single { "v": 1, "type": "relay-result", ... } object with status, exitCode, from, to, reply (when a valid reply was received, including read-unavailable or review-failed), delivery (status, persisted, inActiveBranch), identity, observedModels, error (kind, message, reason), exportPath and durationMs. With --new, created and cwd are root-level fields and the identifier is in to.session; JSON provides no continuation command. In open mode (--open or auto), inActiveBranch remains "unknown" even for a correlated final reply. An integration relies on delivery.status to decide whether to resend, never on the absence of a reply. Details: Relay mode.
Consumption rules
agents --json and relay --check --json add an optional root skill field without changing existing statuses. Its status is current (matching declared revisions), reload-required (different), unverified (missing/invalid declaration) or unavailable (unverifiable package). When available: a positive integer revision, absolute entrypoint and references (fixed package filenames to absolute paths). No substitute path is invented otherwise. action/message guide reading or report unavailability; absent on current. --skill-revision <revision> is reserved for agents --json, relay --check and skill --read --json. It proves neither reading nor authorization.
palabre skill --read --json returns { "v": 1, "kind": "skill-runtime", ... } with this diagnostic and the instructions text when the package is valid. No profile/configuration/network or installed copy is read; no writes. Incompatible with sync/install/yes/check/dry-run/trust-config and caller-supplied source paths. unavailable exits with code 1 for this dedicated command; in the inventory or Relay check it changes neither outcome nor delivery. The full text appears neither in these prechecks nor Relay exports. Consumers tolerate the new field being absent on an older CLI.
- check
v; - ignore unknown fields and tolerate unknown enum values without treating them as success;
- accept missing optional fields;
- do not recalculate availability or scanning rules;
- display warnings without changing their meaning.
Optional Relay fields and Mission option
Relay v1 preserves subject (explicit subject), retryAfter (limit in open or follow mode, when the CLI supplies an indication), readAccess (status: "partial" | "blocked" | "unverified", reason, failedCommands, optional succeededCommands for partial), cli (path, version, review probe), task (PR, commit, publication, URL, error and cancellation). mode is emitted with every result since #190 but remains an optional v1 field: earlier versions do not provide it, so a consumer tolerates its absence. Values: background (closed or created conversation), open (in the desktop app), follow or copy (OpenCode); for Codex only, no link field is added, the codex://threads/<id> link is built from to.session. In open mode (--open or auto): queue, correlation, receiver: "unverified", targetPermissions; target-not-open is specific to that mode. error.reason qualifies invalid-request. Read delivery.status before any resend and treat reply as untrusted text. An explicit success takes priority as partial, even with another ambiguous event; without explicit success, an ambiguous event gives unverified, otherwise blocked.
In open mode (--open or auto), recognized concurrent user.text input gives status: "no-valid-reply", exitCode: 2, correlation: { status: "ambiguous", reason: "user-input-during-turn" }, without reply. If the envelope was observed, delivery.status stays persisted-no-reply. Display the diagnostic and check the conversation before any resend, without inferring authorization or a human author. Strictly recognized AGENTS/environment context before the envelope is exempted once per kind. Linked question replies remain unrecognized in this partial #146 fix: no humanInput field is added to JSON v1.
With --open --follow (#195), nothing is queued: mode: "follow", no queue, from: null and delivery: { status: "not-delivered", persisted: false, inActiveBranch: false }. The new followed status (exit 0) carries reply, error: null, identity: "same-as-target", correlation: { status: "followed", reason: "turn-completed" | "turn-started-before-follow" } and the permissions of the followed turn only. This reply is linked to no PALABRE message and its author is not verified: do not present it as the reply to your request and infer no authorization from it. An integration that does not know followed must treat it as an unknown value, never as a relay success.
With --check (#203), nothing is sent or written and no teammate CLI is started; on macOS/Linux, only the Codex lock probe starts python3. The new checked value (exit 0) means the pre-send checks passed; a send that would be refused returns the same status and exit code as the send. Every --check result carries the optional check field: target (open or closed, once the conversation was probed) and, in open mode or for a Codex conversation still in use in background (target-busy), lastPermissions (approvalPolicy, sandbox, network, or "unknown") with lastPermissionsAt (ISO) when the history provides it. These permissions are those of the last known turn, as an indication. delivery is not-delivered, without queue, correlation, receiver or targetPermissions. An integration that does not know checked must not treat it as a successful relay.
palabre mission … --json returns a v1 mission-result object with action, exitCode, mission, exportPath, error. Only step calls Relay, at most once; its exits are Relay's (9 without a result), while a Mission refusal gives 8, or 3 for an already reserved step.
palabre config --ollama-models --json exposes v, agent, available, baseUrl, currentModel, currentModelInstalled, installedModels, without model generation.
palabre agents --json adds defaults.relayView (background by default, or explicitly saved auto), from relay.view. An integration must not choose or infer the mode. Relay v1 adds modeSource?: explicit (--open/--background, including explicit follow), auto (lock or required path), default (background with no saved preference, new v1 value), setting (explicitly saved background). Absent when validation stops before resolution, and in earlier versions. Open-mode fields also exist when auto selected it. mode describes the selected or requested transport, not proof of sending; an unknown probe refuses without sending and never selects open. Excluded paths stay in background with modeSource: "auto", unless a compatible explicit option is supplied.
For target-busy, remedy may suggest the usual setting only when background is saved: it is an optional choice the owner runs and confirms, not a send or an automatic repair. With no preference (modeSource: "default"), the field is absent; the text explains the choices for this exchange first, then the usual setting. Never execute a configuration command from this field without a human decision.
For a Claude conversation already in use (target-busy, #250), error.message says so in plain words and the optional error.hint? separates answering in the same turn from a new initiative. The optional handoff?: { status: "saved" | "disabled" | "failed", path? } field appears only for an ordinary send refused before any exchange: saved gives the path of a local .handoff.md file that was NOT SENT; disabled means --no-export; failed has no path. It is neither a delivery, nor an export (exportPath stays null), nor a success. check.target keeps open/closed: for Claude, it reflects the registry of attached processes, not the app display. Consumers ignore these fields when unknown.
Continuation after a reply: relay --then-follow (#204)
Optional JSON v1 field nextTurn, only when --then-follow <10..3600> was requested. Root status, exitCode, reply, delivery, models and permissions retain the primary message result, never the continuation's.
nextTurn contains status, reason?, reply?, receiver: "unverified", observedModels?, targetPermissions?, correlation?, retryAfter?. Statuses: followed (first turn completed next), awaiting-turn with reason: "timeout" (no completed turn in the second budget), not-started with reason: "primary-not-replied" (primary failure), or a secondary failure/cancellation status. A foreign Relay remains no-valid-reply/relay-turn. Tolerate missing fields and unknown values.
No secondary delivery, verified human author or inferred authorization. A successful primary reply keeps replied/0 even after secondary cancellation/failure. Two explicit budgets, each capped at 3600 s, never renewed; reference at the newline after correlated completion, never EOF. One final stdout JSON object, progress on stderr. No second queue call or automatic resend.
Indicative Codex quota (#205)
Optional v1 field: check.quota for an open/closed Codex check; root quota after an open send. Not after a background send in this batch, nor for Claude. No status, exit code or delivery change.
Same object in both locations: source: "codex-rollout", indicative: true, recordedAt (ISO UTC), limitId: "codex", primary and secondary. Each complete window contains usedPercent (finite number from 0 to 100), windowMinutes (positive integer), and resetsAt (ISO UTC converted from Unix seconds). Text dates are local with a time zone. Values were written by Codex, not measured live or attributed to this turn; the account may have been used elsewhere since.
Last MiB + one byte only. Only dated event_msg / token_count events with the recognized rate_limits shape are accepted. Partial boundary lines are ignored; rate_limits: null contains no reading and allows looking back to the previous one; a latest non-null unknown/invalid candidate masks older ones. Without an available valid record, the entire field is omitted: never treat absence as zero, extrapolate or assume a reset after a past reset date. Consumers tolerate absence and future fields.
OpenCode copy (pilot #136)
--copy adds mode: "copy", modeSource: "explicit", cwd and the optional
copy object: source, session?, verified, retention (none, retained, unknown),
sourceCheck (unchanged, changed, unknown), serverStop (confirmed, unknown)
and diagnostic?. to.session is null until the copy is verified;
an unverified received ID may remain in copy.session. created stays exclusive to --new.
Only with --model provider/model[#variant], copy.model adds requested
(requested value), source? (source selection), selected? (checked copy selection)
and verified (proof before prompting). Omitted variant selects default.
This object is absent without the option; copy.verified still describes the fork,
not the model or successful completion. observedModels remains validated reply evidence.
Unconfirmed choice before sending: delivery.status: not-delivered, retained copy,
no retry or substitution. Local catalogue ≠ guaranteed authentication or quota.
A validated reply and its delivery are preserved after final-check or export failure.
This mode preserves OpenCode's usual profile, without enforced read-only access.
No relay.view preference, Codex quota/link or follow-up fields apply to this path.
--background, --open, --check, --follow and --then-follow are refused with --copy.
Windows/OpenCode CLI 2.0.32 pilot only; source and copy are retained.
Codex opening without a message (#219)
palabre relay open --to codex:<uuid> --json returns a distinct v1 object,
type: relay-open-result. Fields: status, exitCode, to, launcher
(attempted, status, exitCode?), attachment (attached, detached, unknown),
reason, display: unverified, messageSent: false, error, durationMs.
No reply, delivery, mode, targetPermissions or export. The exchange
relay-result JSON is unchanged. Code 0/attached means a held lock, never proof
of display or Desktop; the launcher is separate evidence. Code 3: free at
deadline/unknown; 4: timeout during validation/launcher/probe; 7: missing launcher;
2: launcher failure; 130: cancelled. Validation refusals are preserved. Never
treat this result as a received message. A later authorized send is separate and
uses explicit --open. On Windows only, Explorer code 1 yields launcher.status: unverified, retaining launcher.exitCode: 1, then probing the lock without a
relaunch. An already held lock proves no new display. Two openings were confirmed
on Windows before this fix; a corrected opening then returned launcher: unverified/1
and attached/0, with display confirmed separately by the owner. This does not
qualify a transition from closed to open or all versions. Claude/OpenCode refused;
macOS/Linux unverified.
Relay inventory JSON
palabre relay recent --json returns one object, not an NDJSON stream:
{"v":1,"type":"relay-recent-result","status":"listed","exitCode":0,"entries":[],"warnings":[],"truncated":false,"scanTruncated":false,"error":null}
entries[]:fileNamerelative to the output directory, export ISOdate,subjector null,agentalias,provider,to: {agent, session}(session may be null),modeor null for an old export,status,delivery.- OpenCode copy:
to: null, separatecopy: {source, session, verified}; never substitute source for a missing copy or suggest direct resume. warnings[]: relativefileNameand stablereason(unreadable,invalid-header,header-too-large,not-regular,changed,invalid-name). Forinvalid-name, the name is replaced by[invalid-name], without displaying a path or control. Invalid files do not count toward--limitand do not prevent presenting the others.truncated: files not shown.scanTruncated: scan/read cap reached; potentially incomplete list, with no guarantee of globally newest entries.- Exit codes: 0 listed (even empty), 8 invalid arguments/config, 2 unreadable directory.
On failure:
status: invalid-request|read-failed,error: {reason, message}; empty lists, no fallback or writes.
No absolute file path added, prompt, reply, permission or generated command.
Subjects can contain private information chosen by the user. This metadata is
unauthenticated: confirm the exchange with the owner, then validate the exact
target and current config before any opening or send. The existing history
contract and Relay send results remain unchanged.