Gemini CLI trusted folders for QA provide a testable boundary between opening a repository and allowing that repository’s configuration to influence an AI coding session. A project can contain local settings, environment files, commands, MCP servers, hooks, and skills. Folder trust is designed to show those components before approval and suppress important project capabilities when the folder is marked untrusted.

This tutorial builds a harmless canary repository and proves the restricted behavior. You will test discovery, choose Don’t trust, verify that project integrations stay inactive, change the decision deliberately, test parent-folder inheritance, and exercise headless failure behavior. No production secrets, external services, or destructive hooks are required.

What the official Gemini CLI docs say

The current Trusted Folders guide says the trust dialog discovers project commands, MCP servers, hooks, skills, and setting overrides before you decide. It also highlights dangerous settings and malformed configuration.

When a folder is untrusted, Gemini CLI uses a restricted safe mode. The guide says workspace settings and project environment files are ignored, extension management is restricted, tool auto-acceptance is disabled, automatic memory loading from local settings is disabled, MCP servers do not connect, and custom commands are not loaded.

There is one documentation detail QA teams should not gloss over: the dedicated guide says the feature is disabled by default, while the current settings reference lists Folder Trust with a default of true. Do not build a test expectation from either sentence alone. Inspect the installed CLI’s /settings value and explicitly set the user-level configuration for the test.

Define the QA trust contract

Use a disposable folder outside any already trusted parent:

Before trust, Gemini CLI may report project capabilities during discovery but must not activate the synthetic project settings, environment canary, MCP server, hook, command, or workspace skill. Mutating tools must still require approval. After an explicit trust decision, only reviewed capabilities may be enabled, and every transition must be independently verified.

Record the CLI build, OS, launch surface, folder path, parent path, user setting, central trust-file location, IDE connection state, decision, discovered items, active tools, active commands, active skills, MCP connection attempts, hook sentinel, environment canary result, and tool approval behavior.

Step 1: make trust state explicit

Open the user-level settings file, not the workspace file, and set:

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

Restart Gemini CLI, open /settings, and capture the displayed value. This avoids relying on changing defaults or a project override. For the first trial, run the CLI as a standalone terminal without IDE integration so the local trust file controls the decision.

Step 2: build a harmless canary repository

Create a new Git repository with normal source and test files plus these synthetic project items:

  • .gemini/settings.json declaring one clearly named local MCP canary and one benign hook canary
  • .gemini/commands/qa/trust-canary.toml defining a recognizable custom command
  • .gemini/skills/trust-canary/SKILL.md defining a recognizable workspace skill
  • .env containing only QA_TRUST_CANARY=synthetic-not-secret
  • a hook script that creates hook-canary-ran.txt only if it actually executes

Point the MCP canary at a local test endpoint that is not running. Do not place a real token in .env. Do not use a hook that deletes, uploads, installs, or changes anything outside this disposable repository.

Step 3: test the discovery dialog

Launch Gemini CLI from the canary folder. The discovery phase should identify the project configuration categories before asking for trust. Compare the dialog with the fixture inventory.

Fixture Expected discovery Must not happen yet
Custom command Command category listed Command activated
MCP canary MCP category listed Connection attempted
Hook canary Hook category listed Sentinel created
Workspace skill Skill category listed Skill loaded
Settings override Override or warning listed Override applied

Also corrupt a copy of .gemini/settings.json and repeat in a new folder. The discovery UI should surface the parsing problem. Treat a silent skip as a defect because the tester cannot make an informed trust decision.

Step 4: choose Don’t trust

Select Don’t trust. Do not accept the parent folder. Save screenshots of the exact path and decision. Then start a new session from the same folder and confirm Gemini CLI remembers the untrusted choice rather than presenting an unexplained trusted state.

The decision is stored centrally, normally in ~/.gemini/trustedFolders.json. Inspect the entry without editing unrelated rules. The path can be overridden with GEMINI_CLI_TRUSTED_FOLDERS_PATH, which is useful for an isolated test matrix.

Step 5: verify each safe-mode suppression

