What Is Gemini CLI: Google's Open-Source Terminal Agent

Gemini CLI is Google's open-source (Apache-2.0) terminal agent: you state a goal, and it runs an agent loop — calling a Gemini model, reading and editing files, running shell commands, and searching the web — pausing for your approval before changes. Current docs support personal Google sign-in, organization-managed sign-in, Gemini API keys, and Vertex AI. This guide explains the CLI and the documented boundary with Antigravity.

The agentic loop

The source is two packages. packages/cli is the terminal frontend you type into; packages/core is the backend that talks to the Gemini API, manages tools, and processes each request. A turn runs as a loop: core assembles context (history + tool definitions + discovered GEMINI.md files) and sends it to the model; the model replies with an answer or a tool call (read file, run command, search); core executes the tool and returns the result; the model decides the next step. This repeats until the task is done.

Two mechanisms keep the loop safe and durable. Mutating tools require confirmation — before a file write (write_file, replace) or a shell command (run_shell_command), the CLI shows the diff or exact command and waits; read-only tools (grep_search, read_file) run silently. And when a conversation nears the model's token limit, core auto-compresses history (documented as "lossless in terms of information conveyed") so long tasks do not run out of room.

Authenticating — three backends with different access

The model access, quota, and billing path come from one of three backends. Organization-managed Google sign-in uses the browser flow, an AI Studio key uses GEMINI_API_KEY, and Vertex AI combines project/location with one credential method plus a selection in /auth. The same gemini binary serves all three, but available models, limits, billing, and compliance can differ.

Models, defaults, and Auto routing

Gemini CLI defaults to Auto routing. Gemini 3 participates when it is enabled and available to the selected authentication route; the unpaid API-key tier remains Flash-only. The current recommended Pro model ID is gemini-3.1-pro-preview — 1,048,576 input / 65,536 output tokens, knowledge cutoff January 2025, reasoning ("Thinking") supported. You rarely need to type a model ID: use /model to inspect the available Auto and Manual choices, or launch one directly with -m, e.g. gemini -m gemini-3.1-pro-preview or gemini -m gemini-2.5-flash.

Auto routing chooses among the models your account can currently use. When a selected Pro model hits quota or availability trouble, the CLI offers a fallback rather than silently changing the session: Gemini 3 Pro can fall back to 2.5 Pro, then 2.5 Pro to 2.5 Flash. If model identity matters, inspect Manual in /model or pin a live ID with -m, and confirm the model in the session report.