Run

athena agent run executes a published agent. By default it streams the execution as NDJSON; pass --final-only to wait for the terminal event and emit a single response.

Default — streaming (NDJSON)

echo '{"input":"hello"}' | athena agent run my-agent --input -

Output is one JSON object per line. Every line has at minimum:

{ "execution_id": "019f902b-db71-7ea4-8ef2-60a8ff5747cd", "event": "node_started", "node_id": "trigger-1", "ts": "2026-05-21T12:00:00Z" }
{ "execution_id": "019f902b-db71-7ea4-8ef2-60a8ff5747cd", "event": "node_finished", "node_id": "trigger-1", "ts": "2026-05-21T12:00:00Z" }
...
{ "execution_id": "019f902b-db71-7ea4-8ef2-60a8ff5747cd", "event": "execution_finished", "status": "completed", "output": {...}, "is_terminal": true }

The last event always has is_terminal: true. Consumers can pipe through jq -c or read line-by-line without buffering surprises.

The CLI caps the SSE buffer at 64 KiB. If a malformed server stream never emits the separator the CLI rejects the connection with stream_error (exit 7) instead of OOMing the process. If the connection closes cleanly but no terminal event arrives, the CLI exits 9 with stream_lost and a hint to look up the execution manually.

Inputs

Source	Example
File	`--input ./input.json`
Stdin	`--input -` (the convention)
Inline	`--input '{"q":"hello"}'`

The CLI rejects non-JSON inputs at the boundary with a clear error.

Idempotency

For one-shot retries, pass --idempotency-key:

athena agent run my-agent --input @./input.json --idempotency-key run-12345

The server dedupes within a window per (agent_id, idempotency_key) — calling twice with the same key yields the same execution.

Terminal JSON — `--final-only`

echo '{"input":"hi"}' | athena agent run my-agent --input - --final-only

Uses the streaming endpoint, suppresses progress events, and emits one terminal JSON response on stdout when the execution finishes. Useful for scripts, smoke tests, and short workflows where you don’t care about progress events.

{
  "execution_id": "019f902b-db71-7ea4-8ef2-60a8ff5747cd",
  "status": "completed",
  "output": {
    "text": "...",
    "usage": { "total_tokens": 120 },
    "node_outputs": {
      "ai-1": { "text": "..." }
    }
  },
  "latency_ms": 842
}

The connection stays open for the duration of the execution. If the workflow fails or the stream ends without a terminal event, the CLI exits non-zero using the same exit-code mapping as the streaming mode.

Exit codes

Pass/fail signal scripts can act on:

Code	Meaning
0	Success
2	Usage / invalid input / failed pre-flight validation
3	Auth — not logged in or token expired and refresh failed
13	Forbidden — logged in but no permission for this workspace / agent
4	Not found — agent slug/ID doesn’t exist
5	Conflict — optimistic-lock race on draft update
6	Rate limited — back off and retry
7	Unreachable — network failure, chunk decode error, malformed stream
8	Payment required — workspace credits exhausted
9	Execution failed — workflow ran but exited with `status: failed`, or stream closed without terminal event
10	Execution cancelled
11	Execution timed out
12	Execution suspended (HITL waiting on approval)

See Reference → Exit codes for the full table.

Error envelope

Every non-zero exit writes to stderr:

{
  "code": "rate_limit",
  "message": "Too many concurrent executions for this workspace",
  "hint": "Rate-limited. Back off and retry; see Retry-After header if surfaced.",
  "trace_id": "abc-123-def-456"
}

code is stable across versions. trace_id correlates with server-side logs if you need to escalate.

Preview cost without running

athena agent preview-credits my-agent --input @./input.json

Returns the credit estimate plus a per-node breakdown. Useful before running expensive multi-step workflows.

Cancel a running execution

Currently API-only; CLI subcommand is planned for v1.1.

# Direct API call until the CLI subcommand lands:
curl -X POST -H "Authorization: Bearer $TOKEN" -H "X-Workspace-Id: $WS" \
  https://athena-dev-api.leanscale.com/executions/<execution_id>/cancel

Run