gemini-cli/docs/cli/headless.md

Headless mode reference

Headless mode provides a programmatic interface to Gemini CLI, returning structured text or JSON output without an interactive terminal UI.

Technical reference

Headless mode is triggered when the CLI is run in a non-TTY environment or when providing a query as a positional argument without the interactive flag.

Output formats

You can specify the output format using the --output-format flag.

JSON output

Returns a single JSON object containing the response and usage statistics.

• Schema:
  • session_id: (string, optional) Session ID.
  • auth_method: (string, optional) Authentication method. Emitted with --debug.
  • user_tier: (string, optional) User tier name. Emitted with --debug.
  • response: (string) The model's final answer.
  • stats: (object) Token usage and API latency metrics.
  • stats.api_requests: (number, optional) Total API requests. Emitted with --debug.
  • stats.api_errors: (number, optional) Total API errors. Emitted with --debug.
  • stats.retry_count: (number, optional) Total retries. Emitted with --debug.
  • stats.loop_detected: (boolean, optional) Whether a loop was detected. Emitted with --debug.
  • stats.loop_type: (string, optional) Loop classification. Emitted with --debug.
  • error: (object, optional) Error details if the request failed.

Streaming JSON output

Returns a stream of newline-delimited JSON (JSONL) events.

• Event types:
  • init: Session metadata (session ID, model). Includes auth_method and user_tier with --debug.
  • 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.
  • retry: Retry attempt diagnostics. Emitted with --debug.
  • loop_detected: Loop detection diagnostics. Emitted with --debug.
  • result: Final outcome with aggregated statistics.

In debug mode (--debug), result.stats also includes api_requests, api_errors, and retry_count.

Exit codes

The CLI returns standard exit codes to indicate the result of the headless execution:

• 0: Success.
• 1: General error or API failure.
• 42: Input error (invalid prompt or arguments).
• 53: Turn limit exceeded.

Next steps

• Follow the Automation tutorial for practical scripting examples.
• See the CLI reference for all available flags.