Gemini CLI, plainly
Five-minute orientation to Gemini CLI — Google's open-source terminal coding agent. What it does, where it runs, what it costs, and where it fits vs Claude Code, Codex CLI, and GitHub Copilot CLI.
The thirty-second version#
Gemini CLI is Google’s terminal coding agent. You install it via npm, run gemini inside any project directory, and the agent reads your code, edits files, runs commands, and calls Gemini’s reasoning models with tool use. It’s the closest analogue to Claude Code and Codex CLI from the Google side.
Three things to know:
- Open source, TypeScript / Node-based, Apache-2.0. The CLI binary itself is free. Built on Node.js 20+; runs on macOS 15+, Windows 11 24H2+, and Ubuntu 20.04+. Pre-installed in Cloud Shell and Cloud Workstations.
- A documented free tier that’s unusually useful for tinkering. Sign in with a personal Google account and you get 1,000 model requests per day at no cost — no card required, no credit timer. (For comparison: Claude Code has no free tier; Codex CLI’s Free tier only covers exploration on quick coding tasks — productive use needs a paid plan (Go, Plus, or Pro) or an OpenAI API key. The old $5 trial credit is gone.)
- Speaks MCP — as a client. It connects to MCP servers (filesystems, GitHub, databases, browser automation, your own) over Stdio, SSE, and Streamable HTTP. There’s no
gemini mcp-servermode — Gemini CLI itself isn’t exposed as a server other agents can call.
A real example#
You’re staring at a Next.js project that’s failing to build. Open a terminal, cd into the project, and type:
geminiThen ask in plain English: “the build is failing — figure out why.”
What happens:
- Gemini reads the error from
npm run build. - It opens
next.config.mjs, sees an experimental flag that’s been removed. - It checks
package.jsonfor the Next.js version (15.3 — the flag landed in 14.2). - It edits the config file, removes the flag, runs
npm run buildagain. - Build passes. Gemini tells you what it did.
The interesting bit isn’t “AI writes code” — every editor has that now. The interesting bit is the loop tightens: the agent reads, decides, runs, reads-the-result, decides-again, without you copying snippets back and forth.
Why this matters#
Three things fall out of the design:
- Your repo, your machine. Files are edited locally. Commits happen through your normal git workflow. The agent doesn’t push or open PRs unless you ask. What does cross the wire: model calls include whatever code, file contents, and conversation context the model needs to answer — same as any LLM-backed tool.
- Sandbox is optional and opt-in. Unlike Codex CLI (which sandboxes by default), Gemini CLI runs unsandboxed unless you turn the sandbox on. Six backends are available — macOS Seatbelt, Docker, Podman, Windows Native Sandbox, Linux gVisor, LXC — but the default posture is “trust your folder.” More on this in GCL.5 Pitfalls.
- Mono-agent architecture. One agent, one context window. There’s no subagent primitive (Codex CLI and Claude Code have these). Long sessions can drift as conflicting history accumulates — issue #3132 is tracking this.
How it compares#
| Gemini CLI | Codex CLI (OpenAI) | Claude Code (Anthropic) | Copilot CLI (GitHub) | |
|---|---|---|---|---|
| Vendor | OpenAI | Anthropic | Microsoft / GitHub | |
| Language | TypeScript / Node 20+ | Rust | Not open source | Not open source |
| Licence | Apache-2.0 (open) | Apache-2.0 (open) | Proprietary | Proprietary |
| Default model | gemini-2.5-pro (stable channel) | gpt-5.5 | Claude Sonnet 4.6 | Claude Sonnet 4.5 (per README) |
| Context window | 1M tokens | ~1M (gpt-5.5; 922K input) | 1M | 200K (Sonnet 4.5 ships 1M only as Bedrock/Vertex beta) |
| Free tier | 1,000 req/day (personal Google account) | Free tier (explore-only); paid plans Go/Plus/Pro for productive use | None | Limited (Copilot Free tier) |
| Sandbox | Optional (6 backends, OFF by default) | Built-in (per-OS, ON by default) | None | None |
| MCP | Client (Stdio + SSE + HTTP, OAuth-aware) | Client | Client | Limited |
| Subagents | No native primitive | Not confirmed for the CLI | Yes | No |
| Project context file | GEMINI.md | AGENTS.md | CLAUDE.md | None |
| Local models (Ollama, LM Studio) | No | No | No | No |
Sush’s honest take (sourced, not yet tried): the free tier is the standout — 1,000 req/day on a Pro-tier model with no card on file is unusually generous and lowers the bar for tinkering meaningfully. Apache-2.0 plus open source means you can read the sandbox code, pin a version, fork it. The MCP client implementation is unusually polished — OAuth auto-discovery, three transports, tool allowlists per server, automatic credential redaction all come pre-built. The trade-offs are real though: sandbox-off-by-default differs from Codex CLI’s safer default, the “tool loop” issue (#1531) is a regular complaint, and the README’s marketing for “Gemini 3 models” doesn’t reflect the stable-channel default of
gemini-2.5-pro.
The other Gemini surfaces (so you don’t confuse them)#
Gemini CLI is one of several “Gemini” surfaces from Google:
| Surface | Where it lives | Typical use |
|---|---|---|
| Gemini CLI | Your terminal | Interactive coding sessions, scripted automation |
| Gemini API | Your code | Direct programmatic access via SDK |
| Gemini App | gemini.google.com | Chat, Deep Research, Workspace integration |
| Gems | Inside the Gemini app | Custom personalities (no-code Custom-GPT analogue) |
| AI Studio | aistudio.google.com | Web playground; where you generate API keys |
| Vertex AI Agents | Google Cloud | Production agent stack with cloud auth |
The CLI shares config and credentials across user-wide (~/.gemini/) and project (.gemini/) scopes. Sign in once, future sessions reuse your auth.
What it costs#
The CLI binary is free (Apache-2.0). Usage consumes:
- Personal Google account (free): 1,000 model requests / day. Spans Pro and Flash; CLI picks per task.
- Gemini API key (free, from AI Studio): 250 requests / day, Flash model only. No Google Cloud project required.
- Google AI Pro subscription: 1,500 req/day. Around $19.99/month at the time of writing.
- Google AI Ultra subscription: 2,000 req/day. Pricing is materially higher (around $249.99/month at the time of writing in some regions).
- Vertex AI: standard per-token pricing through your Google Cloud billing account.
- Gemini Code Assist (Standard / Enterprise): 1,500–2,000 req/day per user, billed via GCP.
Verify before relying on these numbers. The README’s “60 requests/minute” claim isn’t confirmed by Google’s canonical quota page (which shows “2 requests/second” for general Gemini for Cloud). Subscription prices change regularly — check Google One pricing for current AI Pro and AI Ultra figures rather than depending on this page. Per-day caps are on the quota and pricing page. The
/stats modelslash command shows your current session usage and applicable limits.
What to do next#
- §GCL.2 Install — npm, Homebrew, MacPorts, Anaconda for restricted environments; release channels (stable / preview / nightly)
- §GCL.3 Auth — Google OAuth, API key, Vertex AI (3 sub-paths), Code Assist licence
- §GCL.6 MCP integration — adding MCP servers, allowlisting tools, OAuth for remote servers
- §GCL.4 Use cases — what the docs say Gemini CLI is good at
- §GCL.5 Pitfalls — known issues from the GitHub tracker, sandbox quirks, the “Gemini 3” naming wrinkle