Skip to content

feat(cli): add --schema-file flag for custom JSON schema output #18032

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
medic-code wants to merge 3 commits into
base: main
Choose a base branch
from
Open

feat(cli): add --schema-file flag for custom JSON schema output #18032

medic-code wants to merge 3 commits into from
+829 −13

Conversation

@medic-code
Copy link
Contributor

@medic-code medic-code commented Jan 31, 2026

Summary

Adds --schema-file flag to enable custom JSON schema output for headless/non-interactive mode. This allows users to define their own response structure for automation, orchestration, and pipeline integration.

Details

New flags:

  • --schema-file <path> - Path to a JSON schema file for structured output
  • --enable-tools - Re-enable tools when using --schema-file (tools disabled by default)

Behavior:

  • --schema-file implies --output-format json automatically
  • Tools are disabled by default when using a schema (ideal for "tell me what to do" orchestration)
  • Use --enable-tools to re-enable tool execution with structured output

Validation:

  • Schema file must exist and be valid JSON
  • Schema must have type or properties field
  • Maximum file size: 1MB
  • Cannot combine with --output-format text or --output-format stream-json

Example usage:

# Create schema
echo '{"type":"object","properties":{"action":{"type":"string"}}}' > schema.json

# Get structured output
gemini --schema-file schema.json -p "What should I do next?"
# Output: {"action": "run the tests"}

Summary of Changes

File Changes
packages/cli/src/config/config.ts Add --schema-file and --enable-tools yargs options with coerce validation, conflict checks, implied json output
packages/core/src/config/config.ts Add jsonSchema and enableTools fields to Config class with getters
packages/core/src/core/client.ts Disable tools when schema is set (unless --enable-tools)
packages/core/src/core/geminiChat.ts Add responseJsonSchema and responseMimeType to API request when schema is set
packages/cli/src/config/config.test.ts Add 17 tests for schema-file parsing, validation, errors, and Config integration
packages/core/src/core/client.test.ts Add 3 tests for tools disabled/enabled behavior, fix mock config
packages/core/src/core/geminiChat.test.ts Add 2 tests for responseJsonSchema in API request, fix mock config
packages/core/src/core/geminiChat_network_retry.test.ts Fix mock config to include new getters
docs/cli/headless.md Add "Custom JSON Schema Output" section, update config options table

Related Issues

Fixes #13388

How to Validate

  1. Basic schema output:

    echo '{"type":"object","properties":{"answer":{"type":"string"}}}' > /tmp/test.json
gemini --schema-file /tmp/test.json -p "What is 2+2?"

    Verify: JSON output matching schema, no tool calls

  2. With tools enabled:

    gemini --schema-file /tmp/test.json --enable-tools -p "List files"

    Verify: Tool calls allowed, structured JSON output

  3. Error cases:

    gemini --schema-file missing.json -p "test"  # File not found
gemini --schema-file /tmp/test.json --output-format text -p "test"  # Conflict
gemini --enable-tools -p "test"  # Missing schema-file

Pre-Merge Checklist

  • Updated relevant documentation and README
  • Added/updated tests
  • Noted breaking changes (none)
  • Validated on required platforms/methods:
    • MacOS
      • npm run
      • npx
    • Windows
    • Linux
@medic-code medic-code requested review from a team as code owners January 31, 2026 23:55
@gemini-code-assist
Copy link
Contributor

gemini-code-assist bot commented Jan 31, 2026

Summary of Changes

Hello @medic-code, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the Gemini CLI's capabilities for automation and integration by introducing a mechanism to enforce structured JSON output based on a user-defined schema. This allows external systems to reliably parse and process responses, making the CLI more adaptable for pipelines and orchestration. The changes also refine how tools interact with structured output, providing control over their execution based on the desired response format.

