Gemini CLI Skill

Run Google's Gemini CLI to leverage Gemini 3 models directly from the terminal.

When to Use

• Code understanding and generation
• Multi-file analysis and refactoring
• Debugging with natural language
• Research with Google Search grounding
• Automation and scripting tasks
• Tasks benefiting from 1M token context window

Quick Start

Interactive mode

gemini

One-shot query (non-interactive)

gemini -p "Your prompt here"

With specific model

gemini -p "Complex task" -m gemini-2.5-pro
gemini -p "Quick task" -m gemini-2.5-flash

JSON output (for parsing)

gemini -p "Your prompt" --output-format json

Stream JSON (real-time events)

gemini -p "Run tests and deploy" --output-format stream-json

Installation

# npm (recommended)
npm install -g @google/gemini-cli

# Homebrew (macOS/Linux)
brew install gemini-cli

# Run without installing
npx @google/gemini-cli

Key Options

Option	Description
-p, --prompt	Non-interactive mode, print response and exit
-m, --model	Model: gemini-2.5-flash, gemini-2.5-pro
--output-format	text (default), json, stream-json
--include-directories	Include additional directories
--yolo	Auto-approve tool calls (use with caution)
--sandbox	Run in sandbox mode (safer)

Authentication

Option 1: Google OAuth (Recommended)

gemini
# Follow browser auth flow on first run

• Free tier: 60 req/min, 1,000 req/day
• No API key needed

Option 2: Gemini API Key

export GEMINI_API_KEY="YOUR_API_KEY"
gemini

Get key from: https://aistudio.google.com/apikey

Option 3: Vertex AI (Enterprise)

export GOOGLE_API_KEY="YOUR_API_KEY"
export GOOGLE_GENAI_USE_VERTEXAI=true
gemini

Working with Files

Gemini CLI can read and work with files in the current directory:

# Analyze codebase
cd /path/to/project && gemini -p "Explain this codebase architecture"

# Include multiple directories
gemini --include-directories ../lib,../docs -p "Review the API"

# Pipe file content
cat myfile.py | gemini -p "Review this code"

Built-in Tools

Gemini CLI has built-in capabilities:

• Google Search: Ground responses with real-time web data
• File Operations: Read, write, edit files
• Shell Commands: Execute terminal commands
• Web Fetching: Retrieve content from URLs

For Sub-Agent Delegation

When spawning Gemini CLI for background work:

# Run with timeout
timeout 300 gemini -p "Complete this task..." 2>&1

# Capture structured output
gemini -p "Generate a report" --output-format json > result.json

# Auto-approve for automation (careful!)
gemini -p "Run the build" --yolo

Script: Run Gemini Task

Use the bundled script for reliable sub-agent execution:

node {baseDir}/scripts/run-gemini-task.cjs "Your task prompt" [options]

Options:

• --model <model> — Model to use (default: gemini-2.5-flash)
• --timeout <secs> — Timeout in seconds (default: 300)
• --json — Output in JSON format
• --workdir <path> — Working directory

The script handles:

• Timeout protection
• Error capture and formatting
• Clean output for parsing
• Exit code propagation

Model Selection

Model	Best For
gemini-2.5-flash	Fast, cost-effective, everyday tasks
gemini-2.5-pro	Complex reasoning, large context, nuanced tasks

Context File (GEMINI.md)

Create a GEMINI.md file in your project root to customize behavior:

# Project: My App

## Guidelines
- Use TypeScript for all new code
- Follow existing patterns in src/
- Run tests before committing

## Architecture
- Frontend: React + Vite
- Backend: Node.js + Express

Gemini will automatically read this for project context.

Tips

1. Use -p for scripts — Non-interactive mode for automation
2. Set timeouts for long-running tasks
3. Use --output-format json when parsing results programmatically
4. Working directory matters — Gemini sees files relative to cwd
5. Use --yolo carefully — Auto-approves all tool calls
6. Google Search grounding — Great for real-time info queries

Rate Limits (Free Tier)

• 60 requests per minute
• 1,000 requests per day
• 1M token context window

Comparison with Claude CLI

Feature	Gemini CLI	Claude CLI
Free tier	✅ 1000/day	✅ Limited
Context window	1M tokens	200K tokens
Google Search	✅ Built-in	❌
Shell execution	✅ Built-in	✅ Built-in
MCP support	✅	✅
Auth	Google OAuth	Anthropic OAuth

Troubleshooting

Authentication Issues

# Clear cached auth
rm -rf ~/.gemini-cli

# Re-authenticate
gemini

Command Not Found

# Check installation
which gemini

# Reinstall
npm install -g @google/gemini-cli