Output and errors

Agents consume JSON, not terminal tables. This page is the contract every other page in this section relies on: how to turn JSON on, the envelope shape, where output goes, and the stable codes the CLI guarantees. Read it once and branch on it. (Per-command flags live in the command reference.)

Get machine-readable output

Pass --json explicitly in scripts. The CLI also switches to JSON automatically when stdout is not a terminal, but an explicit flag keeps logs auditable.

Trigger	Result
`--json`	JSON on stdout.
`--output json` / `--output table`	Forces JSON on, or human tables on.
Non-TTY stdout (piped or redirected)	JSON automatically.

Precedence: --output wins, then --json, then the TTY check (non-terminal → JSON, terminal → human tables).

Data goes to stdout. Diagnostics, progress, and errors go to stderr. Parse stdout; never scrape stderr for results.

Read the success envelope

Almost every command returns the same two-field envelope. (The few that don’t are listed under envelope exceptions.)

string

required

Stable identifier for the output shape, for example repost.events.search/v1. Branch on this — it is versioned and never changes meaning within a major version.

object

required

The command result. Its shape is determined by schema.

repost events search 'method:POST' --bucket stripe-prod --since 15m --limit 2 --json

{
  "schema": "repost.events.search/v1",
  "data": {
    "items": [
      {
        "id": "evt_01JZ8V1",
        "bucket_id": "bkt_01HV9S",
        "method": "POST",
        "path": "/stripe/webhook",
        "received_at": "2026-06-19T08:31:22Z",
        "response_status": 500
      }
    ],
    "total": 12,
    "next_cursor": "eyJvZmZzZXQiOjJ9",
    "has_more": true
  }
}

Guard on schema, then read data. The same result, parsed two ways — this is your consuming code, not Repost internals:

result=$(repost events search 'method:POST' --bucket stripe-prod --since 15m --json)

# Fail loudly if the shape isn't the one you built against
echo "$result" | jq -e '.schema == "repost.events.search/v1"' >/dev/null

# Read fields; take the next page only when there is one
echo "$result" | jq -r '.data.items[] | select(.response_status >= 500) | .id'
next=$(echo "$result" | jq -r 'if .data.has_more then .data.next_cursor else empty end')

import { execFileSync } from "node:child_process";

const stdout = execFileSync("repost", [
  "events", "search", "method:POST",
  "--bucket", "stripe-prod", "--since", "15m", "--json",
]);
const result = JSON.parse(stdout.toString());

if (result.schema !== "repost.events.search/v1") {
  throw new Error(`unexpected schema: ${result.schema}`);
}
const failed = result.data.items.filter((e) => e.response_status >= 500);
const nextCursor = result.data.has_more ? result.data.next_cursor : null;

Event payloads in data are redacted by default — credential and signature headers and secret-like JSON keys are masked, but PII is not. See Transcript safety for exactly what is and isn’t removed.

Know the envelope exceptions

A few commands do not use the {schema, data} envelope. An agent that assumes a schema field everywhere will break on these.

Command	Output
`expect`	A single bare JSON object (no envelope, no `schema`). Always JSON, even without `--json`.
`tail`	NDJSON — one bare JSON object per matching event, one per line. Always JSON.
`capabilities`	Top-level `{ schema, version, commands }`. Always JSON.
`events get --body-only`	The raw request body, no envelope.
`docs schema`	`{ schema, command, output_schema, output_mode, envelope, data_shape? }`.
`docs agent` / `docs search`	Markdown text, not JSON.

Wait commands (expect, tail) are covered in Wait for events. Discovery commands (capabilities, docs schema) are covered in Discovery.

Handle errors

When JSON is enabled, failures are structured: the error object goes to stderr and the process exits non-zero.

string

required

Stable machine code. Branch on this, never on the message.

string

required

Human-readable explanation. For people, not programs.

integer

required

Mirrors the process exit status (see the table below).

string

Suggested next step, when one applies.

string

Always present; defaults to repost docs agent.

string

The exact scope to request. Present only on forbidden_scope.

string

Where to mint a token with the missing scope. Present only on forbidden_scope.

