Gemini CLI reference - Config files
Gemini CLI config files and locations
Gemini CLI documents 15 config files, including ~/.gemini/settings.json, .gemini/settings.json and /etc/gemini-cli/system-defaults.json. These are the files and directories Gemini CLI reads its configuration from. Each row gives the docs' description, accepted values and an example where one is documented.
Last verified 9 official pagesFull Gemini CLI reference
| Path | Description |
|---|---|
~/.gemini/settings.json | User settings file; applies to all sessions for the current user. Docs: ~/.gemini/settings.json |
.gemini/settings.json | Project settings file; overrides user settings and system defaults. Docs: .gemini/settings.json |
/etc/gemini-cli/system-defaults.json | System defaults file (lowest precedence). macOS: /Library/Application Support/GeminiCli/system-defaults.json; Windows: C:\ProgramData\gemini-cli\system-defaults.json. Docs: /etc/gemini-cli/system-defaults.json |
/etc/gemini-cli/settings.json | System settings file that overrides all other settings files. macOS and Windows equivalents under GeminiCli / ProgramData. Docs: /etc/gemini-cli/settings.json |
.env / .gemini/.env | .env is searched from the cwd up to project root or home, then ~/.env. Variables from .gemini/.env are never excluded. Docs: .env / .gemini/.env |
~/.gemini/trustedFolders.json | Central store of folder trust decisions. Docs: ~/.gemini/trustedFolders.json |
~/.gemini/keybindings.json | JSON array of {command, key|keys} entries; prefix a command with - to unbind. Docs: ~/.gemini/keybindings.json |
GEMINI.md | Default hierarchical context file (global ~/.gemini/GEMINI.md plus project files); name configurable via context.fileName. Docs: GEMINI.md |
.geminiignore | Excludes files and directories from Gemini CLI tools, similar to .gitignore. Docs: .geminiignore |
~/.gemini/commands/ and <project>/.gemini/commands/ | Custom command .toml files; project commands override user commands with the same name. Docs: ~/.gemini/commands/ and <project>/.gemini/commands/ |
~/.gemini/skills/ and .gemini/skills/ | User skills (alias ~/.agents/skills/) and workspace skills directories. Docs: ~/.gemini/skills/ and .gemini/skills/ |
~/.gemini/policies/*.toml | User-tier policy files. Admin tier: /etc/gemini-cli/policies (Linux); workspace tier currently disabled. Docs: ~/.gemini/policies/*.toml |
gemini-extension.json | Extension manifest in ~/.gemini/extensions/<name>/ (name, version, mcpServers, contextFileName, excludeTools, settings). Docs: gemini-extension.json |
~/.gemini/mcp-server-enablement.json | Stores MCP server enablement state. Docs: ~/.gemini/mcp-server-enablement.json |
.gemini/sandbox.Dockerfile | Custom sandbox Dockerfile, built when BUILD_SANDBOX is set. Docs: .gemini/sandbox.Dockerfile |
The rest of the Gemini CLI reference
FAQ
How many config files does Gemini CLI have?
The official Gemini CLI docs list 15 config files, including ~/.gemini/settings.json, .gemini/settings.json and /etc/gemini-cli/system-defaults.json. All of them are in the table above, in the docs' order.
What does ~/.gemini/settings.json do in Gemini CLI?
User settings file; applies to all sessions for the current user.
Where are Gemini CLI config files documented?
On 9 official docs pages at github.com, last read on October 17, 2026. Every row in the table links the exact section it came from.
More on Gemini CLI
Sources
Last verified . Names and examples are copied verbatim from the 9 official pages below, and every row above links the exact section it came from.
- github.com/google-gemini/gemini-cli/blob/main/docs/reference/configuration.md7 items
- github.com/google-gemini/gemini-cli/blob/main/docs/cli/trusted-folders.md1 item
- github.com/google-gemini/gemini-cli/blob/main/docs/reference/keyboard-shortcuts.md1 item
- github.com/google-gemini/gemini-cli/blob/main/docs/cli/gemini-ignore.md1 item
- github.com/google-gemini/gemini-cli/blob/main/docs/cli/custom-commands.md1 item
- github.com/google-gemini/gemini-cli/blob/main/docs/cli/skills.md1 item
- github.com/google-gemini/gemini-cli/blob/main/docs/reference/policy-engine.md1 item
- github.com/google-gemini/gemini-cli/blob/main/docs/extensions/reference.md1 item
- github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md1 item
Newsletter
Know when your tools change
One email per week. New coding agent releases, the flags and commands they add, and what they mean for how you work.