How to configure a Gemini API key for Gemini CLI proxy

What Gemini CLI is

Gemini CLI is Google’s command-line AI tool for terminal-based chat, code explanation, file analysis, and development assistance. It is not a Claude Code or Codex clone; authentication, environment variables, and model routing are different.

This guide only covers the two paths that matter for proxy users:

• Login with Google: use a Google account, best for trying the official CLI first.
• Gemini API Key (AI Studio): use GEMINI_API_KEY, which is the path most proxy guides expect.

Many “Gemini CLI proxy” providers are really multi-model API aggregators that expose Google or Gemini models, which does not automatically mean native Gemini CLI compatibility.

Do not change global configuration first. Pick a provider that clearly lists Google or Gemini models, run a small test with a temporary key or small credit balance, and only then decide whether it belongs in your daily coding setup.

If you are still comparing providers, start with Gemini CLI Proxy Providers. For broader multi-model options, also check OpenRouter Alternatives and the AI API Directory.

Install Gemini CLI

Check Node.js first. Gemini CLI should use Node.js 20+:

node --version

The official npm install path is:

npm install -g @google/gemini-cli
gemini --version

For a temporary run without global install, you can also use:

npx @google/gemini-cli

Start it once after installation:

gemini

Make it easier to use after install

Add a short command alias

If typing gemini every time feels too long, add a shell alias. I recommend gm instead of g, because g often collides with git aliases, directory jump tools, or other local shortcuts.

On macOS / Linux with Bash or Zsh, add the alias to your shell profile:

# Zsh usually uses ~/.zshrc; Bash usually uses ~/.bashrc or ~/.bash_profile
echo 'alias gm="gemini"' >> ~/.zshrc
source ~/.zshrc

Then start Gemini CLI with:

gm

On Windows PowerShell, open your $PROFILE:

notepad $PROFILE

Then add:

Set-Alias gm gemini

Note: this alias only expands gm to gemini in your terminal before Gemini CLI starts. It is not an internal Gemini CLI alias; shell aliases from your profile may not work inside Gemini CLI shell commands.

Choose an authentication path

On first launch, focus on Login with Google and Gemini API Key. Use this simple rule:

• You only want to try the official Gemini CLI: choose Login with Google, best for personal users who can open the Google sign-in page.
• You want to use a proxy provider or API key: choose Gemini API Key (AI Studio), which is the path most proxy setup guides expect.

Start once:

gemini

If you need to switch authentication later, run this inside Gemini CLI:

/auth

Then choose the matching option:

○ Login with Google
● Gemini API Key (AI Studio)

For most proxy setups, choose Gemini API Key (AI Studio) and let Gemini CLI read GEMINI_API_KEY from your terminal environment.

Configure API key and proxy endpoint

For an official AI Studio API key, the smallest setup is:

export GEMINI_API_KEY="your Gemini API key"
gemini

For a proxy provider, many guides ask you to set both an API key and a proxy endpoint:

export GEMINI_API_KEY="your proxy API key"
export GOOGLE_GEMINI_BASE_URL="https://your-proxy.example"
gemini

For long-term use, put these values in your shell profile. Zsh users usually edit ~/.zshrc:

nano ~/.zshrc

Add:

export GEMINI_API_KEY="your proxy API key"
export GOOGLE_GEMINI_BASE_URL="https://your-proxy.example"

Reload the profile:

source ~/.zshrc

Bash users usually edit ~/.bashrc:

nano ~/.bashrc
source ~/.bashrc

Windows CMD can set temporary variables with:

set GEMINI_API_KEY=your proxy API key
set GOOGLE_GEMINI_BASE_URL=https://your-proxy.example

PowerShell can use:

$env:GEMINI_API_KEY="your proxy API key"
$env:GOOGLE_GEMINI_BASE_URL="https://your-proxy.example"

Note: whether GOOGLE_GEMINI_BASE_URL is supported, and whether the URL needs a path suffix, depends on the provider. Do not copy another provider’s endpoint blindly.

Common launch patterns

After setup, use these patterns:

# Interactive mode
gm

# Ask one direct question
gemini "Explain this project's directory structure"

# Test a specific model; use the model name from your provider docs
gemini -m gemini-2.5-flash "Introduce Gemini CLI in one sentence"

Verify it works after install

Use a clean terminal and clear old variables first:

unset GEMINI_API_KEY GOOGLE_API_KEY
export GEMINI_API_KEY="provider or official test key"
gemini

If the provider requires a custom Base URL, add the endpoint it gives you:

export GOOGLE_GEMINI_BASE_URL="https://your-proxy.example"
gemini "Explain in one sentence which model you are connected to"

After basic chat works, run four small checks:

1. gemini -p "Explain this codebase architecture" returns normally.
2. gemini -m gemini-2.5-flash "hello" works with a specific model.
3. Start gemini inside a project and ask it to read a small file.
4. Run one low-risk code explanation or generation task to check streaming, tool behavior, and model names.

A normal answer only proves that basic requests work. Still test code reading, file edits, streaming behavior, and model names. If the provider documentation does not mention Gemini CLI, ask whether it supports native Gemini CLI or only Gemini models through an OpenAI-compatible endpoint.

What to ask a proxy provider

I usually check two things first: whether the docs mention GEMINI_API_KEY, and whether they mention GOOGLE_GEMINI_BASE_URL. If the first launch shows an auth picker, then check whether the guide tells you to choose Gemini API Key (AI Studio) in /auth.

If the provider only lists a Gemini model, or only says “OpenAI-compatible,” do not treat it as Gemini CLI compatible yet. It may expose Gemini through an OpenAI-compatible endpoint without supporting Gemini CLI file reading, streaming, or tool behavior.

When the docs are unclear, test only with a small balance. If support cannot explain the variable names, Base URL, and /auth choice, keep it marked as unverified.

Common errors

• 401 / unauthorized: wrong key type, or the provider does not accept the authentication format Gemini CLI sends.
• 403 / permission denied: the key authenticates, but the account, project, or model permission is missing.
• 404 / not found: wrong Base URL path, often around whether /v1 is required.
• model not found: the model alias does not match the provider’s listed model name.
• 429 / too many requests: no usable quota, rate limit reached, or the CLI / coding agent is retrying too aggressively.
• network error / timeout: local network, proxy, provider node, or upstream timeout.
• Chat works but coding tools fail: the provider may support ordinary completions but not the tool calling or streaming behavior Gemini CLI needs.

For 401 or 429, do not switch providers first. Open the related error pages at the bottom and check Base URL, API key, model name, balance, and rate limits in order.

Tools that make setup easier

If you only connect one proxy endpoint, editing ~/.zshrc manually is enough. Tools become useful when you switch providers often.

Configuration managers such as CC Switch can help manage provider profiles, Base URLs, API keys, model names, and usage tracking across Claude Code, Codex, Gemini CLI, and OpenCode.

The order matters: test the minimal setup manually first, then save the working setup in a tool. Otherwise a tool only helps you organize broken configs faster.

Next step

A useful Gemini CLI proxy page should not only say “supports Gemini.” It should show whether the provider publicly lists Google or Gemini models, pricing, payment methods, and Gemini CLI setup notes. The model list gets a provider into the shortlist; stable CLI behavior is the real bar.