How to Install Gemini CLI (2026): Setup, Free Limits, API Key and Custom Endpoints

We installed and configured Gemini CLI 0.64.0 on an Apple-silicon Mac on October 15, 2026, and the commands and errors below are from those runs. Two things we found that most guides miss: the Homebrew package is deprecated, and custom endpoints need one extra setting.

Install Gemini CLI

Unlike Claude Code and Codex, Gemini CLI has no standalone installer, so you do need Node.js. Check with node -v. If you don't have version 20 or later, install the current LTS from nodejs.org or with a version manager such as nvm.

npm install -g @google/gemini-cli

added 7 packages in 2s

The install takes about 100 MB. You may see npm WARN deprecated node-domexception or npm WARN deprecated glob along the way. Google's troubleshooting guide says these come from dependencies and are harmless. Don't use sudo for the global install. If npm hits permission errors, point its prefix at your home folder or use nvm.

Verify:

gemini --version

0.64.0

About Homebrew

Google's installation page still lists brew install gemini-cli. When we checked on October 15, 2026, Homebrew had marked the formula deprecated on June 18, 2026, and it was frozen at 0.46.0, nearly 20 releases behind npm, which ships a new version roughly every week. If you installed it that way, switch:

brew uninstall gemini-cli
npm install -g @google/gemini-cli

System recommendations

Google recommends macOS 15+, Windows 11 24H2+ or Ubuntu 20.04+, with 4 GB of RAM for light use and 16 GB for long sessions on large codebases. It runs in Bash, Zsh or PowerShell.

Sign in: three options and their free limits

On first launch, gemini asks how to authenticate. You can change it later with /auth.

Google sign-in is only offered in supported locations. Elsewhere you'll see not currently available in your location (see errors).

To use an API key, create one in Google AI Studio and set it. To keep it across sessions, put it in ~/.gemini/.env, which Gemini CLI loads on startup:

mkdir -p ~/.gemini
echo 'GEMINI_API_KEY="your-key"' >> ~/.gemini/.env

On Windows, the file is %USERPROFILE%\.gemini\.env.

Use a custom endpoint

Gemini CLI can send its requests to any service that implements the Gemini API (the native generateContent format), such as an API gateway or proxy. Google's docs don't cover this yet, but version 0.64.0 reads a GOOGLE_GEMINI_BASE_URL variable. It takes two steps.

1. Endpoint and key in ~/.gemini/.env:

GEMINI_API_KEY="sk-your-key"
GOOGLE_GEMINI_BASE_URL="https://api.foo"

2. Auth type in ~/.gemini/settings.json. If the file already has settings, merge the security block into them:

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

Step 2 is the part people miss. With only the variables set, Gemini CLI 0.64.0 refused to run in our headless test (gemini -p):

Invalid auth method selected.

Setting a custom base URL makes Gemini CLI pick an internal auth mode that its own validation doesn't accept, and the explicit selectedType sidesteps that.

To test both steps, we pointed Gemini CLI at api.foo, the API gateway that publishes these docs, using a deliberately invalid key. The request reached the gateway and came back with the gateway's own rejection. The message is Chinese for "invalid token":

_ApiError: {"error":{"code":"","message":"无效的令牌 (request id: …)","type":"new_api_error"}}
  status: 401

That error means the endpoint and auth type are wired correctly, and only the key needs fixing. A few more details:

• Give only the host in GOOGLE_GEMINI_BASE_URL. Gemini CLI appends /v1beta/models/… itself.
• Pick a model explicitly. In the default Auto mode, Gemini CLI first sends a small classification request (to gemini-2.5-flash-lite, per Google's docs) to decide between Pro and Flash. Through a gateway, that's an extra billed call to a model your provider may not offer, and when it fails you'll see [Routing] NumericalClassifierStrategy failed before the real request goes out. Start with gemini -m <model> or choose a model under /model, and the extra call goes away. We confirmed this.
• Shell variables win over .env. If GEMINI_API_KEY is already exported in your shell profile, the .env value is ignored.

Everyday commands

Fix common errors

command not found: gemini

npm's global bin folder isn't on your PATH. Run npm config get prefix, add its bin subfolder (on Windows, the folder itself) to PATH, and open a new terminal.

Invalid auth method selected.

You set GOOGLE_GEMINI_BASE_URL without choosing an auth method. Add "selectedType": "gemini-api-key" as shown in Use a custom endpoint, or run /auth interactively and pick the API key option.

Gemini CLI is not running in a trusted directory

Gemini CLI is not running in a trusted directory. To proceed, either use `--skip-trust`, set the `GEMINI_CLI_TRUST_WORKSPACE=true` environment variable, or trust this directory in interactive mode.

Headless runs (gemini -p) refuse to run in folders you haven't trusted. Open gemini interactively once and trust the folder, or set GEMINI_CLI_TRUST_WORKSPACE=true for that command, but only for code you trust.

Your current account is not eligible … not currently available in your location

Google sign-in isn't offered where you are. Use a Gemini API key or another provider instead.

You must be a named user on your organization's Gemini Code Assist Standard edition subscription

You're signing in with a personal account, but GOOGLE_CLOUD_PROJECT or GOOGLE_CLOUD_PROJECT_ID is set, which makes Gemini CLI check for an organization license. Remove those variables from your shell profile and any .env files.

UNABLE_TO_GET_ISSUER_CERT_LOCALLY

A corporate proxy is inspecting HTTPS traffic. Try export NODE_USE_SYSTEM_CA=1 so Node.js trusts your OS certificate store, or set NODE_EXTRA_CA_CERTS to your company's root certificate file.

Update, log out and uninstall

gemini update                                  # or: npm install -g @google/gemini-cli@latest
npm uninstall -g @google/gemini-cli            # uninstall an npm install
rm -rf "$(npm config get cache)/_npx"          # clear npx runs

Use the @preview or @nightly tags if you want the weekly preview or daily builds. Most people should stay on the default stable channel.

To sign out, type /auth logout inside the CLI. It clears cached credentials and also resets the selected auth type, so if you use a custom endpoint, set selectedType again afterwards. Uninstalling doesn't remove ~/.gemini, where your settings, credentials and history live. Delete it for a clean slate.

Related

• How to install Claude Code
• Install Codex CLI and set up config.toml
• CC Switch guide