mirror of
https://github.com/google-gemini/gemini-cli.git
synced 2026-06-15 22:07:29 -07:00
Chris Williams
57 lines
2.7 KiB
Markdown
57 lines
2.7 KiB
Markdown
# 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 Gemini CLI uses specific exit codes to indicate the reason for termination.
|
|
This is especially useful for headless scripting and automation:
|
|
|
|
| Exit Code | Error Type | Description |
|
|
| --------- | -------------------------- | --------------------------------------------------------------------------------------------------- |
|
|
| 0 | `Success` | Success. |
|
|
| 1 | `GeneralError` | General error or API failure. |
|
|
| 41 | `FatalAuthenticationError` | An error occurred during the authentication process. |
|
|
| 42 | `FatalInputError` | Invalid or missing input was provided to the CLI. (non-interactive mode only) |
|
|
| 44 | `FatalSandboxError` | An error occurred with the sandboxing environment (e.g., Docker, Podman, or Seatbelt). |
|
|
| 52 | `FatalConfigError` | A configuration file (`settings.json`) is invalid or contains errors. |
|
|
| 53 | `FatalTurnLimitedError` | The maximum number of conversational turns for the session was reached. (non-interactive mode only) |
|
|
|
|
## Next steps
|
|
|
|
- Follow the [Automation tutorial](./tutorials/automation.md) for practical
|
|
scripting examples.
|
|
- See the [CLI reference](./cli-reference.md) for all available flags.
|