xeroctl approvals
List the pending approval queue, inspect a request, and approve or reject from a shell. This is the escalation path destructive XEM 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.
Status
Known defect (route prefix mismatch). The
current CLI build targets /v1/approvals/* without the
exec/ segment and will return 404 until
the prefix is aligned. The documented server path
(/v1/exec/approvals/*) is authoritative; the CLI fix
is tracked in the project Fix Queue.
Deferred flags. --note,
--reason, and --confirm are accepted by
the CLI but the router does not yet decode them, so they are
not persisted or compared server-side. Treat them as
forward-compatible placeholders.
Usage Pattern
xeroctl approvals list [--risk <r>]
xeroctl approvals show <aid>
xeroctl approvals approve <aid> [--note <n>] [--confirm <tool-name>]
xeroctl approvals reject <aid> [--reason <r>]
xeroctl approvals watch [--risk <r>]
list
Lists approval requests. Optionally filter by risk level.
xeroctl approvals list
xeroctl approvals list --risk destructive
xeroctl approvals list --risk irreversible
Options
| Option | Required | Description |
|---|---|---|
--risk <r> | No | Filter by risk level: read, write, destructive, irreversible. |
Output columns: ID, Status, Risk, Tool, Created.
show
Shows details for a single approval, including the tool, workspace, risk level, and resolution status.
xeroctl approvals show 5f9c3b1a-8d0e-4c2f-9c1d-2b9f5e7a8c10
Arguments
| Argument | Description |
|---|---|
approval-id (positional) | Approval ID (UUID string, e.g. 5f9c3b1a-8d0e-4c2f-9c1d-2b9f5e7a8c10). |
approve
Approves a pending approval request. The CLI accepts an optional note and a tool-name confirmation flag.
xeroctl approvals approve 5f9c3b1a-8d0e-4c2f-9c1d-2b9f5e7a8c10
xeroctl approvals approve 5f9c3b1a-8d0e-4c2f-9c1d-2b9f5e7a8c10 --note "Reviewed and confirmed"
xeroctl approvals approve 5f9c3b1a-8d0e-4c2f-9c1d-2b9f5e7a8c10 --confirm kubectl_drain
Arguments
| Argument | Description |
|---|---|
approval-id (positional) | Approval external ID. |
Options
| Option | Required | Description |
|---|---|---|
--note <n> | No | Approval note. Planned to land in the audit log and on the approval bus event. See Status -- currently deferred. |
--confirm <tool-name> | No | Safety check that the approval's tool name matches the supplied value. See Status -- currently deferred. |
reject
Rejects a pending approval request. The CLI accepts an optional rejection reason.
xeroctl approvals reject 5f9c3b1a-8d0e-4c2f-9c1d-2b9f5e7a8c10
xeroctl approvals reject 5f9c3b1a-8d0e-4c2f-9c1d-2b9f5e7a8c10 --reason "Wrong target namespace"
Arguments
| Argument | Description |
|---|---|
approval-id (positional) | Approval external ID. |
Options
| Option | Required | Description |
|---|---|---|
--reason <r> | No | Rejection reason. Planned to land in the audit log and forward to the inference model on the rejection bus event. See Status -- currently deferred. |
watch
Polls every 5 seconds (interval is fixed; no flag). New approvals
appear on the next poll, resolved ones drop off. The router also
exposes a Server-Sent Events feed at
/v1/exec/approvals/stream for push delivery; the current
CLI does not consume it.
xeroctl approvals watch
xeroctl approvals watch --risk destructive
Options
| Option | Required | Description |
|---|---|---|
--risk <r> | No | Filter watched approvals by risk level. |
Press Ctrl+C to stop watching. The watch loop runs until interrupted.
Examples
On-call approval workflow
The --note and --confirm flags are
accepted today but not yet persisted server-side
(see Status). The approval still succeeds;
only the annotation is dropped.
# Watch for high-risk approvals
xeroctl approvals watch --risk destructive
# When an approval appears, inspect it
xeroctl approvals show 5f9c3b1a-8d0e-4c2f-9c1d-2b9f5e7a8c10
# Approve (note and confirm are forward-compatible placeholders)
xeroctl approvals approve 5f9c3b1a-8d0e-4c2f-9c1d-2b9f5e7a8c10 \
--note "Verified: drain is safe, no user pods" \
--confirm kubectl_drain
Batch-reject all pending approvals (JSON mode)
xeroctl approvals list --output json \
| jq -r '.data[] | select(.status == "pending_approval") | .id' \
| xargs -I{} xeroctl approvals reject {} --reason "Batch rejection"
