CC-Switch CLI

Command-Line Management Tool for Claude Code, Codex & Gemini CLI

Unified management for Claude Code, Codex & Gemini CLI provider configurations, MCP servers, Skills extensions, and system prompts.

English | 中文

📖 About

This project is a CLI fork of CC-Switch.

🔄 The WebDAV sync feature is fully compatible with the upstream project.

Credits: Original architecture and core functionality from farion1231/cc-switch

❤️ Sponsor

Thanks to PackyCode for sponsoring this project! PackyCode is a reliable and efficient API relay service provider, offering relay services for Claude Code, Codex, Gemini, and more.
PackyCode provides special discounts for our software users: register via this link and use promo code cc-switch-cli when recharging to get 10% off.

Thanks to RightCode for sponsoring this project! RightCode reliably provides routing services for models such as Claude Code, Codex, and Gemini. It features a highly cost-effective Codex monthly subscription plan and supports quota rollovers—unused quota from one day can be carried over and used the next day.
RightCode offers a special deal for CC-Switch CLI users: register via this link and get 25% bonus pay-as-you-go credits on every top-up!

📸 Screenshots

Home

Switch	Settings

Legacy UI (no longer actively maintained)

[!WARNING] The legacy interactive UI is temporarily not maintained. Please use the new TUI.

Interactive Main Menu	Provider Management

🚀 Quick Start

Interactive Mode (Recommended)

cc-switch

🤩 Follow on-screen menus to explore features.

Command-Line Mode

cc-switch provider list # List providers cc-switch provider switch <id> # Switch provider cc-switch mcp sync # Sync MCP servers Use the global --app flag to target specific applications: cc-switch --app claude provider list # Manage Claude providers cc-switch --app codex mcp sync # Sync Codex MCP servers cc-switch --app gemini prompts list # List Gemini prompts Supported apps: claude (default), codex, gemini

See the "Features" section for full command list.

📥 Installation

Method 1: Quick Install (macOS / Linux)

Windows users: see Manual Installation below.

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

This installs cc-switch to ~/.local/bin. Set CC_SWITCH_INSTALL_DIR to change the target directory.

Manual Installation

macOS

# Download Universal Binary (recommended, supports Apple Silicon + Intel) 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 Add execute permission chmod +x cc-switch Move to PATH sudo mv cc-switch /usr/local/bin/ If you encounter "cannot be verified" warning

xattr -cr /usr/local/bin/cc-switch

Linux (x64)

# Download curl -LO https://github.com/saladday/cc-switch-cli/releases/latest/download/cc-switch-cli-linux-x64-musl.tar.gz Extract tar -xzf cc-switch-cli-linux-x64-musl.tar.gz Add execute permission chmod +x cc-switch Move to PATH

sudo mv cc-switch /usr/local/bin/

Linux (ARM64)

# For Raspberry Pi or 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 the zip file # https://github.com/saladday/cc-switch-cli/releases/latest/download/cc-switch-cli-windows-x64.zip After extracting, move cc-switch.exe to a PATH directory, e.g.: move cc-switch.exe C:\Windows\System32\ Or run directly

.\cc-switch.exe

Method 2: Build from Source

Prerequisites:

Rust 1.85+ (install via rustup)

Build:

git clone https://github.com/saladday/cc-switch-cli.git cd cc-switch-cli/src-tauri cargo build --release Binary location: ./target/release/cc-switch

Install to System:

# macOS/Linux sudo cp target/release/cc-switch /usr/local/bin/ Windows

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

✨ Features

🔌 Provider Management

Manage API configurations for Claude Code, Codex, and Gemini.

Features: One-click switching, multi-endpoint support, API key management, speed testing, provider duplication.

cc-switch provider list              # List all providers
cc-switch provider current           # Show current provider
cc-switch provider switch <id>       # Switch provider
cc-switch provider add               # Add new provider
cc-switch provider edit <id>         # Edit existing provider
cc-switch provider duplicate <id>    # Duplicate a provider
cc-switch provider delete <id>       # Delete provider
cc-switch provider speedtest <id>    # Test API latency

🛠️ MCP Server Management

Manage Model Context Protocol servers across Claude/Codex/Gemini.

Features: Unified management, multi-app support, three transport types (stdio/http/sse), automatic sync, smart TOML parser.

