Skip to content

Gemini CLI: Google's AI Agent in Your Terminal

  • How Gemini CLI installs and authenticates through Google AI Studio.
  • Using the 1 million token context window to analyze entire repositories in one pass.
  • How Google Search grounding keeps responses current when library APIs change.
  • Configuring project conventions with GEMINI.md and running agentic coding tasks.
  • When to prefer Gemini CLI over Claude Code, the Codex CLI, or the Antigravity IDE.

Gemini CLI is Google’s open-source, terminal-native AI coding agent. Powered by the Gemini model family (Gemini 2.5 Pro and Gemini 2.5 Flash as of mid-2026), it brings a 1 million token context window, real-time Google Search grounding, and agentic file editing directly into your shell. The tool is free to use within Google AI Studio’s generous tier limits and open-source under the Apache 2.0 license.

Unlike the Google Antigravity IDE which wraps Gemini inside a full visual development environment, Gemini CLI stays in the terminal and works alongside any editor you already use — the same philosophy as Claude Code.

Large, modern codebases are hard to hold in one AI context. A 200K-token context window can hold roughly 150,000 words of code — large by older standards, but still not enough to load a mature monorepo alongside its tests and documentation. Developers end up cherry-picking files to paste into chat windows, losing cross-module relationships that are only visible across the whole tree.

Gemini CLI addresses this in two ways:

  1. 1 million token context: The full repository can be loaded at once, including deeply nested sub-packages, generated API clients, and large test suites. This matters for tasks like finding all callers of a deprecated interface across 300 files.
  2. Live search grounding: When a library releases a breaking change after Gemini’s training cutoff, the CLI can search Google in real time to retrieve the current migration guide rather than generating an outdated pattern from memory.

Gemini CLI requires Node.js 18 or later.

Terminal window
# Install globally
npm install -g @google/gemini-cli
# Or run without installing
npx @google/gemini-cli
# Authenticate — opens a browser flow to connect your Google account or API key
gemini auth login

After authentication, gemini is available in any directory. Run gemini --version to confirm.

For CI environments or headless servers, authenticate with a Google Gemini API key:

Terminal window
export GOOGLE_API_KEY="AIzaSy-your-key-here"

Start an interactive session in a project directory:

Terminal window
cd my-project
gemini

Send a one-shot question without entering interactive mode:

Terminal window
gemini "Explain what this codebase does and how the main data flow works."

Request an agentic task — Gemini CLI reads files, edits them, and reports what changed:

Terminal window
gemini "Add input validation to every POST endpoint in src/routes/ and write tests for each one."

Gemini 2.5 Pro accepts up to 1 million tokens per request, roughly 750,000 words of code. In practice this means loading an entire medium-sized monorepo, its configuration files, and test suites in one call.

Use --include to control which file patterns are loaded:

Terminal window
# Load only TypeScript source and config
gemini --include "**/*.ts,**/*.json" "Find all places where we directly query the database instead of going through the repository layer."
# Load everything for a full audit
gemini "Review this codebase for OWASP Top 10 vulnerabilities."

The large context is most valuable for cross-cutting concerns: finding all usages of a pattern, tracing a data model through every layer, or catching inconsistencies between a schema definition and its consumers.

Gemini CLI can query Google in real time during a task. This matters when:

  • A dependency was updated after Gemini’s training cutoff.
  • You are working with a niche library that the model has limited training data for.
  • You want to verify that a generated API call uses current syntax.
Terminal window
gemini "Migrate all AWS SDK v2 calls in src/ to AWS SDK v3 syntax."
# Gemini searches for the AWS SDK v3 migration guide, extracts the new patterns,
# then applies the correct current syntax rather than the v2 patterns in its training data.

Enable search grounding in config:

Terminal window
gemini config set search true

Create a GEMINI.md file at the repository root to give Gemini CLI persistent instructions — the equivalent of CLAUDE.md for Claude Code or .cursorrules for Cursor:

# OrdersPortal — Gemini CLI Context
## Stack
- Backend: Node.js 22, TypeScript 7, PostgreSQL 17
- ORM: Drizzle with generated types
- Testing: Vitest with @testing-library/react
## Conventions
- Never use raw SQL; go through the repository layer in src/db/
- All monetary values use the `Money` value object — never raw numbers
- Run `npm test` after every change that touches src/
## Commands
- Build: `npm run build`
- Test: `npm test`
- Lint: `npm run lint`

Gemini CLI reads this file on every session start. It conditions the model on your project’s specific rules without repeating them in every prompt.

In agentic mode, Gemini CLI reads files, proposes changes, and writes them to disk after showing you a diff:

Terminal window
gemini "Refactor the authentication module to use JWT access tokens (15 min expiry) and refresh tokens (7 days). Keep all existing tests passing."

The agent:

  1. Reads the current authentication implementation.
  2. Plans the changes across affected files.
  3. Shows a unified diff of every proposed modification.
  4. Writes the changes on approval.
  5. Runs npm test (from GEMINI.md) to verify no regressions.

For fully autonomous execution without per-step approval, use --yolo (not recommended for production changes):

Terminal window
gemini --yolo "Fix all TypeScript compilation errors."

Gemini CLI supports the Model Context Protocol (MCP), letting it connect to databases, internal APIs, and third-party services:

Terminal window
# Start with an MCP server providing database schema access
gemini --mcp-server postgres://localhost/orders "What indexes are missing on the orders table given this query pattern?"

This is the same protocol supported by Claude Code, Kiro, and Cursor Agent, so MCP server configurations can be shared across tools.

Feature Gemini CLI Claude Code Codex CLI
Context window 1 M tokens 1 M tokens ~1 M tokens
Search grounding Live Google Search Web search integration None
Foundation model Gemini 2.5 Pro / Flash Claude Opus 5.5 / Sonnet 5.5 GPT-6.1 (Terra / Sol)
MCP support Yes Yes Limited
Open source Yes (Apache 2.0) Yes No
Free tier Yes (AI Studio limits) Requires Claude Pro Via ChatGPT Pro
Best cloud fit Google Cloud (GCP) Cloud-agnostic GitHub / Azure
Editor requirement None — terminal only None — terminal only None — terminal only
  • Whole-repository analysis: The 1 M token window is the largest available for a terminal agent and handles monorepos other tools must split across sessions.
  • Current information: Search grounding makes it reliable for frameworks and APIs that change frequently.
  • Cost at scale: The free AI Studio tier and competitive token pricing make Gemini CLI affordable for high-volume automated workflows.
  • GCP specialization: The deepest integrations and shortest prompts for cloud scaffolding are GCP-specific (Cloud Run, GKE, BigQuery). AWS and Azure patterns require more explicit prompting.
  • No visual diff UI: Unlike Cursor’s Composer pane, changes are applied through the terminal. Reviewing large multi-file edits requires careful attention to the printed diff.
Scenario Recommendation
Analyzing a large codebase in one pass Use Gemini CLI
Working with recently updated libraries Use Gemini CLI (search grounding)
Developing on Google Cloud infrastructure Use Gemini CLI
Visual multi-file diffs in a GUI Use Cursor or Antigravity
Tight GitHub and Azure integration Use Claude Code or Codex CLI
  • Gemini CLI is a free, open-source terminal agent powered by Gemini 2.5 Pro and Flash.
  • The 1 million token context window allows loading an entire medium-sized repository in a single call.
  • Google Search grounding keeps API knowledge current past the model’s training cutoff.
  • GEMINI.md provides persistent project conventions, the same role as CLAUDE.md or .cursorrules.
  • MCP support allows connecting to databases, APIs, and services alongside any coding task.