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
- Gemini CLI: YOLO mode, auto_edit and allowing specific shell commands
- Gemini CLI: turn off usage statistics and telemetry
- Configure Gemini CLI with settings.json
- Gemini CLI extensions and custom commands
- GEMINI.md in Gemini CLI: context file locations, imports and /memory
- Gemini CLI MCP servers: gemini mcp add and mcpServers in settings.json
- Gemini CLI custom slash commands: TOML files, {{args}}, !{shell} and @{file}
- Gemini CLI sandbox: enable Docker, Podman, macOS Seatbelt or gVisor
- Gemini CLI hooks: settings.json, BeforeTool, AfterTool, exit codes and /hooks
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 →