Gemini CLI

Gemini CLI speaks the Google Gemini protocol. We accept both the v1 and v1beta version segments — the official docs use both, and either one lands.

Recommended: let CC Switch do it#

CC Switch supports Gemini CLI — add a provider with https://gateway.amux.ai as the Base URL. Open a fresh terminal after switching.

The manual route is below.

1. Install#

npm install -g @google/gemini-cli
# or
pnpm install -g @google/gemini-cli

gemini --version

2. Create an Amux key#

Create one on the keys page in the console. The key remains viewable there after creation, so you do not need to rotate it just to retrieve it again.

3. Configure#

Environment variables#

mkdir -p ~/.gemini

Write into ~/.gemini/.env:

.env

GOOGLE_GEMINI_BASE_URL=https://gateway.amux.ai
GEMINI_API_KEY=your Amux key
GEMINI_MODEL=google/gemini-3-pro

Or use the shell:

Terminal

export GOOGLE_GEMINI_BASE_URL=https://gateway.amux.ai
export GEMINI_API_KEY=your Amux key
export GEMINI_MODEL=google/gemini-3-pro

PowerShell

$env:GOOGLE_GEMINI_BASE_URL = "https://gateway.amux.ai"
$env:GEMINI_API_KEY = "your Amux key"
$env:GEMINI_MODEL = "google/gemini-3-pro"

No /v1 on the address: Gemini clients append /v1beta/models/{model}:generateContent themselves.

Turn off the Google login#

Edit ~/.gemini/settings.json and set the auth type to API key explicitly:

{
  "security": {
    "auth": {
      "selectedType": "gemini-api-key"
    }
  }
}

Without it, the CLI runs the Google account login flow and never looks at the key you set.

4. Check it works#

source ~/.zshrc   # or open a new terminal
gemini -p "Reply with OK only." --output-format json

The output should contain "response": "OK". Then try one with a file:

cd my-project
gemini -p "@README.md Summarize this file in one sentence." --output-format json

Choosing models#

Change GEMINI_MODEL, or pass it on the command line:

gemini --model anthropic/claude-opus-5

Model names are canonical IDs and are not limited to Google's models — what matters is that the model's upstream serves the Gemini protocol, which each model's page states.

Pinning a provider or choosing a strategy#

Append a colon to pin one provider (google/gemini-3-pro:google), or use an @ suffix to choose the ordering (:@price, :@latency). Full details in the API reference.

Troubleshooting#

A Google login prompt appears#

settings.json has no selectedType. Check it:

cat ~/.gemini/settings.json

Authentication failure#

Was the key copied in full (leading or trailing whitespace is the usual culprit)? Is it still enabled in the console? Does the workspace have balance?

The .env file is ignored#

Shell variables override the file. Look at what the process actually has:

env | grep -E "GEMINI_|GOOGLE_"

A .env in the current directory also takes precedence over ~/.gemini/.env, so a stray one in your project wins.

Cannot connect#

curl https://gateway.amux.ai/v1beta/models -H "x-goog-api-key: $GEMINI_API_KEY"

A model list coming back means the network and the key are fine. Also confirm the address is https://gateway.amux.ai with no /v1 appended.

Model unavailable#

Model IDs need the vendor prefix (google/gemini-3-pro, not gemini-3-pro). And not every model supports every protocol — Gemini CLI speaks Gemini, so pick a model whose upstream serves it.

Timeouts#

A long context on a strong reasoning model is slow to the first token by nature. Shorten the prompt or attach fewer files, try a faster tier, or use the :@latency suffix so routing prefers low-latency providers.