Skip to content

Gemini CLI

Last verified: 2026-05-06 · Drift risk: medium Official sources: google-gemini/gemini-cli on GitHub, Gemini CLI documentation, Hands-on with Gemini CLI codelab

What This Surface Is

Gemini CLI is an open-source terminal agent from Google. It runs in your shell, authenticates with your Google account or a Gemini API key, and gives you an interactive AI agent that can read and modify files, run commands, and call external tools—all from a prompt.

Unlike the Gemini web app, Gemini CLI is not a browser interface. It operates in your existing terminal workflow, making it a direct comparison to Claude Code. The key difference is that Gemini CLI is open source under Apache 2.0, so you can read, fork, and extend the code. The repository is at github.com/google-gemini/gemini-cli.

Gemini CLI has built-in support for MCP (Model Context Protocol) servers, configurable via a JSON settings file, which means you can connect it to the same tool ecosystem as Claude Desktop and Claude Code.

Who It Is Best For

  • Developers who want a terminal-based AI agent and prefer Google's model family
  • Anyone who wants an open-source codebase they can audit or modify
  • Teams using Google Cloud who want Vertex AI authentication without browser-based OAuth
  • Developers who want to run agents in Google Cloud Shell, where Gemini CLI comes pre-installed
  • CI/CD workflows that need a Gemini-backed agent without managing a full API integration

Prerequisites

  • Node.js 20 or later (check with node -v)
  • macOS, Linux, or Windows
  • A personal Google account for free-tier auth, or a Gemini API key from Google AI Studio for higher rate limits or headless environments
  • Optional: a Google Cloud project for Vertex AI authentication

Step-by-Step Setup

1. Install Node.js 20+

If node -v returns a version below 20, install a newer version via nodejs.org or a version manager like nvm:

nvm install 20
nvm use 20

2. Install Gemini CLI

The standard install method per the official documentation:

npm install -g @google/gemini-cli

Verify the installation:

gemini --version

Alternative methods:

# Homebrew (macOS/Linux)
brew install gemini-cli

# Run without installing (temporary)
npx @google/gemini-cli

Note: Corporate networks with strict proxy settings may encounter issues with the npm postinstall script downloading a ripgrep binary. If you see a timeout during npm install, set your proxy environment variables before running npm, or use the Homebrew method. See the GitHub issues tracker for current workarounds.

3. First-run authentication

Start the CLI:

gemini

On first launch, you will be prompted to choose a theme and an authentication method. The two primary options:

Option A: Sign in with Google account (recommended for personal use)

