erectl exec
Drive EEM (the governed-execution mesh) from a shell. List discoverable tools, invoke them with typed args, watch the run, and inspect history. Destructive invocations route through the approval gate; the CLI submits the call, prints its invocation id and status, and exits; follow it with erectl exec watch.
Overview
The exec command group provides CLI access to the
EEM execution management surface. Browse the tools your project's
EEM manifests expose, invoke them against an operational workspace
(its ws_ id, from
erectl workspaces list --kind operational),
monitor an in-flight invocation, and list recent tool runs.
All exec commands require an API key with the
execution scope. Requests hit
/v1/exec/* on the router. Destructive and
irreversible tools land in awaiting_approval until a
human approves via erectl
approvals.
Usage Pattern
erectl exec tools # List available tools
erectl exec tool-show <name> # Show tool details
erectl exec invoke --workspace <ws_id> --tool <name> \
--args '<json>' # Invoke a tool
erectl exec watch <invocation-id> # Poll invocation status
erectl exec cancel <invocation-id> # Cancel an invocation
erectl exec show <invocation-id> # Show invocation details
erectl exec history [--from <iso>] [--to <iso>] \
[--status <s>] [--limit <n>] [--all] # List recent tool runs
tools
Lists all tools available in the project's registered EEM manifests.
erectl exec tools
erectl exec tools -o wide
Output columns: Name, Description. With -o wide also Domain, Risk, Approval (required or none), Timeout, Credential and EEM_ID, the EEM that advertises the entry. When two EEMs offer the same tool it is listed once for each, so the EEM_ID column tells them apart.
tool-show
Renders one tool: its name, description, domain, risk,
whether a call waits for approval, whether it is reversible,
the credential type, timeout, idempotency, the workspaces
it is served for and the EEMs that serve it (each EEM's
UUID and worker id), then its parameter schema, pretty-printed.
The schema is the shape exec invoke --args
takes.
erectl exec tool-show k8s_drain_node
erectl exec tool-show openstack_server_stop
Arguments
| Argument | Description |
|---|---|
name (positional) | Tool name as declared in the EEM manifest. |
invoke
Invokes a tool in a workspace. The tool call is dispatched to an online EEM that serves the specified workspace.
Tools tagged destructive or
irreversible in the EEM manifest enter
awaiting_approval on invoke. The CLI prints the
invocation id, its status, and the erectl exec watch
line to follow it, then exits; nothing runs until a human approves
via erectl approvals
approve <aid>.
erectl exec invoke \
--workspace ws_a1b2c3d4 \
--tool k8s_get_pods \
--args '{"namespace": "default"}'
Options
| Option | Required | Description |
|---|---|---|
--workspace <ws_id> | Yes | The workspace's ws_ id, from erectl workspaces list --kind operational. |
--tool <name> | Yes | Tool name to invoke. |
--args <json> | Yes | JSON-encoded tool arguments. Shape comes from the tool's parameter schema in the EEM manifest; erectl exec tool-show <name> prints that schema. |
--idempotency-key <key> | No | A repeat carrying the same key within the deduplication window (30 seconds by default) returns the earlier invocation instead of running the tool again, whatever its arguments. |
Without a key, an identical call (same tool, same arguments) repeated within
that window also returns the earlier invocation. To run the same call twice in
quick succession, give each its own --idempotency-key.
The response includes the created invocation id. Use
exec watch <invocation-id> to poll until
completion, or read the recorded invocation later with
exec show <invocation-id>.
watch
Polls an invocation's status every 2 seconds until it reaches a
terminal state. While the invocation waits for approval, the watch
gives up two minutes after the approval's deadline if the run has
not ended by then; a running invocation is followed until it ends at
the tool's own timeout. --wait-timeout <seconds>
gives up after that long instead.
It stops on every terminal status: completed,
failed, cancelled, rejected,
timeout, failed_router_restart, and
orphan_execution.
erectl exec watch 5f9c3b1a-8d0e-4c2f-9c1d-2b9f5e7a8c10
Arguments
| Argument | Description |
|---|---|
invocation-id (positional) | Invocation external ID. |
--wait-timeout <seconds> | Give up after this many seconds, whatever the state. |
Press Ctrl+C to stop watching. The poll loop runs until the invocation reaches a terminal state, its limit passes (the command then names the status and exits non-zero), or you interrupt.
cancel
Cancels a non-terminal invocation (queued,
dispatched, executing, or
awaiting_approval). To
reject an invocation waiting on approval, you can either
cancel it here or reject it via
erectl approvals.
Errors:
404 invocation_not_found, no invocation matched the supplied id.409 invocation_terminal, the invocation is already in a terminal state and cannot be cancelled.
erectl exec cancel 5f9c3b1a-8d0e-4c2f-9c1d-2b9f5e7a8c10
Arguments
| Argument | Description |
|---|---|
invocation-id (positional) | Invocation external ID. |
show
Shows one invocation as the router records it: id, tool,
domain, risk, status, created time, latency, and any error
code and message, followed by the call's parameters and its
result as JSON when present, then its timeline. A result
field longer than 16,384 characters, such as the
stdout of a large listing, is cut there with a
note; -o json prints the whole result.
erectl exec show 5f9c3b1a-8d0e-4c2f-9c1d-2b9f5e7a8c10
The Timeline block lists each moment of the
run, oldest first: requested, waiting for approval, escalated,
approved or rejected (with the approver's note or reason),
dispatched, started, and how it ended. People and EEMs are
named by id. -o json carries the same entries as
the timeline array.
Invocation Details:
ID: 5F9C3B1A-8D0E-4C2F-9C1D-2B9F5E7A8C10
Tool: k8s_drain_node
Domain: kubernetes
Risk: destructive
Status: completed
Created: 2026-10-17T14:02:11Z
Latency (ms): 41250
Parameters:
{
"node" : "worker-3"
}
Result:
{
"drained" : true
}
Timeline:
2026-10-17T14:02:11Z Requested by 3E1A9C24-7B5D-4F08-9A6E-1C2D3B4A5F60
2026-10-17T14:02:11Z Waiting for approval
2026-10-17T14:05:40Z Approved by 8B7C6D5E-4F3A-4B2C-9D1E-0F9A8B7C6D5E: ok for staging
2026-10-17T14:05:41Z Dispatched to C0FFEE00-1234-4567-89AB-CDEF01234567
2026-10-17T14:05:41Z Started
2026-10-17T14:06:22Z Finished
Arguments
| Argument | Description |
|---|---|
invocation-id (positional) | Invocation id (UUID). |
history
Lists recent tool runs, newest first. Without --from
the range starts seven days before --to, which
defaults to now.
erectl exec history
erectl exec history --status failed --limit 20
erectl exec history --from 2026-10-01T00:00:00Z --to 2026-10-08T00:00:00Z --all
Options
| Option | Description |
|---|---|
--from <iso> | Start of the range (ISO-8601). |
--to <iso> | End of the range (ISO-8601). |
--status <status> | Only runs with this status. |
--limit <n> | Rows per page, 1 to 200 (default 50). |
--all | Follow every page. Without it, the CLI notes when more runs exist. |
Output columns: Invocation, Tool, Risk, Status, Workspace, Created, Latency.
Examples
Invoke a Kubernetes tool and wait for completion
# Invoke k8s_get_pods and watch for result
INV_ID=$(erectl exec invoke \
--workspace ws_a1b2c3d4 \
--tool k8s_get_pods \
--args '{"namespace": "default"}' \
--output json | jq -r '.invocation_id')
erectl exec watch "$INV_ID"
List recent failed runs
erectl exec history --status failed
Inspect one run
erectl exec show 5f9c3b1a-8d0e-4c2f-9c1d-2b9f5e7a8c10
See Also
The erectl exec CLI covers seven leaves. The
governed-execution REST surface is broader; the following
endpoints are reachable today only via direct REST or via
MCP exec.* tools, not through erectl:
- Learnings
/v1/exec/learnings- Context
/v1/exec/context
Approvals workflow has a dedicated CLI surface; see erectl approvals.