Agentic use is different from interactive use. A person reads tables, retries by hand, and infers intent from terminal text. A program needs the opposite: a stable output contract, bounded searches, explicit scopes, safe mutation rules, and a way to wait for webhook state without noisy polling. This section is for when another program drives repost.
Nearly every agent run cycles through the same six stages. Learn it once. Every playbook in this section is a variation on it.
flowchart LR
A["Identify<br/>auth status · whoami"] --> B["Discover<br/>capabilities · docs schema"]
B --> C["Search bounded<br/>--bucket --since --limit"]
C --> D["Inspect by ID<br/>events get · forwards chain"]
D --> E["Mutate behind a guard<br/>--dry-run · --idempotency-key"]
E --> F["Wait for state<br/>replay wait · expect"]
F --> Crepost auth status --json and repost whoami --json. Cache token scopes, active org, plan, and limits for the run.
repost capabilities --json once per binary version; repost docs schema "<command>" when you need an exact output shape.
Always pass --bucket, --since/--until, and --limit; page with --cursor. Avoid account-wide searches unless the job truly needs them.
Carry returned IDs into events get, events diff, and forwards chain. Don't rediscover the same resource.
Preview with --dry-run; bulk replay needs --yes; pass --idempotency-key on anything retryable.
Use replay wait, expect, or tail --count instead of polling. Branch on the terminal status, not on elapsed time.
The same loop, start to finish: verify the credential, check health, find the failing event, inspect its delivery chain, preview a replay, create it, and wait for the result.
repost auth status --json
repost health --bucket stripe-prod --forwarder prod-api --window 30m --json
repost events search 'method:POST AND path:/stripe/*' --bucket stripe-prod --since 30m --limit 5 --json
repost forwards chain evt_01JZ8V1 --bucket stripe-prod --forwarder prod-api --json
repost replay evt_01JZ8V1 --bucket stripe-prod --forwarder prod-api --dry-run --json
repost replay evt_01JZ8V1 --bucket stripe-prod --forwarder prod-api --yes --idempotency-key incident-1842-evt_01JZ8V1 --json
repost replay wait replay_01JZ8X9 --max-wait 5m --jsonReport success only when finalized is true and failed is 0. If failed > 0, inspect forwards chain for the remaining failure instead of retrying blindly.
The stable contract every run depends on: output, identity, how to query, and how to write safely. Read these before your first call.
The JSON envelope, the stdout/stderr split, exit codes, and stable error codes.
Environment auth, the read/write/secrets model, and missing-scope recovery.
capabilities, docs schema, and the repo primer.
The live observe stream versus the indexed store, and the blind spot between them.
Query grammar, the live-filter subset, and cursor pagination.
Dry-run, idempotency, the --yes guard, and conflict recovery.
Goal-driven recipes. Jump to the one that matches the task in front of you.
Health, bounded search, event detail, and the delivery retry chain.
expect for one match, tail for a bounded live stream.
Dry-run, idempotency, the --yes guard, and waiting for terminal state.
Pause and resume forwarders, and gate on health --fail-on.
Bootstrap a bucket and forwarder, and infer a payload schema.
Cross-cutting concerns that apply to every playbook.
Drop these operating rules into your agent's context, then commit a repo-local primer so every run starts informed.
You operate the Repost CLI headlessly.
- Always pass
--json. Read stdout for data, stderr for diagnostics. - Authenticate with
REPOST_TOKEN. Runrepost auth status --jsononce and cache identity, scopes, and active org. - Discover commands with
repost capabilities --json; get one command's shape withrepost docs schema "<command>". - Search with bounds (
--bucket,--since,--limit,--cursor). Move to stable IDs (events get,forwards chain). - Mutate only after a
--dry-run. Bulk replay needs--yes. Pass--idempotency-keywhen a retry could duplicate work. - Branch on
error.codeand exit codes, never on messages. Output redacts credentials but NOT PII. Scrub PII before sharing a transcript.
Run repost docs agent --install to write .repost/AGENTS.md into the current repository. See Discovery.
This section documents headless operation. For human deploy scripts, see Install & Auth and the forwarder command reference.
Orientation for agents#
Drive repost through the loop: identify → discover → search bounded → inspect by ID → mutate behind a guard → wait.
repost auth status --json # cache identity, scopes, active org
repost capabilities --json # command manifest (cache by version)
repost health --bucket B --forwarder F --window 30m --json
repost events search '<query>' --bucket B --since 30m --limit 20 --json
repost forwards chain <EVENT_ID> --bucket B --forwarder F --json
repost replay <EVENT_ID> --bucket B --forwarder F --dry-run --json # preview count
repost replay <EVENT_ID> --bucket B --forwarder F --yes --idempotency-key <KEY> --json
repost replay wait <JOB_ID> --max-wait 5m --json # branch on finalized + failedContract: success is {schema,data} on stdout; failure is {error:{code,exit_code,...}} on stderr with a non-zero exit. Branch on error.code, not messages. Output redacts credentials, not PII. Full rules: /agents/output-and-errors.
On This Page
Orientation for agents