Select Sign in with Google when prompted. The CLI opens a browser tab for Google OAuth. Authenticate with your Google account, accept the terms, and return to the terminal. The free tier via a personal Google account allows approximately 60 requests per minute and 1,000 requests per day (per third-party documentation drawing on Google's published limits—verify current limits at ai.google.dev).

Credentials are stored locally in ~/.gemini/ and you will not need to authenticate again on subsequent runs.

Option B: Gemini API key (for CI/CD or higher rate limits)

Get an API key from aistudio.google.com. Set it as an environment variable:

export GEMINI_API_KEY=your_api_key_here
gemini

To persist across sessions, add the export to your shell profile (~/.bashrc, ~/.zshrc, etc.).

Option C: Vertex AI (enterprise)

export GOOGLE_CLOUD_PROJECT=your-project-id
export GOOGLE_CLOUD_LOCATION=us-central1
export GOOGLE_GENAI_USE_VERTEXAI=true
gcloud auth application-default login
gemini

4. Configure settings.json (optional)

Gemini CLI persists its configuration in ~/.gemini/settings.json. You can set the theme, default model, MCP server connections, and more. The file is created on first run. Edit it with any text editor:

nano ~/.gemini/settings.json

Building Your First Useful Agent: Refactor a File and Run Tests

This worked example takes a Python file with callback-based async code and refactors it to use async/await, then runs the test suite to confirm nothing broke.

Project setup

Assume you have a repository at ~/projects/myapp with:

  • src/fetcher.py: the file to refactor
  • tests/test_fetcher.py: existing tests
  • requirements.txt with the project dependencies

Start the CLI in your project

cd ~/projects/myapp
gemini

Understand the project

What does this project do? Describe the structure of src/.

Gemini CLI reads the files it needs and returns a description.

Refactor the file

Refactor src/fetcher.py to use async/await instead of callbacks.
Keep the function signatures compatible with the existing tests.
Show me the diff before applying any changes.

Gemini CLI will:

  1. Read src/fetcher.py
  2. Propose a rewritten version
  3. Show a diff
  4. Wait for your approval before writing

Approve the change:

Apply the changes.

Run the tests

Run the tests in tests/test_fetcher.py and report any failures.

Gemini CLI executes the test command in your shell and returns the output. If tests fail:

Fix the test failures and re-run.

Commit

Commit the changes with a message that explains the refactor.

Customization

GEMINI.md

Gemini CLI reads a GEMINI.md file from the workspace root at the start of each session. Use it to encode project-specific conventions:

# Project conventions

- Python 3.11. Use pytest for tests.
- Run `ruff check .` before committing.
- Async code uses asyncio; do not introduce threading.
- The main entry point is src/main.py.

Global conventions can go in ~/.gemini/GEMINI.md and apply across all workspaces.

MCP server integration

Gemini CLI supports MCP servers via the settings.json file. Add an mcpServers block:

{
  "mcpServers": {
    "github": {
      "httpUrl": "https://api.githubcopilot.com/mcp/",
      "trust": true,
      "headers": {
        "Authorization": "Bearer ${GITHUB_PAT}"
      }
    }
  }
}

Secrets like GITHUB_PAT can be stored in ~/.gemini/.env and Gemini CLI will load them automatically.

Rules and workflows

Beyond GEMINI.md, Gemini CLI supports structured rules and workflow files. These are stored in .agents/rules/ and .agents/workflows/ within your workspace (workspace scope) or ~/.gemini/ (global scope). Rules constrain behavior; workflows define multi-step procedures that can be triggered with a slash command.

Limits and Gotchas

  • Free tier rate limits apply with Google account auth. Approximately 60 requests per minute and 1,000 per day based on available documentation. Use an API key or Vertex AI for higher limits.
  • Node.js 20+ is required. Older Node versions will fail. This is a common source of install failures for developers on older LTS versions.
  • Not pre-installed outside Google Cloud Shell and Cloud Workstations. You must install it manually on your own machine.
  • Corporate network proxy issues. The npm postinstall downloads a ripgrep binary from GitHub. Strict proxy environments may block this. Using Homebrew or the npx method avoids this step.
  • Open source means breaking changes can ship. Gemini CLI is under active development. Check the releases page before updating in production workflows. Consider pinning a version in CI.
  • Authentication token is stored locally. The Google OAuth token is stored in ~/.gemini/. On shared machines, treat this directory as sensitive.
  • MCP integration is newer. The MCP server support is confirmed by community documentation and GitHub issues, but the configuration format may change. Verify against the current README before deploying MCP integrations.

Confirmed by Docs vs. Practical Inference

Claim Status
Install command: npm install -g @google/gemini-cli Confirmed by official docs and codelab
Node.js 20+ required Confirmed by official documentation
Google account OAuth on first run Confirmed by codelab
API key via GEMINI_API_KEY env variable Confirmed by codelab and community documentation
Vertex AI via env variables + ADC Confirmed by Warp docs and community documentation
~60 RPM / 1000 RPD free tier limit Confirmed per Warp docs drawing on Google published limits; verify at ai.google.dev
GEMINI.md project context file Confirmed by codelab and Antigravity codelab (same pattern used by Google's agent tools)
MCP server support via settings.json Confirmed by community docs and GitHub issues; configuration format may shift
Settings stored in ~/.gemini/settings.json Confirmed by codelab
Homebrew install method Confirmed by official installation docs

Cost and Rate-Limit Notes

Gemini CLI is open source and free to install. Usage costs depend on your authentication method. With a personal Google account, you get a free daily quota. With an API key from AI Studio, you are billed per token via the Gemini API pricing tier you selected—the free API tier has lower rate limits than paid tiers. With Vertex AI, costs are billed through your Google Cloud project. Check ai.google.dev/pricing and cloud.google.com/vertex-ai/pricing for current rates.

Where to Go Next