| # 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 with the `-p` (or `--prompt`) 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 and per-model token usage |
| breakdowns. |
| |
| ## 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](./tutorials/automation.md) for practical |
| scripting examples. |
| - See the [CLI reference](./cli-reference.md) for all available flags. |
|
|
