aicli-switch

Switch between multiple Claude Code accounts without re-authenticating.

When one account hits its usage limit, just aicli-switch another-account — no need to claude login again.

Install

npm (recommended)

npm install -g @kio_ai/aicli-switch

This downloads the pre-built binary for your platform automatically.

Manual download

Download the binary for your OS from Releases:

| Platform | File | |----------|------| | Windows x64 | aicli-switch-windows-amd64.exe | | macOS x64 | aicli-switch-darwin-amd64 | | macOS Apple Silicon | aicli-switch-darwin-arm64 | | Linux x64 | aicli-switch-linux-amd64 | | Linux ARM64 | aicli-switch-linux-arm64 |

Move it to a directory in your PATH:

# macOS / Linux
chmod +x aicli-switch-*
mv aicli-switch-* /usr/local/bin/aicli-switch

# Windows — move to any directory in your PATH
move aicli-switch-windows-amd64.exe %USERPROFILE%\.local\bin\aicli-switch.exe

Build from source

Requires Go 1.24+:

git clone https://github.com/killaragorn/aicli-switch.git
cd aicli-switch
go build -o aicli-switch .

Quick Start

# Step 1: You're logged into account A in Claude Code
# Save it as a profile
aicli-switch add work

# Step 2: Log into account B
claude login

# Step 3: Save account B
aicli-switch add personal

# Step 4: Now switch freely — no re-login needed
aicli-switch work        # → switches to work account
aicli-switch personal    # → switches to personal account

Commands

| Command | Description | |---------|-------------| | aicli-switch add <name> | Save current OAuth session as a named profile (default) | | aicli-switch add <name> -t apikey | Add an API Key profile (interactive prompt) | | aicli-switch <name> | Switch to a profile (cleans up all auth conflicts) | | aicli-switch ls | List all profiles with subscription, status and expiry | | aicli-switch status | Show active profile and compare with live credentials | | aicli-switch refresh [name] | Manually refresh an OAuth token | | aicli-switch rm <name> | Delete a profile | | aicli-switch version | Show version |

What It Looks Like

$ aicli-switch ls
  NAME       TYPE    SUBSCRIPTION  STATUS   EXPIRY
▶ work       oauth   max           valid    6.9h
  personal   oauth   pro           valid    4.2h
  relay      apikey  api key       ready    n/a

$ aicli-switch personal
Switched to profile "personal" (oauth)

$ aicli-switch status
Active Profile: personal (oauth)
  Created:  2026-03-21T10:00:00+08:00
  Switched: 2026-03-23T14:30:00+08:00

Profile (saved):
  Token:        valid (expires in 4.2h, at 2026-03-23 18:30:00)
  Subscription: pro

~/.claude/.credentials.json (live):
  Token:        valid (expires in 4.2h, at 2026-03-23 18:30:00)
  Subscription: pro

  ✓ In sync

How It Works

OAuth Profiles

1. add — reads claudeAiOauth from ~/.claude/.credentials.json and saves it to ~/.cc-profiles/<name>/oauth.json
2. switch — writes saved OAuth data back to ~/.claude/.credentials.json, clears conflicting API keys from settings.json, and removes cached oauthAccount from ~/.claude.json so Claude CLI picks up the new identity
3. Token refresh — calls Claude's OAuth endpoint with the saved refresh_token, no browser needed

API Key Profiles

1. add -t apikey — prompts for API Key and Base URL, saves to profile
2. switch — updates ANTHROPIC_API_KEY and ANTHROPIC_BASE_URL in ~/.claude/settings.json, clears claudeAiOauth from credentials, and removes cached oauthAccount from ~/.claude.json

What gets cleaned up on switch

Switching profiles ensures a clean auth state by clearing conflicting credentials:

| Switch to | Actions | |-----------|---------| | OAuth | Write claudeAiOauth → clear ANTHROPIC_API_KEY from settings → clear oauthAccount cache | | API Key | Write ANTHROPIC_API_KEY to settings → clear claudeAiOauth from credentials → clear oauthAccount cache |

This prevents the "Both a token and an API key are set" conflict in Claude Code.

Storage Layout

~/.cc-profiles/
├── _active                # Name of the currently active profile
├── work/
│   ├── oauth.json         # OAuth credentials (accessToken, refreshToken, expiresAt, etc.)
│   └── profile.json       # Metadata (name, type, timestamps)
└── relay/
    ├── settings.env.json  # API Key and Base URL
    └── profile.json

Files Modified on Switch

| File | Purpose | |------|---------| | ~/.claude/.credentials.json | OAuth tokens (claudeAiOauth), preserves mcpOAuth | | ~/.claude/settings.json | API key env vars (ANTHROPIC_API_KEY, ANTHROPIC_BASE_URL) | | ~/.claude.json | Cached account info (oauthAccount — email, org, billing) |

Update Detection

aicli-switch checks for new versions on every startup (non-blocking). When an update is available:

Update available: 0.2.0 → 0.3.0
  Run: npm update -g @kio_ai/aicli-switch
  Or:  https://github.com/killaragorn/aicli-switch/releases/tag/v0.3.0

Roadmap

• [ ] OpenAI Codex CLI credential switching
• [ ] Gemini CLI credential switching
• [ ] Automatic failover on rate-limit
• [ ] Profile import/export

License

MIT