cc-switch mcp list                   # List all MCP servers
cc-switch mcp add                    # Add new MCP server (interactive)
cc-switch mcp edit <id>              # Edit MCP server
cc-switch mcp delete <id>            # Delete MCP server
cc-switch mcp enable <id> --app claude   # Enable for specific app
cc-switch mcp disable <id> --app claude  # Disable for specific app
cc-switch mcp validate <command>     # Validate command in PATH
cc-switch mcp sync                   # Sync to live files
cc-switch mcp import --app claude    # Import from live config

💬 Prompts Management

Manage system prompt presets for AI coding assistants.

Cross-app support: Claude (CLAUDE.md), Codex (AGENTS.md), Gemini (GEMINI.md).

cc-switch prompts list               # List prompt presets
cc-switch prompts current            # Show current active prompt
cc-switch prompts activate <id>      # Activate prompt
cc-switch prompts deactivate         # Deactivate current active prompt
cc-switch prompts create             # Create new prompt preset
cc-switch prompts edit <id>          # Edit prompt preset
cc-switch prompts show <id>          # Display full content
cc-switch prompts delete <id>        # Delete prompt

🎯 Skills Management

Manage and extend Claude Code/Codex/Gemini capabilities with community skills.

Features: SSOT-based skills store, multi-app enable/disable, sync to app directories, unmanaged scan/import, repo discovery.

cc-switch skills list                # List installed skills
cc-switch skills discover <query>      # Discover available skills (alias: search)
cc-switch skills install <name>      # Install a skill
cc-switch skills uninstall <name>    # Uninstall a skill
cc-switch skills enable <name>       # Enable for current app (--app)
cc-switch skills disable <name>      # Disable for current app (--app)
cc-switch skills info <name>         # Show skill information
cc-switch skills sync                # Sync enabled skills to app dirs
cc-switch skills sync-method [m]     # Show/set sync method (auto|symlink|copy)
cc-switch skills scan-unmanaged      # Scan unmanaged skills in app dirs
cc-switch skills import-from-apps    # Import unmanaged skills into SSOT
cc-switch skills repos list          # List skill repositories
cc-switch skills repos add <repo>    # Add repo (owner/name[@branch] or GitHub URL)
cc-switch skills repos remove <repo> # Remove repo (owner/name or GitHub URL)

⚙️ Configuration Management

Manage configuration backups, imports, and exports.

Features: Custom backup naming, interactive backup selection, automatic rotation (keep 10), import/export.

cc-switch config show # Display configuration cc-switch config path # Show config file paths cc-switch config validate # Validate config file Common snippet (shared settings across providers) cc-switch --app claude config common show cc-switch --app claude config common set --json '{"env":{"CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC":1},"includeCoAuthoredBy":false}' --apply cc-switch --app claude config common clear --apply Backup cc-switch config backup # Create backup (auto-named) cc-switch config backup --name my-backup # Create backup with custom name Restore cc-switch config restore # Interactive: select from backup list cc-switch config restore --backup <id> # Restore specific backup by ID cc-switch config restore --file <path> # Restore from external file Import/Export cc-switch config export <path> # Export to external file cc-switch config import <path> # Import from external file

cc-switch config reset # Reset to default configuration

🌐 Multi-language Support

Interactive mode supports English and Chinese, language settings are automatically saved.

Default language: English
Go to ⚙️ Settings menu to switch language

🔧 Utilities

Shell completions, environment management, and other utilities.

# Shell completions cc-switch completions <shell> # Generate shell completions (bash/zsh/fish/powershell) Environment management cc-switch env check # Check for environment conflicts cc-switch env list # List environment variables Self-update

cc-switch update # Update to latest release cc-switch update --version v4.7.2 # Update to a specific version

🏗️ Architecture

Core Design

SSOT: All config in ~/.cc-switch/config.json, live configs are generated artifacts
Safe Live Sync (Default): Skip writing live files for apps that haven't been initialized yet (prevents creating ~/.claude, ~/.codex, ~/.gemini unexpectedly)
Atomic Writes: Temp file + rename pattern prevents corruption
Service Layer Reuse: 100% reused from original GUI version
Concurrency Safe: RwLock with scoped guards

Configuration Files

CC-Switch Storage:

~/.cc-switch/config.json - Main configuration (SSOT)
~/.cc-switch/settings.json - Settings
~/.cc-switch/backups/ - Auto-rotation (keep 10)

