> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.athenaintel.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.athenaintel.com/_mcp/server.

# 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

#### macOS / Linux

```bash
# 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')"
```

#### Windows

```powershell
# Download the x86_64-pc-windows-msvc archive from the latest release,
# extract it, and put athena.exe on your PATH.
Start-Process "https://github.com/Athena-Intel/athena-cli/releases/latest"
```

#### From source

```bash
git clone https://github.com/Athena-Intel/athena-cli
cd athena-cli
cargo build --release --bin athena
```

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.

> **Note**
>
> 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:

```bash
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:

```bash
export ATHENA_API_KEY="<your api key>"
```

Confirm it works:

```bash
athena users me
```

## Explore

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

```bash
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:

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

## Call an operation

```bash
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:

```bash
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:

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

> **Warning**
>
> **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:
>
> ```bash
> 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`.

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

| Variable              | Description                              |
| --------------------- | ---------------------------------------- |
| `ATHENA_API_KEY`      | API key — the same variable the SDKs use |
| `ATHENA_BASE_URL`     | Override the API base URL                |
| `ATHENA_CA_BUNDLE`    | PEM file with extra trust roots          |
| `ATHENA_PROXY`        | HTTP(S) proxy URL                        |
| `ATHENA_TIMEOUT_SECS` | Total request timeout                    |
| `ATHENA_OUTPUT`       | Default `--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

```bash
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](https://github.com/Athena-Intel/athena-cli/blob/main/reference.md),
regenerated from the spec on every API change.