The agent surface

Ripen's machine-facing interface is the CLI and one MCP server. They are the same surface: every MCP tool maps to a CLI verb with the same guard, the same parameters, and the same answer.

Neither can apply an update or clear the Circuit breaker from MCP. Those tools do not exist — not disabled, not permissioned, absent.

This page is about agents operating Ripen. Agents working on Ripen's own source are a different audience, served by AGENTS.md.

Everything answers one envelope

There is no --json flag. The default, and the only output an agent should consume, is one JSON object on stdout, success or failure:

{
  "schema_version": 1,
  "command": "status",
  "occurred_at": "2026-08-19T09:14:22Z",
  "ok": true,
  "data": { }
}

A failure is the same envelope with ok: false and a typed error:

{
  "schema_version": 1,
  "command": "propose",
  "occurred_at": "2026-08-19T09:14:22Z",
  "ok": false,
  "error": { "code": "precondition_failed", "message": "…", "retryable": false }
}

Failures also print one human-readable line on stderr. Machines can ignore stderr entirely; people usually want it.

The four read verbs — status, candidates, audit, explain — accept --pretty, which renders the same payload as text. It is never inferred from a TTY: an agent running in a pty still gets the envelope unless it asked. --pretty is not registered on writes, daemon, or mcp.

Error codes

Ignore codes you do not recognize; the set can grow without a version bump.

Exit codes

Read 3 narrowly: the Circuit breaker is open, or a rollback failed. Nothing else uses it, so it is worth alerting on.

The verbs

Reads

status is driven by the policy, not by what happens to be in the database: a Service that has never been observed still appears, with baseline: null.

audit reads the attempts table — the record of what Ripen did — never the Event stream, which is a notification channel. It pages:

ripen audit --limit 50
ripen audit --limit 50 --cursor 412        # from a previous next_cursor
ripen audit --run 01920e2f-…               # one run
ripen audit --stack media --result rolled_back

An empty cursor starts at the newest attempts. Otherwise, pass a positive decimal integer from next_cursor, within the signed 64-bit range. Signs, whitespace, and trailing text are rejected with a usage error. A null next_cursor means the last page.

The limit defaults to 50 when omitted, zero, or negative. Malformed limits and values that overflow pagination are rejected. CLI and MCP use the same pagination rules. The Web UI's /audit and /api/audit routes accept limit and cursor query parameters and return HTTP 400 for invalid values.

explain answers offline, from policy and state alone. No backend call, no registry call, no network. It lists the blockers in the order a run would hit them:

{"blockers": ["the configured mode is monitor", "the candidate matures at 2026-08-20T09:14:22Z"]}

Writes

The clear- verbs and rebaseline require a reason, and it is recorded. An operator saying what they fixed, or why a change should stand, is the point of the gate.

Process verbs

Identity on the wire

Every read carries backend, stack, and service, with service null for a stack-level policy. The state store's internal key never appears in JSON.

actor — cli, daemon, or mcp — is recorded on every write and every Event. It is determined by the surface that ran the code. There is no parameter for it, and no caller can declare its own.

Every run has a UUIDv7 run_id, persisted on attempts, echoed in status, and stamped on Events. It is how you tie an alert to what actually happened:

ripen audit --run "$(ripen run --mode monitor | jq -r .data.run_id)"

Schemas

ripen schema emits a JSON Schema per command, and the same documents are checked into docs/schema/v1/ and shipped in every release archive. A test asserts the two are identical, so the published schema cannot drift from what the binary emits.

Receivers should ignore unknown fields and unknown result codes. Adding either is not a breaking change and does not bump schema_version.

MCP

ripen mcp                    # four read tools
ripen mcp --enable-writes    # plus three write tools

Stdio, tools only. Nothing but protocol frames is ever written to stdout.

Results carry the identical Response envelope as structuredContent. A failure is isError: true with the failure envelope attached, never a JSON-RPC protocol error, so a caller can see what went wrong and correct itself.

Read-only mode is structural. Without --enable-writes the write tools are never registered and the write path is never built: the process loads no credentials and opens no clients. Apply mode and clear_breaker have no tool in either mode.

Container packaging

Read-only, which is what the Docker MCP Catalog entry ships:

services:
  ripen-mcp:
    image: ghcr.io/frankieramirez/ripen:latest
    command: ["mcp"]
    stdin_open: true
    volumes:
      - ./policy.yaml:/config/policy.yaml:ro
      - ./data:/data:ro

Writes enabled, which is a deliberate choice for your own infrastructure:

    command: ["mcp", "--enable-writes"]
    volumes:
      - ./policy.yaml:/config/policy.yaml:ro
      - ./data:/data

The difference is one flag and one :ro.