Gemini CLI: The Complete Guide (2026)

Updated 2026-05-23.

The three big terminal AI agents in 2026 are Claude Code, OpenAI Codex CLI, and Google Gemini CLI. Of the three, Gemini CLI is the only one with a genuinely free tier — 1,000 requests per day, 1 million tokens of context, no credit card — which makes it the cheapest way to try out an autonomous coding agent in your terminal.

This guide covers what Gemini CLI is, how to install it on macOS, Linux and Windows, how to authenticate (Google account, API key, Vertex AI), the day-to-day commands, the MCP and tool layer, and how it stacks up against Claude Code and Codex CLI.

What is Gemini CLI?

Gemini CLI is an open-source command-line agent that runs Google’s Gemini models against your local working directory. Source is at github.com/google-gemini/gemini-cli and the npm package is @google/gemini-cli. It is built in TypeScript, ships as a single binary on npm, and follows a weekly release cadence (preview on Tuesdays UTC 23:59, stable on Tuesdays UTC 20:00, nightly daily).

It is structurally similar to Claude Code: you run gemini in a project directory, the agent reads files, plans, edits, runs shell commands, and you confirm or reject each tool call. The difference is the underlying model and the price.

Key features

• Free tier: 60 requests/min, 1,000 requests/day with a personal Google account.
• 1M-token context: holds substantially more of a repo than competitors’ default windows.
• Built-in tools: file read/write/edit, shell execution, Google Search grounding, web fetch.
• MCP support: add custom MCP servers for databases, internal APIs, design systems.
• Open source: Apache-2.0 license; you can audit, fork or self-modify the agent.

How to install Gemini CLI

Prerequisites

• Node.js 20+. Check with node --version. Install via your OS package manager, nvm or nodejs.org if missing.
• A Google account (for the free tier) or a Google AI Studio API key (for automation / CI).

How to install Gemini CLI on macOS

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

If you hit an EACCES permission error, install Node via nvm rather than the system package so npm can write to a user-owned prefix.

How to install Gemini CLI on Linux

# Debian/Ubuntu — install Node 20 first if needed
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

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

How to install Gemini CLI on Windows

1. Install Node.js LTS from nodejs.org.
2. Open PowerShell and run npm install -g @google/gemini-cli.
3. Verify with gemini --version.

Run without installing

npx @google/gemini-cli

Handy for one-off use; for daily work the global install is faster.

Gemini CLI authentication

Gemini CLI supports three auth paths. Pick the one that matches your use case.

1. Google account (free tier, recommended for individuals)

Just run:

gemini

The CLI opens your browser, you sign in with Google, and the token is stored locally. This unlocks the 60 RPM / 1,000 RPD free tier with Gemini 2.5 Pro and the 1M-token window.

2. API key (automation / CI)

1. Visit aistudio.google.com/apikey, sign in, click Create API key.
2. Copy the key (starts with AIza).
3. Export it:

# macOS / Linux
export GEMINI_API_KEY=AIza...your-key...
# add it to ~/.zshrc or ~/.bashrc to persist

# Windows PowerShell
setx GEMINI_API_KEY "AIza...your-key..."

API-key usage is billed per token at Google AI Studio rates; the free-tier limits do not apply once you authenticate this way.

3. Vertex AI (enterprise / Google Cloud)

For Vertex AI workloads, use Application Default Credentials via gcloud, or a service-account JSON:

export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
export GOOGLE_CLOUD_PROJECT=your-project-id
export GOOGLE_CLOUD_LOCATION=us-central1

Grant the service account the Vertex AI User role. This is the right path for org-managed quota, audit logs and VPC controls.

Basic usage

Open a project directory and run:

cd ~/code/my-project
gemini

You drop into an interactive prompt. Type a request in plain English — “Add a Postgres health-check endpoint to server.ts and a test in tests/health.spec.ts” — and the agent plans, reads the necessary files, proposes edits and shell commands, and asks you to approve each.

Useful flags

• gemini --model gemini-2.5-pro — pin a specific model.
• gemini --yolo — auto-approve tool calls (use only in a sandbox or container).
• gemini --help — full flag list for your installed version.

Useful slash commands

• /help — in-session command list.
• /auth — re-run authentication.
• /model — switch between Gemini 2.5 Pro and Flash mid-session.
• /memory — view or edit persistent project memory.
• /quit — exit.

Built-in tools and MCP

Out of the box Gemini CLI can:

• Read, write and edit files in the working directory.
• Run shell commands (with confirmation by default).
• Fetch URLs and ground answers in Google Search.
• Call user-defined MCP servers (databases, Jira, design systems, Linear, anything with an MCP wrapper).

Add an MCP server by editing ~/.gemini/settings.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/code"]
    }
  }
}

Restart gemini and the MCP tools appear under the model’s tool list.

Gemini CLI vs Claude Code vs OpenAI Codex CLI

All three are first-class terminal AI coding agents. They differ on model, price, ergonomics and benchmarks.

