Athena Agent CLI

The Agent CLI is a small statically-linked binary (athena) that wraps the Athena REST API. It’s the same surface human operators and AI agents (like Claude) use to log in, pick a workspace, manage agents, and stream executions.

The CLI is external-only — it ships from a public RustFS feed as a single binary, talks HTTP to the Athena API, and has zero dependency on the internal database, workflow engine, or any other Athena crate. Anything you can do via the API you can do via the CLI.

Why agent-friendly?

Every command emits machine-readable output:

JSON on stdout for successful responses (envelope {data, next_cursor})
Flat structured errors on stderr with stable code, message, hint, trace_id
Documented exit codes (0=success, 2=usage, 3=auth, 13=forbidden, 9=execution failed, …)
NDJSON streaming for agent run (one JSON object per line, terminal event has is_terminal: true)
Schema dumps via --schema on every subcommand so a fresh agent can discover the surface without docs

The shape is intentionally boring so an agent can grep, jq, or shell-pipe the output without surprises.

Install

Get the binary on your $PATH in under a minute. Install →

Quickstart

Agents

list, get, create, clone, update, draft lifecycle, run. Agents →

Reference

Exit codes, error codes, machine-readable schema dumps. Reference →

Common workflows

Goal	Commands
First-run setup	`athena login --email <e> --password "$ATHENA_PASSWORD"` → `athena workspace list` → `athena workspace use <slug>`
Run an agent	`echo '{"input":"hi"}' \| athena agent run my-agent --input -`
Discover surface	`athena --schema` (full JSON tree of every subcommand)
Inspect a single command	`athena agent run --schema`
Update the CLI	`athena update` (no API config or login required)
Build an agent from a JSON spec	`athena agent create --from-spec ./spec.json`
Iterate on a draft	`athena agent draft create my-agent` → `agent draft update` → `agent draft publish`

Configuration

The CLI stores everything under ~/.athena/:

~/.athena/
  bin/athena           the binary
  config.toml          profile + api_url + active_workspace
  credentials.toml     chmod 600, written by `athena login`

You can override the location with ATHENA_CONFIG_DIR=/some/path. See Authentication for the full resolver chain.