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.
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.
| Code | Retryable | Means |
|---|---|---|
usage |
no | The command or its flags are wrong. |
config_invalid |
no | The policy would not load. |
not_found |
no | No such stack, or nothing to clear. |
precondition_failed |
no | Something must change before this can work. |
breaker_open |
no | The Circuit breaker is open. A person has to clear it. |
state_locked |
yes | Another run holds the lease. |
backend_unavailable |
yes | The backend could not be reached. |
registry_unavailable |
yes | The registry could not be reached. |
internal |
no | Something Ripen could not classify. |
Ignore codes you do not recognize; the set can grow without a version bump.
| Code | Meaning |
|---|---|
0 |
Success. |
1 |
Operational failure. |
2 |
Configuration or usage. |
3 |
A human needs to look at this. |
Read 3 narrowly: the Circuit breaker is open, or a rollback failed. Nothing
else uses it, so it is worth alerting on.
| Verb | Answers |
|---|---|
ripen status [--pretty] |
Every configured Service with its Baseline, Candidate, pending Proposal, and last result, plus the breaker, the lease, Notifier health, versions, and the effective policy. |
ripen candidates [--pretty] |
Every Candidate under observation and whether it has matured. |
ripen audit [--pretty] |
The audit trail, newest first. |
ripen explain [--pretty] <stack> |
Why the next run would, or would not, act on this stack. |
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_backAn 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"]}An unfinished Transaction blocks every apply and every Proposal on every
stack, so explain names it for each Service. status carries the same
Transaction as active_transaction, in one of four phases:
| Phase | The Transaction is |
|---|---|
deploying |
Sending the pinned Compose file to the backend. |
verifying |
Waiting for health and the running digest to prove the deploy. |
rolling_back |
Restoring the accepted Baseline after a failed deploy or a failed verification. |
proposing |
Asking the forge to open a Proposal. Nothing is deployed. |
A direct apply moves from deploying to verifying to rolling_back. It
skips verifying when the deploy itself fails, and it never goes back. A
Proposal is only ever proposing.
interrupted: true means the run that owned the Transaction is gone. Nothing
on the Agent surface can settle it: a person runs
ripen clear-breaker --reconcile --reason "…" at a terminal.
| Verb | Does |
|---|---|
ripen run --mode monitor |
One observation cycle. Never mutates a Stack. |
ripen run --mode apply |
One Transaction that may change one Service. |
ripen propose <stack> |
Open the Proposal for a matured Candidate. |
ripen clear-proposal <stack> --reason "…" |
Drop a reviewed, stale Proposal. |
ripen clear-breaker --reason "…" |
Close the Circuit breaker. |
ripen rebaseline <stack> [--service name] --reason "…" |
Accept a drifted Service's proven running digest as its Baseline. |
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.
| Verb | Does |
|---|---|
ripen daemon [--once] [--success-reports=false] |
Run on the configured interval. Writes nothing to stdout. Successful updates also print a plain-text report to stderr by default; disable it for structured-only consumers. |
ripen mcp [--enable-writes] |
Serve MCP over stdio. |
ripen notify test |
Send a real notifier.test through the real webhook path. |
ripen schema |
The JSON Schema for every response. |
ripen version |
Build metadata and every schema version. |
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)"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.
ripen mcp # four read tools
ripen mcp --enable-writes # plus three write toolsStdio, tools only. Nothing but protocol frames is ever written to stdout.
| Tool | CLI equivalent |
|---|---|
status |
ripen status |
candidates |
ripen candidates |
audit |
ripen audit |
explain |
ripen explain <stack> |
run_monitor_cycle |
ripen run --mode monitor (writes only) |
create_proposal |
ripen propose <stack> (writes only) |
clear_proposal |
ripen clear-proposal <stack> --reason … (writes only) |
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.
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:roWrites enabled, which is a deliberate choice for your own infrastructure:
command: ["mcp", "--enable-writes"]
volumes:
- ./policy.yaml:/config/policy.yaml:ro
- ./data:/dataThe difference is one flag and one :ro.