Discovery

Learn the command surface and output schemas directly from the binary, and install a repo-local agent primer.

The installed binary describes itself. An agent should learn the surface from repost rather than from a possibly-stale copy of these docs. The manifest and schemas always match the version in front of it.

Read the command manifest

capabilities is the first machine-readable inventory to fetch for a binary. It always emits JSON.

repost capabilities --json

The manifest lists command paths, usage, descriptions, command kind, group IDs, output mode, agent contract status, output schema names, and flags.

{
  "schema": "repost.capabilities/v1",
  "version": "8cf7709",
  "commands": [
    {
      "path": "events search",
      "use": "repost events search [QUERY]",
      "short": "Search received events",
      "kind": "command",
      "group_id": "search_debug",
      "output_mode": "json_envelope_or_table",
      "agent_contract": true,
      "output_schema": "repost.events.search/v1",
      "flags": [
        { "name": "bucket", "shorthand": "b", "type": "string", "usage": "Bucket slug or ID to search" },
        { "name": "limit", "type": "int", "default": "20", "usage": "Maximum events to return" }
      ]
    }
  ]
}

Cache the manifest by version. Refresh it after repost update, after installing a different binary, or when a workflow needs a command that is not present.

Read one command's schema

Use docs schema when generated code needs field-level expectations for a single command.

repost docs schema "events search"

The response gives the command path, output schema, output mode, runtime envelope shape, and a documented data shape when one exists.

{
  "schema": "repost.command_schema/v1",
  "command": "events search",
  "output_schema": "repost.events.search/v1",
  "output_mode": "json_envelope_or_table",
  "envelope": {
    "schema": "string",
    "data": "object",
    "error": "object"
  },
  "data_shape": {
    "items": "EventSearchItem[]",
    "total": "integer",
    "next_cursor": "string|null",
    "has_more": "boolean",
    "item": {
      "id": "string",
      "bucket_id": "string",
      "method": "string",
      "path": "string",
      "received_at": "RFC3339 timestamp",
      "response_status": "integer"
    }
  }
}

The envelope describes the runtime contract exactly. Most commands succeed with {schema, data} and fail with {error}; exception modes such as top_level_json, single_json_object, jsonl, and markdown are declared by output_mode. Use data_shape when present, and fall back to output_schema plus the Output & errors contract for commands without a field-level shape.

Look up search syntax

docs search prints a compact query cheatsheet:

repost docs search

The full grammar is in Search & filters: searchable fields, boolean operators and wildcards, the live-filter subset for expect/tail, and cursor pagination.

Install a repo primer

Commit a compact operating manual so every agent run in a repository starts informed.

repost docs agent --install
# writes .repost/AGENTS.md, then prints an @include line for your AGENTS.md / CLAUDE.md

--install writes .repost/AGENTS.md (mode 0600). Reference it from your existing agent instructions with @include .repost/AGENTS.md. The runbooks topic ships three ready-made procedures the agent can follow directly.

Every page in these docs also exposes assistant entry points (top-right Copy / Open in): copy as Markdown, open in ChatGPT, Claude, Perplexity, Cursor, or VS Code, or use the MCP endpoint. Append .md to any page URL for its canonical machine-readable form.

For agents

The .md form of any page (append .md to its URL) is the canonical machine-readable version, and pages in this section include agent-only blocks, like this one, that compress the human walkthrough into copy-ready commands. Prefer the .md export when ingesting these docs programmatically.