Gemini CLI Skill
⚠️ Environment Notice
| Environment | Command Format |
|---|---|
| Interactive terminal | gemini (enters interactive mode) |
| Claude Code / CI | gemini -p "prompt" (headless mode) |
| Scripting with JSON | gemini -p "prompt" --output-format json |
| Stdin input | echo "prompt" | gemini or cat file | gemini -p "analyze" |
Non-TTY environments (Claude Code, CI pipelines) require -p flag or stdin input.
Quick Start
Headless Mode (Claude Code/CI)
# Basic review
gemini -p "Review this code for bugs"
# With JSON output for parsing
gemini -p "Analyze this code" --output-format json
# With specific model and directories
gemini -m gemini-3-flash-preview --include-directories ./src,./lib -p "Code analysis"
# Stdin input with prompt
cat src/auth.py | gemini -p "Review for security issues"
JSON Output Parsing
result=$(gemini -p "Query" --output-format json)
response=$(echo "$result" | jq -r '.response')
Reference Documentation
- Commands Reference - Slash commands, @ commands, shell mode
- Options Reference - Models, output formats, directories, JSON schema
- Examples - Code review, CI/CD integration, automation scripts
Available Models
| Model | Description | Best For |
|---|---|---|
gemini-3-flash-preview | Fast and efficient (DEFAULT) | Standard reviews, batch operations, general use |
gemini-3-pro-preview | Flagship model | Complex architecture analysis, security audits only |
Output Formats
| Format | Description | Use Case |
|---|---|---|
| (default) | Human-readable text | Terminal output |
json | Structured with stats | Script parsing, automation |
stream-json | JSONL events | Real-time monitoring |
JSON Response Structure
Full schema: See Options Reference
Key fields: response (string), stats (object), error (optional object)
Key Options
| Option | Alias | Description |
|---|---|---|
--prompt | -p | Run in headless mode with prompt |
--model | -m | Model selection |
--output-format | Output format (json, stream-json) | |
--include-directories | Additional context directories (comma-separated) | |
--yolo | -y | Auto-approve all actions |
--sandbox | -s | Sandbox mode (restrictive) |
--approval-mode | Set approval mode (auto_edit) |
Common Patterns
Full examples: See Examples for detailed patterns
Essential Patterns
# Code review with output
cat src/auth.py | gemini -p "Review for security issues" > review.txt
# JSON output with jq parsing
result=$(gemini -p "Query" --output-format json)
echo "$result" | jq -r '.response'
# Cross-directory analysis
gemini --include-directories ./backend,./frontend -p "Review API integration"
Timeout Configuration
| Task Type | Recommended Timeout | Claude Code Tool |
|---|---|---|
| Quick checks | 2 minutes | timeout: 120000 |
| Standard review | 5 minutes | timeout: 300000 |
| Deep analysis | 10 minutes | timeout: 600000 |
Recommendation: Use timeout: 600000 for complex analysis with gemini-3-pro-preview.
Error Handling
Detailed error handling patterns: See Examples
| Error | Cause | Solution |
|---|---|---|
| No output | Missing -p flag | Use gemini -p "prompt" |
| Empty response | No stdin/prompt | Provide via -p or stdin |
Exit code 1 | General error | Check JSON .error field |
| Context too large | Too many files | Use specific paths |
| Permission denied | Sandbox restrictions | Use --yolo carefully |
Best Practices
- Use
-pflag in Claude Code and CI environments - Use
--output-format jsonfor script parsing - Parse with
jqfor reliable extraction - Check
.errorin JSON response for error handling - Use
--include-directoriesfor multi-directory context - Match model to task:
gemini-3-flash-previewfor most tasks,gemini-3-pro-previewonly for complex architecture/security - Set 10-minute timeout for deep analysis (
timeout: 600000)