Using Gemini CLI

Using Gemini CLI - Headless Guide

Overview

Headless mode runs Gemini CLI non-interactively from scripts and CI. It accepts prompts via flags or stdin and returns text, JSON, or streaming JSON events—ideal for automation, logging, and tool-driven workflows.

When to Use

• Automating prompts in shell scripts or CI/CD
• Needing structured output (JSON or streaming JSON) for downstream tools
• Piping files, git diffs, or logs into Gemini
• Building dashboards that monitor model/tool activity in real time
• Not for interactive chat; use normal Gemini CLI for conversational sessions

Run a Task (minimal steps)

1. Confirm model and output format if unspecified (speed: gemini-2.5-flash; depth: gemini-3-pro-preview; formats: text, json, stream-json).
2. Build the command:
   • Direct prompt: gemini -p "What is machine learning?"
   • From stdin: echo "Explain this code" | gemini
   • File + prompt: cat README.md | gemini -p "Summarize this documentation" --output-format json
   • Add repo context: gemini -p "Review repository risks" --include-directories src,docs
3. Optional safety/verbosity:
   • -m, --model <model> (e.g., gemini-2.5-flash, gemini-3-pro-preview)
   • --output-format json|stream-json
   • --yolo or --approval-mode auto_edit to auto-approve actions (use cautiously)
   • --debug for verbose logging
4. Capture output:
   • Text: ... > result.txt
   • JSON: ... --output-format json | jq '.response'
   • Streaming: ... --output-format stream-json > events.jsonl

Quick Reference

Output Formats

• text (default): human-readable response.
• json: structured object { response, stats, error? } including per-model token usage, tool stats, and file line deltas—ideal for automation pipelines.
• stream-json: newline-delimited events (init, message, tool_use, tool_result, error, result) emitted immediately for progress UIs and event-driven scripts.

Example stream pipeline:

gemini --output-format stream-json --prompt "List files" | jq -r '.type'

Common Options

• -p, --prompt: set prompt (headless trigger)
• --output-format text|json|stream-json
• -m, --model <model>: choose Gemini model
• --include-directories dir1,dir2: add repo folders to context
• --debug: verbose logging
• --yolo: auto-approve actions
• --approval-mode <mode>: control approvals (e.g., auto_edit)

Workflow Patterns

• Code review: git diff | gemini -p "Review for bugs and security issues" --output-format json
• Commit message: git diff --cached | gemini -p "Write a concise commit message" --output-format json | jq -r '.response'
• Log triage: grep "ERROR" app.log | tail -50 | gemini -p "Find root cause and fixes" > error-analysis.txt
• Release notes: git log --oneline v1.0.0..HEAD | gemini -p "Generate release notes" --output-format json | jq -r '.response' >> CHANGELOG.md
• Usage tracking:

result=$(gemini -p "Explain this database schema" --include-directories db --output-format json)
total_tokens=$(echo "$result" | jq -r '.stats.models // {} | to_entries | map(.value.tokens.total) | add // 0')
models_used=$(echo "$result" | jq -r '.stats.models // {} | keys | join(", ") | if . == "" then "none" else . end')
tool_calls=$(echo "$result" | jq -r '.stats.tools.totalCalls // 0')
echo "$(date): $total_tokens tokens, $tool_calls tool calls (models: $models_used)" >> usage.log
echo "$result" | jq -r '.response' > schema-docs.md

Common Mistakes

• Forgetting --output-format json when piping to jq, causing parse errors.
• Assuming pro-level depth without setting --model; default may be gemini-2.5-flash.
• Sending both a prompt and unrelated stdin, which muddies context.
• Using --yolo in production scripts without safeguards—can auto-accept tool actions.
• Ignoring non-zero exit codes in CI; always fail the job on errors.

Resources

• Headless mode docs: https://geminicli.com/docs/cli/headless/
• Configuration guide: https://geminicli.com/docs/get-started/configuration
• Authentication: https://geminicli.com/docs/get-started/authentication

Code Review Workflow

0. IMPORTANT/DO NOT SKIP: Always run the command code-review.sh --help and read the help message before using the script.
1. Ask user for model preference (gemini-2.5-flash for speed, gemini-3-pro-preview for depth; default is gemini-3-pro-preview)
2. Run the code-review script (located at scripts/code-review.sh in the skill directory): code-review.sh [--model MODEL] [--output-format json] "<request>" [files...]
3. The script automatically:
   • Includes BOTH staged and unstaged git changes in the review
   • Uses a structured prompt from ~/.gemini/prompts/code-review.md (or $GEMINI_PROMPTS_DIR/prompts/code-review.md)
   • Pipes all context to Gemini CLI via stdin with --prompt flag
   • Uses --output-format json if specified for structured parsing
4. After completion, inform user of the review results and any issues found
5. For follow-up questions, run a new Gemini command with the same context or ask specific questions

Note: The script reviews ALL changes (both staged and unstaged). Users can stage specific files first if they want to review only certain changes.

Following Up

• After every gemini command, immediately use AskUserQuestion to confirm next steps or collect clarifications.
• For follow-up analysis, run a new gemini command with additional context or specific questions.
• Restate the chosen model and output format when proposing follow-up actions.

Error Handling

• Stop and report failures whenever gemini --version or a gemini command exits non-zero; request direction before retrying.
• Before you use high-impact flags (--yolo, --approval-mode auto_edit) ask the user for permission using AskUserQuestion unless it was already given.
• When output includes warnings or partial results, summarize them and ask how to adjust using AskUserQuestion.
• Always check for non-zero exit codes in CI/CD pipelines and fail the job on errors.

Additional References

• Gemini CLI Headless Mode Documentation - Complete guide to non-interactive execution
• Gemini CLI Configuration Guide - Configuration options, settings files, and environment variables
• Gemini CLI Authentication - Setup authentication for Gemini CLI