gemini-reference

Gemini CLI Reference

Invoke the Gemini agent for sub-tasks using structured JSON output and explicit session management.

When to Use Gemini

Use Gemini when you need:

• Large context window - Can process extensive codebases in one pass
• General purpose tasks - Good balance of capability across domains
• Fast responses - Flash models for quick analysis
• Cost efficiency - Lower cost per token for large inputs

Capabilities

• Core Tools: ReadFileTool, WriteFile, Edit, GlobTool, GrepTool, ShellTool.
• MCP Servers:
  • context7: Documentation queries.
  • brave-search: Web search (Brave).
• Specialty: General purpose, large context window.

Calling from Another Agent

Use gemini "prompt" to spawn Gemini as a sub-agent:

# Delegate a documentation task
result=$(gemini "Generate API documentation for @src/api/" --output-format json)

# Extract the response and session_id for follow-up
response=$(echo "$result" | jq -r '.response')
session_id=$(echo "$result" | jq -r '.session_id')

Output Formats

Format	Description
text (default)	Plain text output
json	Single JSON object with response, stats, session_id
stream-json	Streaming newline-delimited JSON (JSONL) events

JSON Response Fields:

• response: (string) The model's final answer
• stats: (object) Token usage and API latency metrics
• session_id: (string) Session identifier for resuming
• error: (object, optional) Error details if request failed

Streaming JSON Event Types:

• init: Session metadata (session ID, model)
• message: User and assistant message chunks
• tool_use: Tool call requests with arguments
• tool_result: Output from executed tools
• error: Non-fatal warnings and system errors
• result: Final outcome with aggregated statistics

Handling Blocked Actions

When Gemini needs approval for an action it wasn't configured to auto-approve, the command may pause or complete with an error. For agent delegation:

# Step 1: Initial attempt with conservative permissions
result=$(gemini "Fix the build errors" --output-format json --approval-mode default)

# Step 2: Check for errors
if echo "$result" | jq -e '.error' > /dev/null 2>&1; then
  error_msg=$(echo "$result" | jq -r '.error.message')
  echo "Action blocked: $error_msg"
  session_id=$(echo "$result" | jq -r '.session_id')

  # Step 3: Continue with auto_edit mode for file operations
  echo "Continue fixing build errors" > /tmp/continue.md
  result=$(gemini "Read /tmp/continue.md" \
    --resume "$session_id" \
    --output-format json \
    --approval-mode auto_edit)
fi

# Extract final response
final_response=$(echo "$result" | jq -r '.response')

Session Management for Agent Delegation

Starting a Task

mkdir -p .gemini/sessions
echo "*" > .gemini/.gitignore

# Write the task with full context
cat > .gemini/sessions/task.md << 'EOF'
Review @src/auth/ and identify:
1. Authentication vulnerabilities
2. Missing input validation
3. Improper error handling
EOF

# Spawn Gemini with scoped permissions
result=$(gemini "Read .gemini/sessions/task.md" \
  --output-format json \
  --approval-mode default)

# Capture session info
session_id=$(echo "$result" | jq -r '.session_id')
rm .gemini/sessions/task.md

Resuming a Session

Continue a specific session when you have the session_id:

echo "Implement fixes for the top 3 issues you found" > .gemini/sessions/continue.md

result=$(gemini "Read .gemini/sessions/continue.md" \
  --resume "$session_id" \
  --output-format json \
  --approval-mode auto_edit)

rm .gemini/sessions/continue.md

Resume Options:

Flag	Description
--resume <id>	Resume specific session by ID or UUID
--resume "latest"	Resume most recent session
--resume 5	Resume by index number
--list-sessions	List available sessions

Important: Always use explicit --resume with session ID when calling from another agent.

Permission Handling

By default, Gemini requests confirmation for actions that modify your system. When calling from another agent, use --approval-mode:

--approval-mode

Set the approval mode for tool execution:

Mode	Description
default	Prompt for permission on sensitive actions
auto_edit	Automatically approve file edits only

# Safe for file editing tasks
gemini "Fix lint errors" --approval-mode auto_edit

# For analysis tasks (no modifications)
gemini "Analyze codebase" --approval-mode default

--sandbox

Run in a sandboxed environment for safer execution:

# Sandbox for untrusted code
gemini "Run untrusted code" --sandbox
gemini "Analyze suspicious file" --sandbox --output-format json

--full-auto

Shortcut for automation: sets --approval-mode auto_edit and --sandbox workspace-write.

gemini "Fix lint errors and run tests" --full-auto

Agent Delegation Patterns

Pattern 1: Analysis → Implementation

# Phase 1: Analysis (default approvals)
analyze_result=$(gemini "Explore @src/ to understand the codebase structure" \
  --output-format json --approval-mode default)

session_id=$(echo "$analyze_result" | jq -r '.session_id')

# Phase 2: Implementation (auto_edit for file changes)
impl_result=$(gemini "Implement a logging middleware" \
  --resume "$session_id" --output-format json \
  --approval-mode auto_edit)

