Quickstart

This guide walks through installing aisw, running the first-run wizard, and switching between accounts.

It is the fastest path if you want to:

install an AI CLI account switcher
manage multiple Claude Code accounts on one machine
manage multiple Codex CLI accounts on one machine
manage multiple Gemini CLI accounts on one machine
switch between work and personal AI CLI profiles

1. Install aisw

Install from crates.io:

cargo install aisw

For local development, build from the checked out repository:

cargo install --path .

Or download a pre-built binary from the GitHub Releases page and place it somewhere on your PATH.

2. Run the first-run wizard

aisw init

The wizard will:

Create ~/.aisw/ and write a default config.json.
Detect your shell and offer to append the shell hook to your RC file.
Scan for existing credentials for Claude Code, Codex CLI, and Gemini CLI, and offer to import each one with defaults of profile name default and label imported. You can override both during interactive onboarding. Imported live credentials become active by default unless aisw is already managing an active profile for that tool. When an import is marked active, aisw also applies it to the live tool config immediately.

Running aisw init a second time is safe — the shell hook will not be duplicated, and existing profiles will not be overwritten.

Successful setup also prints a short next-step hint so you can move directly into list or use.

Shell hook

The shell hook is optional. Normal aisw use behavior updates the live config locations that Claude, Codex, and Gemini actually read, so standalone claude, codex, and gemini commands pick up the selected profile without extra shell steps.

Accept the prompt during init, or install the hook manually if you want shell-level environment exports for advanced or manual workflows:

Shell	Command
bash	`echo 'eval "$(aisw shell-hook bash)"' >> ~/.bashrc`
zsh	`echo 'eval "$(aisw shell-hook zsh)"' >> ~/.zshrc`
fish	`echo ‘aisw shell-hook fish

After adding the hook, restart your shell or source the file.

3. Add a profile

aisw add claude work --api-key sk-ant-api03-...
aisw add codex personal --api-key sk-...
aisw add gemini client --api-key AIza...

Use --label to add a human-readable description:

aisw add claude work --api-key sk-ant-api03-... --label "Work subscription"

Use --set-active to switch to the new profile immediately after adding it:

aisw add claude work --api-key sk-ant-api03-... --set-active

4. Switch profiles

aisw use claude work
aisw use codex personal

The selected profile is applied directly to the live config location each tool reads. For manual shell workflows, --emit-env is still available:

eval "$(aisw use claude work --emit-env)"

5. Check status

aisw status

Shows which profile is active for each tool, whether the binary is installed, and the state of credential files and whether the live tool config matches the configured active profile. Token validity, quota, and subscription state are not checked. If profiles are stored for a tool but none is active, status reports that explicitly.

6. List profiles

aisw list
aisw list claude
aisw list --json

7. Remove a profile

aisw remove claude old-work

A backup of the profile is created before deletion. Use --force to remove the currently active profile, and --yes to skip the confirmation prompt.

Automation note

If you are scripting aisw today:

use --yes for init, remove, and backup restore
use --api-key for non-interactive add
use --json on list, status, and backup list
use use --emit-env only when you explicitly want raw shell exports

8. Rename a profile

aisw rename claude default work

Use this when onboarding imported a generic profile name like default and you want a clearer identifier without deleting and recreating the profile.