docs
// Tools

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

bash
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.

bash
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.

bash
erectl exec tool-show k8s_drain_node erectl exec tool-show openstack_server_stop

Arguments

ArgumentDescription
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>.

bash
erectl exec invoke \ --workspace ws_a1b2c3d4 \ --tool k8s_get_pods \ --args '{"namespace": "default"}'

Options

OptionRequiredDescription
--workspace <ws_id>YesThe workspace's ws_ id, from erectl workspaces list --kind operational.
--tool <name>YesTool name to invoke.
--args <json>YesJSON-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>NoA 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.

bash
erectl exec watch 5f9c3b1a-8d0e-4c2f-9c1d-2b9f5e7a8c10

Arguments

ArgumentDescription
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.
bash
erectl exec cancel 5f9c3b1a-8d0e-4c2f-9c1d-2b9f5e7a8c10

Arguments

ArgumentDescription
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.

bash
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.

text
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

ArgumentDescription
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.

bash
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

OptionDescription
--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).
--allFollow 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

bash
# 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

bash
erectl exec history --status failed

Inspect one run

bash
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.