For a side-by-side of the two paid tools see our Claude Code vs OpenAI Codex comparison. For the broader landscape, see AI coding agents complete guide.

When to use Gemini CLI

• You want to try a terminal AI agent for free. The 1,000 req/day tier is generous enough to do a real day of work.
• You need to reason over a large codebase or document. 1M tokens beats most competitors’ defaults.
• You already use Google Cloud / Vertex AI. Auth integrates cleanly with your existing IAM and billing.
• You want Google Search grounding inside the agent. It is built in and well-tuned.

Where it lags: Gemini 2.5 Pro is currently behind Claude Opus 4.7 on SWE-bench Verified by ~12 points, so on hard multi-file refactors Claude Code still wins on first-pass correctness. For most everyday work the gap is small enough to be noise.

Common issues and fixes

• command not found: gemini. npm’s global bin is not on $PATH. Run npm config get prefix and add $prefix/bin to your shell PATH.
• EACCES on npm install -g. Switch to nvm or use npm config set prefix ~/.npm-global then add ~/.npm-global/bin to PATH.
• Quota exceeded on the free tier. Switch to an API key (no daily cap) or wait until the daily reset (Pacific midnight).
• Wrong project on Vertex. Set GOOGLE_CLOUD_PROJECT explicitly — ADC can pick a stale default.

Security notes

• Auto-approve mode (--yolo) will execute any shell command the model produces. Run it only in a sandboxed VM or container.
• API keys land in plaintext in your shell history if you paste them inline. Use setx on Windows or your shell profile, never export KEY=... on the command line.
• Treat the ~/.gemini directory like an SSH key directory: it contains your auth state.

Related Codersera guides

• Claude Code vs OpenAI Codex (2026)
• AI coding agents complete guide (2026)
• Cursor IDE complete guide (2026)
• Claude Opus 4.7 complete guide (2026)

FAQ

How do I install Gemini CLI?

Install Node.js 20 or higher, then run npm install -g @google/gemini-cli on macOS, Linux or Windows. Verify with gemini --version. For one-off use, npx @google/gemini-cli works without a global install.

Is Gemini CLI free?

Yes, with a Google-account login. The free tier is 60 requests per minute and 1,000 requests per day against Gemini 2.5 Pro, with a 1 million-token context window. API-key usage from Google AI Studio is pay-per-token at standard rates and has no daily cap.

What is the difference between Gemini CLI and Claude Code?

Both are terminal AI coding agents with confirm-per-tool-call ergonomics. Gemini CLI uses Gemini 2.5 Pro, is open-source under Apache-2.0, and has a free tier. Claude Code uses Claude Opus 4.7, is closed-source, requires a Pro/Max subscription, and currently scores higher on SWE-bench Verified (~88% vs ~76%). For hard multi-file refactors Claude wins; for free exploration and long-context reads Gemini is the better starting point.

How do I authenticate Gemini CLI with an API key?

Visit aistudio.google.com/apikey, click Create API key, copy the key (starts with AIza), and set GEMINI_API_KEY in your shell profile. On Windows PowerShell use setx GEMINI_API_KEY "your-key" and reopen the terminal.

Does Gemini CLI support MCP servers?

Yes. Add MCP servers to ~/.gemini/settings.json under the mcpServers key. Each entry specifies a command and args for an stdio MCP process. Restart gemini to pick up the new tools.

Can Gemini CLI use Vertex AI instead of Google AI Studio?

Yes. Set GOOGLE_APPLICATION_CREDENTIALS to a service-account JSON file with the Vertex AI User role, plus GOOGLE_CLOUD_PROJECT and GOOGLE_CLOUD_LOCATION. This is the right path for organizations that need IAM, audit logs and VPC controls.

What context window does Gemini CLI support?

Up to 1 million tokens with Gemini 2.5 Pro. That is enough to hold most mid-sized repositories or a substantial set of long documents in a single conversation.

Is Gemini CLI safe to run on a real codebase?

The default mode asks you to approve each tool call — file edit, shell command, web fetch — before it runs. Avoid the --yolo auto-approve flag outside a sandbox or container, since it will execute any command the model emits.

How does Gemini CLI compare to OpenAI Codex CLI?

Codex CLI is OpenAI’s equivalent terminal agent, built around GPT-5.5 with sandboxed container execution by default. Gemini CLI has a larger context window (1M vs 400K input), a free tier, and is open source; Codex CLI has the strongest sandboxing story and better CI/CD integration. See our full Claude Code vs OpenAI Codex piece for context.

Where are Gemini CLI’s config files?

Per-user config lives in ~/.gemini/, including settings.json (MCP servers, model defaults) and the auth token. Per-project config goes in a .gemini/ directory at the project root; settings there override the global config.

Closing

Gemini CLI is the easiest way to try an autonomous terminal coding agent in 2026: npm install -g @google/gemini-cli, sign in with Google, and you have 1,000 free requests a day against a 1M-token model. It is not yet the top agent on hard benchmarks, but for free exploration, long-context reads, and Google Cloud-native automation it is the most cost-effective choice on the market.