Gemini CLI

On this page 7

Gemini CLI is an open-source AI agent for the terminal developed by Google that connects a command-line session to the Gemini family of language models and lets them read files, edit code, run shell commands and call external tools on the user’s behalf. Among AI models & assistants, it belongs to the group of agentic coding tools, alongside products such as Claude Code and OpenAI Codex, rather than to chat interfaces in a browser.

Released in June 2025 under the Apache 2.0 license, the tool is installed as a Node.js package and runs locally, while the model inference happens on Google servers. Its defining traits are a very large context window, a generous free usage tier for personal accounts and an architecture built on the Model Context Protocol for extensibility.

How Gemini CLI works as a terminal agent

Gemini CLI works by running a reason-and-act loop: the model reads the request, decides which tool to call, observes the result and repeats until the task is complete. The local client handles the user interface, file access and command execution, while each reasoning step is a request to a Gemini model through the Gemini API or Vertex AI.

The client ships with a set of built-in tools that the model may invoke. Before any tool that changes state runs, the default configuration asks the user for explicit confirmation, showing the proposed diff or command. The following table summarizes the main tool categories.

Tool categoryWhat the model can doDefault safeguard
File system toolsList directories, read files, search with patternsRead operations run without prompting
Editing toolsWrite new files, replace text in existing filesDiff shown, approval required
Shell toolRun commands such as tests, builds or gitCommand shown, approval required
Web toolsFetch a URL, ground answers in Google SearchApproval for fetches
MCP toolsCall tools exposed by external MCP serversConfigurable trust per server
Main built-in tool categories

Project knowledge is supplied through GEMINI.md context files. The client loads them hierarchically from the home directory, the project root and subdirectories, so a team can record build commands, coding conventions and architectural rules once and have them included in every session.

Models, context window and access tiers

Gemini CLI is a client, not a model, so its capability depends on the Gemini model it calls. At launch it defaulted to Gemini 2.5 Pro with automatic fallback to Gemini 2.5 Flash under load, and later releases added newer Gemini generations. The Pro-class models offer a context window of about one million tokens, which allows the agent to hold large portions of a codebase in a single request.

Access depends on the authentication method, and quotas have changed several times since release, so current limits should always be checked in the official documentation. The table shows the three routes and their typical use.

Authentication routeTypical userBilling and limits
Personal Google accountIndividual developers, evaluationFree tier with daily request caps
Gemini API keyDevelopers needing a chosen model or higher volumePay per token or free API tier
Vertex AIEnterprises on Google CloudProject billing, enterprise data controls
Authentication routes and typical users

The free tier at launch allowed roughly 60 requests per minute and 1,000 per day. One agent task often consumes many model requests, because every tool call and every observation counts, so a heavy session can reach the daily cap faster than the numbers suggest.

Gemini CLI differs from the Gemini chat app mainly in where it acts: the app answers in a browser, while the CLI operates directly on local files and processes. Compared with other terminal agents, the differences lie in licensing, model choice and extension mechanisms rather than in the basic loop, which is similar across the category.

ToolPrimary interfaceModel sourceClient license
Gemini CLITerminal agentGemini modelsOpen source, Apache 2.0
Claude CodeTerminal agent and IDE integrationsClaude modelsProprietary
OpenAI CodexTerminal agent and cloud agentOpenAI modelsOpen-source CLI
GitHub CopilotIDE completion and chatSeveral providersProprietary
Gemini appBrowser and mobile chatGemini modelsProprietary
Gemini CLI and neighboring tools

The open-source client matters in practice: organizations can audit how prompts, files and commands are handled, contribute fixes and build forks. It does not make the system local, however, because the model itself remains a hosted service.

Configuring and extending the agent

Gemini CLI is configured through settings.json files at user and project level, through command-line flags and through environment variables. The most important settings control the model, the approval mode, sandboxing and MCP servers.

  • Interactive mode opens a chat-style session with slash commands such as /memory, /tools and /chat.
  • Non-interactive mode with the -p flag runs one prompt and prints the result, which suits scripts and CI pipelines.
  • Checkpointing saves project snapshots before edits so that changes can be restored with a single command.
  • Sandboxing runs tools inside macOS Seatbelt profiles or Docker and Podman containers to limit damage from faulty commands.
  • Extensions bundle MCP servers, context files and custom commands into installable packages.

The approval mode deserves deliberate choice. The table lists common situations and the recommended setting.

SituationRecommended settingReason
Exploring an unfamiliar repositoryDefault confirmationsEvery change stays visible
Routine refactoring on a clean branchAuto-approve edits onlyFaster, git allows rollback
Unattended CI jobAuto-approve inside a sandboxNo human present, damage contained
Production server or secrets nearbyAvoid the agent or read-only useRisk outweighs convenience
Choosing an approval strategy

Limitations, risks and common mistakes

Gemini CLI inherits the weaknesses of large language models: it can misread intent, invent APIs or produce code that compiles but behaves incorrectly. Its agentic nature adds operational risk, because a wrong shell command acts on real files. The most frequent problems are listed below.

ProblemCauseFix
Agent ignores project conventionsMissing or vague GEMINI.mdWrite explicit rules and commands
Session stops mid-taskQuota or rate limit reachedUse an API key or smaller tasks
Destructive command executedBlanket auto-approval outside a sandboxEnable sandbox, keep confirmations
Confidential code sent to the serviceUnclear data policy for the account typeReview terms for the chosen tier
Instructions hidden in fetched contentPrompt injection through web or filesLimit web tools, review actions
Typical problems and fixes

A common misconception is that the large context window removes the need for focus. In practice, answers improve when the agent receives a narrow, well-scoped task and only the relevant files, because irrelevant context dilutes attention and raises cost.

The idea in brief

Gemini CLI puts a Google AI assistant inside the text window that programmers use to control their computers. Instead of copying code into a website and back, a developer types a request such as “fix the failing test”, and the assistant looks through the project, proposes changes and runs commands to check them.

It works like a capable helper who must ask before touching anything. The helper can read freely, but before editing a file or running a command it shows what it plans to do and waits for a yes. The thinking happens on Google servers; the hands work on the developer’s own machine.

A practical scenario

A backend developer at a mid-sized logistics company inherits a Python service of about 40,000 lines with outdated dependencies and no documentation. She installs Gemini CLI, signs in with her company’s Vertex AI project and adds a GEMINI.md file stating the test command, the formatting tool and a rule that database migrations must never be edited.

She first asks the agent to explain the request flow from the HTTP layer to the database. Because the model can hold most of the repository in context, it produces an accurate map of modules within minutes. She then asks it to upgrade the web framework by one major version. The agent edits 23 files, runs the test suite, reads the failures and fixes them in three iterations, asking for approval at each step.

The outcome is a reviewed pull request in one afternoon instead of an estimated three days. Two changes still needed manual correction, which confirms the practical rule: the agent accelerates the work, but human review remains mandatory.