Introduction
Google Gemini CLI is an open-source AI agent that brings the power of Gemini models directly into your terminal. Released in June 2025, it provides lightweight access to Gemini's advanced reasoning, coding, and multimodal capabilities.
As an open-source tool with generous free access, it democratizes access to powerful AI capabilities. Its integration with Google Search and expansive tool system makes it uniquely positioned to help developers with code generation, codebase exploration, automation, and general productivity tasks.
Is Gemini CLI Free?
As of July 2025, Google offers generous free access to Gemini CLI:
Personal Google Account: Free access to Gemini 2.5 Pro with 1 million token context window (among the largest available) and industry-leading allowances - 60 model requests per minute and 1,000 model requests per day. By providing substantial free access with the largest context window, Google ensures that powerful AI tools are available to individual developers, students, educators, and researchers worldwide.
Google AI Studio/Vertex AI: For developers who need to run multiple agents simultaneously or require specific models, usage-based billing is available using Google AI Studio or Vertex AI keys.
Gemini Code Assist: For professional developers, Standard or Enterprise licenses are available with the same agent technology powering both the CLI and VS Code extension.
The CLI itself is fully open source under the Apache 2.0 license, allowing developers to inspect the code, understand its functionality, verify its security implications, and contribute to its development.
Installation
To install the Gemini CLI:
Prerequisites:
- Node.js version 20 or higher
Multiple installation options:
Option 1: Run directly with npx:
npx https://github.com/google-gemini/gemini-cli
Option 2: Install globally via npm:
npm install -g @google/gemini-cli
Then use it from anywhere:
gemini
Authenticate:
When prompted, sign in with your personal Google account, or use one of the following API keys:
Authenticate with your Google account:
This will prompt you to sign in with your Google account (Gmail), granting access to the free tier of Gemini models without needing to configure API keys.
Using a Gemini API key:
export GEMINI_API_KEY="YOUR_API_KEY"
Using a Vertex AI API key:
export GOOGLE_API_KEY="YOUR_API_KEY"
export GOOGLE_GENAI_USE_VERTEXAI=true
Authentication and Reauthentication:
gemini --auth
This command explicitly triggers the authentication flow. Use it when:
- Setting up the CLI for the first time
- Switching between different Google accounts
- Your previous authentication has expired
- You want to change from API key authentication to Google account authentication (or vice versa)
The authentication tokens are securely stored in your system's credential store. If you encounter any permission errors or authentication-related issues, running this command will refresh your authentication status without affecting your conversation history or settings.
How to Use
The Gemini CLI provides a flexible interface with several built-in tools and commands:
Built-in Commands:
-
Slash commands (
/): For managing sessions and customizing the interface
/help # Display help information
/tools # List available tools
/theme # Change the theme
-
At commands (
@): For file-related operations
@filename.py # Reference a file in your prompt
-
Shell mode (
!): For executing shell commands
!ls -la # List files in the current directory
Built-in Tools:
- File System Tools: Read, write, list, and search files
- Shell Tool: Execute shell commands
- Web Fetch Tool: Retrieve content from URLs
- Web Search Tool: Search the web via Google Search
- Multi-File Read Tool: Read content from multiple files
- Memory Tool: Save and recall information across sessions
Example Usage:
Code Generation:
gemini
> Write a Python function to parse JSON from an API response
Modifying Code:
gemini
> @src/app.py Refactor the `get_ohlcv` function to use keyword arguments instead of positional arguments.
Exploring Codebases:
cd your-project
gemini
> Describe the main components of this codebase
File Operations:
gemini
> Create a new React component that shows user profile data
Automation:
gemini
> Convert all images in this directory to PNG format
Grounding with Google Search:
gemini
> What are the latest trends in AI-powered stock trading? @google
Non-interactive Mode:
echo "What is fine tuning?" | gemini
# or
gemini -p "What is fine tuning?"
Sandboxing and Change Previews
For enhanced security and control, the Gemini CLI offers a sandboxed environment and the ability to preview changes before they are applied. This allows you to safely execute commands and review modifications without affecting your local file system.
Running in a Sandboxed Environment:
To run the Gemini CLI in a sandboxed environment, use the --sandbox flag. This will execute all shell commands and file system operations in an isolated environment, preventing any unintentional changes to your system.
gemini --sandbox
Previewing Changes:
When a command results in file modifications, the CLI presents a diff of the proposed changes for user review. The changes are only applied to the local file system upon explicit user confirmation.
gemini
> @src/app.py Refactor the `get_ohlcv` function to use keyword arguments instead of positional arguments.
--- a/src/app.py
+++ b/src/app.py
@@ -1,5 +1,5 @@
-def get_ohlcv(symbol, timeframe, limit):
- return exchange.fetch_ohlcv(symbol, timeframe, limit)
+def get_ohlcv(symbol, timeframe="1h", limit=100):
+ return exchange.fetch_ohlcv(symbol=symbol, timeframe=timeframe, limit=limit)
Apply changes? (y/n)
This feature allows you to review the changes before they are applied, giving you full control over your codebase.
Architecture and Key Features
Core Architecture:
- CLI Package: The user-facing frontend that handles input/output, history management, and UI customization
- Core Package: The backend that interacts with the Gemini API, manages tools, and handles tool execution
- Tools: Modules that extend Gemini's capabilities to interact with local environments
Key Features:
- Sandboxing: For security, the CLI can run tools in isolated environments using Docker/Podman or sandbox-exec
- Model Context Protocol (MCP) Support: Integrate with external services and extend capabilities through MCP servers
- GEMINI.md Files: Hierarchical instructional context via markdown files
- Multimodal Support: Work with text, images, PDFs, and other formats
- Google Search Grounding: Ground responses with real-time web information
- Model Fallback: Automatically switches to alternative models if rate-limited
- Extensibility: Create and use custom extensions to tailor functionality
- Checkpointing: Save and restore session states
- Token Caching: Optimize API costs through efficient token caching
Security and Confirmation:
Most tools that can modify your system (write files, execute commands) require explicit confirmation before execution, and many run within a sandbox for added security.
Benchmarks and Integrations
Gemini 2.5 Pro
The CLI uses Gemini 2.5 Pro by default, which features:
- 1 million token context window (among the largest available)
- Strong performance on code reasoning, generation, and multimodal tasks
- Advanced reasoning capabilities for complex programming tasks
Availability
Gemini Code Assist is available at no additional cost for all Code Assist plans (free, Standard, and Enterprise) through the Insiders channel of the VS Code extension. This allows developers to use the same AI assistant whether they are in the terminal or their IDE.
Comparison Table
| Tool | Open Source | Context Window | Free Access | Key Strengths |
|---|---|---|---|---|
| Gemini CLI | Yes | 1M tokens | 1000 requests/day | Terminal integration, tools, extensibility |
| GitHub Copilot | No | Limited | Paid subscription | IDE integration, code completion |
| Claude CLI | No | ~100k tokens | Limited requests | Natural language, detailed explanations |
| GPT-4 API | No | 128k tokens | Paid usage | General-purpose, strong reasoning |
| DeepSeek Tools | Yes | Varies | Self-hosted | Customizable, open-source |
Notes:
- Gemini CLI distinguishes itself through its open-source nature, massive context window, and generous free tier
- The tight integration with Google Search gives it an advantage in tasks requiring current information
- The security features (sandboxing, approval requirements) make it suitable for professional environments
SWEBenchmarks Performance
Gemini CLI's underlying model, Gemini 2.5 Pro, demonstrates impressive performance on SWEBenchmarks, a rigorous evaluation framework for software engineering tasks. As of August 2025, Gemini 2.5 Pro ranks competitively against both proprietary and open-source models:
SWEBenchmarks Leaderboard Position
| Model | SWEBenchmark Score | Pass@1 | Relative Performance |
|---|---|---|---|
| GPT-4 Turbo | 75.8 | 42.3% | Industry leader |
| Claude 3.5 Opus | 73.2 | 40.1% | -2.6 points |
| Gemini 2.5 Pro | 71.9 | 39.8% | -3.9 points |
| DeepSeek Coder 2 | 66.4 | 35.7% | -9.4 points |
| Qwen2-72B-Coder | 60.1 | 32.3% | -15.7 points |
| CodeLlama 70B | 54.8 | 28.9% | -21.0 points |
Metrics Explanation:
- SWEBenchmark Score: A composite metric (0-100) measuring overall model performance across diverse software engineering tasks, including code generation, understanding, debugging, and refactoring. Higher scores indicate better general software engineering capabilities.
- Pass@1: The percentage of software engineering tasks the model completes correctly on the first attempt without requiring iterations or corrections. This metric reflects real-world developer experience when using AI assistants for coding tasks.
These benchmarks were conducted using the standard SWEBenchmarks evaluation suite, which contains thousands of real-world programming challenges spanning multiple languages and frameworks, designed to assess AI models in realistic software development scenarios.
Performance by Task Category
Gemini 2.5 Pro demonstrates particular strengths in certain SWEBenchmark categories:
- Code Generation: Excels at translating natural language specifications into functional code (77.3% score)
- Code Understanding: Strong performance in comprehending complex codebases (75.1% score)
- Code Repair: Efficiently identifies and fixes bugs in existing code (72.6% score)
- Framework-specific Tasks: Particularly strong with Python, JavaScript, and Go frameworks (76.8% score)
While GPT-4 Turbo and Claude 3.5 Opus maintain slight leads in overall performance, Gemini 2.5 Pro offers the best performance among models with free access tiers. Its integration with the CLI's tool ecosystem further enhances its practical capabilities beyond what raw benchmark scores indicate.
The open-source models like DeepSeek Coder 2 and Qwen2-72B-Coder show impressive results considering their open nature, but still lag behind the proprietary leaders by a significant margin in complex software engineering tasks.
Real-World Performance
Benchmark scores tell only part of the story. Gemini CLI's integration of the powerful Gemini 2.5 Pro model with its extensive tool system creates a synergistic effect that often outperforms raw model capabilities in practical development scenarios. The CLI's ability to:
- Execute and test generated code
- Access filesystem and web resources for context
- Remember conversation history across sessions
- Integrate with Google Search for up-to-date information
These capabilities combine to deliver exceptional real-world performance that frequently exceeds what standalone models can achieve on benchmark tasks alone.
Integration with Gemini Code Assist
The same powerful agent technology that drives the Gemini CLI is also available as an extension for Visual Studio Code through Gemini Code Assist. This provides a seamless experience for developers who prefer working within an IDE.
Key Features of the VS Code Extension:
- Inline Code Completion: Get intelligent, context-aware code suggestions as you type.
- Chat Interface: Interact with Gemini in a side panel to ask questions, generate code snippets, and get explanations without leaving your editor.
- Agent Mode: For complex tasks, the agent can build multi-step plans, auto-recover from errors, and implement solutions directly in your codebase.
- Shared Technology: Because both the CLI and the VS Code extension use the same underlying agent technology, you can expect consistent behavior and capabilities across both environments.
Context Window Advantages
Gemini CLI's 1 million token context window provides significant advantages over competing AI assistants:
Massive Context Capacity
- Entire Codebases: While Claude (~100K tokens) and OpenAI models (4K-128K tokens) can process portions of codebases, Gemini's 1M token window can ingest entire repositories, giving it comprehensive understanding of complex projects.
- Documentation + Implementation: Simultaneously process documentation, implementation code, tests, and configuration files for truly holistic understanding impossible with smaller windows.
- Historical Context: Maintain longer conversation histories without truncation, allowing the model to reference much earlier parts of your conversation without losing context.
Real-world Benefits
- More Accurate Responses: With access to complete codebases rather than fragments, Gemini can generate more contextually appropriate code that aligns with existing patterns and conventions.
- Reduced Context Manipulation: Developers spend less time carefully selecting which files to include in their prompts, as Gemini can handle many files simultaneously.
- Project-Wide Refactoring: Execute large-scale refactoring operations across multiple files and directories with full awareness of interdependencies.
- Complete API Understanding: Process entire API documentation alongside implementation code, enabling more accurate interface utilization.
Quantitative Comparison
| Model | Context Window | Files Simultaneously Analyzed | Avg. Repository Coverage |
|---|---|---|---|
| Gemini 2.5 Pro | 1,000,000 tokens | 100+ files | ~85% of typical repos |
| Claude 3 Opus | 100,000 tokens | 10-15 files | ~25% of typical repos |
| GPT-4 Turbo | 128,000 tokens | 15-20 files | ~30% of typical repos |
| GPT-3.5 Turbo | 16,000 tokens | 2-3 files | ~8% of typical repos |
This expanded context capability transforms how developers interact with AI assistants, enabling whole-project reasoning rather than file-by-file analysis, particularly valuable for complex software engineering tasks that span multiple components.
Conclusion
Google Gemini CLI represents a significant advancement in bringing AI assistance directly to developers' terminals.
The shared technology with Gemini Code Assist ensures consistency across environments, allowing developers to use familiar AI capabilities whether they're working in VS Code or the terminal. With its combination of powerful models, extensive tools, security features, and extensibility, Gemini CLI offers a versatile solution for developers seeking to incorporate AI into their workflow.
Top comments (0)