[!NOTE] Not IBM AIX. This project has no relation to IBM's AIX operating system.
aix (AI eXecute) is a profile-aware CLI for AI tools and LiteLLM-compatible AI gateways. You describe your profiles once (which key, which gateway, where each secret comes from) and aix launches Claude Code, Codex, OpenCode, Pi, or any other tool with the matching environment variables.
Why
If you use more than one AI tool, or more than one key, the setup drifts:
Claude Code reads ANTHROPIC_*, most other tools read OPENAI_*, some
LiteLLM-aware tools read LITELLM_*, and the key itself lives in a password
manager, a secrets file, or an environment variable that differs between work
and personal machines. aix replaces that with named profiles:
config file → profile selection → secret resolution → env vars → your tool
30-second example
# ~/.config/aix/aix.toml
= "work"
[]
= { = "AIX_BASE_URL" }
[]
= "Work"
= { = "pass show aix/work-key" }
[]
= "Personal"
= { = "/run/secrets/aix/personal" }
Features
- Launch any tool with a profile.
aix <tool> [PROFILE]works with any binary on$PATH. Optional[tools.<name>]entries choose the executable, credential format (anthropic,openai, orboth), and extra variables. - Backend-agnostic secrets. Keys and gateway URLs can be a literal, an
environment variable, a file, or the output of a command (
pass, 1Password CLI, Bitwarden CLI, ...). - Shell integration.
aix use workswitches the active profile in bash, zsh, fish, Nushell, and PowerShell.aix env,aix exec, andaix shellcover the cases where you want the variables directly. - Gateway utilities. List models, show current key spend and budget, check
gateway status, and run read-only diagnostics with
aix doctor. - One-shot inference. Pipe text into
aix ask, or define reusable[prompts.<name>]presets foraix prompt. - Sign in with ChatGPT. Profiles can use ChatGPT plan credentials for Codex app-server and OpenCode v2 through a local bridge, so the tool never sees the real token.
- Per-profile tool configs. Select a separate Codex home, Pi agent directory, or OpenCode config per profile.
- Local, metadata-only run history.
aix rungives a command a run ID and records its lifecycle without storing arguments, prompts, output, or secrets. - Scriptable. A stable
--jsonenvelope and documented exit codes. - Declarative on Nix. A home-manager module generates the config. The CLI itself has no Nix dependency and runs on Linux, macOS, and Windows.
API-key values are not logged or written to disk by aix. OAuth credentials are the exception: they are retained in aix's owner-only local auth store. See Security notes.
Installation
Linux / macOS:
|
Windows (PowerShell):
irm https://github.com/get-aix/aix/releases/latest/download/install.ps1 | iex
Cargo (the crate is aix-rs; the binary is aix):
Nix: nix run github:get-aix/aix -- --help, or use the
home-manager module.
The installers fetch the latest stable release. Prebuilt binaries cover Linux x86_64/aarch64, macOS arm64/x86_64, and Windows x86_64. See Installation for custom install locations, manual downloads, and nightly builds. Release notes are in the changelog.
Quick start
-
Create
aix.tomlin the platform config directory:~/.config/aix/on Linux,~/Library/Application Support/aix/on macOS,%APPDATA%\aix\on Windows (see Config path resolution). Start from the example above or the full example. -
Check it:
-
Enable profile switching in your shell (zsh shown; see Shell integration for other shells):
-
Launch a tool:
Documentation
| Installation | Installer scripts, Cargo, prebuilt binaries, Nix, nightly builds |
| Configuration | Config location and format, secret sources, models and aliases |
| Running AI tools | aix <tool>, [tools.<name>], emitted variables, Codex/Pi/OpenCode specifics |
| Shell integration | aix use, aix env, aix exec, aix shell |
| Gateway commands | models, spend, status, doctor, usage, cache |
| One-shot inference | aix ask and aix prompt presets |
| Managed runs | aix run, run history, run policies |
| ChatGPT authentication | Sign in with ChatGPT profiles |
| Nix and home-manager | Declarative configuration |
| Command reference | All commands and global options |
| JSON output and exit codes | Scripting contract |
| Security notes | How secrets and credentials are handled |