Headless Mode & Automation

Headless mode transforms Gemini CLI from an interactive tool into a scriptable automation engine. The -p flag passes a prompt non-interactively: Gemini processes it, prints the output, and exits. Combined with --output-format, you can produce machine-readable output that other tools consume. This is the building block for CI/CD integration, batch processing, and automated workflows.

# Basic headless execution
gemini -p "Summarize the changes in the last commit"

# JSON output for scripting
gemini -p "List all TODO comments in the codebase" --output-format json

# Streaming JSON for real-time processing
gemini -p "Review this PR for issues" --output-format stream-json

GitHub Actions integration is where headless mode really shines. You can create workflows that use Gemini CLI to review PRs, generate documentation, validate code quality, or automate release notes. The pattern is: trigger on PR event, run gemini -p with a structured prompt, parse the output, and post results as a PR comment or check.

name: Gemini Code Review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Install Gemini CLI
        run: npm install -g @google/gemini-cli
      - name: Review PR
        env:
          GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
        run: |
          DIFF=$(git diff origin/main...HEAD)
          gemini -p "Review this diff for bugs, security issues, and style problems:\n$DIFF" \
            --output-format json > review.json
      - name: Post Review Comment
        uses: actions/github-script@v7
        with:
          script: |
            const review = require('./review.json');
            // Post as PR comment