Stop Juggling AI CLIs! cc-switch-cli Unifies Them All

Stop Juggling AI CLIs! cc-switch-cli Unifies Them All

What if I told you that every hour you spend copy-pasting API keys between Claude Code, Codex, and Gemini CLI is an hour you'll never get back?

Here's the brutal truth most developers won't admit: we've become digital hoarders of configuration files. ~/.claude/settings.json here, ~/.codex/config.toml there, ~/.gemini/.env lurking in the shadows. Each AI coding assistant demands its own ritual of setup, its own cryptic format, its own special place in your filesystem. And when you need to switch from Claude to Codex for that one project? You're manually editing files, praying you don't typo an API key, and wondering why your "smart" assistant suddenly can't connect.

The cognitive load is insane. But what if a single command could flip your entire AI coding environment between providers like changing TV channels?

Enter cc-switch-cli — the cross-platform, Rust-powered CLI tool that's secretly becoming the standard for developers who refuse to let configuration chaos steal their flow state. Built by SaladDay as a powerful CLI fork of the original CC-Switch project, this isn't just another dotfile manager. It's a unified command center for Claude Code, Codex, Gemini CLI, OpenCode, and OpenClaw that transforms the fragmented nightmare of AI assistant management into something almost... elegant.

Ready to reclaim those lost hours? Let's dive deep into why cc-switch-cli deserves permanent residence in your PATH.

What is cc-switch-cli?

cc-switch-cli is a cross-platform command-line interface built in Rust that provides unified management for multiple AI coding assistant configurations. Think of it as a mission control for your AI development environment — one tool to rule Claude Code, OpenAI's Codex, Google's Gemini CLI, OpenCode, and OpenClaw.

The project originated as a CLI-focused fork of CC-Switch by farion1231, with SaladDay taking the original architecture and extending it specifically for terminal-native developers who prefer keyboard-driven workflows over GUI interactions. The WebDAV sync feature maintains full compatibility with upstream, so users of both versions can share configurations seamlessly.

Why it's trending now: The explosion of AI coding assistants in 2024-2025 created a configuration crisis. Developers adopted Claude Code for its reasoning, Codex for its speed, Gemini for its context window — but each tool demanded separate setup rituals. cc-switch-cli arrived at the perfect inflection point, offering provider-agnostic management when the market desperately needed consolidation. Its Rust foundation delivers sub-second performance, while the SQLite-backed architecture ensures your configurations survive across machines via WebDAV sync.

The tool currently sits at version 5.5.0 with active development, MIT licensing, and a growing ecosystem of sponsor-backed API relay services that integrate directly with its workflow.

Key Features That Make It Irreplaceable

🔌 Provider Management with Surgical Precision

cc-switch-cli doesn't just store API keys — it orchestrates them. You get one-click provider switching, standalone Claude settings export for team sharing, multi-endpoint support for load balancing, remote model discovery, and per-app diagnostics including speed tests and stream health checks. When your Claude provider starts timing out at 3 AM, you'll know before your coffee gets cold.

🛠️ MCP Server Management Across Five Apps

Model Context Protocol servers are the secret sauce that makes AI assistants truly powerful. cc-switch-cli unifies MCP management across all supported apps with three transport types (stdio, HTTP, SSE), automatic sync to live config files, and live-config adapters for both TOML and JSON targets. No more hand-editing ~/.claude.json and praying your JSON is valid.

💬 Prompt Presets with Cross-App Intelligence

System prompts make or break AI assistant performance. cc-switch-cli manages CLAUDE.md, AGENTS.md, GEMINI.md, and their variants across apps — letting you activate, deactivate, and version your best prompts. Found a prompt that makes Claude code like a senior architect? Save it once, deploy everywhere.

🎯 Skills Store with SSOT Architecture

The Skills feature uses a Single Source of Truth pattern: skill files live in ~/.cc-switch/skills/ while enablement state stays in SQLite. This means you can discover, install, and sync community skills without worrying about which app owns what. The repo discovery system pulls from GitHub automatically, and the sync method (auto/symlink/copy) adapts to your workflow.

⚙️ Bulletproof Configuration Management

Atomic writes via temp-file-then-rename prevent corruption. Automatic backup rotation keeps 10 snapshots. WebDAV sync with dedicated Jianguoyun integration means your config follows you across machines. And the Safe Live Sync default prevents accidentally creating ~/.claude or ~/.codex directories for apps you haven't even installed yet.

🌉 Local Proxy with Telemetry Dashboard

For developers routing through API relays or dealing with corporate proxies, cc-switch-cli includes a built-in multi-app proxy with foreground serve mode for debugging. Inspect routes, toggle persistence, and monitor traffic without external tools.

