Trusted Folders

The Trusted Folders feature is a security setting that gives you control over which projects can use the full capabilities of Gemini CLI. It prevents potentially malicious code from running by asking you to approve a folder before the CLI loads any project-specific configurations from it.

Enabling the feature

The Trusted Folders feature is disabled by default. To use it, you must first enable it in your settings.

Add the following to your user settings.json file:

{
  "security": {
    "folderTrust": {
      "enabled": true
    }
  }
}

How it works: The trust dialog

Once the feature is enabled, the first time you run Gemini CLI from a folder, a dialog will automatically appear, prompting you to make a choice:

• Trust folder: Grants full trust to the current folder (for example, my-project).
• Trust parent folder: Grants trust to the parent directory (for example, safe-projects), which automatically trusts all of its subdirectories as well. This is useful if you keep all your safe projects in one place.
• Don't trust: Marks the folder as untrusted. The CLI will operate in a restricted "safe mode."

Your choice is saved in a central file (~/.gemini/trustedFolders.json), so you will only be asked once per folder.

Understanding folder contents: The discovery phase

Before you make a choice, Gemini CLI performs a discovery phase to scan the folder for potential configurations. This information is displayed in the trust dialog to help you make an informed decision.

The discovery UI lists the following categories of items found in the project:

• Commands: Custom .toml command definitions that add new functionality.
• MCP Servers: Configured Model Context Protocol servers that the CLI will attempt to connect to.
• Hooks: System or custom hooks that can intercept and modify CLI behavior.
• Skills: Local agent skills that provide specialized capabilities.
• Setting overrides: Any project-specific configurations that override your global user settings.

Security warnings and errors

The trust dialog also highlights critical information that requires your attention:

• Security Warnings: The CLI will explicitly flag potentially dangerous settings, such as auto-approving certain tools or disabling the security sandbox.
• Discovery Errors: If the CLI encounters issues while scanning the folder (for example, a malformed settings.json file), these errors will be displayed prominently.

By reviewing these details, you can ensure that you only grant trust to projects that you know are safe.

Why trust matters: The impact of an untrusted workspace

When a folder is untrusted, Gemini CLI runs in a restricted "safe mode" to protect you. In this mode, the following features are disabled:

1. Workspace settings are ignored: The CLI will not load the .gemini/settings.json file from the project. This prevents the loading of custom tools and other potentially dangerous configurations.

2. Environment variables are ignored: The CLI will not load any .env files from the project.

3. Extension management is restricted: You cannot install, update, or uninstall extensions.

4. Tool auto-acceptance is disabled: You will always be prompted before any tool is run, even if you have auto-acceptance enabled globally.

5. Automatic memory loading is disabled: The CLI will not automatically load files into context from directories specified in local settings.

6. MCP servers do not connect: The CLI will not attempt to connect to any Model Context Protocol (MCP) servers.

7. Custom commands are not loaded: The CLI will not load any custom commands from .toml files, including both project-specific and global user commands.

Granting trust to a folder unlocks the full functionality of Gemini CLI for that workspace.

Headless and automated environments

When running Gemini CLI in a headless environment (for example, a CI/CD pipeline) where interactive prompts are not possible, the trust dialog cannot be displayed. If the folder is untrusted and the Folder Trust feature is enabled, the CLI will throw a FatalUntrustedWorkspaceError and exit.

To proceed in these environments, you can bypass the trust check using one of the following methods:

• Command-line flag: Run the CLI with the --skip-trust flag.
• Environment variable: Set the GEMINI_CLI_TRUST_WORKSPACE=true environment variable.

These methods will trust the current workspace for the duration of the session without prompting.

For detailed instructions on managing folder trust within CI/CD workflows, review the Gemini CLI trust guidance for GitHub Actions.

Overriding the trust file location

By default, trust settings are saved to ~/.gemini/trustedFolders.json. If you need to store this file in a different location, you can set the GEMINI_CLI_TRUSTED_FOLDERS_PATH environment variable to the desired absolute file path.

Managing your trust settings

If you need to change a decision or see all your settings, you have a couple of options:

• Change the current folder's trust: Run the /permissions command from within the CLI. This will bring up the same interactive dialog, allowing you to change the trust level for the current folder.

• View all trust rules: To see a complete list of all your trusted and untrusted folder rules, you can inspect the contents of the ~/.gemini/trustedFolders.json file in your home directory.

The trust check process (advanced)

For advanced users, it's helpful to know the exact order of operations for how trust is determined:

1. IDE trust signal: If you are using the IDE Integration, the CLI first asks the IDE if the workspace is trusted. The IDE's response takes highest priority.

2. Local trust file: If the IDE is not connected, the CLI checks the central ~/.gemini/trustedFolders.json file.