Gemini CLI: Google's AI Agent in Your Terminal
What you’ll learn
Section titled “What you’ll learn”- 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.mdand running agentic coding tasks. - When to prefer Gemini CLI over Claude Code, the Codex CLI, or the Antigravity IDE.
Summary
Section titled “Summary”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.
The problem it solves
Section titled “The problem it solves”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 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.
- 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.
Installation and authentication
Section titled “Installation and authentication”Gemini CLI requires Node.js 18 or later.
# Install globallynpm install -g @google/gemini-cli
# Or run without installingnpx @google/gemini-cli
# Authenticate — opens a browser flow to connect your Google account or API keygemini auth loginAfter 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:
export GOOGLE_API_KEY="AIzaSy-your-key-here"Running Gemini CLI
Section titled “Running Gemini CLI”Start an interactive session in a project directory:
cd my-projectgeminiSend a one-shot question without entering interactive mode:
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:
gemini "Add input validation to every POST endpoint in src/routes/ and write tests for each one."The 1 million token context window
Section titled “The 1 million token context window”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:
# Load only TypeScript source and configgemini --include "**/*.ts,**/*.json" "Find all places where we directly query the database instead of going through the repository layer."
# Load everything for a full auditgemini "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.
Google Search grounding
Section titled “Google Search grounding”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.
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:
gemini config set search trueProject conventions with GEMINI.md
Section titled “Project conventions with GEMINI.md”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.
Agentic file editing
Section titled “Agentic file editing”In agentic mode, Gemini CLI reads files, proposes changes, and writes them to disk after showing you a diff:
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:
- Reads the current authentication implementation.
- Plans the changes across affected files.
- Shows a unified diff of every proposed modification.
- Writes the changes on approval.
- Runs
npm test(fromGEMINI.md) to verify no regressions.
For fully autonomous execution without per-step approval, use --yolo (not recommended for production changes):
gemini --yolo "Fix all TypeScript compilation errors."MCP support
Section titled “MCP support”Gemini CLI supports the Model Context Protocol (MCP), letting it connect to databases, internal APIs, and third-party services:
# Start with an MCP server providing database schema accessgemini --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.
Gemini CLI vs Claude Code vs Codex CLI
Section titled “Gemini CLI vs Claude Code vs Codex CLI”| 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 |
Strengths and limitations
Section titled “Strengths and limitations”Where Gemini CLI excels
Section titled “Where Gemini CLI excels”- 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.
Limitations
Section titled “Limitations”- 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.
When to use it and when not to
Section titled “When to use it and when not to”| 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 |
Key takeaways
Section titled “Key takeaways”- 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.mdprovides persistent project conventions, the same role asCLAUDE.mdor.cursorrules.- MCP support allows connecting to databases, APIs, and services alongside any coding task.
Related pages
Section titled “Related pages”- Google Antigravity IDE — Gemini inside a full visual development environment
- Claude Code — Anthropic’s terminal-native coding agent
- OpenAI Codex — GPT-based cloud agent and CLI
- AI Native Editors overview — comparison of modern AI-first development environments
- Google Gemini API Key — authenticating with the Gemini API
Official references
Section titled “Official references”- Gemini CLI GitHub repository — source code, issues, and releases
- Google AI Studio — API key management and free-tier dashboard
- Gemini API documentation — model reference and pricing