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 category | What the model can do | Default safeguard |
|---|---|---|
| File system tools | List directories, read files, search with patterns | Read operations run without prompting |
| Editing tools | Write new files, replace text in existing files | Diff shown, approval required |
| Shell tool | Run commands such as tests, builds or git | Command shown, approval required |
| Web tools | Fetch a URL, ground answers in Google Search | Approval for fetches |
| MCP tools | Call tools exposed by external MCP servers | Configurable trust per server |
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 route | Typical user | Billing and limits |
|---|---|---|
| Personal Google account | Individual developers, evaluation | Free tier with daily request caps |
| Gemini API key | Developers needing a chosen model or higher volume | Pay per token or free API tier |
| Vertex AI | Enterprises on Google Cloud | Project billing, enterprise data controls |
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.
How Gemini CLI compares with related assistants
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.
| Tool | Primary interface | Model source | Client license |
|---|---|---|---|
| Gemini CLI | Terminal agent | Gemini models | Open source, Apache 2.0 |
| Claude Code | Terminal agent and IDE integrations | Claude models | Proprietary |
| OpenAI Codex | Terminal agent and cloud agent | OpenAI models | Open-source CLI |
| GitHub Copilot | IDE completion and chat | Several providers | Proprietary |
| Gemini app | Browser and mobile chat | Gemini models | Proprietary |
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,/toolsand/chat. - Non-interactive mode with the
-pflag 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.
| Situation | Recommended setting | Reason |
|---|---|---|
| Exploring an unfamiliar repository | Default confirmations | Every change stays visible |
| Routine refactoring on a clean branch | Auto-approve edits only | Faster, git allows rollback |
| Unattended CI job | Auto-approve inside a sandbox | No human present, damage contained |
| Production server or secrets nearby | Avoid the agent or read-only use | Risk outweighs convenience |
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.
| Problem | Cause | Fix |
|---|---|---|
| Agent ignores project conventions | Missing or vague GEMINI.md | Write explicit rules and commands |
| Session stops mid-task | Quota or rate limit reached | Use an API key or smaller tasks |
| Destructive command executed | Blanket auto-approval outside a sandbox | Enable sandbox, keep confirmations |
| Confidential code sent to the service | Unclear data policy for the account type | Review terms for the chosen tier |
| Instructions hidden in fetched content | Prompt injection through web or files | Limit web tools, review actions |
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.