Real-World Use Cases Where cc-switch-cli Shines

Scenario 1: The Multi-Client Freelancer

You're juggling three client projects — one demands Claude Code for its reasoning capabilities, another standardized on Codex for team compatibility, and a third experiment uses Gemini for its massive context window. Without cc-switch-cli, you're maintaining five different config files across three directory structures, and every API key rotation is a scavenger hunt. With cc-switch-cli: cc-switch provider switch client-a-claude and you're deployed in under a second. WebDAV sync means your laptop and desktop stay identical.

Scenario 2: The DevOps^{↗ Bright Coding Blog} Engineer Managing Team Onboarding

New hire needs identical AI assistant setups? Previously you'd document ~/.claude/settings.json structure, explain ANTHROPIC_API_KEY vs CLAUDE_CODE_DEBUG, and troubleshoot why their Codex can't find ~/.codex/config.toml. With cc-switch-cli: Export your perfected Claude configuration with cc-switch provider export <id> --output team-claude.json, hand them the file, and they cc-switch config import their way to productivity.

Scenario 3: The Prompt Engineer A/B Testing

You've crafted seventeen variants of a system prompt for code review. Previously, testing meant manually copying into CLAUDE.md, running a session, remembering what worked, and repeating. With cc-switch-cli: cc-switch prompts list shows all variants, cc-switch prompts activate variant-7 deploys instantly, and cc-switch prompts deactivate returns to baseline. The feedback loop collapses from minutes to seconds.

Scenario 4: The API Relay Power User

You're optimizing costs across PackyCode, AICodeMirror, and RightCode relay services. Each has different endpoints, rate limits, and pricing tiers. Previously, switching meant editing environment variables and hoping nothing cached incorrectly. With cc-switch-cli: Multiple providers configured with cc-switch provider add, speed-tested with cc-switch provider speedtest <id>, and switched with cc-switch provider switch <id>. The stream health check catches degraded endpoints before your pipeline fails.

Step-by-Step Installation & Setup Guide

Method 1: Quick Install (Recommended for macOS/Linux)

The fastest path to productivity — one command, minimal friction:

curl -fsSL https://github.com/SaladDay/cc-switch-cli/releases/latest/download/install.sh | bash

This installs cc-switch to ~/.local/bin by default. Want a different location? Set the environment variable first:

export CC_SWITCH_INSTALL_DIR=/usr/local/bin
curl -fsSL https://github.com/SaladDay/cc-switch-cli/releases/latest/download/install.sh | bash

Important behavioral notes:

• If cc-switch already exists, the installer prompts in TTY mode and refuses to overwrite in non-interactive shells
• Force overwrite in CI/automation: CC_SWITCH_FORCE=1 curl ... | bash
• Linux users needing glibc instead of musl: CC_SWITCH_LINUX_LIBC=glibc curl ... | bash

Method 2: Manual Installation (All Platforms)

macOS (Universal Binary — Apple Silicon + Intel)

# Download the universal binary
curl -LO https://github.com/saladday/cc-switch-cli/releases/latest/download/cc-switch-cli-darwin-universal.tar.gz

# Extract
tar -xzf cc-switch-cli-darwin-universal.tar.gz

# Make executable and move to PATH
chmod +x cc-switch
sudo mv cc-switch /usr/local/bin/

# Fix macOS quarantine if "cannot be verified" appears
xattr -cr /usr/local/bin/cc-switch

Linux x64

curl -LO https://github.com/saladday/cc-switch-cli/releases/latest/download/cc-switch-cli-linux-x64-musl.tar.gz
tar -xzf cc-switch-cli-linux-x64-musl.tar.gz
chmod +x cc-switch
sudo mv cc-switch /usr/local/bin/

Linux ARM64 (Raspberry Pi, ARM servers)

curl -LO https://github.com/saladday/cc-switch-cli/releases/latest/download/cc-switch-cli-linux-arm64-musl.tar.gz
tar -xzf cc-switch-cli-linux-arm64-musl.tar.gz
chmod +x cc-switch
sudo mv cc-switch /usr/local/bin/

Windows

# Download from browser or PowerShell:
# https://github.com/saladday/cc-switch-cli/releases/latest/download/cc-switch-cli-windows-x64.zip

# After extraction, add to PATH:
move cc-switch.exe C:\Windows\System32\

# Or run directly from directory:
.\cc-switch.exe

Method 3: Build from Source (Rust Developers)

Prerequisites: Rust 1.85+ (install via rustup)

# Clone the repository
git clone https://github.com/saladday/cc-switch-cli.git
cd cc-switch-cli/src-tauri

