docs/cli/trusted-folders.md

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

```json
{
  "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)](../tools/mcp-server.md) 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](https://github.com/google-github-actions/run-gemini-cli/blob/main/docs/trust-guidance.md).

## 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](../ide-integration/index.md), 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.