Gemini CLI: Google's Free AI Agent for Your Terminal

TL;DR

Gemini CLI is Google’s open-source AI agent that brings Gemini’s power directly to your terminal. Key highlights:

Free tier: 60 requests/minute and 1,000 requests/day with a personal Google account
Gemini 3 models: Access to 1M token context window for massive codebase analysis
Built-in tools: Google Search grounding, file operations, shell commands, web fetching
MCP support: Extensible through Model Context Protocol for custom integrations
GitHub Actions: Native integration for automated PR reviews and issue triage
Apache 2.0: Fully open-source and community-driven

Install with: npm install -g @google/gemini-cli or brew install gemini-cli

What is Gemini CLI?

In the rapidly evolving landscape of AI-powered development tools, Google has made a significant move with Gemini CLI - an open-source AI agent designed specifically for developers who prefer working in the terminal. Unlike browser-based AI assistants or IDE plugins, Gemini CLI provides the most direct path from your prompt to Google’s Gemini models.

Gemini CLI isn’t just another chatbot wrapped in a terminal interface. It’s a fully-featured AI agent capable of:

Understanding and navigating large codebases
Executing shell commands and file operations
Searching the web with Google Search grounding
Integrating with external services through MCP servers
Automating GitHub workflows

The tool has gained substantial traction in the developer community, particularly because of its generous free tier and the powerful Gemini 3 models that come with a 1-million token context window - enough to analyze entire projects in a single conversation.

Why Choose Gemini CLI?

Before diving into installation and usage, let’s understand what makes Gemini CLI stand out:

Generous Free Tier

Perhaps the most compelling feature is the free tier. With a personal Google account, you get:

60 requests per minute
1,000 requests per day
Access to Gemini 3 models (mix of Flash and Pro)
1M token context window

For most individual developers, this is more than enough for daily development tasks. No credit card required, no API key management - just sign in with your Google account.

Terminal-First Design

Gemini CLI was designed from the ground up for developers who live in the command line. It integrates naturally with your existing workflow:

# Start in your project directory
cd my-project/
gemini

# Include additional directories for context
gemini --include-directories ../lib,../docs

# Use specific model
gemini -m gemini-2.5-flash

# Non-interactive mode for scripts
gemini -p "Explain the architecture of this codebase"

Built-in Tools

Unlike generic AI chatbots, Gemini CLI comes with powerful built-in tools:

File System Operations: Read, write, and modify files directly
Shell Commands: Execute terminal commands with proper error handling
Web Fetch: Retrieve and analyze web content
Google Search: Ground responses with real-time search results

MCP Extensibility

The Model Context Protocol (MCP) support means you can extend Gemini CLI’s capabilities infinitely. Connect to databases, APIs, custom scripts, or any external system through standardized MCP servers.

Installation

Gemini CLI requires Node.js version 20 or higher and runs on macOS, Linux, or Windows.

Quick Install Options

Using npx (no installation required):

npx @google/gemini-cli

Install globally with npm:

npm install -g @google/gemini-cli

Install with Homebrew (macOS/Linux):

brew install gemini-cli

Install with MacPorts (macOS):

sudo port install gemini-cli

Install with Anaconda (for restricted environments):

# Create and activate a new environment
conda create -y -n gemini_env -c conda-forge nodejs
conda activate gemini_env

# Install Gemini CLI globally via npm
npm install -g @google/gemini-cli

Release Channels

Gemini CLI offers three release channels:

Stable (latest): Weekly releases on Tuesdays, fully validated
Preview (preview): Weekly releases with newer features, less validation
Nightly (nightly): Daily releases from main branch, cutting-edge

# Install specific channel
npm install -g @google/gemini-cli@latest
npm install -g @google/gemini-cli@preview
npm install -g @google/gemini-cli@nightly

Authentication Options

Gemini CLI supports multiple authentication methods to fit different use cases.

The simplest option - just sign in with your Google account:

gemini
# Select "Login with Google" when prompted
# Follow the browser authentication flow

Benefits:

Free tier: 60 requests/min and 1,000 requests/day
No API key management
Automatic model updates

If you have a Gemini Code Assist License from your organization:

export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
gemini

Option 2: Gemini API Key

For developers who need specific model control or paid tier access:

