aix-rs 1.0.0

Manage AI gateway profiles and launch AI coding tools with the right credentials
aix-rs-1.0.0 is not a library.

[!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
default_profile = "work"

[endpoint]
base_url = { env = "AIX_BASE_URL" }

[profiles.work]
label   = "Work"
api_key = { command = "pass show aix/work-key" }

[profiles.personal]
label   = "Personal"
api_key = { file = "/run/secrets/aix/personal" }
aix claude              # Claude Code with ANTHROPIC_API_KEY/ANTHROPIC_BASE_URL for "work"
aix codex personal      # Codex with OPENAI_API_KEY/OPENAI_BASE_URL for "personal"
aix opencode work --dry-run   # show what would run; never prints secrets

aix status work         # gateway reachability, auth, and current-key budget
aix models work --filter gpt

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, or both), 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 work switches the active profile in bash, zsh, fish, Nushell, and PowerShell. aix env, aix exec, and aix shell cover 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 for aix 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 run gives a command a run ID and records its lifecycle without storing arguments, prompts, output, or secrets.
  • Scriptable. A stable --json envelope 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:

curl -fsSL https://github.com/get-aix/aix/releases/latest/download/install.sh | sh

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):

cargo install aix-rs

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

  1. Create aix.toml in 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.

  2. Check it:

    aix config path       # the file aix found
    aix config validate
    aix doctor
    
  3. Enable profile switching in your shell (zsh shown; see Shell integration for other shells):

    eval "$(command aix init zsh)"
    aix use work
    aix current
    
  4. Launch a tool:

    aix claude
    aix codex -- --help
    

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

License

AGPL-3.0-only