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

  or 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:

1. Global Scope:

   ~/.gemini/settings.json

   (User-wide defaults)
2. Project Scope:

   .gemini/settings.json

   (Per-project overrides)
3. Environment Variables:

   GEMINI_*

   (Runtime overrides)

Trusted Folders Security

The Trusted Folders feature is a critical security boundary.

• Enabled via:

  "security.folderTrust.enabled": true

  in

  settings.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)

settings.json schema

configuration options

trusted folders

folder trust

safe mode

policy engine

execution policies

allow list

proxy settings

network configuration

timeout

telemetry configuration

mouse support

sticky headers

Quick Decision Tree

What do you want to do?

1. Enable Trusted Folders -> Query

   gemini-cli-docs

   : "enable trusted folders settings"
2. Edit Global Settings -> Query

   gemini-cli-docs

   : "global settings.json location"
3. Override for Project -> Query

   gemini-cli-docs

   : "project specific settings .gemini"
4. Configure UI/Telemetry -> Query

   gemini-cli-docs

   : "telemetry configuration settings"
5. 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

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

  path 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

• "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