Google's Gemini CLI dropped an AI agent straight into your terminal with two things no rival could match: a 1-million-token context window and a genuinely free tier. It became a lot of developers' default for "just throw the whole repo at it." Then Google announced it's pulling the plug on the consumer version.
This guide covers the whole picture as of June 2026: how to install and use Gemini CLI, what the free tier really gives you, how subagents and extensions work — and the part you can't ignore, the June 18, 2026 migration to Antigravity CLI. If you're adopting it now, you need to know what you're walking into.
Gemini CLI is Google's open-source, command-line AI coding agent. It runs Gemini models inside your terminal to read and edit files, run shell commands, search the web live, and work through multi-step coding tasks — authenticated with a Google account and a free daily quota.
- Install:
npm install -g @google/gemini-cli→gemini login→gemini - Free tier: 60 requests/min, 1,000 requests/day with a Google account — no API key needed.
- Superpowers: 1M-token context window (holds a whole codebase) and live Google Search grounding.
- The catch: Google retires the consumer Gemini CLI on June 18, 2026, replacing it with Antigravity CLI.
- vs Claude Code: lower benchmark scores, but free and far bigger context. Great second tool, risky sole tool.
What you'll need
- Node.js 18+ — Gemini CLI installs as a global npm package.
- A Google account — for the free tier. No API key or credit card required to start.
- A terminal — macOS, Linux, or Windows (WSL recommended on Windows).
- (Optional) A Gemini API key — only if you want to bill against the API instead of the Google-account free tier.
How do you install and run Gemini CLI?
Installation is one command, and the first run walks you through auth.
npm install -g @google/gemini-cli
gemini login # opens a browser to sign in with your Google account
cd your-project
gemini # starts an interactive session in the current directory
That's it — no API key, no config file. Once you sign in, the free tier is active and you're talking to Gemini inside your repo.
For a one-off, non-interactive task you can prompt it directly:
gemini "add input validation to the signup handler and write a test for it"
Gemini reads the relevant files, proposes edits, runs commands when needed, and reports back. The context → instruction → result loop is the same as every terminal agent; what differs is how much it can see at once and what it costs.
Is Gemini CLI free? The tier and quota breakdown
This is Gemini CLI's biggest draw. The free tier is real and generous, not a teaser.
| Plan | Daily requests | Rate limit | Cost |
|---|---|---|---|
| 🆓 Google account | 1,000 / day | 60 / min | Free |
| Gemini API key (unpaid) | 250 / day | varies | Free |
| Google AI Pro | 1,500 / day | higher | Subscription |
| Google AI Ultra | 2,000 / day | highest | Subscription |
| Code Assist Standard | 1,500 / day | higher | Workspace plan |
| Code Assist Enterprise | 2,000 / day | highest | Workspace plan |
Quota figures per Google's Gemini CLI quota-and-pricing docs.
For most solo developers, 1,000 requests a day is hard to exhaust during normal work. That's the whole reason Gemini CLI spread so fast — it cost nothing to try and nothing to keep using.
How do subagents and extensions work?
Gemini CLI isn't just a single prompt loop. It has a real extension story.
Subagents
Subagents are specialist agents that run in their own isolated context window, so they don't pollute your main conversation. Gemini ships with built-ins:
@codebase-investigator— explores and explains your repo@browser-agent— drives a browser for tasks needing the web
You can define custom subagents as Markdown files with a restricted tool set, a custom system prompt, and even a different underlying model. This is how you build a "reviewer" agent or a "test-writer" agent that behaves consistently.
Extensions
Extensions add capabilities, often via MCP servers:
gemini extensions install @google/web-search
gemini extensions install @playwright/mcp
gemini extensions list
The one feature genuinely unique to Gemini: Google Search grounding. Gemini CLI can pull live information from the web during a task — current package versions, fresh API docs, real-time data. No other terminal agent does this natively, and it's the reason to keep Gemini in your toolkit even alongside a stronger coder.
The Antigravity migration: read this before you commit
Here's the thing every "Gemini CLI guide" published before May 2026 gets wrong.
What this means in practice:
- If you're a free / Pro / Ultra user: your Gemini CLI workflows need to move to Antigravity CLI before June 18, 2026. Antigravity adds subagent orchestration, cross-platform terminal sandboxing, credential masking, and hardened Git policies — it's a genuine upgrade, but the commands and config differ.
- If you bill via a Gemini API key or paid Code Assist: you're less affected in the immediate term, but the product's center of gravity has clearly shifted to Antigravity. Plan accordingly.
- If you're choosing a CLI today: don't build a long-term workflow on the consumer Gemini CLI. Either learn Antigravity directly, or pick a tool without a looming sunset.
This isn't a reason to avoid Gemini's models — they're excellent, and the 1M context and Search grounding carry straight into Antigravity. It's a reason to point your muscle memory at the right binary.
Gemini CLI vs Claude Code: an honest comparison
The question everyone types into search. Here's the straight answer.
| Gemini CLI | Claude Code | |
|---|---|---|
| Context window | 🟢 1M tokens | 200K tokens |
| SWE-bench Verified | 63.8% | 🟢 80.9% |
| Free tier | 🟢 1,000 req/day | API trial only |
| Live web search | 🟢 Built-in grounding | Via MCP/tools |
| Complex refactors | Good (needed 3 corrections in one benchmark) | 🟢 Best (zero interventions) |
| Ecosystem | Extensions + subagents | 🟢 Largest (2,810+ skills) |
| Long-term stability | 🔴 Consumer CLI sunset June 2026 | 🟢 Stable |
| Cost | 🟢 Free to start | $20–200/mo |
Benchmark figures per CodeAnt's 2026 CLI comparison.
Use Gemini CLI when you need to reason over a huge codebase in one shot, want live web data, or simply don't want to pay. Use Claude Code when the task is a hard multi-file refactor and getting it right the first time matters more than the bill.
Honestly? Many developers run both — Gemini's free tier and giant context for exploration and research, Claude Code for the surgery. They complement each other more than they compete.
Common problems and fixes
| Problem | Fix |
|---|---|
command not found: gemini |
Node's global bin isn't on PATH. Run npm config get prefix and add its /bin to your shell PATH. |
| Login loop / auth fails | Clear cached creds (~/.gemini/), run gemini login again, and make sure you're not behind a proxy blocking the OAuth redirect. |
| Hitting the 1,000/day limit | You're on the free tier — upgrade to Google AI Pro (1,500/day) or switch to API-key billing for higher throughput. |
| Worried about June 18 sunset | If you're a consumer-tier user, install and test Antigravity CLI now so the cutover isn't a fire drill. |
| Extension behaving badly | Run gemini extensions list, remove anything you don't recognize — third-party extensions aren't vetted by Google. |
Frequently Asked Questions
How do I install Gemini CLI?
Run npm install -g @google/gemini-cli, then gemini login to authenticate with your Google account, then gemini inside your project. No API key is needed for the free tier.
Is Gemini CLI free?
Yes. With a personal Google account you get 60 requests per minute and 1,000 requests per day at no cost. Google AI Pro and Ultra subscriptions raise that to 1,500 and 2,000 requests per day.
Is Gemini CLI being replaced by Antigravity CLI?
Yes, for consumer users. On June 18, 2026, Google retires Gemini CLI for free, Google AI Pro, and Ultra tiers and replaces it with the Go-based Antigravity CLI announced at I/O 2026. Migrate your workflows before that date.
What is Gemini CLI's context window?
Gemini CLI has a 1 million token context window — roughly 3 to 4 million characters, enough to hold an entire mid-sized codebase without chunking. It is the largest context window of any major terminal coding agent in 2026.
Gemini CLI vs Claude Code: which is better?
Claude Code scores higher on coding benchmarks (80.9% vs 63.8% on SWE-bench Verified) and is better at complex multi-file work. Gemini CLI wins on free access, a 1M-token context window, and live Google Search grounding. Use Gemini CLI for large-context tasks and research; use Claude Code for hard refactors.
What's Next
- 🪐 Plan your migration: read the Google Antigravity review — it's where consumer Gemini CLI users land after June 18.
- 🆚 Compare all four CLIs: see Claude Code vs Codex vs Gemini CLI vs OpenCode to pick your stack.
- 🧠 Get more from any agent: context engineering techniques sharpen Gemini's already-huge context window.
- 🔒 Want it fully local instead? The Local LLM + Ollama RAG guide shows how to run a private coding model with no quotas at all.
Gemini CLI is a brilliant free starting point — just build your real workflow somewhere with a future. Start with the Claude Code Workflow Guide for the strongest all-rounder, and grab the free AI engineering resources to level up how you work with any coding agent.