fix(cli): coerce env-resolved boolean strings in settings

[joycebeatriz]

Summary

This PR fixes env-based boolean configuration for settings.json.

Previously, interpolated env values were always strings, which could trigger validation warnings for boolean settings (for example, ui.autoThemeSwitching). This change adds schema-aware coercion so "true"/"false" values are interpreted as booleans where appropriate.

Details

• Resolve env vars, then normalize schema-typed boolean fields before validation.
• Keep coercion limited to boolean settings defined in the schema.
• Preserve existing behavior for string-only maps (for example, MCP server env values stay strings).
• Add focused tests for both coercion and non-coercion paths.
• Document the boolean casting behavior in the configuration reference.

Related Issues

Fixes #25573

How to Validate

1. Add an env-based boolean setting in settings.json, for example:
   • "ui": { "autoThemeSwitching": "${GEMINI_AUTO_THEME:-true}" }
2. Set GEMINI_AUTO_THEME to TRUE or FALSE.
3. Run:
   • npm test -w @google/gemini-cli -- src/config/settings.test.ts
4. Verify these tests pass:
   • should coerce env-resolved boolean setting values from strings
   • should not coerce env-resolved values in string-only map settings

Pre-Merge Checklist

• Updated relevant documentation and README (if needed)
• Added/updated tests (if needed)
• Noted breaking changes (if any)
• Validated on required platforms/methods:
  • MacOS
    • npm run
    • npx
    • Docker
    • Podman
    • Seatbelt
  • Windows
    • npm run
    • npx
    • Docker
  • Linux
    • npm run
    • npx
    • Docker

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! 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 improves the handling of environment-based boolean configurations in settings.json. By introducing schema-aware coercion, the CLI now correctly interprets interpolated environment variables as booleans when expected, resolving validation issues while maintaining existing behavior for string-only maps.

Highlights

• Schema-Aware Boolean Coercion: Implemented automatic casting of environment-resolved string values ("true"/"false") to booleans for settings defined as boolean in the schema.
• Validation Improvement: Updated the settings loading process to resolve environment variables and coerce types before Zod validation, preventing false-positive validation errors.
• Documentation Update: Added documentation to the configuration reference explaining the new automatic boolean casting behavior for environment variables.

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.

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. ↩

[gemini-code-assist]

Code Review

This pull request implements automatic boolean coercion for configuration settings resolved from environment variables, ensuring strings like "true" or "false" are cast to booleans based on the schema. It includes documentation updates and new test cases. However, the review identifies critical issues: the coercion logic does not handle schema references ($ref), which will cause it to fail for many settings, and the internal type definitions for schema nodes are incompatible with nested collections, potentially leading to incomplete normalization.

[joycebeatriz]

Addressed in 340c2bc: boolean coercion is now ref-aware (via schema definitions), recursive traversal was fixed for nested structures, and regression tests were added.

[joycebeatriz]

Could a maintainer please approve the pending workflows and provide code owner review? Feedback was addressed in 340c2bc.

[midnight-wonderer]

I am not the maintainer, but I am the original issue reporter.
Thanks for helping me out; my apologies, I didn't see your PR before I opened mine.

My PR took the opposite approach, keeping the changes minimal.
You can check it out at #25634; of course, this does not imply which one is better.
At least we can see each other's approach and could learn something; yours is more thorough, mine is minimalist.

[joycebeatriz]

Hi @midnight-wonderer! No problem at all! It’s actually nice to see more than one solution to the same problem. Thanks for sharing yours.