# Gemini CLI Command Patterns

**Purpose**: Common command templates for Gemini CLI integration
**Version**: v0.16.0+
**Last Updated**: 2025-11-18

## Basic Invocation Patterns

### One-Shot Queries (Headless Mode)

```bash
# Preferred syntax (positional prompt)
gemini -m gemini-3-pro-preview "Explain the observer pattern in software design"

# Alternative (deprecated -p flag, still works)
gemini -m gemini-3-pro-preview -p "Explain the observer pattern in software design"

# With stdin input
echo "function add(a, b) { return a + b; }" | gemini -m gemini-3-pro-preview "Explain this code"
```

### Model Selection

```bash
# Use Gemini 3 Pro (default for complex reasoning)
gemini -m gemini-3-pro-preview "Design a microservices architecture"

# Use Gemini 2.5 Pro (stable, general reasoning)
gemini -m gemini-2.5-pro "Review this API design"

# Use Gemini 2.5 Flash (faster, code-focused)
gemini -m gemini-2.5-flash "Refactor this function for performance"
```

### Version-Based Model Selection

When user requests a specific version, map to the latest model in that family:

```bash
# User says "use Gemini 3" or "use 3" → Latest 3.x Pro
gemini -m gemini-3-pro-preview "Design a distributed caching system"

# User says "use Gemini 2.5" for general tasks → 2.5 Pro
gemini -m gemini-2.5-pro "Explain the CAP theorem with examples"

# User says "use Gemini 2.5" for code editing → 2.5 Flash
gemini -m gemini-2.5-flash "Refactor this module for readability"

# No version specified → Default to latest Pro
gemini -m gemini-3-pro-preview "Research microservices best practices"
```

**Fallback Strategy** (when primary model unavailable):

```bash
# Try Gemini 3 Pro first
gemini -m gemini-3-pro-preview "Complex reasoning task" 2>&1

# If quota exhausted, fallback to 2.5 Pro (general) or 2.5 Flash (code)
if [ $? -ne 0 ]; then
    # For general reasoning
    gemini -m gemini-2.5-pro "Complex reasoning task"

    # OR for code editing
    # gemini -m gemini-2.5-flash "Complex reasoning task"
fi
```

## Output Formatting

### Text Output (Default)

```bash
gemini -m gemini-3-pro-preview "What is dependency injection?"
```

### JSON Output (Programmatic)

```bash
gemini -m gemini-3-pro-preview --output-format json "List top 5 design patterns"
```

### Streaming JSON (Real-time)

```bash
gemini -m gemini-3-pro-preview --output-format stream-json "Explain async/await in JavaScript"
```

## Approval Modes & Security

### Default Mode (Prompt for all actions)

```bash
# Explicit
gemini -m gemini-3-pro-preview --approval-mode default "Refactor this code"

# Implicit (no flag = default)
gemini -m gemini-3-pro-preview "Refactor this code"
```

### Auto-Edit Mode (Auto-approve edit tools only)

```bash
gemini -m gemini-3-pro-preview --approval-mode auto_edit "Fix bugs in this file"
```

### YOLO Mode (Auto-approve all tools)

```bash
# Long form
gemini -m gemini-3-pro-preview --approval-mode yolo "Deploy to production"

# Short form
gemini -m gemini-3-pro-preview -y "Deploy to production"
```

## Sandbox Mode

### Enable Sandbox

```bash
gemini -m gemini-3-pro-preview -s "Run untrusted code analysis"
```

### Disable Sandbox (Default)

```bash
gemini -m gemini-3-pro-preview "Analyze trusted codebase"
```

## Session Management

### List Sessions

```bash
gemini --list-sessions
```

### Resume Sessions

```bash
# Resume most recent session
gemini -r latest

# Resume specific session by index
gemini -r 3

# Resume and add new prompt
gemini -r latest "Continue from where we left off"
```

### Delete Sessions

```bash
gemini --delete-session 5
```

## Extensions & MCP

### List Available Extensions

```bash
gemini -l
# or
gemini --list-extensions
```

### Use Specific Extensions

```bash
gemini -e web_search,code_analysis "Research React best practices"
```

### Use All Extensions (Default)

```bash
gemini "Research React best practices"
```

## Workspace Context

### Include Additional Directories

```bash
gemini --include-directories ./lib,./tests "Analyze the full project"

# Or multiple flags
gemini --include-directories ./lib --include-directories ./tests "Analyze project"
```

## Combined Patterns

### Production-Safe Code Review

```bash
gemini -m gemini-2.5-pro \
  --approval-mode default \
  --output-format json \
  "Review this pull request for security issues"
```

### Fast Code Refactoring

```bash
gemini -m gemini-2.5-flash \
  --approval-mode auto_edit \
  "Refactor these functions for better performance"
```

### Research with Web Search

```bash
gemini -m gemini-3-pro-preview \
  -e web_search \
  --output-format text \
  "What are the latest trends in GraphQL?"
```

### Sandbox Testing

```bash
gemini -m gemini-2.5-pro \
  -s \
  --approval-mode default \
  "Test this suspicious code snippet"
```

## Claude Code Integration Patterns

### Skill Invocation (via Claude)

```bash
# Basic invocation from skill
gemini -m gemini-3-pro-preview "Explain microservices"

# With explicit approval mode
gemini -m gemini-2.5-pro --approval-mode auto_edit "Fix type errors"

# With JSON output for parsing
gemini -m gemini-2.5-flash --output-format json "List API endpoints"
```

### Error Handling Pattern

```bash
# Check CLI availability
if ! command -v gemini &> /dev/null; then
    echo "Error: Gemini CLI not installed"
    exit 1
fi

# Execute with error capture
gemini -m gemini-3-pro-preview "task" 2>&1 || echo "Gemini CLI failed"
```

## Model Selection by Task Type

### Complex Reasoning (General)

```bash
gemini -m gemini-3-pro-preview "Design system architecture"
```

### Code Review & Analysis

```bash
gemini -m gemini-2.5-pro "Review this pull request"
```

### Fast Code Editing

```bash
gemini -m gemini-2.5-flash "Fix syntax errors in this file"
```

## Anti-Patterns (Avoid These)

```bash
# ❌ Using -p flag (deprecated)
gemini -p "prompt"  # Will be removed in future

# ❌ Using -i for headless mode
gemini -i "prompt"  # This starts interactive mode, not one-shot

# ❌ Hardcoding model without fallback
# Always have fallback logic when gemini-3-pro-preview unavailable

# ❌ Using YOLO mode without user confirmation
# Always require explicit user approval for YOLO mode
```

## Best Practices

1. **Prefer Positional Prompts**: Use `gemini "prompt"` instead of `gemini -p "prompt"`
2. **Specify Model Explicitly**: Always use `-m` flag for predictable behavior
3. **Use Appropriate Approval Mode**: Default for untrusted tasks, auto_edit for code editing
4. **Enable Sandbox for Unknown Code**: Use `-s` when analyzing untrusted input
5. **Format Output for Parsing**: Use `--output-format json` when processing results programmatically
6. **Resume Sessions When Needed**: Use `-r latest` for multi-turn conversations
7. **Validate CLI Availability**: Always check `command -v gemini` before invocation

## See Also

- `gemini-help.md` - Full CLI reference
- `session-workflows.md` - Session continuation patterns
- `model-selection.md` - Model selection guidance