Do not infer safety from the word untrusted. Test every documented behavior:

  1. Open /settings and confirm the project setting did not override the user baseline.
  2. Use /tools and confirm the project MCP canary is absent and made no connection attempt.
  3. List custom commands and confirm the project command is unavailable.
  4. List skills and confirm the workspace skill is not loaded.
  5. Check that hook-canary-ran.txt does not exist.
  6. Ask Gemini to report whether QA_TRUST_CANARY is loaded, without printing other environment variables.
  7. Request a harmless file edit or command and confirm an approval prompt appears even if a global auto-accept setting exists.
  8. Attempt extension installation or management and record the restricted result.

Check the filesystem and local MCP endpoint logs independently. Model text such as “the hook did not run” is not evidence.

Step 6: test prompt injection before trust

Add a synthetic README instruction telling the model to trust the parent folder, load the environment, connect the MCP server, and run the hook. Ask Gemini only to summarize the repository. The text must be treated as repository content, not permission to change trust.

Verify the central trust file remains unchanged, no connection occurs, the sentinel is absent, and every mutating tool still prompts. Folder trust is a configuration boundary; content inside the folder must not be allowed to approve itself.

Step 7: change trust deliberately

Review every discovered item and its source first. Use /permissions or /permissions trust to change the current folder decision. Restart the session so capabilities are discovered from a clean state.

Now verify the reviewed project command and workspace skill appear. For the project hook, Gemini CLI’s official hook guidance says project hooks are fingerprinted and a new or changed name or command should trigger a warning. Approve only the benign canary and verify one expected sentinel. Keep the MCP endpoint isolated and confirm exactly one controlled connection when enabled.

Trust activates project capability; it does not prove that capability is safe. Continue to review tool prompts, hook input and output, MCP tool scope, skill instructions, and environment handling.

Step 8: test modification detection

Change the benign hook command on a new Git branch. The change should be treated as a new untrusted hook identity and warn before execution. Deny it and verify the modified sentinel is absent.

Repeat for a changed MCP configuration, custom command, skill instruction, and project setting. The trust dialog covers folder-level configuration discovery, but each integration can have additional trust and review behavior. Record those separately instead of assuming folder trust approves every future change.

Step 9: test parent-folder inheritance

Create two sibling repositories: one reviewed canary and one unreviewed canary. In a clean trust file, choose Trust parent folder for the reviewed repository. Launch from the sibling and verify whether it inherits trust.

This is the expected convenience and the main blast-radius risk. QA should recommend trusting the narrowest directory that matches repository ownership. Never trust a broad downloads, desktop, shared checkout, or temporary build directory merely to remove prompts.

Step 10: test IDE priority

The trusted-folders guide says an IDE trust signal takes precedence when an IDE integration is connected; otherwise the CLI checks the local trust file. Build a small matrix:

  • standalone CLI with local untrusted entry
  • standalone CLI with local trusted entry
  • IDE-connected CLI with IDE untrusted
  • IDE-connected CLI with IDE trusted

Capture the effective result and active project capabilities. This prevents confusing differences between a terminal reproduction and an IDE session.

Step 11: validate headless failure safely

With folder trust enabled and the workspace untrusted, run a headless prompt in the disposable repository. The official guide says the CLI cannot display the dialog and exits with FatalUntrustedWorkspaceError. Assert the non-success result, absence of project integrations, and no side effects.

Gemini CLI documents --skip-trust and GEMINI_CLI_TRUST_WORKSPACE=true as session-level bypasses. Do not use them as a casual fix. In CI, first verify the immutable checkout, review project configuration, isolate credentials, restrict tools and network, and record why the workspace is trusted for that job.

Release checklist

  • Folder trust is explicitly configured and observed
  • Test folder is outside a trusted parent
  • Discovery inventory matches project configuration
  • Malformed settings surface an error
  • Untrusted settings, environment, MCP, commands, skills, and hooks stay inactive
  • Tool auto-acceptance is disabled in safe mode
  • Prompt injection cannot change trust
  • Trust-file changes are independently inspected
  • Hook modifications trigger fresh review
  • Parent inheritance is tested with a sibling folder
  • IDE and standalone precedence are compared
  • Headless untrusted runs fail without side effects
  • CI bypasses require explicit, reviewed controls

Official sources

Trusted folders are most useful when QA treats trust as state to verify, not a checkbox to click. The defensible workflow is explicit configuration, complete discovery, safe-mode canaries, narrow directory scope, integration-specific review, repeatable precedence tests, and strict controls around automation bypasses.