CC Switch CLI: install and switch on a server
CC Switch CLI is a community-maintained command-line version and not an official CC Switch product: the official README states that CC Switch itself ships only as a desktop app that needs a graphical interface, and recommends this CLI for servers, SSH sessions and machines without a desktop. It is a CLI fork of CC Switch, released separately by another author. Installation, switching and the shared data directory below follow the CLI project's README; the QCode fields follow the QCode docs.
Updated 2026-10-20
Point this tool at the QCode endpoint — one key for Claude, GPT and Chinese models.
- Billed per token — live rates on /models
- Pay by card (Visa / Mastercard / AMEX), Apple Pay, Google Pay or crypto
- Self-service: top up and activate instantly
What it is, how to install, how to switch, data directory, QCode fields
not an official CC Switch product
It is a CLI fork of CC Switch, released separately by another author and not an official CC Switch product; the official README recommends it for servers, SSH sessions and machines without a desktop.
two ways to install
The quick install in that project's README is curl -fsSL https://github.com/SaladDay/cc-switch-cli/releases/latest/download/install.sh | bash, which puts the binary in ~/.local/bin; the README also documents Homebrew with brew install cc-switch-cli.
listing and switching
The basic usage listed in that project's README: cc-switch opens the full-screen terminal interface; cc-switch provider list lists the saved entries; cc-switch provider switch (id) switches; cc-switch use (id) is the shortcut for that; cc-switch --app codex provider list picks the tool with --app, and the default is claude.
data directory shared with the desktop app
The QCode docs state that this CLI shares the ~/.cc-switch data directory with the desktop app by default; the database version it supports sometimes lags behind the desktop app, so when the database version turns out to be too new, upgrade the CLI or wait for it to catch up.
When the command-line version makes sense
On servers, SSH sessions and containers, where there is no desktop, the desktop app is not an option, and this is where the command-line version fits. The project's own README says it offers a full-screen terminal interface and a scriptable command line.
The official recommendation and the latest version
The official CC Switch README answers "Is there a command-line or headless version?" by recommending the community-maintained CC Switch CLI. The latest release of that CLI project is v5.11.2, published on 2026-10-16.
Timeline
CC Switch v4.0.12 for the desktop app was released; the QCode docs page states that the download and command-line sections were checked against the README and Releases on 2026-10-15.
The date the QCode docs page on CC Switch is marked with; it states that there is no official command-line version, that the community CLI is recommended for servers and SSH, and that the ~/.cc-switch data directory is shared by default.
The community CLI project released v5.11.2; the release page lists the tag v5.11.2 and the published timestamp 2026-10-16T13:51:51Z. The QCode docs page recorded v5.11.1 when it was checked on 2026-10-15.
What has a source, and what does not
Backed by a source
① The official README states that CC Switch ships only as a desktop app that needs a graphical interface. ② For servers, SSH sessions or machines without a desktop it recommends the community-maintained CC Switch CLI; according to the CLI project's README and the QCode docs, it is a CLI fork of CC Switch, released separately by another author and not an official CC Switch product. ③ The project's README gives two ways to install: the install script and Homebrew. ④ The basic usage covers opening the full-screen terminal interface, listing, switching, the shorthand for switching, choosing the tool with --app, and running one session with a given entry only. ⑤ By default the ~/.cc-switch data directory is shared with the desktop app and the core data sits in ~/.cc-switch/cc-switch.db; CC_SWITCH_CONFIG_DIR moves it elsewhere. ⑥ The QCode fields follow the QCode docs: ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN for Claude, Base URL and API Key for Codex.
Not written by the official docs or the project
① There is no official feature-by-feature comparison between the command-line version and the desktop app, and the QCode docs state that the community CLI was not tested feature by feature. ② The project's README does not describe how its database version relates to the one of the desktop app. ③ Neither side states the exact conditions under which "database version is too new" appears. ④ Neither side states which dependencies the CLI needs inside a container image.
Command-line version and desktop app
Desktop app (official)
The QCode docs page lists the desktop installation methods as the installers for each system and package-manager commands; what you end up with is an app that has a graphical interface.
Command-line version (community fork)
The community project offers a full-screen terminal interface and a scriptable command line; when the two versions drift apart, the CLI reports that the database version is too new.
Installing, switching and checking versions on a server
① Install: follow the project's README and run curl -fsSL https://github.com/SaladDay/cc-switch-cli/releases/latest/download/install.sh | bash, which installs into ~/.local/bin, or use Homebrew with brew install cc-switch-cli. ② Add an entry: cc-switch provider add, with the fields taken from the QCode docs. ③ Switch: cc-switch provider switch (id) (short form cc-switch use (id)); to use a given entry for one launch only, run cc-switch start claude (id) — the README says this affects only the session started by that command, while provider switch and use still change the global entry. ④ Data directory and updates: the core data lives in ~/.cc-switch/cc-switch.db by default and CC_SWITCH_CONFIG_DIR points it elsewhere (the README says existing data under ~/.cc-switch is not migrated automatically); the README says Homebrew installations should be updated with brew upgrade cc-switch-cli.
On QCode
Following the QCode docs page on CC Switch: for Claude, fill in ANTHROPIC_BASE_URL https://api.qcode.cc/api and ANTHROPIC_AUTH_TOKEN (a key starting with cr_); for Codex, fill in Base URL https://api.qcode.cc/openai and API Key; CC Switch writes the configuration into ~/.claude/settings.json and ~/.codex/config.toml. QCode bills per token; per-model rates are listed on qcode.cc/models. To keep Claude Code or Codex running on a server, you can use QCode cloud servers: put the machine abroad, install Claude Code / Codex on it and call models with your QCode key; the AI service and the cloud servers share one balance (qcode.cc/en/cloud).
FAQ
Is there an official command-line version of CC Switch?
No. The official README states that CC Switch ships only as a desktop app that needs a graphical interface; for servers, SSH sessions or machines without a desktop it recommends the community-maintained CC Switch CLI (according to the CLI project's README and the QCode docs, it is not an official CC Switch product).
How do I install it on a server?
The project's README gives two ways: Homebrew with brew install cc-switch-cli, or curl -fsSL https://github.com/SaladDay/cc-switch-cli/releases/latest/download/install.sh | bash, which installs into ~/.local/bin. The README also covers downloading the archive for your platform and putting it on the PATH, and the Linux build is the static musl one.
How do I switch to another entry?
The basic usage in the project's README: cc-switch provider list lists the saved entries; cc-switch provider switch (id) switches; cc-switch use (id) is the shortcut for that; cc-switch --app codex provider list picks the tool with --app, and the default is claude. To use a given entry for one launch only, run cc-switch start claude (id).
What should I do about "database version is too new"?
The official README's FAQ and the QCode docs both state that this CLI shares the ~/.cc-switch data directory with the desktop app by default, and that the database version it supports sometimes lags behind the desktop app — in that case upgrade the CLI or wait for it to catch up.
Which fields do I fill in for QCode?
Follow the QCode docs page on CC Switch: for Claude, ANTHROPIC_BASE_URL is https://api.qcode.cc/api and ANTHROPIC_AUTH_TOKEN takes the key starting with cr_; for Codex, Base URL is https://api.qcode.cc/openai and API Key takes the same key. CC Switch writes these into ~/.claude/settings.json and ~/.codex/config.toml. These field names come from the QCode docs, which describe the desktop app and state that the community CLI was not tested feature by feature; when you run cc-switch provider add, go by the prompts that actually appear.
Is there a package named cc-switch-cli on npm?
There is one, but it is not the same thing as the project in the README: the package of that name on the npm registry has jacob.shi as its maintainer, its latest version is 1.0.1 and it was published on 2026-04-26; the project the official README points to is a binary program written in Rust, its command is named cc-switch, and its README has no npm installation. Install the Homebrew build or the install script as the README describes.
Sources
The README and releases/latest of the community CC Switch CLI project (tag v5.11.2, published 2026-10-16, fetched and checked on 2026-10-20); the QCode docs page on CC Switch (updated 2026-10-15, checked on 2026-10-20); the registry metadata of the npm package with the same name (checked on 2026-10-20).
Connect Claude Code to QCode on your server
Billed per token; per-model rates are listed on qcode.cc/models.
Related reading
Claude Code Pay-as-you-go Packs: No Subscription, 7–90 Days
One-time quota packs valid for 7–90 days, no subscription; extra packs add to the same key.
CC Switch Guide: Switch APIs in Claude Code and Codex
How the desktop app switches APIs between Claude Code and Codex, the configuration fields and what to check when a switch does not take effect.
CC Switch 4.0: Aggregation, Deep Links, CLI (Oct 2026)
4.0 splits direct, routing and aggregation into three tabs and notes that the official README has no command-line version.
Crypto payment guide
Nine coins, 56 networks, zero platform fee for AI coding API credits.
This page was checked on 2026-10-20 against the README and the release of the community CC Switch CLI project and against the QCode docs; that project is maintained by the community and released on its own, so versions and features can change at any time — read its README before installing. The configuration fields on the QCode side follow the QCode documentation, and model availability is listed on /models.