Live Configs:

Claude: ~/.claude/settings.json, ~/.claude.json (MCP), ~/.claude/CLAUDE.md (prompts)
Codex: ~/.codex/auth.json, ~/.codex/config.toml (MCP), ~/.codex/AGENTS.md (prompts)
Gemini: ~/.gemini/.env, ~/.gemini/settings.json (MCP), ~/.gemini/GEMINI.md (prompts)

❓ FAQ (Frequently Asked Questions)

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

First, make sure the target CLI has been initialized at least once (i.e. its config directory exists). CC-Switch may skip live sync for uninitialized apps; you will see a warning. Run the target CLI once (e.g. claude --help, codex --help, gemini --help), then switch again.

This is usually caused by environment variable conflicts. If you have API keys set in system environment variables (like ANTHROPIC_API_KEY, OPENAI_API_KEY), they will override CC-Switch's configuration.

Solution:

Check for conflicts:
```
cc-switch env check --app claude
```
List all related environment variables:
```
cc-switch env list --app claude
```
If conflicts are found, manually remove them:
- macOS/Linux: Edit your shell config file (~/.bashrc, ~/.zshrc, etc.)
```
# Find and delete the line with the environment variable
nano ~/.zshrc
# Or use your preferred text editor: vim, code, etc.
```
- Windows: Open System Properties → Environment Variables and delete the conflicting variables
Restart your terminal for changes to take effect.

Which apps are supported?

CC-Switch currently supports three AI coding assistants:

Claude Code (--app claude, default)
Codex (--app codex)
Gemini (--app gemini)

Use the global --app flag to specify which app to manage:

cc-switch --app codex provider list

How do I report bugs or request features?

Please open an issue on our GitHub Issues page with:

Detailed description of the problem or feature request
Steps to reproduce (for bugs)
Your system information (OS, version)
Relevant logs or error messages

🛠️ Development

Requirements

Rust: 1.85+ (rustup)
Cargo: Bundled with Rust

Commands

cd src-tauri cargo run # Development mode cargo run -- provider list # Run specific command cargo build --release # Build release

cargo fmt # Format code cargo clippy # Lint code cargo test # Run tests

Code Structure

src-tauri/src/
├── cli/
│   ├── commands/          # CLI subcommands (provider, mcp, prompts, env, skills, ...)
│   ├── tui/               # Interactive TUI mode (ratatui)
│   ├── interactive/       # Legacy interactive mode
│   └── ui/                # UI utilities (tables, colors)
├── services/              # Business logic (provider, mcp, prompt, webdav, ...)
├── database/              # SQLite storage, migrations, backup
├── main.rs                # CLI entry point
└── ...                    # App-specific configs, proxy, error handling

🤝 Contributing

Contributions welcome! This fork focuses on CLI functionality.

Before submitting PRs:

✅ Pass format check: cargo fmt --check
✅ Pass linter: cargo clippy
✅ Pass tests: cargo test
💡 Open an issue for discussion first

📜 License

CLI Fork Maintainer: saladday

NAME

SYNOPSIS

INFO

DESCRIPTION

README

CC-Switch CLI

📖 About

❤️ Sponsor

📸 Screenshots

Home

🚀 Quick Start

Use the global --app flag to target specific applications:

Supported apps: claude (default), codex, gemini

📥 Installation

Method 1: Quick Install (macOS / Linux)

macOS

Extract

Add execute permission

Move to PATH

If you encounter "cannot be verified" warning

Linux (x64)

Extract

Add execute permission

Move to PATH

Linux (ARM64)

Windows

After extracting, move cc-switch.exe to a PATH directory, e.g.:

Or run directly

Method 2: Build from Source

Binary location: ./target/release/cc-switch

Windows

✨ Features

🔌 Provider Management

🛠️ MCP Server Management

💬 Prompts Management

🎯 Skills Management

⚙️ Configuration Management

Common snippet (shared settings across providers)

Backup

Restore

Import/Export

🌐 Multi-language Support

🔧 Utilities

Environment management

Self-update

🏗️ Architecture

Core Design

Configuration Files

❓ FAQ (Frequently Asked Questions)

🛠️ Development

Requirements

Commands

Code Structure

🤝 Contributing

📜 License

SEE ALSO

Use the global `--app` flag to target specific applications:

Supported apps: `claude` (default), `codex`, `gemini`