Gemini CLI Skill

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

-p, --prompt

-m, --model

gemini-2.5-flash

gemini-2.5-pro

--output-format

text

json

stream-json

--include-directories

--yolo

--sandbox

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

Option 3: Vertex AI (Enterprise)

export GOOGLE_API_KEY="YOUR_API_KEY"
export GOOGLE_GENAI_USE_VERTEXAI=true
gemini

Working with Files

# 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

• 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

# 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

node {baseDir}/scripts/run-gemini-task.cjs "Your task prompt" [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

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

Model Selection

gemini-2.5-flash

gemini-2.5-pro

Context File (GEMINI.md)

GEMINI.md

# 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

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

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