Gemini Configuration Management
🚨 MANDATORY: Invoke gemini-cli-docs First
STOP - Before providing ANY response about Gemini configuration: 1. INVOKE gemini-cli-docs skill 2. QUERY for the specific configuration topic (e.g., "trusted folders", "settings.json schema") 3. BASE all responses EXCLUSIVELY on official documentation loaded Skipping this step results in outdated or incorrect information.Overview
Expert skill for managing Google Gemini CLI configuration. It handles the hierarchy of settings, security policies, and environment overrides.
When to Use This Skill
Keywords: gemini config, settings.json,.gemini folder, trusted folders, folder trust, security policy, environment variables, scope, global settings, project settings, telemetry, ui configuration
Use this skill when:
- Configuring
settings.json(Global~/.gemini/settings.jsonor Project.gemini/settings.json) - Managing Trusted Folders (
security.folderTrust.enabled) - Setting up Policy Engine rules
- Configuring UI & Telemetry (mouse support, sticky headers, disable telemetry)
- Troubleshooting configuration precedence (User > Project > Default)
- Configuring proxy settings or network behaviors
Configuration Scopes
Gemini CLI uses a cascading configuration system:
- Global Scope:
~/.gemini/settings.json(User-wide defaults) - Project Scope:
.gemini/settings.json(Per-project overrides) - Environment Variables:
GEMINI_*(Runtime overrides)
Trusted Folders Security
The Trusted Folders feature is a critical security boundary.
- Enabled via:
"security.folderTrust.enabled": trueinsettings.json. - States:
- Trusted: Full access (MCP, extensions, shell execution). - Untrusted: Restricted "Safe Mode" (No shell, no MCP, read-only).
- Storage: Decisions saved in
~/.gemini/trustedFolders.json.
Keyword Registry (Delegates to gemini-cli-docs)
| Topic | Query Keywords |
|---|---|
| Settings Schema | settings.json schema, configuration options |
| Trusted Folders | trusted folders, folder trust, safe mode |
| Policy Engine | policy engine, execution policies, allow list |
| Network | proxy settings, network configuration, timeout |
| UI & Telemetry | telemetry configuration, mouse support, sticky headers |
Quick Decision Tree
What do you want to do?
- Enable Trusted Folders -> Query
gemini-cli-docs: "enable trusted folders settings" - Edit Global Settings -> Query
gemini-cli-docs: "global settings.json location" - Override for Project -> Query
gemini-cli-docs: "project specific settings.gemini" - Configure UI/Telemetry -> Query
gemini-cli-docs: "telemetry configuration settings" - Debug Config -> Query
gemini-cli-docs: "debug configuration loading"
Troubleshooting
Issue: "My settings aren't applying." Check: Is the folder trusted? If Untrusted, project settings are IGNORED. Action: Run /permissions to check trust status.
Test Scenarios
Scenario 1: Global Settings
Query: "Where is the Gemini CLI global settings file?" Expected Behavior:
- Skill activates on "settings.json" or "global settings"
- Provides
~/.gemini/settings.jsonpath Success Criteria: User receives correct path and configuration options
Scenario 2: Trusted Folders
Query: "How do I enable trusted folders in Gemini CLI?" Expected Behavior:
- Skill activates on "trusted folders"
- Delegates to gemini-cli-docs for security settings Success Criteria: User receives security.folderTrust configuration
Scenario 3: Configuration Debugging
Query: "My Gemini settings aren't applying, how do I debug?" Expected Behavior:
- Skill activates on "settings not applying"
- Checks trust status recommendation Success Criteria: User receives troubleshooting steps including /permissions check
References
Official Documentation: Query gemini-cli-docs for:
- "configuration"
- "trusted folders"
- "policy engine"
Version History
- v1.1.0 (2025-12-01): Added Test Scenarios section
- v1.0.0 (2025-11-25): Initial release