xeroctl exec
Drive XEM (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
XEM execution management surface. Browse the tools your project's
XEM manifests expose, invoke them against an operational workspace
(the ws_-prefixed external ID from
xeroctl 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 xeroctl
approvals.
Usage Pattern
xeroctl exec tools # List available tools
xeroctl exec tool-show <name> # Show tool details
xeroctl exec invoke --workspace <wid> --tool <name> \
--args '<json>' # Invoke a tool
xeroctl exec watch <invocation-id> # Poll invocation status
xeroctl exec cancel <invocation-id> # Cancel an invocation
xeroctl exec list # List executions
xeroctl exec show <execution-id> # Show execution details
xeroctl exec raw <execution-id> # Get raw execution output
tools
Lists all tools available in the project's registered XEM manifests.
xeroctl 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.
xeroctl exec tool-show kubectl_drain
xeroctl exec tool-show openstack_server_stop
Arguments
| Argument | Description |
|---|---|
name (positional) | Tool name as declared in the XEM manifest. |
invoke
Invokes a tool in a workspace. The tool call is dispatched to an online XEM agent that serves the specified workspace.
Tools tagged destructive or
irreversible in the XEM manifest enter
pending_approval on invoke. The CLI prints the
invocation ID and exits; nothing runs until a human approves
via xeroctl approvals
approve <aid>.
xeroctl 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 XEM manifest; xeroctl 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.
xeroctl 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
xeroctl 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.
xeroctl exec cancel 5f9c3b1a-8d0e-4c2f-9c1d-2b9f5e7a8c10
Arguments
| Argument | Description |
|---|---|
invocation-id (positional) | Invocation external ID. |
list
Lists execution records for the project.
xeroctl exec list
Output columns: ID, Invocation, Status, Exit Code, Created.
show
Shows details for a single execution record.
xeroctl 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.
xeroctl 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=$(xeroctl exec invoke \
--workspace ws_a1b2c3d4 \
--tool kubectl_get \
--args '{"resource": "pods", "namespace": "kube-system"}' \
--output json | jq -r '.id')
xeroctl exec watch "$INV_ID"
List recent failed executions
xeroctl exec list --output json | jq '.data[] | select(.status == "failed")'
Check raw output of a failed execution
xeroctl exec raw 7d2e4a91-0b3c-4f5a-8e1d-9c4b3a2f1e08
See Also
The xeroctl 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 xeroctl:
- 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 xeroctl approvals.
