First Steps with Gemini CLI: A Complete Tutorial

What Is Gemini CLI?

Google's Gemini CLI brings Gemini's powerful multimodal AI capabilities directly to your terminal. Unlike cloud-only interfaces, Gemini CLI runs locally, giving you fast, offline-capable AI assistance for coding, file analysis, and automation tasks.

It's Google's answer to Claude Code — a terminal-native AI agent that understands your project context and can read, write, and execute code.

Installation

macOS / Linux

# Install via npm
npm install -g @google/gemini-cli
# Or via Homebrew
brew install google-gemini-cli

Windows

# Using npm
npm install -g @google/gemini-cli
# Or using winget
winget install Google.GeminiCLI

Verify Installation

gemini --version
# Expected output: gemini-cli/1.x.x

Getting Your API Key

Gemini CLI requires a Google AI API key:

1. Visit Google AI Studio 2. Click "Create API Key" 3. Copy the key

# Set your API key
export GEMINI_API_KEY="your-key-here"
# Add to shell profile for persistence
echo 'export GEMINI_API_KEY="your-key-here"' >> ~/.zshrc

Your First Commands

Interactive Mode

# Start an interactive session
gemini
# You'll see a prompt like this:
Gemini CLI v1.2.0
Type 'help' for commands, 'exit' to quit
> 

Try asking questions about your project:

> What does this project's package.json tell you about the tech stack?

Gemini will read your files and analyze them.

One-Shot Mode

# Ask a question directly
gemini "Summarize the main function of this project"
# Execute a specific task
gemini "Find all TODO comments in the codebase and categorize them"

File Analysis

Gemini CLI excels at analyzing files because of its multimodal capabilities:

# Analyze code files
gemini "Explain the authentication flow in src/auth/"
# Analyze images (yes, it can see images!)
gemini -f screenshot.png "What's wrong with this UI?"
# Analyze PDFs
gemini -f documentation.pdf "Extract the API endpoints from this doc"

Practical Coding Workflows

Workflow 1: Code Generation

gemini "Create a Python script that:
- Reads a CSV file containing sales data
- Aggregates sales by month
- Generates a bar chart using matplotlib
- Saves the chart as sales-by-month.png"

Gemini will generate the complete script, ready to run.

Workflow 2: Code Review

# Review recent changes
git diff HEAD~1 | gemini "Review these code changes. 
Check for bugs, security issues, and style problems."
# Review a specific file
gemini "Review src/utils/validation.ts for:
1. Type safety issues
2. Missing edge cases
3. Performance bottlenecks
4. Suggest improvements"

Workflow 3: Debugging

gemini "The test suite is failing. Here's the error:
FAIL src/__tests__/api.test.ts
Expected: 200
Received: 401
Find the cause and suggest a fix. Check the auth middleware 
and the test setup."

Workflow 4: Documentation

# Generate API docs
gemini "Generate OpenAPI 3.0 documentation for the API routes 
in src/app/api/. Include request/response schemas."
# Add inline documentation
gemini "Add JSDoc comments to all exported functions in src/lib/"

Gemini CLI vs Claude Code

| Feature | Gemini CLI | Claude Code | |---------|------------|-------------| | Model | Gemini 2.5 Pro | Claude Sonnet 4 / Opus | | Multimodal | ✅ Native (images, audio, video) | ❌ Text only | | Context Window | 1M+ tokens | ~200K tokens | | Pricing | Free tier + pay-as-you-go | Pay-as-you-go | | Offline Mode | Limited caching | No | | Code Execution | Yes | Yes | | MCP Support | Yes | Yes | | Price per token | ~$0.10/1M input tokens | ~$3/1M input tokens |

Key Differentiator: Gemini CLI's multimodal capabilities are unique — it can analyze screenshots, diagrams, and PDFs directly.

Advanced Features

MCP Server Integration

Like Claude Code, Gemini CLI supports MCP (Model Context Protocol) servers:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@google/mcp-filesystem"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@google/mcp-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_xxxx"
      }
    }
  }
}

Configure these in ~/.gemini/config.json.

Streaming Output

# Get real-time streaming responses
gemini --stream "Write a Python web scraper"
# Useful for long generation tasks
# You see output as it's being generated

Cost Control

# Set usage limits
gemini config set monthlyLimit 1000000000  # 1M tokens/month
# Check current usage
gemini usage
# View costs
gemini costs --period month

Real-World Example: Building a Dashboard

Let's use Gemini CLI to build a real-time monitoring dashboard:

# Step 1: Scaffold the project
gemini "Create a React dashboard app that shows real-time 
server metrics. Use Vite, TypeScript, and Recharts."
# Step 2: Add data simulation
gemini "Add mock data generation that simulates:
- CPU usage (0-100%)
- Memory usage (0-100%)
- Request rate (0-1000 req/s)
Update every 2 seconds"
# Step 3: Create visualizations
gemini "Add three Recharts components:
1. A line chart for CPU over time (last 60 seconds)
2. A gauge for current memory usage
3. A bar chart for request rate by endpoint"

Each step builds on the previous one, and Gemini maintains context throughout.

Troubleshooting

API Key Issues

# Check if API key is set
echo $GEMINI_API_KEY
# If empty, set it
export GEMINI_API_KEY="your-key"

Rate Limiting

# Free tier has rate limits
# Check your usage in Google AI Studio
# Consider upgrading to paid tier for heavy use

Model Not Available

# List available models
gemini models list
# Switch to a different model
gemini config set model gemini-2.5-flash

Should You Switch?

Use Gemini CLI if: - You need multimodal AI (image, audio, PDF analysis) - You want a much cheaper AI coding tool - You work with Google Cloud services - 1M+ token context is important for your use case - You want a free tier to start

Stick with Claude Code if: - You prioritize code quality over cost - You need the best coding-specific AI - You're already invested in the Claude ecosystem - MCP server ecosystem is important to you

Best of both: Use Gemini CLI for analysis and Claude Code for heavy coding — they complement each other well.

---

New to AI coding tools? Start with our Claude Code installation guide and then try Gemini CLI as a lighter alternative.