Gemini CLI Permissions and Policy Engine

Updated September 30, 2026 by Alex Sorokoletov

Independent reference, not affiliated with Google. Tables are generated from the Gemini CLI source at v0.62.0 (v0.62.0). Official documentation: geminicli.com.

Gemini CLI decides whether a tool call runs, prompts or fails with a policy engine: TOML rules that pair a tool with a decision (allow, deny or ask_user) and a priority, stacked in five tiers from bundled defaults to admin policies. The approval mode selects which rules apply, and an optional sandbox limits what an approved command can reach.

What approval modes does Gemini CLI have?#

The CLI flag and the policy files spell one mode differently: --approval-mode auto_edit on the command line, modes = ["autoEdit"] in TOML. A rule written with modes = ["auto_edit"] fails schema validation and its whole file is skipped. In a session, Shift+Tab cycles default, auto_edit and plan, and Ctrl+Y toggles YOLO; in an untrusted folder only default and plan can be selected. general.defaultApprovalMode sets the starting mode.

How do I enable YOLO mode in Gemini CLI?#

Start with gemini --yolo (or -y), or gemini --approval-mode=yolo; the two flags cannot be combined. Ctrl+Y switches YOLO on and off inside a running session. YOLO cannot be the saved default: general.defaultApprovalMode accepts only default, auto_edit and plan, and a yolo value there is ignored. security.disableYoloMode or the admin setting secureModeEnabled turns the flag into a startup error and blocks Ctrl+Y, and in an untrusted folder the mode silently drops back to default.

YOLO is not a bypass of the policy engine. It is a bundled rule, toolName = "*", decision = "allow" at priority 1.998, so every user and admin rule still outranks it: a deny in ~/.gemini/policies/ or in tools.exclude keeps blocking in YOLO mode, and the ask_user tool still asks.

What is the Gemini CLI policy engine?#

Every tool call is checked against all loaded rules from the highest effective priority down; the first rule that matches decides. A rule matches when its tool name, MCP server, approval modes, interactive flag, annotations and argument pattern all fit. With no match, interactive sessions ask and headless runs (-p) deny.

# ~/.gemini/policies/shell.toml
[[rule]]
toolName = "run_shell_command"
commandPrefix = ["git status", "git diff", "npm test"]
decision = "allow"
priority = 100

[[rule]]
toolName = "run_shell_command"
commandRegex = "rm -rf .*"
decision = "deny"
priority = 200
denyMessage = "Recursive deletes are blocked by policy."

commandPrefix and commandRegex work only with toolName = "run_shell_command" (a single name, not a list) and cannot be combined with each other or with argsPattern. A shell command with output redirection is downgraded from allow to ask unless the rule sets allowRedirection = true.

How do policy priority tiers resolve?#

Each file's priority (0 to 999) is divided by 1000 and added to its tier, so an admin rule at priority 0 (5.000) beats a user rule at 999 (4.999). Project-level .gemini/policies/ files are not loaded in 0.62.0: the workspace-policy switch in the CLI is off by default and nothing turns it on, so project rules have to go in a user or admin directory. The system directory is also skipped with a "Security Warning" if its permissions are not secure.

Several settings keys become rules in the user tier:

Narrowed entries behave differently from plain names. "tools.allowed": ["run_shell_command(git status)"] allows git status and adds a deny rule just below it, so every other shell command is denied rather than prompted. tools.core works the same way for the whole tool list: anything not named is denied outside plan mode.

Which policy rules ship by default?#

Read-only tools are allowed, file writes, shell commands, skills and web fetches ask, autoEdit allows replace, write_file and web_fetch, and headless runs deny anything that would have asked. Plan mode denies everything at 1.040 and then carves out read-only tools, the codebase_investigator and cli_help subagents, prompts for ask_user, web_fetch, activate_skill and read-only MCP tools, and allows writing Markdown plan files.

Why does Gemini CLI say "Tool execution denied by policy"?#

The denial comes from the highest-priority matching deny rule. Common sources: a deny in ~/.gemini/policies/ or an admin policy, tools.exclude or mcp.excluded in settings, a narrowed tools.allowed entry that denies every other command, tools.core denying unlisted tools, plan mode, or a headless run where a rule would have asked. Set GEMINI_DEBUG_LOG_FILE=/tmp/gemini.log before starting to log every check; the deciding rule appears as [PolicyEngine.check] MATCHED rule.

How does the Gemini CLI sandbox work?#

--sandbox (-s), tools.sandbox in settings or the GEMINI_SANDBOX environment variable runs the CLI inside a sandbox. tools.sandbox also takes an object with enabled, command, image, allowedPaths and networkAccess. Policy decides whether a call runs; the sandbox limits what an allowed call can touch.

On macOS the default is Seatbelt (sandbox-exec) with the permissive-open profile. Choose another with SEATBELT_PROFILE:

What are trusted folders in Gemini CLI?#

Trust decides how much a project may configure Gemini CLI. Until a folder is trusted, its .gemini/settings.json, its hooks and any approval mode other than default are ignored.

Security settings#

Frequently asked questions#

What is the Gemini CLI policy engine?#

The component that decides whether each tool call is allowed, denied or needs confirmation. Rules live in TOML files with toolName, decision and priority, plus optional matchers for MCP server, arguments, shell command prefix, approval mode and interactivity. Rules are layered in default, extension, workspace, user and admin tiers, and the highest-priority match wins.

Is there a Gemini CLI equivalent of --dangerously-skip-permissions?#

Yes: gemini --yolo or gemini --approval-mode=yolo. It adds an allow-everything rule near the top of the default tier, so it approves any call your own rules do not deny. It cannot be set as the default in settings.json, is refused when security.disableYoloMode is on, and is dropped to default in untrusted folders.

How do I auto-approve only specific shell commands in Gemini CLI?#

Add a rule in ~/.gemini/policies/ with toolName = "run_shell_command", commandPrefix = ["git status", "npm test"], decision = "allow" and a priority. Other shell commands keep asking. Listing run_shell_command(git status) in tools.allowed also works but denies every other shell command instead of asking, and --allowed-tools is deprecated.

Why does Gemini CLI say "Tool execution denied by policy"?#

A matching rule with decision = "deny" outranked every allow rule for that call, and any denyMessage is appended to the error. Check ~/.gemini/policies/ and admin policies, tools.exclude, mcp.excluded, a narrowed tools.allowed or tools.core list, plan mode, and headless runs, where calls that would ask are denied. GEMINI_DEBUG_LOG_FILE logs the matching rule.

How do Gemini CLI policy priority tiers work?#

Five tiers: default (1), extension (2), workspace (3), user (4) and admin (5). A rule's effective priority is its tier plus priority / 1000, so any admin rule beats any user rule, which beats extension and default rules. Settings such as tools.exclude become user-tier rules; "Always allow" answers land at 4.95 or 3.95.

What approval modes does Gemini CLI have?#

Four: default prompts for writes and shell commands, auto_edit also approves file edits, plan is read-only apart from writing plan files, and yolo approves everything your rules do not deny. Select one with --approval-mode, Shift+Tab or Ctrl+Y. In TOML policy files auto_edit is spelled autoEdit.

Why do my .gemini/policies files in the project do nothing?#

Gemini CLI 0.62.0 does not load workspace policy files. The CLI keeps workspace policies switched off by default and no command or setting turns them on, so rules in a project's .gemini/policies/ are ignored. Put them in ~/.gemini/policies/, pass them with --policy, or list their paths in policyPaths.

Release-by-release changes: Gemini CLI version tracker. All Gemini CLI pages: Gemini CLI reference index.