Highlights

  • New CLI Flags for Structured Output: Introduced --schema-file <path> to specify a JSON schema for structured output, and --enable-tools to re-enable tool execution when a schema is active.
  • Schema-Driven Output Behavior: Using --schema-file automatically implies --output-format json. Tools are disabled by default with a schema, promoting 'tell me what to do' orchestration, but can be explicitly re-enabled.
  • Robust Schema Validation: The provided schema file undergoes validation checks for existence, valid JSON format, presence of type or properties fields, and a maximum size of 1MB. Conflicts with --output-format text or --output-format stream-json are also prevented.
  • Enhanced Tool Output Rendering: Tool results are now intelligently rendered, with valid JSON content being pretty-printed for improved readability, even when Markdown rendering is generally enabled.
  • Comprehensive Testing and Documentation: Extensive unit tests have been added for the new flags, their validation logic, and their impact on core functionalities. Documentation for headless CLI usage has been updated to include the new features.
Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature Command Description
Code Review /gemini review Performs a code review for the current pull request in its current state.
Pull Request Summary /gemini summary Provides a summary of the current pull request in its current state.
Comment @gemini-code-assist Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help /gemini help Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

  1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩
@chrstnb
Copy link
Collaborator

chrstnb commented Jan 31, 2026

Build failed: Build process failed (no specific link errors found). Check logs for details.
gemini-code-assist[bot]
gemini-code-assist bot reviewed Jan 31, 2026
View reviewed changes
Copy link
Contributor

@gemini-code-assist gemini-code-assist bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request introduces a valuable feature, --schema-file, for enforcing a custom JSON schema on the model's output. The implementation is thorough, with changes spanning configuration, client logic, and API requests, all supported by a comprehensive suite of tests and updated documentation. The code quality is high, and the feature is well-designed for automation and integration scenarios. I've identified one high-severity issue concerning the handling of the file path provided to --schema-file. The path is used directly without resolution, which is inconsistent with other parts of the application and could lead to unexpected behavior. Additionally, the current implementation uses synchronous file system operations, which can block the event loop. I've provided a suggestion to resolve the path and use asynchronous file system operations for better robustness, consistency, and performance.
@chrstnb
Copy link
Collaborator

chrstnb commented Feb 1, 2026

Build failed: Build process failed (no specific link errors found). Check logs for details.
@chrstnb
Copy link
Collaborator

chrstnb commented Feb 1, 2026

Build failed: Build process failed (no specific link errors found). Check logs for details.
@medic-code
feat(cli): add --schema-file and --enable-tools flags
aa9e77d 
- Add jsonSchema and enableTools to Config class
- Add CLI argument parsing with validation
- Validate schema file (size, JSON syntax, has type/properties)
- Error on conflicting flags (schema + text output, enable-tools without schema)
@medic-code
test(cli): add comprehensive tests for --schema-file flag
f74291d 
- Add 13 tests for schema-file parsing, validation, and error cases
- Add 3 tests for loadCliConfig integration with schema
- Add 3 tests for tools disabled/enabled behavior in client.test.ts
- Fix mock configs to include getJsonSchema and getEnableTools methods
- Improve help descriptions for --schema-file and --enable-tools
- Fix typo in error message ("must have name" -> "must have")
- Remove unreachable empty object check
@medic-code
docs(cli): add --schema-file documentation
562cf06 
- Add --schema-file and --enable-tools to configuration options table
- Add "Custom JSON Schema Output" section with usage examples
- Document schema requirements and behavior
@chrstnb
Copy link
Collaborator

chrstnb commented Feb 1, 2026

Build failed: Build process failed (no specific link errors found). Check logs for details.
1 similar comment
@chrstnb
Copy link
Collaborator

chrstnb commented Feb 1, 2026

Build failed: Build process failed (no specific link errors found). Check logs for details.
@medic-code
Copy link
Contributor Author

medic-code commented Feb 1, 2026

i see the docs-pr-check is failing, but can't really see any more details on my side. Let me know how i can help.
@gemini-cli gemini-cli bot added priority/p2 Important but can be addressed in a future release. area/non-interactive Issues related to GitHub Actions, SDK, 3P Integrations, Shell Scripting, Command line automation help wanted We will accept PRs from all issues marked as "help wanted". Thanks for your support! labels Feb 1, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area/non-interactive Issues related to GitHub Actions, SDK, 3P Integrations, Shell Scripting, Command line automation help wanted We will accept PRs from all issues marked as "help wanted". Thanks for your support! priority/p2 Important but can be addressed in a future release.

2 participants

@medic-code @chrstnb