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 surfaces the URL and waits.
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
(the ws_-prefixed external ID from
erectl agents), monitor an
in-flight invocation, and retrieve raw output once the run
completes.
All exec commands require an API key with the
execution scope. Requests hit
/v1/exec/* on the router. Destructive and
irreversible tools land in pending_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 <wid> --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 list # List executions
erectl exec show <execution-id> # Show execution details
erectl exec raw <execution-id> # Get raw execution output
tools
Lists all tools available in the project's registered EEM manifests.
erectl exec tools
Output columns: Name, Description.
tool-show
Renders the tool's Name and
Description for a single tool. Fuller
descriptor fields (risk, domain, parameter schema, timeout)
are available from the underlying
/v1/exec/tools/<name> endpoint but are
not surfaced by the CLI today.
erectl exec tool-show kubectl_drain
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 agent that serves the specified workspace.
Tools tagged destructive or
irreversible in the EEM manifest enter
pending_approval on invoke. The CLI prints the
invocation ID and exits; nothing runs until a human approves
via erectl approvals
approve <aid>.
erectl exec invoke \
--workspace ws_a1b2c3d4 \
--tool kubectl_get \
--args '{"resource": "pods", "namespace": "default"}'
Options
| Option | Required | Description |
|---|---|---|
--workspace <wid> | Yes | Workspace external ID. |
--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> surfaces the canonical name and description, and the underlying GET /v1/exec/tools/<name> endpoint returns the full schema. |
The response includes the created invocation ID. Use
exec watch <invocation-id> to poll until
completion, or fetch the persisted execution record later with
exec show <execution-id>.
watch
Polls an invocation's status every 2 seconds until it reaches a terminal state. Times out after 10 minutes.
The router's full terminal set is completed,
failed, cancelled, rejected,
and timeout. The current CLI only stops on
completed, failed, or
cancelled; an invocation that ends in
rejected or timeout will keep polling
until the 10-minute CLI deadline.
erectl exec watch 5f9c3b1a-8d0e-4c2f-9c1d-2b9f5e7a8c10
Arguments
| Argument | Description |
|---|---|
invocation-id (positional) | Invocation external ID. |
Press Ctrl+C to stop watching. The poll loop runs until the invocation reaches a terminal state, the 10-minute deadline fires, or you interrupt.
cancel
Cancels a non-terminal invocation (queued,
running, or pending_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. |
list
Lists execution records for the project.
erectl exec list
Output columns: ID, Invocation, Status, Exit Code, Created.
show
Shows details for a single execution record.
erectl exec show 7d2e4a91-0b3c-4f5a-8e1d-9c4b3a2f1e08
Arguments
| Argument | Description |
|---|---|
execution-id (positional) | Execution external ID. |
raw
Retrieves the raw byte payload returned by the agent for a completed execution.
erectl exec raw 7d2e4a91-0b3c-4f5a-8e1d-9c4b3a2f1e08
Arguments
| Argument | Description |
|---|---|
execution-id (positional) | Execution external ID. |
Examples
Invoke a Kubernetes tool and wait for completion
# Invoke kubectl_get and watch for result
INV_ID=$(erectl exec invoke \
--workspace ws_a1b2c3d4 \
--tool kubectl_get \
--args '{"resource": "pods", "namespace": "kube-system"}' \
--output json | jq -r '.id')
erectl exec watch "$INV_ID"
List recent failed executions
erectl exec list --output json | jq '.data[] | select(.status == "failed")'
Check raw output of a failed execution
erectl exec raw 7d2e4a91-0b3c-4f5a-8e1d-9c4b3a2f1e08
See Also
The erectl exec CLI covers eight 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:
- Agent introspection
GET /v1/exec/agents/:id/manifest,.../environment,.../connectivity- Execution streams
GET /v1/exec/executions/stream(SSE)- Rerun
POST /v1/exec/executions/:id/rerun- Learnings
/v1/exec/learnings/*(3 routes)- Context
/v1/exec/context(2 routes)
Approvals workflow has a dedicated CLI surface; see erectl approvals.
