> ## Documentation Index
> Fetch the complete documentation index at: https://docs.repost.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents

> Drive Repost from coding agents, CI jobs, and headless automation with stable JSON contracts, scoped tokens, and safe mutation rules.

export const Section = ({children}) => {
  return <section className="py-10 border-t border-gray-100 dark:border-white/10 first:border-t-0 first:pt-6">
      {children}
    </section>;
};

export const SectionTitle = ({eyebrow, title, children}) => {
  return <div className="mb-8 max-w-3xl">
      <div className="mb-3 repost-eyebrow">{eyebrow}</div>
      <div className="text-2xl tracking-tight text-gray-950 dark:text-gray-100">{title}</div>
      <p className="mt-3 text-base leading-7 text-gray-600 dark:text-gray-400">{children}</p>
    </div>;
};

<div className="w-full">
  <Section>
    <div className="max-w-4xl">
      <p className="text-lg leading-8 text-gray-600 dark:text-gray-400">
        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 <code>repost</code>.
      </p>

      <div className="mt-7 repost-action-row">
        <a href="/agents/output-and-errors" className="repost-action-primary">
          Read the contract

          <Icon icon="arrow-right" size={15} />
        </a>

        <a href="/agents/diagnose-webhooks" className="repost-action-secondary">
          Diagnose a webhook
        </a>
      </div>
    </div>
  </Section>

  <Section>
    <SectionTitle eyebrow="Model" title="The operating loop">
      Nearly every agent run cycles through the same six stages. Learn it once — every playbook in this section is a variation on it.
    </SectionTitle>

    ```mermaid theme={null}
    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 --> C
    ```

    <Steps>
      <Step title="Identify">
        `repost auth status --json` and `repost whoami --json`. Cache token scopes, active org, plan, and limits for the run.
      </Step>

      <Step title="Discover">
        `repost capabilities --json` once per binary version; `repost docs schema "<command>"` when you need an exact output shape.
      </Step>

      <Step title="Search bounded">
        Always pass `--bucket`, `--since`/`--until`, and `--limit`; page with `--cursor`. Avoid account-wide searches unless the job truly needs them.
      </Step>

      <Step title="Inspect by ID">
        Carry returned IDs into `events get`, `events diff`, and `forwards chain`. Don't rediscover the same resource.
      </Step>

      <Step title="Mutate behind a guard">
        Preview with `--dry-run`; bulk replay needs `--yes`; pass `--idempotency-key` on anything retryable.
      </Step>

      <Step title="Wait for state">
        Use `replay wait`, `expect`, or `tail --count` instead of polling. Branch on the terminal status, not on elapsed time.
      </Step>
    </Steps>
  </Section>

  <Section>
    <SectionTitle eyebrow="Example" title="A complete run">
      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.
    </SectionTitle>

    <CodeGroup>
      ```bash Commands theme={null}
      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 --json
      ```

      ```json Final result theme={null}
      {
        "schema": "repost.replay.status/v1",
        "data": {
          "job_id": "replay_01JZ8X9",
          "status": "COMPLETED",
          "finalized": true,
          "total": 1,
          "pending": 0,
          "succeeded": 1,
          "failed": 0,
          "completed_at": "2026-06-19T08:42:11Z"
        }
      }
      ```
    </CodeGroup>

    <Check>
      Report success only when `finalized` is `true` **and** `failed` is `0`. If `failed > 0`, inspect `forwards chain` for the remaining failure instead of retrying blindly.
    </Check>
  </Section>

  <Section>
    <SectionTitle eyebrow="Foundations" title="Read once, cache for the run">
      The stable contract every run depends on: output, identity, how to query, and how to write safely. Read these before your first call.
    </SectionTitle>

    <Columns cols={3} className="gap-y-4">
      <Card title="Output & errors" icon="braces" href="/agents/output-and-errors" cta="Read output" arrow="true">
        The JSON envelope, the stdout/stderr split, exit codes, and stable error codes.
      </Card>

      <Card title="Authentication & scopes" icon="key-round" href="/agents/authentication" cta="Pick a token" arrow="true">
        Environment auth, the read/write/secrets model, and missing-scope recovery.
      </Card>

      <Card title="Discovery" icon="compass" href="/agents/discovery" cta="Learn the surface" arrow="true">
        `capabilities`, `docs schema`, and the repo primer.
      </Card>

      <Card title="Consistency model" icon="layers" href="/agents/consistency-model" cta="Two data planes" arrow="true">
        The live observe stream versus the indexed store, and the blind spot between them.
      </Card>

      <Card title="Search & filters" icon="filter" href="/agents/search-and-filters" cta="Write queries" arrow="true">
        Query grammar, the live-filter subset, and cursor pagination.
      </Card>

      <Card title="Safe mutations" icon="shield" href="/agents/safe-mutations" cta="Write safely" arrow="true">
        Dry-run, idempotency, the `--yes` guard, and conflict recovery.
      </Card>
    </Columns>
  </Section>

  <Section>
    <SectionTitle eyebrow="Playbooks" title="One page per job">
      Goal-driven recipes. Jump to the one that matches the task in front of you.
    </SectionTitle>

    <Columns cols={2} className="gap-y-4">
      <Card title="Diagnose a failing webhook" icon="search-check" href="/agents/diagnose-webhooks" cta="Investigate" arrow="true">
        Health, bounded search, event detail, and the delivery retry chain.
      </Card>

      <Card title="Wait for a webhook" icon="timer" href="/agents/wait-for-events" cta="Wait" arrow="true">
        `expect` for one match, `tail` for a bounded live stream.
      </Card>

      <Card title="Replay deliveries safely" icon="rotate-ccw" href="/agents/replay-deliveries" cta="Remediate" arrow="true">
        Dry-run, idempotency, the `--yes` guard, and waiting for terminal state.
      </Card>

      <Card title="Guard a deployment" icon="shield-check" href="/agents/guard-deployments" cta="Protect" arrow="true">
        Pause and resume forwarders, and gate on `health --fail-on`.
      </Card>

      <Card title="Provision a target" icon="circle-plus" href="/agents/provision-targets" cta="Set up" arrow="true">
        Bootstrap a bucket and forwarder, and infer a payload schema.
      </Card>
    </Columns>
  </Section>

  <Section>
    <SectionTitle eyebrow="Operations" title="Stay fast and safe">
      Cross-cutting concerns that apply to every playbook.
    </SectionTitle>

    <Columns cols={2} className="gap-y-4">
      <Card title="Caching & performance" icon="gauge" href="/agents/caching-performance" cta="Stay fast" arrow="true">
        Cache stable metadata, prefer waits to polling, and back off deliberately.
      </Card>

      <Card title="Transcript safety" icon="file-lock-2" href="/agents/transcript-safety" cta="Avoid leaks" arrow="true">
        What redaction does and does not cover — and why it never covers PII.
      </Card>
    </Columns>
  </Section>

  <Section>
    <SectionTitle eyebrow="Bootstrap" title="Prime your agent">
      Drop these operating rules into your agent's context, then commit a repo-local primer so every run starts informed.
    </SectionTitle>

    <Prompt description="Operating rules for driving the Repost CLI" actions={["copy", "cursor"]} icon="bot">
      You operate the Repost CLI headlessly.

      * Always pass `--json`. Read stdout for data, stderr for diagnostics.
      * Authenticate with `REPOST_TOKEN`. Run `repost auth status --json` once and cache identity, scopes, and active org.
      * Discover commands with `repost capabilities --json`; get one command's shape with `repost 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-key` when a retry could duplicate work.
      * Branch on `error.code` and exit codes, never on messages. Output redacts credentials but NOT PII — scrub PII before sharing a transcript.
    </Prompt>

    <p className="mt-4 text-sm leading-6 text-gray-600 dark:text-gray-400">
      Run <code>repost docs agent --install</code> to write <code>.repost/AGENTS.md</code> into the current repository. See <a href="/agents/discovery">Discovery</a>.
    </p>

    <Note>
      This section documents headless operation. For human deploy scripts, see [Install & Auth](/cli/install-auth#credential-priority) and the [forwarder command reference](/cli/reference#forwarder).
    </Note>
  </Section>
</div>

## Orientation for agents

Drive `repost` through the loop: identify → discover → search bounded → inspect by ID → mutate behind a guard → wait.

```bash theme={null}
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 + failed
```

Contract: 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.