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

• Repository: google-gemini/gemini-cli
• Author: joycebeatriz
• State: open | merged: False
• Link: https://github.com/google-gemini/gemini-cli/pull/25608

Description (problem / solution / changelog)

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

Changed files

• docs/reference/configuration.md (modified, +5/-3)
• packages/cli/src/config/settings.test.ts (modified, +64/-0)
• packages/cli/src/config/settings.ts (modified, +90/-5)