> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aperium.apps.hillspire.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Terminal client (aperium / ap)

> The experimental Rust terminal chat client for Aperium's deployed API.

<Warning>
  **Experimental / internal.** The terminal client is an internal, unreleased tool
  distributed through a private Homebrew tap. It is not part of the supported product
  surface. Expect rough edges and breaking changes.
</Warning>

`aperium` (and its short alias `ap`) is a native terminal chat client for Aperium. It's a
thin, chat-centric frontend that talks to the **deployed `/api` surface** over REST and
Server-Sent Events — the same backend the web UI and mobile shells use. It is a *client*,
not a build tool; for local development use the [`dev` CLI](/develop/dev-cli) instead.

It's written in Rust (Clap for the command surface, Ratatui for the TUI) and ships as a
single binary under two interchangeable names, `aperium` and `ap`.

## What it does

* A chat TUI: streaming transcript, tool-call badges, approval/question prompts, a `/`
  command palette, model/agent/theme/environment pickers, session and artifact browsers,
  and input history.
* Tiered artifact rendering: datatables as aligned tables and dashboards walked into native
  charts, with an open-in-browser escape hatch for full fidelity.
* One-shot commands (`ask`, `sessions`, `agents`, `auth`, `config`) with output that
  degrades to plain text when piped or when `NO_COLOR` is set.

## Install

<Note>
  The release archives are private GitHub assets, so installation requires a token with
  read access to the Aperium repository. This is an internal tool — access is gated.
</Note>

### Homebrew (no Rust required)

```bash theme={null}
export HOMEBREW_GITHUB_API_TOKEN=<token-with-read-access>
brew tap hillspire/tap git@github.com:Hillspire/homebrew-tap.git
brew trust hillspire/tap
brew install aperium-cli
```

Add the export to your shell profile so `brew upgrade aperium-cli` keeps working. Two steps
are easy to miss: the tap is a **private** repo (clone over SSH, or run `gh auth setup-git`
for HTTPS), and `brew trust hillspire/tap` is required because the formula carries custom
Ruby. Supported platforms: macOS (arm64 + x86\_64) and Linux x86\_64.

### From source

```bash theme={null}
cargo install --path apps/aperium-cli          # -> ~/.cargo/bin/{aperium,ap}
cargo install --path apps/aperium-cli --force  # re-run to update after a pull
```

Verify with `which aperium` and `aperium --version`.

## Configure and authenticate

Settings live in a config file (`aperium config path`; `aperium config edit` opens it) and
can be grouped into named **environment profiles** (local / staging / prod), each with its
own `base_url`, token, and OIDC block:

```bash theme={null}
aperium config list
aperium config use <name>
aperium auth login          # OAuth2 authorization-code + PKCE on a loopback redirect
```

Authentication is a bearer token, resolved from (highest first) `APERIUM_TOKEN`, the active
profile's stored token, or — for local stacks with header-fallback auth — a dev-fixtures
identity. `--profile <name>` (or `APERIUM_PROFILE`) overrides per invocation.