# Get your key from https://aistudio.google.com/apikey
export GEMINI_API_KEY="YOUR_API_KEY"
gemini

Benefits:

Model selection flexibility
Usage-based billing for higher limits

Option 3: Vertex AI (Enterprise)

For enterprise teams and production workloads:

export GOOGLE_API_KEY="YOUR_API_KEY"
export GOOGLE_GENAI_USE_VERTEXAI=true
gemini

Benefits:

Advanced security and compliance
Higher rate limits
Integration with existing Google Cloud infrastructure

Basic Usage and Commands

Starting a Session

# Start in current directory
gemini

# Include multiple directories for context
gemini --include-directories ../lib,../docs

# Use a specific model
gemini -m gemini-2.5-flash

Non-Interactive Mode

Perfect for scripting and automation:

# Get a simple text response
gemini -p "Explain the architecture of this codebase"

# Get structured JSON output
gemini -p "Explain the architecture" --output-format json

# Stream JSON events (for long-running operations)
gemini -p "Run tests and deploy" --output-format stream-json

Slash Commands

Gemini CLI includes built-in slash commands:

/help - Show available commands
/chat - Manage conversations
/mcp - View MCP server status and tools
/bug - Report issues directly

Context Files (GEMINI.md)

Create a GEMINI.md file in your project root to provide persistent context:

# Project: My Awesome App

## Architecture
- Frontend: React with TypeScript
- Backend: Node.js with Express
- Database: PostgreSQL

## Coding Standards
- Use functional components
- Prefer composition over inheritance
- Write tests for all new features

## Important Files
- `src/api/` - API routes
- `src/models/` - Database models
- `src/utils/` - Shared utilities

Gemini CLI automatically reads this file and uses it to understand your project better.

Built-in Tools Deep Dive

File System Operations

Gemini CLI can directly interact with your file system:

> Read the package.json and summarize the dependencies
> Create a new file called utils/helpers.ts with a function to format dates
> Update the README.md with installation instructions

The AI agent understands file operations contextually and can make surgical edits to existing files.

Shell Command Execution

Need to run commands? Gemini CLI handles it:

> Run the test suite and summarize any failures
> Check git status and show me uncommitted changes
> Install the lodash package and update my code to use it

Commands are executed with proper sandboxing and you can configure trusted folders for automatic execution.

Web Fetch and Google Search

Ground your queries with real-time information:

> Search for the latest best practices for React 19
> Fetch the documentation from https://docs.example.com/api
> What's the current price of Bitcoin?

Google Search grounding ensures responses include up-to-date information rather than relying solely on training data.

MCP Server Integration

The Model Context Protocol (MCP) is where Gemini CLI truly shines for power users. MCP servers act as bridges between Gemini and external systems.

What Can MCP Servers Do?

Database Access: Query databases directly from your conversations
API Integration: Interact with Slack, GitHub, Jira, and more
Custom Tools: Build specialized tools for your workflow
Media Generation: Create images with Imagen, videos with Veo

Configuring MCP Servers

Add servers to your ~/.gemini/settings.json:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "$GITHUB_TOKEN"
      }
    },
    "slack": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-slack"],
      "env": {
        "SLACK_TOKEN": "$SLACK_TOKEN"
      }
    }
  }
}

Using MCP Tools

Once configured, use @ syntax to invoke MCP tools:

> @github List my open pull requests
> @slack Send a summary of today's commits to #dev channel
> @database Run a query to find inactive users

Building Custom MCP Servers

With FastMCP, creating custom servers is straightforward:

from fastmcp import FastMCP

mcp = FastMCP("My Custom Server")

@mcp.tool()
def analyze_logs(path: str) -> str:
    """Analyze log files for errors and patterns"""
    # Your custom logic here
    return analysis_result

if __name__ == "__main__":
    mcp.run()

Then add to Gemini CLI:

gemini mcp add my-server uv -- run --with fastmcp fastmcp run server.py

GitHub Actions Integration

Gemini CLI integrates directly into GitHub workflows with the official GitHub Action:

name: AI Code Review
on: [pull_request]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: google-github-actions/run-gemini-cli@v1
        with:
          prompt: "Review this PR for potential issues and suggest improvements"

Use Cases for GitHub Integration

Pull Request Reviews: Automated code review with contextual feedback
Issue Triage: Auto-label and prioritize issues based on content
On-demand Help: Mention @gemini-cli in issues for debugging help
Documentation: Auto-generate or update docs when code changes

