AI Native Notes

Official References: Headless mode · Authentication

Why headless mode matters

Interactive chat is only half of Gemini CLI. The other half is automation: using the CLI inside shell scripts, CI jobs, and content pipelines. Official docs define headless mode as non-interactive execution that returns structured text or JSON instead of the terminal UI.

How headless mode starts

Headless mode is triggered when:

Gemini CLI runs in a non-TTY environment (like CI/CD), or
you provide a direct prompt with -p / --prompt

Example:

gemini -p "Summarize the architecture of this repository" --output-format json

Using --output-format json (or jsonl) returns a highly parseable object containing response, stats, and error.

The auth choice changes automation quality

The authentication guide explicitly says headless mode should use either:

Gemini API key (via GEMINI_API_KEY env var)
Vertex AI service account

By using these, you automatically unlock Token Caching, which drastically reduces costs for repetitive CI pipelines analyzing the same repository.

Practical automation patterns

1) Content QA in a script

gemini -p "@content Compare gemini-cli articles across ko, en, and es and report missing slugs" --output-format json

2) Pipe the response into another tool

gemini -p "Summarize security risks from @src" --output-format json | jq -r '.response'

3) Machine-readable event stream (`jsonl`)

gemini -p "Review @content/en/gemini-cli" --output-format jsonl

This is useful for gathering tool_use traces and integrating with custom UI wrappers.

4) Real-world Example: GitHub Actions Code Review

A typical workflow where Gemini CLI automatically reviews code on every pull request to ensure standards in GEMINI.md are met.

name: Gemini CLI Code Review
on: [pull_request]
 
jobs:
  gemini-review:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0 # crucial for diffing
 
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
 
      - name: Install Gemini CLI
        run: npm install -g @google/gemini-cli
 
      - name: Run Headless Review
        env:
          GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
        run: |
          gemini -p "Read the recently changed files and verify if they violate rules in GEMINI.md. Output as JSON." --output-format json > review.json
          cat review.json

A good use case in this repo

AI Native Notes already stores knowledge in localized MDX files. Use Gemini interactively to discover a workflow (e.g., frontmatter audits, tone parity), then freeze the useful prompt into a GitHub Actions headless script.

Headless Automation with Gemini CLI