CLI

Athena CLI

The Athena CLI (athena) is generated from the same OpenAPI specification as the Python and TypeScript SDKs, so every public API operation is available as a subcommand — no per-endpoint work, and no drift between the three.

Reach for it when you want to explore the API, script an operation, or work from a terminal or CI job without writing code.

Install

$# The repo is private: this authenticates the script fetch AND the release
$# downloads in one go (requires the gh CLI, logged in).
$GITHUB_TOKEN="$(gh auth token)" sh -c "$(gh api repos/Athena-Intel/athena-cli/contents/install.sh -H 'Accept: application/vnd.github.raw')"

The installer picks the right build for your platform, including the static musl build on Alpine and other non-glibc systems, and verifies the download against the release checksums.

The repository is private, so an unauthenticated curl | sh cannot even fetch the script — raw.githubusercontent.com returns 404. The command above authenticates both the script fetch and the release-asset downloads.

Authenticate

Store your key in the OS keyring:

$athena auth login
$athena auth status   # shows every credential source it can see

Or pass it through the environment — the same ATHENA_API_KEY the SDKs read:

$export ATHENA_API_KEY="<your api key>"

Confirm it works:

$athena users me

Explore

The command tree mirrors the API, so --help is the reference:

$athena --help                     # every command group
$athena assets --help              # operations on one resource
$athena assets list --help         # flags for one operation

Two flags make it agent- and script-friendly:

$athena assets list --schema       # machine-readable schema for this scope
$athena assets list --dry-run      # print the request, send nothing

Call an operation

$athena assets list
$athena assets list --format table
$athena sessions list --query 'items[].{id: id, title: title}'
$athena aop execute_async --json '{"aop_asset_id": "asset_…"}'

Request bodies come from --json, a flag per field, or stdin:

$echo '{"asset_type": "document", "title": "Notes"}' | athena assets create --json -

Read assets

read-asset exposes the same progressive-disclosure read the agent runtime uses — anchors, formats, versions, and pagination:

$athena read-asset "asset_abc"
$athena read-asset "asset_abc?anchor=page&page=3&format=text"
$athena read-asset "asset_abc@4"                 # a pinned version
$athena read-asset asset_a asset_b asset_c       # up to 10 per call
$athena read-asset-capabilities                  # what each asset type supports

Long assets come back truncated. A large text read returns only the first 50,000 characters, and it does so as a successful response — nothing in the exit code says the content is partial. The CLI warns on stderr when this happens. Pass --page-all to follow every window and concatenate them:

$athena read-asset "asset_abc" --page-all

Output formats

--format accepts json (default when piped), table (default on a TTY), yaml, csv, jsonl, raw, and http.

$athena assets list --format json | jq '.items | length'
$athena assets list --format csv > assets.csv
$athena assets list --page-all --format jsonl   # NDJSON, one record per line

--query takes a JMESPath expression and is applied before formatting, which is usually shorter than piping through jq.

Environment variables

VariableDescription
ATHENA_API_KEYAPI key — the same variable the SDKs use
ATHENA_BASE_URLOverride the API base URL
ATHENA_CA_BUNDLEPEM file with extra trust roots
ATHENA_PROXYHTTP(S) proxy URL
ATHENA_TIMEOUT_SECSTotal request timeout
ATHENA_OUTPUTDefault --format value

HTTPS_PROXY / HTTP_PROXY / NO_PROXY / SSL_CERT_FILE are also honored. A .env file in the working directory is auto-loaded on startup.

Shell completion

$athena completion zsh > "${fpath[1]}/_athena"

bash, fish, and powershell are also supported.

Full reference

Every command, flag, and endpoint is listed in reference.md, regenerated from the spec on every API change.