Gemini CLI Folder Trust: Check What Loads

Before letting an agent work in a downloaded repository, check whether its project configuration can load. This exercise gives you one visible signal: a uniquely named custom command that should appear only after a deliberate trust decision.

Google documents folder trust as opt-in. In an untrusted workspace, project settings and custom commands are suppressed; global custom commands are also unavailable. That makes command discovery a useful small probe. It does not establish a filesystem or network sandbox. Trusted Folders

Checked November 6, 2026. This is a documentation-backed exercise, not a reported Gemini CLI runtime test. The fixture’s shell setup and TOML parsing were checked locally. Gemini CLI was not installed in the editorial environment; the interactive observations below remain checks for you to perform.

Prepare a small, inspectable fixture

Use Bash on Linux or macOS, Python 3.11 or newer for the optional syntax check, and an installed, authenticated Gemini CLI. Run gemini --version and keep its output in your lab notes. Use a standalone terminal for this exercise, outside an IDE integration, to reduce competing sources of workspace trust.

Create a new temporary directory. Keep the same shell open so the variable continues to identify it:

trust_lab_dir=$(mktemp -d "${TMPDIR:-/tmp}/gemini-trust-lab.XXXXXX")
cd "$trust_lab_dir"
mkdir -p .gemini/commands
cat > .gemini/commands/sb-trust-probe-614.toml <<'TOML'
description = "Harmless folder-trust discovery probe"
prompt = "Reply with TRUST_PROBE_614 only. Do not use tools."
TOML
pwd -P
cat .gemini/commands/sb-trust-probe-614.toml

The fixture contains no shell interpolation, file imports, MCP server or hook. Read both lines before continuing. You can check its syntax without starting an agent:

python3 - <<'PY'
from pathlib import Path
import tomllib
path = Path('.gemini/commands/sb-trust-probe-614.toml')
command = tomllib.loads(path.read_text())
assert command['prompt'] == 'Reply with TRUST_PROBE_614 only. Do not use tools.'
assert command['description'] == 'Harmless folder-trust discovery probe'
print('Fixture TOML parsed; no Gemini session tested.')
PY

Google’s command reference places project commands under .gemini/commands/, derives their names from their file paths, and requires a string prompt. It also documents /commands list for inspecting available files. Here, the file maps to /sb-trust-probe-614. Custom commands

Enable the control at user scope

Back up your existing ~/.gemini/settings.json before editing it. Merge this setting into the existing JSON, retaining other keys. If the file does not exist, create its parent directory and use this as the initial content:

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

Use an editor rather than overwriting a working configuration with a shell redirect. User settings apply across sessions; system settings can override them. Do not put this lab’s enabling setting only inside the project you intend to leave untrusted. Configuration reference

Before launching, check privately whether your shell defines GEMINI_CLI_TRUST_WORKSPACE. A true value bypasses the trust decision for that session. Do not use --skip-trust in this exercise. If a managed machine enforces different settings, record that limitation instead of trying to override its policy. The configuration reference documents these environment and command-line controls.

Compare two fresh sessions

From the temporary directory, start gemini. Choose Don’t trust. Run /commands list and save the relevant observation in a note outside the fixture. Do not invoke the probe yet. Exit the session after recording whether the command appeared.

Then reopen Gemini in that same directory, use /permissions, and choose Trust folder for the exact lab path. Avoid the parent-folder option: it extends trust to descendants. Restart once more before collecting the second observation so you are comparing fresh sessions. The official guide documents /permissions for changing an existing decision. Trust choices and management

Run /commands list again. Compare what you actually see with this answer key:

Observation	Expected in this exercise	What to record
Fresh untrusted session	Probe absent from command list	Trust choice and relevant list output
Fresh trusted session	Probe present with the fixture path	Exact command name and source path
Optional invocation after discovery	A response containing the requested marker	Actual response and any tool request

The optional third check sends a prompt to the configured model and uses your account’s normal access. Only invoke /sb-trust-probe-614 after confirming its file path. Decline any unexpected tool request. A response with the right marker is a separate model-behavior observation; it cannot substitute for the command-list comparison.

Copy this blank evidence record and fill it with your own observations:

Date and Gemini CLI version:
Exact temporary directory:
User folder-trust setting:
IDE integration or managed settings involved:
Untrusted session: probe absent / present / unable to inspect
Trusted session: probe absent / present / unable to inspect
Optional response: not attempted / actual observation
Unexpected tool requests:
Conclusion: matched expectations / mismatch / incomplete

A missing observation makes the result incomplete. A command present in both sessions is a mismatch to investigate, not a pass. Never label the whole repository safe from this one probe.

Diagnose a mismatch before trusting more

If no initial dialog appears, inspect existing trust rules and the launch environment. The guide says IDE trust takes priority over the local trust file. A previously trusted parent can also explain an unexpected result. Keep the exact path in your notes. Trust resolution

If the command stays absent after trust, check the file extension, TOML syntax and current directory. Confirm that your installed version supports /commands list; if it does not, consult its matching documentation and record the exercise as incomplete. Do not infer discovery from a model saying it read the command.

If the wrong command appears, inspect its reported source path. Project commands can override identically named user commands, so this fixture deliberately uses an unusual name. For a real workflow, check for name collisions before relying on a shortcut. Command precedence

Close the experiment

Use /permissions to mark this lab untrusted again, then exit. Retain your evidence note. If you changed user settings only for this experiment, restore that specific setting to its prior value while preserving any other changes made since the backup. Leaving folder trust enabled may be your preferred ongoing choice; decide deliberately.

For the next repository, define what you need to inspect before granting trust, and what would prove the requested task correct. The lesson on project acceptance checks helps turn that decision into a small, reviewable task.

Official references

All sources checked November 6, 2026:

• Trusted Folders: opt-in behavior, trust choices, command restrictions and trust resolution.
• Custom commands: command locations, TOML format, discovery and precedence.
• Configuration reference: user settings, configuration layers and session trust controls.

Put this to work

Distinguish a project configuration gate from a successful model response.

Try

Look for a unique command in two fresh Gemini CLI sessions with different trust choices.

Prove it worked

Keep the CLI version, exact directory, trust choice and command-list observations together.

Keep in view

• Create one harmless project command in a disposable folder.
• Compare command discovery before and after trusting only that folder.
• Record unexpected behavior and revoke the lab's trust afterward.

Learn the workflow: Define acceptance checks for an agent task →