Gemini CLI

Leverage Gemini's 1M+ context window as your AI pair programmer within Claude Code workflows.

This skill teaches Claude Code how to use the official Google Gemini CLI (

gemini

command) to get second opinions, architectural advice, debugging help, and comprehensive code reviews. Based on production testing with the official CLI tool.

---

Table of Contents

1. Quick Start
2. When to Use Gemini Consultation
3. Installation
4. Model Selection: Flash vs Pro
5. Top 3 Use Cases
6. Integration Example
7. Top 3 Errors & Solutions
8. When to Load References
9. Production Rules

---

Quick Start

Prerequisites:

• Gemini CLI installed (

  bun add -g @google/gemini-cli

  )
• Authenticated with Google account (run

  gemini

  once to authenticate)

Core Command Patterns:

# Quick question (non-interactive with -p flag)
gemini -p "Should I use D1 or KV for session storage?"

# Code review with file context
cat src/auth.ts | gemini -p "Review this authentication code for security vulnerabilities"

# Architecture advice using Pro model
gemini -m gemini-2.5-pro -p "Best way to handle WebSockets in Cloudflare Workers?"

# With all files in directory
gemini --all-files -p "Review this auth implementation for security issues"

# Interactive mode for follow-up questions
gemini -i "Help me debug this authentication error"

Critical: Always use

-p

flag for non-interactive commands in automation/scripts.

---

When to Use Gemini Consultation

ALWAYS Consult (Critical Scenarios)

Claude Code should automatically invoke Gemini in these situations:

1. Major Architectural Decisions

   • Example: "Should I use D1 or KV for session storage?"
   • Example: "Durable Objects vs Workflows for long-running tasks?"
   • Pattern:

     gemini -m gemini-2.5-pro -p "[architectural question]"

2. Security-Sensitive Code Changes

   • Authentication systems, payment processing, PII handling
   • API key/secret management
   • Pattern:

     cat [security-file] | gemini -m gemini-2.5-pro -p "Security audit this code"

3. Stuck Debugging (2+ Failed Attempts)

   • Error persists after 2 debugging attempts
   • Stack trace unclear or intermittent bugs
   • Pattern:

     gemini -p "Help debug: [error message]" < error.log

4. Large Refactors (5+ Files)

   • Core architecture changes, database schema migrations
   • Pattern:

     gemini --all-files -m gemini-2.5-pro -p "Review this refactoring plan"

5. Context Window Pressure (70%+ Full)

   • Approaching token limit, need to offload analysis
   • Pattern:

     cat large-file.ts | gemini -p "Analyze this code structure"

OPTIONALLY Consult

6. Unfamiliar Technology - Using library/framework for first time
7. Code Reviews - Before committing major changes

---

Installation

1. Install Gemini CLI

bun add -g @google/gemini-cli

2. Authenticate

gemini

Follow the authentication prompts to link your Google account.

3. Verify Installation

gemini --version  # Should show 0.13.0+
gemini -p "What is 2+2?"  # Test connection

---

Model Selection: Flash vs Pro

gemini-2.5-flash (Default)

• Speed: ~5-25 seconds
• Quality: Good for most tasks
• Use For: Code reviews, debugging, quick questions
• Cost: Lower

gemini -m gemini-2.5-flash -p "Review this function for performance issues"

gemini-2.5-pro

• Speed: ~15-30 seconds
• Quality: Excellent, thorough analysis
• Use For: Architecture decisions, security audits, major refactors
• Cost: Higher

gemini -m gemini-2.5-pro -p "Security audit this authentication system"

Quick Decision Guide

Quick question? → Flash
Security/architecture? → Pro
Debugging? → Flash (try Pro if stuck)
Refactoring 5+ files? → Pro

CRITICAL FINDING: Flash and Pro can give opposite recommendations on the same question (both valid, different priorities). Flash prioritizes performance, Pro prioritizes consistency/correctness. For details, load

references/models-guide.md

.

---

Top 3 Use Cases

1. Security Audit

# Audit authentication code
cat src/middleware/auth.ts | gemini -m gemini-2.5-pro -p "
Security audit this authentication middleware. Check for:
1. Token validation vulnerabilities
2. Timing attack risks
3. Error handling leaks
4. CSRF protection
5. Rate limiting
"

2. Architecture Decision

# Compare technologies with context
gemini -m gemini-2.5-pro -p "
Context: Building Cloudflare Worker with user authentication.

Question: Should I use D1 or KV for storing session data?

Considerations:
1. Session reads on every request
2. TTL-based expiration
3. Cost under 10M requests/month
4. Deployment complexity
"

3. Debugging Root Cause

# Analyze error logs with context
tail -100 error.log | gemini -p "
These errors started after deploying auth changes. What's the likely root cause?

