Motivation

Gemini CLI is a powerful tool for interactive use. However, its current plain-text output format, while excellent for human readability, presents a significant barrier in non-interactive use. To unlock the next level of integration and enable developers to build robust tools and automation on top of the CLI, we must provide a stable, machine-readable output format.

This proposal outlines a foundational feature: a structured JSON output mode. This will establish a clear API contract for developers, allowing them to reliably parse session results, including responses, errors, and performance statistics. Adopting this feature will unblock a wide range of advanced use cases in CI/CD integrations, automations and third-party tool development.

Proposal

Introduce both a command line argument and a persistent configuration setting to control the output format for the CLI. This provides both runtime control for automation and a persistent preference for users who prefer JSON output.

CLI Argument

Add a new --output-format flag that accepts two values:

• "text" (Default): Preserves the existing behavior, outputting a human-readable, plain-text response.
• "json": Outputs a single, structured JSON object to stdout containing the complete result of the session.

Usage Example:

gemini --output-format json --prompt "What is machine learning?"

Configuration Setting

Introduce a new, persistent configuration setting, output.format, which will govern the default output format for the CLI when no command line flag is specified. The setting will accept two values:

• "text" (Default): Preserves the existing behavior, outputting a human-readable, plain-text response.
• "json": Outputs a single, structured JSON object to stdout containing the complete result of the session.

Configuration Example:

{
  "output": {
    "format": "json"
  }
}

JSON Schema Definition

When output.format is set to "json", the CLI will produce a JSON object adhering to the following schema.

Top-Level Object

stats Object

error Object

JSON Output Examples

Successful Output:

{
  "response": "I found the following files: ...",
  "stats": {
    "session": { "duration": 1234 },
    "model": { "turns": 2 },
    "tools": { "calls": 1 },
    "user": { "turns": 1 }
  },
  "error": null
}

Error Output:

{
  "response": null,
  "stats": {
    "session": { "duration": 25 },
    "model": { "turns": 0 },
    "tools": { "calls": 0 },
    "user": { "turns": 1 }
  },
  "error": {
    "type": "FatalAuthenticationError",
    "message": "Authentication failed. Please check your credentials.",
    "code": 41
  }
}

Future Extensibility

This design is intentionally foundational, providing a clear path for future enhancements.

Extending the output Configuration

The output object in the configuration is the designated namespace for all output-related settings. Future additions could include:

• output.styles: For theming and customizing the color and style of the text output.
• output.redact: For defining patterns to automatically redact from the output.

Extending the JSON Output

The top-level JSON object can be gracefully extended with new keys for more detailed analysis. A prime candidate for future inclusion is:

• conversation: An optional key containing an array of the full conversation history. This would provide a complete, self-contained record of the session for deep analysis and could be enabled by a verbosity setting.

cc @leehagoodjames @NTaylorMullen @allenhutchison @abhipatel12