CtrlK
Gemini CLI is an open-source, terminal-based AI agent developed by Google that enables developers to interact with Gemini models directly from the command line. Released on June 25, 2025, under the Apache 2.0 license, it provides a conversational interface for coding assistance, code explanation, file manipulation, shell command execution, and research tasks grounded with real-time Google Search results. Built on Node.js and written primarily in TypeScript, Gemini CLI rapidly became one of the fastest-growing open-source AI projects, reaching 50,000 GitHub stars within a week of its launch.
The tool is positioned as a direct counterpart to Claude Code by Anthropic and the Codex CLI by OpenAI, distinguishing itself through its generous free tier, its 1 million token context window via Gemini 2.5 Pro, full open-source transparency, and native integration with Google's broader AI and cloud ecosystem.
By 2025, the developer tooling landscape had shifted substantially toward AI-assisted workflows embedded directly in code editors and terminals. Anthropic's Claude Code, launched in early 2025, demonstrated strong developer adoption for agentic coding tasks inside the terminal. OpenAI's Codex CLI similarly enabled GPT-series models to operate within shell environments. Google, despite having one of the world's leading AI research organizations in Google DeepMind and a broad suite of developer tools under Google Cloud, lacked a first-party open-source terminal agent that could compete directly in this space.
Google had already deployed Gemini Code Assist, a VS Code and JetBrains IDE plugin, but the terminal remained underserved. Google's developer relations team recognized that terminals occupy a privileged position in developer workflows: they are ubiquitous across macOS, Linux, and Windows, do not require an IDE, and are the environment in which most DevOps work, scripting, and CI/CD automation takes place.
The strategic motivation for open-sourcing Gemini CLI was threefold. First, open sourcing under Apache 2.0 would lower the barrier for enterprise adoption by organizations wary of proprietary AI tooling. Second, it would allow the developer community to extend the tool through plugins and integrations, expanding its ecosystem without requiring Google to build every integration internally. Third, it would enable transparent inspection of how the agent operates, addressing concerns about AI systems taking unintended actions on developer machines.
Gemini CLI shares underlying technology with Gemini Code Assist, Google's professional IDE-based coding assistant, enabling a unified experience across terminal and IDE contexts. The project is maintained by Google under the google-gemini GitHub organization and accepts community contributions.
Google announced and released Gemini CLI on June 25, 2025, publishing the source code to the GitHub repository at github.com/google-gemini/gemini-cli. The release was made under the Apache 2.0 license, which permits commercial use, modification, distribution, and sublicensing without royalty obligations, subject to attribution requirements.
The release was accompanied by a blog post on the Google Developers Blog and covered prominently by technology press including TechCrunch and The Verge. The developer community response was exceptional: the repository accumulated approximately 17,000 GitHub stars overnight and surpassed 50,000 stars within the first week. This rapid adoption placed Gemini CLI among the fastest-growing open-source AI tool repositories of 2025.
Google announced the tool as being in preview at launch, with active development ongoing. The project welcomed community contributions, and the GitHub Issues and Discussions sections quickly filled with feature requests, bug reports, and proposed extensions. Alongside the main CLI tool, Google also launched a companion GitHub Action, google-gemini/gemini-cli-action, enabling Gemini CLI to be invoked within automated CI/CD pipelines.
The choice of an open-source release contrasted with Anthropic's Claude Code, which remained a closed proprietary tool, while aligning with OpenAI's decision to open-source the Codex CLI. Both Gemini CLI and Codex CLI adopted the Apache 2.0 license.
Gemini CLI is implemented primarily in TypeScript (approximately 98% of the codebase), with the remainder in JavaScript. It runs on Node.js and is distributed as an npm package under the package name @google/gemini-cli. The tool can be invoked without installation using npx @google/gemini-cli, installed globally with npm install -g @google/gemini-cli, installed via Homebrew on macOS and Linux, or installed via Conda in restricted environments.
At its core, Gemini CLI operates as an agentic loop following a reason-and-act (ReAct) pattern. The agent receives a user prompt, reasons about what steps are needed, invokes one or more built-in tools (file operations, shell commands, web search, etc.), observes the results, and continues reasoning until the task is complete or requires user input. This loop continues interactively in the terminal, allowing back-and-forth dialogue between the user and the agent.
Configuration is managed through ~/.gemini/settings.json for global settings and project-level GEMINI.md files for workspace-specific context and instructions. GEMINI.md files function as persistent system prompt fragments: when Gemini CLI starts in a directory containing a GEMINI.md file, it loads that file's contents as context, allowing developers to encode project conventions, coding standards, preferred libraries, or architectural notes that the agent applies automatically.
The agent connects to Google's Gemini model API over HTTPS. Authentication can be handled through personal Google account OAuth (for the free tier), a Google AI Studio API key, or Vertex AI credentials for enterprise usage. In OAuth mode, no API key management is required, simplifying onboarding for individual developers.
Gemini CLI supports non-interactive invocation, allowing it to be called from shell scripts with a prompt passed on the command line, which enables integration into automation workflows and CI/CD pipelines without human interaction at runtime.
At launch, Gemini CLI connected by default to Gemini 2.5 Pro, Google's flagship model featuring a 1 million token context window. This context size is substantially larger than most competing models: Claude Code's context window at launch was 200,000 tokens, and Codex CLI supported between 128,000 and 200,000 tokens depending on the model variant selected. The 1 million token context window allows Gemini CLI to ingest entire large codebases, extended documentation sets, or lengthy conversation histories in a single request.
Users can select alternative models at runtime using the -m flag. For example, gemini -m gemini-2.5-flash targets the faster, lower-latency Flash variant of the 2.5 series. As the Gemini model family has evolved post-launch, Gemini CLI has been updated to support newer models including those in the Gemini 3 series.
Gemini 3 Pro, released later in 2025, brought improved reasoning capabilities and maintained the 1 million token context window, with updates to multimodal understanding. Support for Gemini 3 Pro in Gemini CLI was added after the initial June release. The tool's architecture is designed to remain model-agnostic at the API layer, facilitating rapid adoption of new Gemini model variants as Google releases them.
Multimodal inputs are supported through the Gemini API: developers can provide images, PDFs, and references to video content alongside text prompts. This enables workflows such as providing a UI screenshot or a wireframe sketch and asking Gemini CLI to generate corresponding code, or providing a PDF of a technical specification and asking the agent to implement the described interface.
Gemini CLI implements the Model Context Protocol (MCP), an open standard developed by Anthropic in late 2024 that defines a common interface for connecting AI agents to external tools and data sources. By supporting MCP, Gemini CLI can integrate with any MCP-compatible server, enabling connections to databases, version control systems, communication platforms, cloud services, and custom internal APIs.
MCP servers are configured in the mcpServers section of ~/.gemini/settings.json. Each server entry specifies a transport type (stdio, HTTP, or Docker), the command or URL to invoke the server, and optional environment variables. When Gemini CLI starts, it establishes connections to all configured MCP servers and presents their exposed tools to the model as available capabilities.
The MCP ecosystem around Gemini CLI grew rapidly after launch, with community-contributed servers for GitHub, Slack, PostgreSQL, Google Sheets, Notion, and many other services. Extensions (described below) can bundle their own MCP servers, making it straightforward for users to install pre-packaged integrations.
Gemini CLI's MCP client implementation supports all three transport layers defined by the protocol: stdio-based local processes, streamable HTTP servers, and Docker-containerized servers. This flexibility accommodates both lightweight local integrations and more complex, containerized tool servers. Performance optimizations, such as Node.js wrapper layers for MCP servers built on platforms with slow startup times, have been documented by community contributors.
Gemini CLI ships with several built-in tools that the agent can invoke autonomously during task execution:
File System Operations. The agent can read files, write files, create new files, move files, and search within files. These operations enable Gemini CLI to navigate and modify codebases without requiring the user to manually copy and paste content into the prompt.
Shell Command Execution. The agent can execute arbitrary shell commands, enabling it to run test suites, build tools, linters, version control commands, package managers, and other terminal utilities. Shell command execution is the most powerful and also potentially most sensitive capability: by default, Gemini CLI does not run in a sandboxed environment, and all commands execute with the permissions of the user running the agent.
Google Search Grounding. Gemini CLI can perform Google Search queries to retrieve real-time information, documentation, library references, or current events. Search results are incorporated into the model's context before generating a response, enabling accurate answers about recently released software versions, API changes, or other time-sensitive information.
Web Fetching. Beyond Search, the agent can fetch the content of specific URLs, parse web pages, and incorporate their content into its reasoning. This is useful for reading library documentation, checking API specifications, or retrieving data from web services.
Conversation Checkpointing. Gemini CLI supports saving and resuming conversations, allowing developers to pause a complex, multi-step task and resume it in a later session without losing the accumulated context and intermediate results.
Non-Interactive Scripting. Commands can be provided directly on the command line or piped via stdin, allowing Gemini CLI to be embedded in shell scripts, Makefiles, and other automation workflows without human interaction.
One of Gemini CLI's most distinctive launch features was its free tier, described by Google at release as offering the industry's largest free allowance for an AI coding CLI. Under the free tier, developers authenticate using a personal Google account via OAuth and receive a complimentary Gemini Code Assist license that grants access to Gemini 2.5 Pro with no API key required.
The free tier limits are:
Google stated at launch that these limits were approximately double the average request rate observed during internal developer testing, indicating the thresholds were calibrated to accommodate real-world usage patterns without requiring most developers to upgrade.
For developers who prefer to use an unpaid Google AI Studio API key rather than OAuth, the daily limit is reduced to 250 requests per day with access to the Flash model tier only.
Beyond the free tier, Gemini CLI supports several paid configurations:
Google AI Pro and AI Ultra. Individual subscription plans that increase daily limits to 1,500 and 2,000 requests per day, respectively.
Gemini Code Assist Standard and Enterprise. Professional plans for teams and organizations, offering 1,500 and 2,000 daily requests per user respectively, along with enterprise support, compliance features, and integration with Google Workspace.
Vertex AI Pay-as-You-Go. Developers and organizations can connect Gemini CLI to Vertex AI using standard Google Cloud credentials, at which point usage is billed per token according to Vertex AI pricing. For Gemini 2.5 Pro, this is approximately $1.25 per million input tokens and $10.00 per million output tokens as of 2025. This option provides the highest throughput and is suitable for production automation pipelines or CI/CD integration at scale.
Token usage for the current session can be monitored with the /stats model command within the CLI interface.
Gemini CLI includes a formal extension framework that allows developers and third parties to package and distribute reusable configurations, tools, and integrations. Extensions are installed from GitHub repositories or local directories using the gemini extensions install <url-or-path> command. Installed extensions are stored in ~/.gemini/extensions/ and loaded automatically at startup.
Each extension is defined by a gemini-extension.json manifest file at the extension's root directory. This manifest can specify:
GEMINI.md within the extension directory) that provide domain-specific instructions, playbooks, or system prompt fragmentscommands/ subdirectory, encapsulating complex prompts or workflows into simple slash commandsrm -rf commands)Extensions are enabled globally across all workspaces by default, though workspace-level settings can override this. When naming conflicts arise between extension-provided commands and user-defined or project-level commands, extension commands are automatically prefixed with the extension name. For example, a gcp extension's deploy command that conflicts with an existing /deploy command becomes /gcp.deploy.
The extension framework uses dynamic path variables (${extensionPath}, ${workspacePath}, ${/}) to ensure that MCP server configurations remain portable across different machines and operating systems.
Google published a growing directory of official and community extensions, covering integrations with Google Cloud services, GitHub (including pull request review automation), database tools, and productivity applications. The Jules extension for Gemini CLI, released later in 2025, allows developers to delegate asynchronous background coding tasks to Jules (Google) directly from the Gemini CLI interface.
Gemini CLI entered a market with two established terminal AI coding tools: Anthropic's Claude Code and OpenAI's Codex (OpenAI) CLI. Each tool has distinct architectural and pricing characteristics.
| Feature | Gemini CLI | Claude Code | Codex CLI |
|---|---|---|---|
| Developer | Anthropic | OpenAI | |
| License | Apache 2.0 (open source) | Proprietary | Apache 2.0 (open source) |
| Primary language | TypeScript | Unknown | Rust |
| Default model | Gemini 2.5 Pro | Claude Sonnet 4 | GPT-based Codex |
| Context window | 1 million tokens | 200,000 tokens | 128,000-200,000 tokens |
| Free tier | Yes (1,000 req/day) | No | No (API key required) |
| Sandboxing | Optional (not default) | No | Yes (default, kernel-level) |
| MCP support | Yes | Yes | Yes |
| Multimodal input | Yes (images, PDFs, video) | Yes (images, PDFs) | Yes (images) |
| Windows native | Yes | Yes | WSL2 only |
| Google Cloud integration | Native | Standard API | Standard API |
| SWE-bench score | ~63.8% (custom agent) | ~80.9% Verified | ~77.3% Terminal-Bench |
In terms of code quality benchmarks, independent evaluations placed Claude Code highest on the SWE-bench Verified leaderboard at approximately 80.9%, followed by Codex CLI at roughly 77.3% on Terminal-Bench, with Gemini CLI's custom agent configuration achieving approximately 63.8%. However, benchmark performance does not capture the full picture of developer utility: Gemini CLI's 1 million token context window makes it uniquely suited to tasks requiring comprehension of large codebases in a single pass, an area where Claude Code's 200,000 token limit can require chunking or selective context loading.
Codex CLI distinguishes itself through its default sandboxed execution environment: every shell command runs inside an isolated container using kernel-level sandboxing, substantially reducing the risk of unintended system modifications. Gemini CLI and Claude Code both execute commands directly in the user's environment without sandboxing by default. Gemini CLI offers optional sandbox modes, but these are not enabled by default.
On cost, Gemini CLI's free tier provides a significant advantage for individual developers and small teams experimenting with AI-assisted coding. Both Claude Code and Codex CLI require paid subscriptions or API keys from their first use. For professional use at scale, pricing converges toward API-based consumption billing across all three tools.
Open source status is shared by Gemini CLI and Codex CLI under the Apache 2.0 license, while Claude Code remains proprietary. This matters for enterprise teams that require code auditability, customization rights, or the ability to host the tool internally.
Alongside the main CLI tool, Google released the google-gemini/gemini-cli-action GitHub Action, enabling Gemini CLI to be embedded in GitHub repository workflows. The action can be triggered by pull request events, issue creation, scheduled cron jobs, or manual workflow dispatches.
Common workflow patterns include:
Automated PR Review. When a pull request is opened, the action invokes Gemini CLI to analyze the diff, review code quality, flag potential security issues, and post structured feedback as a pull request comment. The review covers code maintainability, performance considerations, and adherence to project conventions encoded in GEMINI.md.
Issue Triage. When new GitHub Issues are created, the action can analyze issue content, apply labels, assign priority levels, and post initial responses based on the project's issue history and documented conventions.
Documentation Generation. Scheduled workflows can invoke Gemini CLI to generate or update documentation based on changes to source code.
Authentication in GitHub Actions can be configured via a Gemini API key stored as a repository secret, Workload Identity Federation for keyless authentication in Google Cloud environments, the default GITHUB_TOKEN for simpler use cases, or a custom GitHub App.
In late 2025, Google released a Jules extension for Gemini CLI that bridges the interactive terminal agent with Jules (Google), Google's autonomous background coding agent. Jules operates asynchronously: it accepts a task description, clones the relevant repository into a virtual machine, implements the required changes, and returns the results without requiring continuous developer attention.
The Jules extension within Gemini CLI allows developers to delegate a task from their terminal session to Jules for asynchronous background execution while continuing to work on other tasks interactively in Gemini CLI. Both tools share the same view of the project, enabling coordination between interactive and autonomous coding workflows. The combination represents a two-tier approach: Gemini CLI for iterative, collaborative tasks requiring real-time feedback, and Jules for well-scoped, parallelizable tasks that can execute independently.
Gemini CLI supports a broad range of developer workflows:
Codebase Understanding. The 1 million token context window allows developers to load entire medium-to-large codebases and ask questions about architecture, dependencies, data flow, or specific module behavior without needing to manually identify and extract relevant files.
Feature Implementation. Developers describe a feature in natural language, and Gemini CLI reads the relevant existing code, generates an implementation, writes tests, and can run the tests to verify correctness before the developer reviews the changes.
Debugging. Error messages, stack traces, or failing tests can be provided to the agent along with relevant source files. The agent reasons about the cause and proposes or directly implements fixes.
Refactoring. Large-scale refactoring tasks, such as migrating to a new framework version, renaming identifiers consistently across a codebase, or restructuring module organization, benefit from the large context window that allows the agent to understand the full scope of required changes.
Research and Documentation. Grounded with Google Search, the agent can answer questions about library APIs, recent framework changes, or industry best practices, incorporating real-time information rather than relying solely on training data.
Multimodal Prototyping. Providing a screenshot of a UI, a PDF wireframe, or an exported Figma design allows Gemini CLI to generate corresponding HTML, CSS, and JavaScript or framework-specific component code.
CI/CD Automation. Through the GitHub Actions integration and non-interactive invocation mode, Gemini CLI can be embedded in build pipelines for automated code review, test generation, or documentation updates.
Google Cloud Workflows. Native integration with Vertex AI, Cloud Functions, BigQuery, and other Google Cloud services makes Gemini CLI particularly productive for teams operating on Google Cloud infrastructure.
The initial reception to Gemini CLI was strongly positive within the developer community. The rapid accumulation of GitHub stars (50,000 in one week) reflected genuine enthusiasm, particularly around three factors: the generous free tier, the open-source licensing, and the 1 million token context window.
TechCrunch's launch coverage noted that the free tier limits were "roughly double the average number of requests developers made when using the tool" during internal testing, suggesting Google had calibrated the tier to accommodate most individual developers without charge. The article also noted broader industry context: a 2024 Stack Overflow survey had found that only 43% of developers trusted the accuracy of AI tools, a headwind that all AI coding assistants faced regardless of vendor.
The speed with which the community began building extensions and MCP integrations was noted as a positive sign of ecosystem health. Google's decision to launch a companion GitHub Action simultaneously with the CLI addressed an immediate request from teams looking to integrate AI assistance into existing CI/CD workflows.
Professional comparisons with Claude Code generally acknowledged that Claude Code scored higher on code quality benchmarks, while Gemini CLI offered advantages in context window size, pricing accessibility, and Google Cloud integration. Developer communities working on large monorepos or constrained by tooling budgets tended to favor Gemini CLI, while teams prioritizing benchmark-measured code quality tended to favor Claude Code.
A Plan Mode feature added in early 2026, in which Gemini CLI restricts itself to reading the codebase and proposing a strategy without writing any files, was welcomed by developers who wanted to review an agent's intended approach before granting write access. This addressed a common concern about agentic tools making unintended changes to codebases.
Security and Sandboxing. The most significant criticism of Gemini CLI at launch was the absence of default sandboxing. Unlike Codex CLI, which isolated all shell command execution in containers by default, Gemini CLI executed shell commands directly in the user's environment. A FOSS Force analysis published shortly after launch summarized the risk: the agent had broad access to the user's home directory, including the ability to create, read, modify, and delete files, with only user-level permission prompts as a safeguard.
Security researchers discovered and disclosed two critical vulnerabilities in Gemini CLI and its associated GitHub Action. The first, a silent data exfiltration vulnerability, combined two flaws to execute shell commands without user permission or knowledge. The second, assigned a CVSS score of 10.0 (the maximum severity), was a remote code execution vulnerability affecting non-interactive (headless) mode: in CI/CD environments, Gemini CLI automatically trusted the current workspace folder and loaded any agent configuration found there without sandboxing or human approval, creating a pathway for attackers to execute arbitrary code by placing malicious configuration files in a repository. Google patched both vulnerabilities after responsible disclosure, and the incidents led to increased attention to headless mode security configurations.
Benchmark Performance. On SWE-bench Verified and comparable multi-file coding benchmarks, Gemini CLI's default configuration scores below both Claude Code and Codex CLI, indicating lower first-pass success rates on complex, multi-step software engineering tasks requiring precise reasoning across interdependent files.
No Default Sandboxing. While sandbox modes are available, they require explicit user configuration and are not enabled by default, placing the burden of security configuration on individual users and potentially exposing less security-aware developers to risk.
Privacy Considerations. Local files processed by Gemini CLI are transmitted to Google's API infrastructure as part of prompts. This has implications for organizations with data residency requirements or those working with sensitive intellectual property, though enterprise Vertex AI configurations offer greater data control.
Windows Support. While Gemini CLI supports Windows more broadly than Codex CLI (which requires WSL2), the experience on Windows was initially less polished than on macOS and Linux, with some features relying on Unix-style path conventions.
Rate Limits on Free Tier. Despite the free tier's generous positioning relative to competitors, the 1,000 requests per day limit can be exhausted by intensive users, particularly in workflows that involve many small, iterative queries during active development sessions.