# Build optimized release binary
cargo build --release

# Install to system
# macOS/Linux:
sudo cp target/release/cc-switch /usr/local/bin/

# Windows:
copy target\release\cc-switch.exe C:\Windows\System32\

Post-Install Verification

cc-switch --version          # Should show 5.5.0 or later
cc-switch env tools          # Verify Claude/Codex/Gemini CLIs detected
cc-switch provider list      # Start with empty provider list

REAL Code Examples from the Repository

Let's examine actual commands from the cc-switch-cli README and understand their power in practice.

Example 1: Interactive Mode — The Gateway Drug

cc-switch

That's it. One command launches the interactive TUI built with ratatui. No memorization required — arrow keys navigate menus, Enter selects, and on-screen guidance reveals features you didn't know existed. This is how you discover capabilities without reading documentation. The TUI automatically saves your language preference (English or Chinese) and persists settings across sessions.

When to use this: First-time exploration, visual verification of configurations, or when you simply forgot the exact subcommand syntax at 2 AM.

Example 2: Provider Switching with App Targeting

# List all configured providers across all apps
cc-switch provider list

# Switch to a specific provider (defaults to Claude if --app not specified)
cc-switch provider switch prod-claude-us-east

# Target Codex specifically — completely isolated provider sets
cc-switch --app codex provider list
cc-switch --app codex provider switch team-codex-mirror

# Export Claude configuration for team sharing or CI/CD
cc-switch provider export prod-claude-us-east --output ./team-claude-config.json

The --app flag is the secret to multi-assistant sanity. Each app maintains its own provider namespace — your Claude providers never collide with Codex providers. The export command generates standalone settings.local.json files that Claude Code auto-loads, making team onboarding frictionless.

Pro tip: Combine with speedtest and stream-check before committing to a provider switch:

cc-switch provider speedtest prod-claude-us-east      # Latency benchmark
cc-switch provider stream-check prod-claude-us-east   # Verify SSE streaming works

Example 3: MCP Server Lifecycle Management

# Add a new MCP server interactively — prompts for name, command, transport type
cc-switch mcp add

# Enable specifically for Claude (other apps unaffected)
cc-switch mcp enable filesystem-server --app claude

# Validate the command exists in PATH before sync
cc-switch mcp validate npx -y @modelcontextprotocol/server-filesystem

# Push to live config files (atomic write, no corruption)
cc-switch mcp sync

# Import existing MCP servers from Claude's live config
cc-switch mcp import --app claude

MCP servers extend AI assistants with filesystem access, database queries, Git operations, and more. Previously, configuring these meant hand-editing JSON files and hoping you didn't break the schema. cc-switch-cli validates commands in PATH, manages enablement per-app, and uses atomic writes (temp file + rename) so you'll never corrupt a live config mid-edit.

The three transport types — stdio for local processes, HTTP for network services, SSE for server-sent events — cover every MCP deployment pattern, and the sync target automatically adapts between Claude's JSON format and Codex's TOML format.

Example 4: Prompt Preset Activation for Context Switching

# List all saved prompt presets
cc-switch prompts list

# Activate "senior-architect-review" preset for current app
cc-switch prompts activate senior-architect-review

# Show full content before activating (trust but verify)
cc-switch prompts show senior-architect-review

# Deactivate and return to default behavior
cc-switch prompts deactivate

Prompt presets are context switching for AI behavior. The "senior-architect-review" preset might instruct Claude to focus on interface design patterns and scalability concerns. The "security-auditor" preset could emphasize injection vulnerabilities and secrets detection. With cc-switch-cli, these personas live in your database, deploy instantly, and sync across machines via WebDAV.

Cross-app support means the same mental model applies everywhere:

• Claude: writes to ~/.claude/CLAUDE.md
• Codex: writes to ~/.codex/AGENTS.md
• Gemini: writes to ~/.gemini/GEMINI.md

Example 5: WebDAV Sync for Multi-Machine Consistency

# Inspect current WebDAV configuration
cc-switch config webdav show

# Configure Jianguoyun (Chinese cloud storage with WebDAV support)
cc-switch config webdav jianguoyun --username myuser --password mypass

# Verify connectivity before trusting it
cc-switch config webdav check-connection

# Upload current state to cloud
cc-switch config webdav upload

# Download and merge on new machine
cc-switch config webdav download

This is dotfiles management for the AI era. Your carefully curated providers, MCP servers, prompt presets, and skills follow you across laptops, desktops, and ephemeral cloud workstations. The migrate-v1-to-v2 command handles upstream compatibility, so you're never locked into old formats.

