ReaperCI CLI and MCP

The release binary is both the ReaperCI hub and its official client. Running it without arguments (or with hub) starts the hub. Client commands call the stable /api/v1 surface with the scopes of the configured token.

Login and contexts

Create a service account in Settings > Team with only the scopes needed for the workflow. Save its one-time token without putting it in shell history:

printf '%s' "$REAPERCI_TOKEN" | reaperci login \
  --url https://ci.example.com \
  --context production \
  --token-stdin

reaperci context list, context current, context use NAME, and context delete NAME manage named targets. Tokens are never printed by the CLI. The context file is created with user-only permissions where the operating system supports POSIX modes. For ephemeral use, set both REAPERCI_URL and REAPERCI_TOKEN; these override the saved context. REAPERCI_CONTEXT selects a saved context without changing the default.

Resource commands

Commands emit structured JSON so humans, scripts, and agents see the same resource snapshots:

reaperci repos list
reaperci repos create demo --description "Demo service"
reaperci builds run demo --ref main
reaperci builds triage 42
reaperci caches list --repo demo
reaperci caches invalidate 7
reaperci previews list --repo demo --state active
reaperci previews close 12
reaperci deploys list --status pending_approval
reaperci deploys compare 18 --base 17
reaperci deploys promote 18 --environment production
reaperci deploys inspect 18
reaperci deploys rollback 18 --target-id 17 --confirm
reaperci servers create edge-1 --host edge.example.com --ssh-user deploy
reaperci runners list
reaperci runners update run_abc --enabled true --concurrency 2
reaperci usage get --period-start 2026-07-01T00:00:00Z --period-end 2026-08-01T00:00:00Z
reaperci environments list
reaperci audit list --actor-type service_account

Complex deployment requests accept a JSON object from a file or standard input:

reaperci deploys request --file deployment.json

The one-call build triage response includes the failed step, exit code, last 100 log lines, pipeline snapshot, commit, last green build, and a diff from that last green commit when the repository data is available.

deploys inspect refreshes desired-versus-observed Docker or Compose state and returns both the inspection time and last-known-live-state time. Rollback is deliberately two-step: review the deployment and previous successful image, then pass the reviewed --target-id with --confirm. The REST API and MCP tool enforce the same exact-target confirmation and reject it if the target changed.

MCP server

Start the stdio MCP server with the current context:

reaperci mcp serve

Configure an MCP client to launch that command, optionally supplying REAPERCI_CONTEXT. The server exposes repository, build, cache, deployment, server, runner, usage, environment, and audit tools. Every call goes through the public API, so token scopes, service-account identity, and audit recording remain in force.

Agents can request production deployments but cannot bypass protected-environment approval. The API rejects service-account approval attempts with human_approval_required, even when that credential also carries the general deployment approval scope. A signed-in human owner, admin, or operator must approve the pending production deployment in the dashboard.

The MCP implementation uses the official Model Context Protocol Go SDK and the standard newline-delimited JSON-RPC stdio transport. Keep stdout reserved for MCP messages; diagnostics are written to stderr.