Pattern 2: Escalating Permissions

# Start conservative
result=$(gemini "Fix the bug" --output-format json --approval-mode default)

# Check for errors
if echo "$result" | jq -e '.error' > /dev/null 2>&1; then
  session_id=$(echo "$result" | jq -r '.session_id')
  # Re-run with broader permissions
  result=$(gemini "Continue fixing with edit permissions" \
    --resume "$session_id" --output-format json \
    --approval-mode auto_edit)
fi

Pattern 3: Model Selection by Task

# Quick analysis - use flash
gemini "Summarize this file" --model flash --output-format json

# Complex reasoning - use pro
gemini "Design a distributed system architecture" --model pro --output-format json

# Balanced - use auto (default)
gemini "Implement feature X" --model auto --output-format json

Code Review Delegation

To delegate code review to Gemini:

mkdir -p .gemini/sessions
echo "Run 'jj diff -s -r @-' and 'jj diff -r @-' and review the output." > .gemini/sessions/review.md

result=$(gemini "Read .gemini/sessions/review.md" \
  --output-format json \
  --approval-mode default)

rm .gemini/sessions/review.md

Important: Do not use --approval-mode auto_edit during reviews - keep it read-only.

Additional Useful Flags

Flag	Description
--model, -m	Model to use (auto/pro/flash/flash-lite)
--output-format, -o	Output format (text/json/stream-json)
--sandbox, -s	Run in sandbox
--include-directories	Add directories to workspace
--extensions, -e	Enable specific extensions
--allowed-mcp-server-names	Allow specific MCP servers
--debug, -d	Debug mode with verbose logging

Model Selection

Alias	Description
auto	Default. Resolves to preview model if enabled, else pro
pro	Complex reasoning tasks
flash	Fast, balanced for most tasks
flash-lite	Fastest for simple tasks

Piping Input

Feed data into Gemini using Unix pipes:

# Pipe a file
cat error.log | gemini "Explain why this failed"

# Pipe command output
git diff | gemini "Write a commit message for these changes"

# Combined with file references
gemini "Review @package.json and explain the dependencies"

Best Practices for Agent Delegation

Prompting

• Be Specific: Provide clear goals, file paths, and constraints.
• Include Context: Use @path/to/file to reference files explicitly.
• Headless Context: Gemini can't see your context - include everything in the prompt.

Permission Safety

• Start Conservative: Use --approval-mode default initially.
• Escalate as Needed: Check .error field and re-run with auto_edit.
• Sandbox Untrusted Code: Always use --sandbox when running untrusted code.

Session Management

• Always Extract session_id: Capture it from JSON output.
• Check for Errors: Always inspect the .error field in JSON response.
• Session per Task: Use separate sessions for unrelated tasks.

Model Selection

• flash: Quick summaries, simple tasks
• pro: Complex architecture, security reviews
• auto: Let Gemini decide based on prompt

Example: Complete Agent Delegation Workflow

#!/bin/bash

# 1. Create temp directory
mkdir -p tmp/.gemini && echo "*" > tmp/.gitignore

# 2. Write task with full context
cat > tmp/task.md << 'EOF'
Analyze the codebase and provide:
1. Architecture overview
2. Potential security issues
3. Performance bottlenecks

Focus on @src/ and @config/ directories.
EOF

# 3. Spawn Gemini with initial permissions (read-only)
result=$(gemini "Read tmp/task.md" \
  --output-format json \
  --approval-mode default)

# 4. Check for errors
if echo "$result" | jq -e '.error' > /dev/null 2>&1; then
  echo "Error: $(echo "$result" | jq -r '.error.message')"
  exit 1
fi

# 5. Extract results
response=$(echo "$result" | jq -r '.response')
session_id=$(echo "$result" | jq -r '.session_id')
stats=$(echo "$result" | jq -r '.stats')

# 6. Report findings to parent agent
echo "=== Analysis Complete ==="
echo "Session ID: $session_id"
echo "Token usage: $(echo "$stats" | jq -r '.total_tokens // "N/A"')"
echo ""
echo "$response"

# 7. Optional: Continue for implementation
# echo "Now implement the security fixes" > tmp/implement.md
# gemini "Read tmp/implement.md" --resume "$session_id" --approval-mode auto_edit ...

# 8. Clean up
rm -rf tmp

Exit Codes

Code	Meaning
0	Success
1	General error or API failure
42	Input error (invalid prompt or arguments)
53	Turn limit exceeded

Structured Output with Schema

Request JSON output matching a JSON Schema:

# Create schema file
cat > /tmp/schema.json << 'EOF'
{
  "type": "object",
  "properties": {
    "project_name": { "type": "string" },
    "programming_languages": { "type": "array", "items": { "type": "string" } }
  },
  "required": ["project_name", "programming_languages"]
}
EOF

# Run with schema
gemini "Extract project metadata from @package.json" \
  --output-schema /tmp/schema.json \
  -o /tmp/result.json \
  --output-format json