gemini-cli-scripting

name: gemini-cli-scripting description: Write scripts that programmatically call Google's Gemini CLI in headless mode. Use when writing automation scripts, building batch processing pipelines, running parallel Gemini API calls, integrating Gemini into shell/Node.js/Python scripts, parsing Gemini CLI JSON output, or answering questions about Gemini CLI models, flags, and configuration.

Gemini CLI Scripting

🚨 CRITICAL: NEVER USE OLDER MODELS 🚨

ONLY use Gemini 3 Pro:

• gemini-3-pro-preview — the ONLY model to use

NEVER use: gemini-2.5-pro, gemini-2.5-flash, gemini-2.5-flash-lite, or any other older model.

This is non-negotiable. Do not downgrade models for "speed" or "cost" reasons.

Quick Reference

Headless Command Syntax

# Basic headless call (ALWAYS specify the model)
gemini -m gemini-3-pro-preview "Your prompt here"

# With JSON output
gemini -m gemini-3-pro-preview --output-format json "prompt"

# Streaming JSON (real-time events)
gemini -m gemini-3-pro-preview --output-format stream-json "prompt"

# Stdin input
echo "code to review" | gemini -m gemini-3-pro-preview "Review this code"
cat file.py | gemini -m gemini-3-pro-preview "Find bugs"

# Auto-approve tool use
gemini -m gemini-3-pro-preview -y "Create a test file"
gemini -m gemini-3-pro-preview --approval-mode yolo "Run the build"

Available Models (USE ONLY 3 Pro)

Remember: Always specify -m gemini-3-pro-preview in ALL calls.

Key Flags

JSON Output Schema

{
  "response": "The AI response text",
  "stats": {
    "models": {
      "gemini-3-pro-preview": {
        "api": { "totalRequests": 1, "totalErrors": 0, "totalLatencyMs": 2500 },
        "tokens": { "prompt": 5000, "candidates": 100, "total": 5100 }
      }
    },
    "tools": { "totalCalls": 0, "totalSuccess": 0 },
    "files": { "totalLinesAdded": 0, "totalLinesRemoved": 0 }
  },
  "error": null
}

Stream JSON Events

When using --output-format stream-json, events are newline-delimited JSON:

1. init - Session start with session_id
2. message - User/assistant messages
3. tool_use - Tool call requests
4. tool_result - Tool execution results
5. error - Non-fatal errors
6. result - Final outcome with stats

Parallel Execution Pattern (Node.js)

Use scripts/gemini-parallel.js for concurrent calls:

const { callGemini, callGeminiParallel } = require('./scripts/gemini-parallel');

// Single call (always specify model)
const result = await callGemini('Your prompt', { model: 'gemini-3-pro-preview' });
console.log(result.response);

// Parallel calls with concurrency control
const results = await callGeminiParallel([
  'Prompt 1',
  'Prompt 2',
  'Prompt 3',
], {
  concurrency: 5,
  model: 'gemini-3-pro-preview',  // ALWAYS use this model
  onProgress: ({ completed, total }) => console.log(`${completed}/${total}`),
});

Shell Script Patterns

# Batch processing
for file in src/*.py; do
  gemini -m gemini-3-pro-preview --output-format json \
    "Review this code" < "$file" > "reviews/$(basename "$file").json"
done

# Extract just the response
gemini -m gemini-3-pro-preview --output-format json "What is 2+2?" | jq -r '.response'

# Generate commit message from diff
git diff --cached | gemini -m gemini-3-pro-preview "Write a concise commit message"

# Code review pipeline
cat src/main.py | gemini -m gemini-3-pro-preview --output-format json \
  "Review for security issues" | jq -r '.response' > review.txt

Authentication

The CLI supports three auth methods (no API key needed for OAuth):

1. Google OAuth (default): 60 req/min, 1000 req/day - just run gemini and login
2. API Key: Set GEMINI_API_KEY env var
3. Vertex AI: Enterprise with GOOGLE_CLOUD_PROJECT

References

• Configuration options: See references/configuration.md for all settings, model aliases, and config file locations
• Headless mode details: See references/headless.md for complete output format reference and advanced patterns