Gemini CLI is Google’s open-source terminal AI agent. It’s free with a Google account, supports Gemini 2.5 Pro and Flash models, and has the most customizable subagent system of any coding CLI. If you’re looking for a Claude Code or Codex CLI alternative that costs $0, this is it.

Install

npm install -g @google/gemini-cli

# Login with Google account
gemini login

# Start a session in your project
cd your-project
gemini

That’s it. No API key needed for personal use — Gemini CLI uses your Google account with a generous free tier.

Core commands

# Interactive session
gemini

# Single-shot prompt (no interactive session)
gemini -p "Explain this codebase structure"

# Attach files
gemini -f src/auth.ts -p "Review this for security issues"

# Vision (analyze screenshots)
gemini --image screenshot.png -p "What's wrong with this UI?"

# Headless mode (for scripts/CI)
gemini --headless -p "Run tests and report failures"

Slash commands inside a session

Command	What it does
/compact	Summarize and compress context
/clear	Start fresh
/rewind	Go back to a previous message
/agents	List available subagents
/todo	Manage task lists
/usage	Check token usage
/save	Save session
/restore	Restore a saved session

Models

Model	Speed	Quality	Context	Cost
Gemini 2.5 Pro	Medium	Best	1M+	Free (rate limited)
Gemini 2.5 Flash	Fast	Good	1M	Free (generous)
Gemini 3.1 Pro	Medium	Frontier	1M+	Free (limited)

Gemini CLI automatically routes between models based on task complexity. Simple questions get Flash (fast), complex ones get Pro (better quality). You can override:

gemini --model gemini-2.5-pro -p "Design a microservices architecture"
gemini --model gemini-2.5-flash -p "Add comments to this function"

The free tier is genuinely generous — most individual developers won’t hit the limits during normal use.

Subagents

Gemini CLI’s standout feature. Subagents are specialist agents that run in isolated context windows:

# Use built-in subagents
@codebase-investigator How does authentication work in this project?
@browser-agent Check the Stripe API docs for webhook verification

# Create custom subagents as Markdown files
# .gemini/agents/security-reviewer.md

Custom subagents can have restricted tools, custom system prompts, and even different models. See our detailed subagents guide for setup instructions.

Extensions

Extensions add capabilities through MCP servers:

# Install extensions
gemini extensions install @google/web-search
gemini extensions install @playwright/mcp

# List installed
gemini extensions list

# Use in session
gemini> Search for the latest Next.js 15 migration guide

The Extensions Gallery has pre-built integrations for databases, APIs, browsers, and development tools.

Jules integration

Jules is Google’s autonomous coding agent that runs in the cloud. From Gemini CLI, you can delegate tasks to Jules:

/jules "Refactor the payment module to support subscriptions"

Jules works asynchronously in the background — you keep working in Gemini CLI while Jules handles the delegated task. Results come back when ready. This is similar to Claude Code Routines but triggered from the CLI rather than scheduled.

Context management

Gemini CLI assembles context from multiple sources:

1. Project files — automatically reads relevant files based on your query
2. GEMINI.md — project-level instructions (like AGENTS.md for Codex)
3. Settings — persistent user preferences in settings.json
4. MCP servers — external tools and data sources
5. Conversation history — previous messages in the session

<!-- GEMINI.md in your project root -->
# Project Instructions

## Stack
- Python 3.12, FastAPI, SQLAlchemy, PostgreSQL

## Rules
- Always use type hints
- Write tests for new functions
- Use async/await for database operations

For long sessions, use /compact proactively. See our long-running agents guide for context management strategies.

Checkpointing

Gemini CLI automatically saves session snapshots. If your terminal crashes or you close the window, you can restore:

# List saved sessions
gemini sessions list

# Restore a session
gemini sessions restore <session-id>

This is built-in — no manual setup needed. It’s a significant advantage for long coding sessions where losing context means losing hours of work.

Headless mode for automation

Run Gemini CLI in scripts and CI/CD pipelines:

# In a GitHub Action
gemini --headless -p "Review the changes in this PR for security issues" < pr_diff.txt

# In a cron job
gemini --headless -p "Check for outdated dependencies and create a report" > report.md

# Pipe output
echo "Explain this error: $(cat error.log | tail -20)" | gemini --headless

Gemini CLI vs Claude Code vs Codex CLI

Feature	Gemini CLI	Claude Code	Codex CLI
Price	Free	$20/mo or API	API usage
Sandbox	❌	❌	✅ OS-level
Subagents	✅ Custom (Markdown)	✅ Natural language	Via Agents SDK
Extensions	✅ Gallery + MCP	✅ MCP	✅ MCP
Cloud delegation	✅ Jules	✅ Routines	Via Agents SDK
Checkpointing	✅ Automatic	❌ Manual	❌ Manual
Vision	✅ Native	✅ Native	✅ Native
Open source	✅	❌	✅

See our full agent comparison for deeper analysis.

Who should use Gemini CLI

• Budget-conscious developers — it’s free, and the quality is competitive
• Google Cloud users — native integration with GCP services
• Teams wanting customizable agents — subagent system is the most flexible
• Open-source advocates — fully open source on GitHub

For maximum quality, Claude Code is still the leader on coding benchmarks. For maximum security, Codex CLI has the best sandbox. For maximum value, Gemini CLI is unbeatable at $0.

FAQ

Is Gemini CLI free?

Yes, Gemini CLI is completely free for personal use with a Google account. It includes access to Gemini 2.5 Pro and Flash models with a generous free tier. Most individual developers won’t hit the rate limits during normal daily use.

How many requests per day?

Google doesn’t publish exact daily request limits, but the free tier is generous enough for typical individual development workflows. The CLI automatically routes between Pro and Flash models to optimize quota usage, and you’re unlikely to hit limits unless running heavy automated pipelines.

Can I use Gemini CLI for commercial projects?

Yes, you can use Gemini CLI for commercial development work. The free tier covers personal and professional use with a Google account. For teams or high-volume commercial usage, Google offers paid plans with higher rate limits and enterprise features.

How does it compare to Claude Code?

Gemini CLI’s biggest advantage is being free, while Claude Code costs $20/month or API usage fees. Claude Code currently leads on coding benchmarks (SWE-bench) and has Routines for cloud automation, but Gemini CLI offers the most customizable subagent system and automatic session checkpointing that Claude Code lacks.

Related: Gemini CLI Subagents Guide · Claude Code vs Codex CLI vs Gemini CLI · Kimi CLI vs Gemini CLI · How to Use Claude Code · Codex CLI Complete Guide · What is MCP? · Best AI Coding Tools