repost replay evt_01JZ8V1 --bucket stripe-prod --forwarder prod-api --yes --json

{
  "error": {
    "code": "forbidden_scope",
    "message": "missing required scope: write",
    "exit_code": 3,
    "hint": "create or select a token that includes the write scope",
    "docs": "repost docs agent",
    "missing_scope": "write",
    "token_creation_url": "https://app.repost.sh/settings/tokens"
  }
}

Decide from error.code and exit_code, never from the human message:

# Capture stdout (data) and stderr (the error envelope) separately
if out=$(repost replay evt_01JZ8V1 --bucket stripe-prod --forwarder prod-api --yes --json 2>err.json); then
  echo "$out" | jq '.data'
else
  case "$(jq -r '.error.code' err.json)" in
    rate_limited|upstream_unavailable) action=retry ;;   # the only codes worth retrying
    forbidden_scope)                   action=request_scope ;;
    partial_failure)                   action=inspect ;;
    *)                                 action=fail ;;
  esac
  exit "$(jq -r '.error.exit_code' err.json)"
fi

// A pure decision from the code alone — no message parsing.
type RepostError = { code: string; exit_code: number; missing_scope?: string };

function decide(error: RepostError | undefined) {
  if (!error) return { action: "succeed" } as const;      // no error key = success
  switch (error.code) {
    case "rate_limited":
    case "upstream_unavailable": return { action: "retry" } as const;
    case "forbidden_scope":      return { action: "request_scope", scope: error.missing_scope } as const;
    case "partial_failure":      return { action: "inspect" } as const;
    default:                     return { action: "fail", exit: error.exit_code } as const;
  }
}

`error.code`	exit	When	Agent response
`validation_failed`	2	Bad input — a client-side flag/argument check or HTTP 400/422	Fix the command. Do not retry unchanged.
`active_org_required`	2	A user token can see zero or multiple licensed organizations, so a mutation has no unambiguous org	Use an organization token or select a user context with exactly one licensed org.
`unauthorized`	3	Invalid or missing token (401)	Refresh or replace `REPOST_TOKEN`.
`forbidden_scope`	3	Token lacks a scope (403)	Request `missing_scope` or take a read-only path.
`not_found`	4	Unknown id/bucket/forwarder (404)	Verify the id and active organization.
`quota_exceeded`	5	Plan limit reached (402)	Not transient. Stop or reduce scope.
`rate_limited`	6	Server limit (429)	Back off, then retry.
`timeout`	7	`expect` / `tail` / `replay wait` deadline, or `promote setup` browser pairing deadline	Report the unmet wait. Inspect state before retrying.
`partial_failure`	8	`health --fail-on` breach; `replay wait` with failures	Inspect details before declaring success.
`conflict`	1	State changed under you (409/412)	Refresh state, then retry.
`upstream_unavailable`	1	Service error / unknown (5xx)	Retry with backoff, then report instability.

validation_failed, active_org_required, forbidden_scope, and quota_exceeded are terminal — retrying the same command will fail the same way. Only rate_limited and upstream_unavailable are worth retrying.

Pin to a contract version

Current contract

Every command schema is repost.<area>/v1. The success envelope is {schema, data}; the failure envelope is {error}. Exit codes 0–8 are stable. When a payload changes incompatibly, the schema suffix bumps (/v2) and both are served during migration — so an agent can pin to the version it was built against.

Continue

Authentication & scopes

Recover from unauthorized and forbidden_scope, and the read / write / secrets model.

Transcript safety

What events get / events diff mask in data — and what they leave in the clear.

Discovery

Pull each command’s exact data shape from the binary with docs schema.

Foundations

Playbooks

Operations

Output and errors

Get machine-readable output

Read the success envelope

Know the envelope exceptions

Handle errors

Pin to a contract version

Continue

Authentication & scopes

Transcript safety

Discovery

​Get machine-readable output

​Read the success envelope

​Know the envelope exceptions

​Handle errors

​Pin to a contract version

​Continue

Authentication & scopes

Transcript safety

Discovery

Get machine-readable output

Read the success envelope

Know the envelope exceptions

Handle errors

Pin to a contract version

Continue