Actualyze CLI

The Actualyze CLI, aai, runs the same workspace operations as the Actualyze app from a terminal or a script: teams, budgets, API keys, endpoints, Virtual Models, requests and more. It is a management tool, not a client for everyday inference (its aai infer command only sends a one-off test prompt), and it signs in through your browser rather than with an API key. Use it to create the API keys the other tools on this page need, and to give a coding agent a way to manage your workspace.

#Before you start

• An Actualyze account in a workspace, and the Actualyze app open in a browser where you can sign in.
• To create API keys, a role that can hold them (Workspace Admin, Member or FinOps Manager) and membership of at least one team. Every key binds a team and a budget when it is created.

#Install

On macOS or Linux:

curl -fsSL https://github.com/actualyze-ai/cli/releases/latest/download/install.sh | sh

On Windows, in PowerShell:

irm https://github.com/actualyze-ai/cli/releases/latest/download/install.ps1 | iex

The script downloads the binary for your platform, checks its SHA-256 checksum, and installs it to ~/.local/bin on macOS and Linux or %LOCALAPPDATA%\actualyze\bin on Windows. The Windows script adds that directory to your user PATH; open a new terminal for the change to apply. On macOS and Linux the script prints a note when ~/.local/bin isn't on your PATH; add it to your shell profile. Then confirm the install:

aai version

• ACTUALYZE_INSTALL_DIR installs to a different directory and ACTUALYZE_VERSION installs a specific version instead of the latest. Set them for the sh side of the pipe, as in curl -fsSL https://github.com/actualyze-ai/cli/releases/latest/download/install.sh | ACTUALYZE_VERSION=16.0.0 sh. In PowerShell, set $env:ACTUALYZE_VERSION = "16.0.0" before running the install command.
• Builds are published for Linux (x64, arm64), macOS (x64, arm64) and Windows (x64). The CLI ships as release binaries; the source is private.
• Each release carries build-provenance attestations. The release notes on the releases page give the steps to verify them.

#Connect to Actualyze

Sign in by pairing the CLI with your browser session:

aai auth login

The CLI prints a login URL and a short pairing code, and opens the URL in your browser. Sign in to Actualyze if you aren't already, check that the code on the page matches the one in your terminal, and approve. The CLI picks up the approval and stores its own session. The pairing attempt expires after ten minutes. On a remote or headless machine, copy the URL into any browser where you can sign in.

Check who you are and which workspace you're in:

aai auth status

• The CLI talks to https://app.actualyze.ai.
• If you belong to more than one workspace, aai workspace list shows them and aai workspace use <name> switches.
• The session is stored in ~/.config/actualyze/credentials.json on macOS and Linux (under $XDG_CONFIG_HOME/actualyze/ when that is set) and under %LOCALAPPDATA%\actualyze on Windows. On macOS and Linux the file is readable only by you.
• aai auth logout ends the session and deletes the stored credentials.

#Create an API key for your tools

Every inference tool on this page needs an Actualyze API key. You can create one from the CLI instead of the app:

aai api-key create --name "Laptop: Claude Code" --team "<team-name>" --budget "<budget-name>"

• --name and --team are required. --team and --budget take names; --team-id and --budget-id take IDs.
• Leave out --budget and the key binds the team's default budget. If the team has no default budget, the key is created without one and its requests fail with 402 Budget required, so pass --budget.
• The default permission is read-write (--permission read-write), which inference needs. A read-only key can't call models. If you pass --scopes, include inference.
• --expires-at takes an ISO 8601 UTC timestamp ending in Z, such as 2026-12-31T00:00:00Z. Leave it out for a key that doesn't expire. (The app's dialog defaults to 30 days; the CLI doesn't.)
• --spend-ceiling sets the key's own monthly limit in dollars, such as --spend-ceiling 50. Leave it out for no per-key limit. aai api-key update-ceiling --api-key "<key-name>" --spend-ceiling <amount> changes it later.

The CLI prints the key once, followed by This value is shown once and will not be stored. Copy it into the tool you're setting up or into a secrets manager. Add --json if a script needs the full response. In the TUI, the transcript shows the key as [redacted] and the value appears once above the prompt; add > key.txt to the command to save it to a file.

aai api-key list shows your keys without their secrets. aai api-key revoke --api-key "<key-name>" revokes one immediately; revocation can't be undone.

#Give your coding agent the CLI

aai skill generates an agent skill: an instruction document that teaches a coding agent what the CLI does, how sign-in works, the command grammar, and how to find commands and flags with --help and --json. It is built from the CLI's own command list, runs offline, and needs no sign-in.

The default format is an Agent Skills SKILL.md named aai-cli. For Claude Code, install it for your user:

aai skill --out ~/.claude/skills/aai-cli/SKILL.md

To install it for one project instead, write it to .claude/skills/aai-cli/SKILL.md in the project root. For other tools that read Agent Skills, write it to that tool's skills directory; the file must be SKILL.md inside a directory named aai-cli. Without --out, the document goes to stdout.

For tools that read an AGENTS.md file, append the agents format:

aai skill --format agents >> AGENTS.md

--format plain writes a standalone document for any other tool. The generated skill ends with a line recording the CLI version that produced it. Regenerate it after you update the CLI.

#Use the interactive TUI

For a session of several commands in a row, start the TUI:

aai tui

You type the same commands without the leading aai, with TAB completion for commands, flags and names. Optional live panes show budget use and workspace events; /budgets and /events toggle them. Sign in with aai auth login before you start it. Mouse support takes over your terminal's text selection; /mouse off inside the TUI gives it back.

For one-off commands and scripts, run aai <command> directly and add --json for machine-readable output.

#Keep it updated

The CLI checks for a newer release in the background, at most once an hour, and prints a one-line notice when one exists. To upgrade in place:

aai update

Set ACTUALYZE_NO_UPDATE_CHECK=1 to turn off the check and the notice, for example in CI. While it is set, aai update refuses to run too; unset it when you want to upgrade.

#Troubleshooting

• aai: command not found: the install directory isn't on your PATH. Add ~/.local/bin to your shell profile (macOS, Linux). On Windows, open a new terminal after installing, or add %LOCALAPPDATA%\actualyze\bin to your user PATH.
• Login timed out or Login expired: the pairing attempt lasts ten minutes. Run aai auth login again.
• Session expired: your CLI session has ended. Run aai auth login again.
• aai api-key create is refused: you must belong to the team you name and have access to the budget you name. Ask a workspace admin to add you. You can also hold at most 25 active API keys; revoke ones you no longer use.
• The agent's instructions don't match your CLI: the installed skill came from an older version. Regenerate it with the same aai skill command you installed it with.

#Reference

The CLI also exports a model catalog file for OpenCode: aai catalog export --format opencode --output actualyze-models.json writes a file OpenCode loads through OPENCODE_MODELS_PATH, replacing its built-in catalog. If you're on more than one team, add --team "<team-name>" or --api-key "<key-name>" to choose whose access the file covers. Most OpenCode users don't need it; the Actualyze plugin in the OpenCode guide reads your model list automatically.

• Releases, install scripts and changelog: actualyze-ai/cli