Skip to content

Latest commit

 

History

History
50 lines (34 loc) · 1.52 KB

headless.md

File metadata and controls

50 lines (34 loc) · 1.52 KB

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:
    • response: (string) The model's final answer.
    • stats: (object) Token usage and API latency metrics.
    • 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).
    • 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.

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