Advanced Usage & Best Practices

Environment Conflict Detection

The #1 support issue? Environment variables overriding cc-switch-cli configurations. Always run:

cc-switch env check --app claude    # Detect ANTHROPIC_API_KEY conflicts
cc-switch env list --app claude     # See all relevant variables

If conflicts exist, remove them from ~/.zshrc, ~/.bashrc, or Windows System Properties. cc-switch-cli manages keys more securely than shell exports.

Safe Live Sync Defaults

By design, cc-switch-cli won't create app directories for uninitialized tools. This prevents ~/.claude from appearing when you've only installed Codex. If sync seems skipped, initialize the target CLI once:

claude --help    # Creates ~/.claude directory structure
codex --help     # Creates ~/.codex directory structure

Then retry your cc-switch-cli operation.

Backup Strategy

# Before major changes, create named backup
cc-switch config backup --name before-team-migration

# Restore if disaster strikes
cc-switch config restore --backup before-team-migration

Automatic rotation keeps 10 backups — combine with WebDAV upload for off-machine safety.

Shell Completion Integration

# Install and activate completions for bash/zsh
cc-switch completions install --activate

# Verify status
cc-switch completions status

Tab completion transforms cc-switch provider switch <TAB> into a discoverable, typo-free experience.

Comparison with Alternatives

The verdict: Manual management gives control at the cost of time and error risk. GUI dotfile managers lack AI-assistant-specific semantics. cc-switch-cli occupies the sweet spot of automation with domain intelligence — it understands what Claude Code needs versus what Codex expects, and handles the translation automatically.

FAQ: Your Burning Questions Answered

Why doesn't my configuration take effect after switching providers?

Two common causes: (1) The target CLI hasn't been initialized — run claude --help or codex --help once to create config directories. (2) Environment variable conflicts — ANTHROPIC_API_KEY in your shell overrides cc-switch-cli. Run cc-switch env check --app claude to diagnose.

Which apps are supported?

Five AI coding assistants: Claude Code (default, --app claude), Codex (--app codex), Gemini CLI (--app gemini), OpenCode (--app opencode), and OpenClaw (--app openclaw). The --app flag isolates configurations per tool.

Is cc-switch-cli free?

Yes — MIT licensed, zero cost. The project is sponsored by API relay services (PackyCode, AICodeMirror, RightCode, DDS Hub) that offer discounts to cc-switch-cli users, but the tool itself has no paid tier or feature restrictions.

How do I migrate from the original CC-Switch GUI?

WebDAV sync is fully compatible — upload from GUI, download with CLI. For local migration, the legacy config.json format is preserved for import flows. Run cc-switch config import on your existing file.

Can I use cc-switch-cli in CI/CD pipelines?

Absolutely. All commands support non-interactive execution. Use CC_SWITCH_FORCE=1 for automated installs, and prefer command-line mode over interactive TUI for scripts. The --output flag on provider export generates machine-readable configs.

Where is my data stored?

Default: ~/.cc-switch/ containing cc-switch.db (SQLite), settings.json, skills/ directory, and backups/. Override with CC_SWITCH_CONFIG_DIR environment variable. Data is not automatically migrated when you change this — copy manually if needed.

How do I contribute or report bugs?

Open an issue on GitHub with reproduction steps, system info, and relevant logs. Before PRs: cargo fmt --check, cargo clippy, and cargo test must pass. Discussion issues are welcomed before major changes.

Conclusion: Your AI Workflow Deserves Better

Let's be honest — the current state of AI coding assistant management is embarrassingly primitive. We're using tools that generate production-grade code, yet we configure them like it's 1995. Copy-pasting API keys. Hand-editing JSON. Hoping our ~/.claude and ~/.codex directories don't drift out of sync.

cc-switch-cli exposes this madness for what it is and offers a genuine escape hatch. With its Rust-powered performance, SQLite-backed reliability, atomic writes, and true multi-app intelligence, it transforms configuration management from a tax on your attention into a genuine productivity multiplier.

The real test? Install it today. Run cc-switch and feel that first provider switch happen in under a second. Experience the relief of cc-switch env check catching a conflict before it costs you an hour of debugging. Watch your carefully crafted prompt presets deploy across five different AI assistants without a single file copy.

This is how AI tooling should work in 2025.

👉 Get cc-switch-cli now — star the repo, open an issue with your use case, and join the growing community of developers who refuse to let configuration chaos dictate their flow state. Your future self — switching effortlessly between Claude and Codex at 11 PM before a deadline — will thank you.

Built with Rust. Licensed under MIT. Maintained by SaladDay. Original architecture by farion1231.