Skip to content
AgentAtlas

Gemini CLI headless mode: gemini -p, JSON output and exit codes for scripts and CI

How do I run Gemini CLI non-interactively in scripts or CI?

Pass your prompt with -p (or --prompt), or run the CLI with piped input in a non-TTY environment. Add --output-format json for one JSON object, or stream-json for newline-delimited events. Check the exit code: 0 is success, 1 is an error, 42 is bad input, 53 is turn limit exceeded.

Compare: headless mode for scripts and CI in every AI coding agent →

Run a single prompt

Shell

gemini -p "Write a poem about TypeScript"

A positional prompt without -p starts interactive mode, unless input or output is piped or redirected.

Pipe input

macOS/Linux

cat error.log | gemini -p "Explain why this failed"
git diff | gemini -p "Write a commit message for these changes"

Windows PowerShell

Get-Content error.log | gemini -p "Explain why this failed"

Get JSON output

--output-format (alias -o) accepts text, json and stream-json. Default is text.

  • json returns one object with response (string), stats (token usage and latency) and an optional error object.
  • stream-json returns JSONL events: init, message, tool_use, tool_result, error and result.

Extract the answer with jq

gemini --output-format json "Return a raw JSON object with keys 'version' and 'deps' from @package.json" | jq -r '.response' > data.json

Handle exit codes

  • 0: success
  • 1: general error or API failure
  • 42: input error (invalid prompt or arguments)
  • 53: turn limit exceeded

Approvals in headless runs

--approval-mode accepts default, auto_edit, yolo and plan. The --yolo flag is deprecated in favor of --approval-mode=yolo. Combine auto approval with the sandbox (-s) when scripts let the agent run tools.

Shell

gemini -s --approval-mode=auto_edit -p "Fix the failing lint errors"

Sources

More Gemini CLI guides

Reviewed Oct 23, 2026. Settings change often; the linked vendor docs are the source of truth.

Built an MCP server? Get it listed everywhere →

Shipping an Android app? Google Play needs 12 testers for 14 days first. Get them with Tester Exchange →