Gemini CLI headless mode: JSON, streams and exit codes

Gemini CLI headless mode runs one prompt without the interactive terminal interface and returns text or JSON that a script can read. The official headless reference says headless mode is triggered when the CLI runs in a non-TTY environment or when the query is passed with -p (or --prompt).

Applies to: Gemini CLI documentation as published on October 26, 2026 (headless reference updated March 10, 2026; automation tutorial updated March 9, 2026; CLI cheatsheet updated May 1, 2026; authentication guide updated September 18, 2026). Last checked: October 26, 2026.

On this page

Run one prompt with -p

The CLI cheatsheet lists this as the non-interactive query:

gemini -p "summarize README.md"

According to the same cheatsheet, --prompt / -p “forces non-interactive mode”, while a positional prompt “defaults to interactive mode in a TTY”. The automation tutorial adds that positional arguments without the flag stay interactive “unless the input or output is piped or redirected”, and that headless mode “runs Gemini CLI once and exits”.

Do not confuse -p with -i. The cheatsheet describes --prompt-interactive / -i as “Execute prompt and continue in interactive mode”.

If Gemini CLI is not installed yet or you are unsure which version you run, see how to update Gemini CLI.

Pipe files and command output

Gemini CLI reads standard input as context and answers on standard output, per the automation tutorial. The cheatsheet notes that the -p text is appended to stdin input when both are given.

Pipe a file on macOS or Linux:

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

Pipe a file in Windows PowerShell:

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

Pipe a command’s output:

git diff | gemini -p "Write a commit message for these changes"

All three commands are from Google’s automation tutorial.

Choose an output format

The --output-format (-o) option takes text, json or stream-json, and text is the default, according to the CLI cheatsheet. The headless reference describes the two structured formats:

Save text output to files

Because Gemini CLI prints to stdout, the automation tutorial shows saving the result with shell redirection. Its bulk documentation example for macOS and Linux (generate_docs.sh) is:

#!/bin/bash

# Loop through all Python files
for file in *.py; do
  echo "Generating docs for $file..."

  # Ask Gemini CLI to generate the documentation and print it to stdout
  gemini -p "Generate a Markdown documentation summary for @$file. Print the
  result to standard output." > "${file%.py}.md"
done

The tutorial runs the script with chmod +x generate_docs.sh and ./generate_docs.sh, and it creates one Markdown file per Python file in the folder.

Parse the JSON object

The headless reference documents this schema for --output-format json:

• response (string): the model’s final answer.
• stats (object): token usage and API latency metrics.
• error (object, optional): error details if the request failed.

The automation tutorial combines the flag with jq to pull out the response field:

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

In that example the model’s own JSON arrives as the string in response, and jq -r '.response' writes it to data.json. The tutorial’s PowerShell version uses ConvertFrom-Json and reads $output.response instead of jq.

Read stream-json events

With --output-format stream-json, the headless reference says the CLI returns newline-delimited JSON (JSONL), one event per line. The documented event types are:

• init: session metadata (session ID, model).
• message: user and assistant message chunks.
• tool_use: tool call requests with arguments.
• tool_result: output from executed tools.
• error: non-fatal warnings and system errors.
• result: final outcome with aggregated statistics and per-model token usage breakdowns.

Check the exit code

The headless reference lists the exit codes of a headless run:

Authenticate a headless runner

Headless mode uses your existing authentication method if a credential is already cached, according to the authentication guide. Without a cached sign-in, the guide says to configure authentication through environment variables with either a Gemini API key or Vertex AI.

For a Gemini API key from Google AI Studio, the authentication guide sets GEMINI_API_KEY:

# Replace YOUR_GEMINI_API_KEY with the key from AI Studio
export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"

For Vertex AI, the same guide requires GOOGLE_CLOUD_PROJECT and GOOGLE_CLOUD_LOCATION with any of its three methods (Application Default Credentials, a service account JSON key, or a Google Cloud API key):

# Replace with your project ID and desired location (for example, us-central1)
export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
export GOOGLE_CLOUD_LOCATION="YOUR_PROJECT_LOCATION"

The guide suggests the service account JSON key “in non-interactive environments, CI/CD pipelines, or if your organization restricts user-based ADC or API key creation”, pointed to by GOOGLE_APPLICATION_CREDENTIALS:

# Replace /path/to/your/keyfile.json with the actual path
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/keyfile.json"

Google’s warnings from the authentication guide: treat API keys as sensitive credentials, protect the service account key file because it gives access to your resources, and remember that when you export API keys or service account paths in a shell configuration file, any process launched from that shell can read them.

The Gemini CLI docs also carry a notice that for unpaid tier and Google One users, Gemini CLI was replaced by Antigravity CLI on June 18, 2026 (authentication guide). If that applies to your account, see the Gemini CLI to Antigravity CLI migration guide.

Limit what the agent may do

The CLI cheatsheet documents these options for tool execution:

• --sandbox / -s: “Run in a sandboxed environment for safer execution” (default false).
• --approval-mode: approval mode for tool execution, with choices default, auto_edit, yolo and plan (default default).
• --yolo / -y: marked “Deprecated. Auto-approve all actions. Use --approval-mode=yolo instead.”
• --allowed-tools: marked “Deprecated. Use the Policy Engine instead.”

The cheatsheet describes yolo as auto-approving all actions and lists default as the default approval mode; the option it documents for safer execution is --sandbox.