Context:
- Added JWT validation middleware
- Using @cloudflare/workers-jwt
- Errors only on /api/* routes
"

For more use cases: Load

references/models-guide.md

for performance optimization, refactoring plans, and code reviews.

---

Integration Example

Claude Consulting Gemini Automatically

Scenario: User asks architectural question

User: "Should I use D1 or KV for storing user sessions?"

Claude (internal): This is an architectural decision. Consult Gemini for second opinion.

[Runs: gemini -m gemini-2.5-pro -p "Compare D1 vs KV for user session storage in Cloudflare Workers. Consider: read/write patterns, cost, performance, complexity."]

Claude (to user): "I've consulted Gemini for a second opinion. Here's what we both think:

My perspective: [Claude's analysis]
Gemini's perspective: [Gemini's analysis]

Key differences: [synthesis]
Recommendation: [combined recommendation]"

Key Pattern: Synthesize both perspectives, don't just forward Gemini's response.

---

Top 3 Errors & Solutions

Error 1: Not Authenticated

Error:

Error: Not authenticated

Solution:

gemini  # Follow authentication prompts

Error 2: Model Not Found

Error:

Error: Model not found: gemini-2.5-flash-lite

Cause: Model deprecated or renamed (flash-lite doesn't exist)

Solution: Use stable models only:

gemini -m gemini-2.5-flash -p "Your question"
gemini -m gemini-2.5-pro -p "Your question"

Error 3: Command Hangs

Cause: Interactive mode when expecting non-interactive

Solution: Always use

-p

flag for non-interactive commands

# ✅ Correct
gemini -p "Question"

# ❌ Wrong (will hang waiting for input)
gemini "Question"

For more troubleshooting: Load

references/models-guide.md

for rate limits, large file context issues, and performance tips.

---

When to Load References

Load reference files in these scenarios:

Load

references/models-guide.md

when:

• User asks about Flash vs Pro differences
• Models give conflicting recommendations
• Need detailed performance comparison
• Choosing model for specific task type
• Want to understand why models disagree

Load

references/prompting-strategies.md

when:

• Crafting complex prompts to Gemini
• Need AI-to-AI prompting format template
• Want to improve prompt quality
• Comparing old vs new prompting approaches

Load

references/gemini-experiments.md

when:

• Need historical context on testing
• Investigating edge cases
• Understanding design decisions
• Troubleshooting unusual behavior

Note:

helper-functions.md

is obsolete (references old gemini-coach wrapper, not the official

gemini

CLI).

---

Production Rules

1. Always Use

-p

for Automation

# ✅ Good for scripts
gemini -p "Question"

# ❌ Bad (interactive)
gemini

2. Select Model Based on Criticality

# Architecture/security → Pro
gemini -m gemini-2.5-pro -p "[critical question]"

# Debugging/review → Flash
gemini -m gemini-2.5-flash -p "[general question]"

3. Provide Context in Prompts

# ✅ Good: Context + Question + Considerations
gemini -p "Context: Building Cloudflare Worker. Question: Best auth pattern? Considerations: 1) Stateless, 2) JWT, 3) <100ms overhead"

# ❌ Bad: Vague
gemini -p "Best auth?"

4. Pipe File Content for Reviews

# ✅ Efficient
cat src/auth.ts | gemini -p "Review for security"

# ❌ Less efficient
gemini -p "Review src/auth.ts"

5. Synthesize, Don't Just Forward

❌ BAD: Just paste Gemini's response

Claude: [runs gemini] "Gemini says: [paste]"

✅ GOOD: Synthesize both perspectives

Claude: "I've consulted Gemini for a second opinion:

My analysis: [Claude's perspective]
Gemini's analysis: [Gemini's perspective]
Key differences: [synthesis]
Recommendation: [unified answer]"

6. Handle Errors Gracefully

if output=$(gemini -p "Question" 2>&1); then
  echo "Gemini says: $output"
else
  echo "Gemini consultation failed, proceeding with Claude's recommendation"
fi

---

Version History

2.1.0 (2025-12-15):

• Optimized to <500 lines (Phase 12.5 → 13 condensation)
• Extracted detailed content to references/
• Added "When to Load References" section
• Condensed to top 3 errors, top 3 use cases

2.0.0 (2025-11-13):

• Complete rewrite for official Gemini CLI (removed gemini-coach wrapper)
• Direct CLI integration patterns
• Updated command examples for

  gemini

  CLI v0.13.0+

1.0.0 (2025-11-08):

• Initial release with gemini-coach wrapper

---

Related Skills

• google-gemini-api - Gemini API integration via SDK
• google-gemini-embeddings - Gemini embeddings for RAG
• google-gemini-file-search - Managed RAG with Gemini

---

License

MIT - See LICENSE

---

Support

• Issues: https://github.com/jezweb/claude-skills/issues
• Email: jeremy@jezweb.net
• Official Gemini CLI: https://github.com/google-gemini/gemini-cli