Gemini CLI vs Claude Code: How Do They Compare?

The most common comparison is with Anthropic’s Claude Code. Here’s an honest assessment:

Where Gemini CLI Excels

Free Tier: The generous 1,000 daily requests are unmatched
Context Window: 1M tokens means entire codebases fit in context
Google Search: Real-time grounding with search results
MCP Support: Extensive extensibility through standardized protocol
Open Source: Apache 2.0 license, fully community-driven

Where Claude Code Has Advantages

Code Quality: Generally produces more polished, production-ready code
Reasoning: Better at complex multi-step problem solving
Tool Use: More reliable at chaining multiple tool calls
Output Format: More readable formatting in terminal output

The Verdict

For individual developers exploring AI-assisted development or those who need to analyze large codebases, Gemini CLI’s free tier and massive context window make it incredibly attractive. For teams prioritizing code quality and willing to pay, Claude Code often produces better results.

Many developers use both - Gemini CLI for exploration and understanding, Claude Code for implementation.

Practical Use Cases

1. Codebase Onboarding

git clone https://github.com/some/large-repo
cd large-repo
gemini
> Give me a comprehensive overview of this codebase architecture
> What are the main entry points?
> How does the authentication system work?

2. Debugging Sessions

> I'm getting a null reference error in UserService.ts line 45. Here's the stack trace: [paste]
> Check the related files and explain what might cause this
> Suggest a fix and show me the code changes

3. Feature Development

> I need to add pagination to the /api/users endpoint
> Show me how to implement cursor-based pagination
> Write tests for the new pagination logic

4. Documentation Generation

> Generate API documentation for all endpoints in src/routes/
> Create a CONTRIBUTING.md file based on our codebase patterns
> Update the README with current setup instructions

5. Code Reviews

> Review the changes in my current git diff
> Are there any security concerns?
> Suggest improvements for performance and readability

Tips for Getting the Most Out of Gemini CLI

Use GEMINI.md: Always create a project context file for better responses
Include Directories: Use --include-directories to provide full context
Checkpointing: Save complex sessions with /checkpoint to resume later
Trusted Folders: Configure trusted folders for seamless shell execution
Combine with MCP: Set up MCP servers for your most-used integrations
Use Non-Interactive Mode: Script repetitive tasks with -p flag

Conclusion

Gemini CLI represents a significant step forward in democratizing AI-powered development tools. With its generous free tier, massive context window, and extensible architecture, it’s an excellent choice for developers who want to experiment with AI-assisted coding without committing to paid subscriptions.

The MCP integration opens up possibilities beyond simple chat - connecting to databases, APIs, and custom tools transforms Gemini CLI from a chatbot into a true development assistant. The GitHub Actions integration brings this power directly into your CI/CD workflows.

While it may not match Claude Code in raw code quality for every task, the combination of free access, 1M token context, and Google Search grounding makes Gemini CLI a must-try for any developer comfortable in the terminal.

Get started today:

npm install -g @google/gemini-cli
gemini

Then just start chatting with your codebase.

Resources:

TL;DR

What is Gemini CLI?

Why Choose Gemini CLI?

Generous Free Tier

Terminal-First Design

Built-in Tools

MCP Extensibility

Installation

Quick Install Options

Release Channels

Authentication Options

Option 1: Login with Google (Recommended for Individuals)

Option 2: Gemini API Key

Option 3: Vertex AI (Enterprise)

Basic Usage and Commands

Starting a Session

Non-Interactive Mode

Slash Commands

Context Files (GEMINI.md)

Built-in Tools Deep Dive

File System Operations

Shell Command Execution

Web Fetch and Google Search

MCP Server Integration

What Can MCP Servers Do?

Configuring MCP Servers

Using MCP Tools

Building Custom MCP Servers

GitHub Actions Integration

Use Cases for GitHub Integration

Gemini CLI vs Claude Code: How Do They Compare?

Where Gemini CLI Excels

Where Claude Code Has Advantages

The Verdict

Practical Use Cases

1. Codebase Onboarding

2. Debugging Sessions

3. Feature Development

4. Documentation Generation

5. Code Reviews

Tips for Getting the Most Out of Gemini CLI

Conclusion