docs
// Tools

erectl approvals

List the pending approval queue, inspect a request, and approve or reject from a shell. This is the escalation path destructive EEM tools dispatch into; every decision is recorded on the approval bus and the audit log.

Overview

The approvals command group provides CLI access to the human-in-the-loop approval queue. List pending approvals, inspect details, approve or reject requests, and watch for new approvals by polling on a fixed interval.

All approvals commands require an API key with the execution scope. The server mounts these routes under /v1/exec/approvals/* on the router, behind the same governed-execution gate documented in MCP Governed Execution. The approvals policies commands need the management scope and an owner's or operator's key.

Usage Pattern

bash
erectl approvals list [--risk read|write|destructive|irreversible] erectl approvals show <aid> erectl approvals approve <aid> [--note <n>] [--confirm "I approve"] erectl approvals reject <aid> [--reason <r>] erectl approvals watch [--risk read|write|destructive|irreversible] erectl approvals policies list [--scope project|workspace|eem] [--workspace <ws_id>] [--eem <id>] erectl approvals policies show <policy-id> erectl approvals policies set [<policy-id>] [--workspace <ws_id> | --eem <id>] [--name <n>] [settings] erectl approvals policies delete <policy-id> erectl approvals policies effective [--eem <id>] [--workspace <ws_id>] [--chat <chat_id>] [--risk <r>] erectl approvals policies autonomous show|on|off --workspace <ws_id|name>

list

Lists the calls waiting for a decision, oldest first. Optionally filter by risk level.

bash
erectl approvals list erectl approvals list --risk destructive erectl approvals list --risk irreversible

Options

OptionRequiredDescription
--risk <r>NoFilter by risk level: read, write, destructive, irreversible.

Output columns: ID, Risk, Tool, Workspace, Waiting since, Deadline, Decider. Decider shows the project decider's verdict on a call it was put to, for example unsure, 0.62 approve, and - otherwise.

show

Shows one approval: status, risk, tool, domain, workspace, description, created time, deadline, and decision time, followed by the call's arguments. For an irreversible call it also prints Confirm with: the phrase I approve, which approve --confirm must carry. A call the decider was put to also prints Decider, its verdict and confidence.

bash
erectl approvals show 5f9c3b1a-8d0e-4c2f-9c1d-2b9f5e7a8c10

Arguments

ArgumentDescription
approval-id (positional)Approval ID (UUID string, e.g. 5f9c3b1a-8d0e-4c2f-9c1d-2b9f5e7a8c10).

approve

Approves a pending approval request, with an optional note. An irreversible call also needs --confirm "I approve" (case and surrounding spaces do not matter); without it, or with anything else, the router refuses the approval. Approving a destructive or irreversible call requires the project owner role.

bash
erectl approvals approve 5f9c3b1a-8d0e-4c2f-9c1d-2b9f5e7a8c10 erectl approvals approve 5f9c3b1a-8d0e-4c2f-9c1d-2b9f5e7a8c10 --note "Reviewed and confirmed" erectl approvals approve 5f9c3b1a-8d0e-4c2f-9c1d-2b9f5e7a8c10 --confirm "I approve"

Arguments

ArgumentDescription
approval-id (positional)Approval external ID.

Options

OptionRequiredDescription
--note <n>NoApproval note, recorded with the decision.
--confirm "I approve"For irreversible callsTyped confirmation for an irreversible call: the phrase I approve, which show prints as Confirm with.

reject

Rejects a pending approval request. The CLI accepts an optional rejection reason.

bash
erectl approvals reject 5f9c3b1a-8d0e-4c2f-9c1d-2b9f5e7a8c10 erectl approvals reject 5f9c3b1a-8d0e-4c2f-9c1d-2b9f5e7a8c10 --reason "Wrong target namespace"

Arguments

ArgumentDescription
approval-id (positional)Approval external ID.

Options

OptionRequiredDescription
--reason <r>NoRejection reason, recorded with the decision.

watch

Polls every 5 seconds (interval is fixed; no flag) and prints one line per change: the time, the event, the approval id, and its risk, tool and workspace. The first poll reports every approval already waiting. The events are:

  • new: an approval started waiting (the line adds its deadline).
  • approved or rejected: someone decided it (the line adds the invocation's status).
  • expired: its deadline passed with no decision.
  • cancelled: its invocation was cancelled.
  • resolved: it left the queue and its record could not be read.

With -o json each event is one JSON object on its own line, {"event": ..., "at": ..., "approval": {...}}, where approval is what approvals show -o json prints. Every line is flushed as it is printed, so a pipe sees it at once. Each poll reads the whole queue, oldest first, 200 at a time, up to 5,000 waiting approvals; when more are waiting, the command prints a note once (on stderr with -o json), and a newer approval is reported when it comes within the 5,000. The router also exposes a Server-Sent Events feed at /v1/exec/approvals/stream for push delivery; the CLI does not consume it.

bash
erectl approvals watch erectl approvals watch --risk destructive erectl approvals watch -o json | jq -r 'select(.event == "new") | .approval.id'

Options

OptionRequiredDescription
--risk <r>NoFilter watched approvals by risk level.

Press Ctrl+C to stop watching. The watch loop runs until interrupted.

policies

An approval policy decides who answers a call waiting for approval. With mode human a person decides every call. With mode auto the project's decider answers first: it approves a write call when it is confident enough, rejects any call when it is confident it should not run, and leaves the rest of the write calls to a person or rejects them (low-confidence). The decider never approves a destructive, irreversible or database call: a person decides it, unless the decider rejects it.

A call uses its workspace's policy, else its EEM's (erectl eems policy), else the project's, else the platform default: a person decides. A chat that names a policy may only make it stricter. Owners and operators only.

bash
erectl approvals policies list erectl approvals policies list --scope workspace erectl approvals policies show 6f1e0b9a-2c4d-4e8f-9a1b-3c5d7e9f1a2b erectl approvals policies delete 6f1e0b9a-2c4d-4e8f-9a1b-3c5d7e9f1a2b

list prints ID, Scope (project, workspace or eem), Target (the workspace or EEM), Name, Mode, Max auto risk and Low confidence. show prints every setting; a threshold left unset shows the platform default it uses. delete removes a policy, and its calls fall back to the next one in the order above.

policies set

Changes a policy by id or, without one, the policy named --name (default default) of a workspace, an EEM or the project, and creates it when there is none. Only the settings given change.

bash
erectl approvals policies set --workspace ws_3kq9x2 --mode auto --max-auto-risk write erectl approvals policies set --reject-threshold 0.9 --low-confidence reject erectl approvals policies set 6f1e0b9a-2c4d-4e8f-9a1b-3c5d7e9f1a2b --approve-threshold-write default

Options

OptionRequiredDescription
<policy-id> (positional)NoThe policy to change.
--workspace <ws_id>NoThe workspace's policy.
--eem <id>NoThe EEM's policy. Not with --workspace.
--name <n>NoThe policy's name in its scope; with a policy id, renames it.
--mode human|autoNoWho answers a waiting call.
--max-auto-risk writeNoThe highest risk the decider may approve: write only. Destructive and irreversible calls always go to a person.
--approve-threshold-write <0..1|default>NoThe decider's confidence needed to approve a write call (default 0.92); default returns it to the platform default.
--reject-threshold <0..1|default>NoThe decider's confidence needed to reject a call (default 0.85).
--low-confidence human|rejectNoWhat happens to a call the decider is unsure about.

policies effective

Shows the policy a call would use and why: where it came from (workspace, EEM, project, chat or platform), every setting with the defaults filled in, the decider that would answer in the workspace (or why none would), and whether the EEM refuses decider approvals in that workspace. For any risk but write it shows Approve at: never (a person decides).

bash
erectl approvals policies effective --workspace ws_3kq9x2 erectl approvals policies effective --eem 7d41a0c2-5b9e-4f13-8c2a-1e6b3f9d0a47 --workspace ws_3kq9x2 --risk write

Options

OptionRequiredDescription
--eem <id>NoThe EEM serving the call.
--workspace <ws_id>NoThe call's workspace.
--chat <chat_id>NoThe chat the call comes from.
--risk <r>Noread, write, destructive (default) or irreversible.

policies autonomous

Autonomous trust approves a workspace's calls with no person. It needs two grants: the project's owner turns it on with autonomous on, and the host of each EEM that serves the workspace opts it in with allow_autonomous: true in its workspaces file (erectl workspaces declare --allow-autonomous). Either side turns it off alone, and a model can never turn it on. Irreversible calls and database calls always wait for a person. Every call it approves is recorded as approved by autonomous trust, with who turned it on and when. See Autonomous trust.

bash
erectl approvals policies autonomous show --workspace dev-code erectl approvals policies autonomous on --workspace ws_3kq9x2 erectl approvals policies autonomous off --workspace dev-code

show prints whether the trust is on, who turned it on and when, what it never approves, and one line per EEM that declares the workspace: whether its host allows it, whether the EEM supports it, and whether it applies there. The trust applies only where all three hold. on prints what it lifts before it is sent, and only an owner may run it; an operator is told so. An owner or an operator may run show and off. Turning it on again keeps the first record; turning it off when it is off is not an error. --dry-run prints what on or off would do.

Options

OptionRequiredDescription
show|on|off (subcommand)NoWhat to do; show when omitted.
--workspace <ws_id|name>YesThe operational workspace, by its id or its name.

Examples

On-call approval workflow

bash
# Watch for high-risk approvals erectl approvals watch --risk destructive # When an approval appears, inspect it erectl approvals show 5f9c3b1a-8d0e-4c2f-9c1d-2b9f5e7a8c10 # Approve; an irreversible call also takes --confirm "I approve" erectl approvals approve 5f9c3b1a-8d0e-4c2f-9c1d-2b9f5e7a8c10 \ --note "Verified: k8s_drain_node is safe, no user pods" \ --confirm "I approve"

Batch-reject all pending approvals (JSON mode)

bash
erectl approvals list --output json \ | jq -r '.data[].id' \ | xargs -I{} erectl approvals reject {} --reason "Batch rejection"

See Also