CC-Switch-CLI usage
CC-Switch-CLI is a provider switching tool for the command line, suitable for servers without a graphical interface, SSH environments, or for people who need to quickly switch providers between Claude Code, Codex, Gemini CLI, OpenCode, and OpenClaw.
Who is it suitable for
If you are an ordinary desktop user, prioritize using the CC Switch graphical interface; if you are already accustomed to the terminal or need to manage configurations in batch, then look at this page. The following code blocks only contain commands, with explanations placed outside the code blocks to avoid copying the explanations along with the commands.
Installation and Startup
macOS / Linux users can follow the official documentation to use the installation script or Releases package; Windows users are recommended to download the corresponding compressed package from Releases, and run it in the program's directory after extracting.
curl -fsSL https://github.com/SaladDay/cc-switch-cli/releases/latest/download/install.sh | bash cc-switch.\cc-switch.exeDirect input cc-switch You will enter the interactive interface, which is suitable for beginners to first look at the menu; the following commands are suitable for when you already know what you want to do and want to execute them directly.
Environmental inspection
| Things to confirm | How to view | Why |
|---|---|---|
| CC Switch or CLI version has been installed | This terminal can recognize the corresponding command | Any configuration command will fail if it is not installed. |
| Target CLI is installed | Claude Code, Codex, and Gemini CLI can at least start individually | CC-Switch-CLI does not install the target tool for you |
| provider information is complete | Prepare the Base URL, API Key, and model name | Command-line configuration has no graphical prompts, and missing one item can easily cause failure. |
| First verify in the test directory | Do not switch in bulk directly in real projects | Easier to roll back when configuration is incorrect |
cc-switch env tools cc-switch env check cc-switch provider current cc-switch --app codex provider currentProvider command
A Provider is a provider configuration. Before adding a Provider, first prepare the Base URL, API Key, and model name from the provider's backend; when editing or switching, first confirm the number using the list command.
cc-switch provider list cc-switch provider add cc-switch provider edit <id> cc-switch provider fetch-models <id>cc-switch provider switch <id> cc-switch provider stream-check <id> cc-switch provider fetch-models <id>< id> Needs to be replaced with cc-switch provider list The number seen inside. Do not directly take < id> Execute exactly as is.By App Management
If you only want to see the configuration of a specific target tool, you can add --app This is very useful for troubleshooting Claude Code, Codex, and Gemini CLI separately.
cc-switch --app claude provider list cc-switch --app codex provider list cc-switch --app gemini provider list cc-switch --app opencode provider list cc-switch --app openclaw provider listcc-switch --app claude provider current cc-switch --app codex provider current cc-switch --app gemini provider currentAfter confirming that the target application and the current provider are fine, then perform the switch. After the switch is complete, restart the terminal, and then use the target tool to send the shortest test issue.
claude "Please reply only: Claude Code is active" codex "Please reply only: Codex is active" gemini "Please reply only: Gemini is active"MCP Synchronization
MCP is not needed for every beginner. Only deal with it when you have already used MCP in Claude Code, Codex, Gemini CLI, and need cross-tool synchronization. For the first time, it is recommended to first enter the TUI menu to check the MCP area, and do not directly copy advanced commands from old tutorials.
cc-switch cc-switch --app codexConfiguration approach
- First confirm the target tool you want to switch to: Claude Code, Codex, Gemini CLI, or other CLI.
- Prepare the Base URL, API Key, and model name from the provider backend.
- Add or select a Provider in CC-Switch-CLI.
- Apply the Provider to the target tool.
- After reopening the terminal, test with a shortest-question on the target CLI.
- Once confirmed successful, apply the same Provider to other target tools.
| Scenarios | Recommendations |
|---|---|
| Local desktop use | Prefer using the CC Switch graphical interface; fields and status are more intuitive |
| Remote server / SSH | Then use CC-Switch-CLI; check the current version commands before operation |
| Batch configuration switching | First verify success in a test project, then apply to real projects |
| Multiple people sharing a machine | Do not write your Key into the public configuration; first confirm the scope of the configuration file |
Beginner troubleshooting
| Phenomenon | Priority check | Solutions |
|---|---|---|
| Command not found | Check whether it is installed and whether it is added to PATH | Reopen the terminal, or return to the official installation instructions to confirm the installation location |
| The target tool did not change after switching | Whether the terminal has been reopened and whether the correct target tool is selected | Close the current terminal window and reopen it, then test again |
| 401 / Unauthorized | Whether the Key is complete and whether it has expired | Copy the Key again, ensuring there are no extra spaces |
| model not found | Whether the model name is copied exactly from the backend | Refill according to the provider's model list |