Gemini CLI settings.json Reference

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 reads settings.json from up to four files and merges them in a fixed order: system defaults, then the user file ~/.gemini/settings.json, then the project file .gemini/settings.json, then a system override file that beats both. Command-line flags such as --model and --approval-mode override the merged result for one session.

Where is Gemini CLI settings.json?#

On Windows the user file is %USERPROFILE%\.gemini\settings.json, since ~ is the home directory on every platform. Setting GEMINI_CLI_HOME moves the whole ~/.gemini tree. The project file is read only when the folder is trusted, so a cloned repository cannot change your settings until you trust it. The system override exists for administrators: anything set there wins over user and project values.

Precedence beyond the files: --model beats GEMINI_MODEL, which beats model.name; --approval-mode or --yolo beats general.defaultApprovalMode; --sandbox beats tools.sandbox.

How do settings from several files combine?#

Files are merged in the order above. Objects merge key by key, so a project file can change one field of general without restating the rest; single values and arrays from a later file replace earlier ones. These keys combine across files instead:

So hooks defined in ~/.gemini/settings.json and in a project's .gemini/settings.json both run, and mcpServers from both files are merged by server name, with the later file winning when both define the same server.

Can settings.json use environment variables?#

A value like "Authorization": "Bearer $MY_TOKEN" in an MCP server's headers, or "url": "${BASE_URL:-http://localhost:8080}/mcp", is resolved at load time, which keeps secrets out of files you commit.

Is there a JSON schema for settings.json?#

Yes. Every key below comes from the generated schema at schemas/settings.schema.json in the Gemini CLI repository. Point an editor at it with a $schema entry to get validation and completion:

{
  "$schema": "https://raw.githubusercontent.com/google-gemini/gemini-cli/main/schemas/settings.schema.json",
  "general": { "defaultApprovalMode": "auto_edit" },
  "hooksConfig": { "enabled": true }
}

Invalid values are reported with the file path when Gemini CLI starts. "Restart" in the table marks keys that only take effect in a new session.

How do I configure MCP servers in settings.json?#

mcpServers maps a server name to its connection. Use command and args for a local stdio server, url with type for SSE or HTTP, or httpUrl for streamable HTTP:

{
  "mcpServers": {
    "local-tools": {
      "command": "node",
      "args": ["./mcp/server.js"],
      "env": { "API_TOKEN": "$API_TOKEN" },
      "timeout": 30000
    },
    "remote": {
      "httpUrl": "https://mcp.example.com/mcp",
      "headers": { "Authorization": "Bearer $REMOTE_TOKEN" }
    }
  }
}

trust: true adds a policy rule that allows the server's tools without a prompt, outside plan mode. mcp.allowed and mcp.excluded allow or block servers by name.

All settings.json keys#

Frequently asked questions#

Where is the Gemini CLI settings.json file?#

Your user settings are in ~/.gemini/settings.json (on Windows %USERPROFILE%\.gemini\settings.json), and project settings in .gemini/settings.json at the project root. System-wide files live in /etc/gemini-cli/ on Linux, /Library/Application Support/GeminiCli/ on macOS and C:\ProgramData\gemini-cli\ on Windows: system-defaults.json below user settings and settings.json above everything.

Which settings file wins in Gemini CLI?#

The system override file wins, then the project .gemini/settings.json, then ~/.gemini/settings.json, then system-defaults.json, then built-in defaults. Hook arrays, mcpServers, tools.exclude, context.includeDirectories and a few other lists combine across files instead of replacing each other. Project settings are skipped entirely in untrusted folders.

How do I set a proxy for Gemini CLI?#

There is no proxy key in settings.json. Gemini CLI reads the proxy from the HTTPS_PROXY, https_proxy, HTTP_PROXY or http_proxy environment variable, taking the first one that is set. Export it in your shell profile, or put it in a .env file such as ~/.env; .env files supply it only in trusted folders.

How do I put an API key in Gemini CLI settings?#

Keep the key out of settings.json. Set GEMINI_API_KEY in your environment or in a .env file: ~/.env is always read, .gemini/.env files only in trusted folders. For values that must appear in settings, such as an MCP server token, write "$MY_TOKEN" or "${MY_TOKEN}" and the variable is substituted when the file loads.

Can I use comments in Gemini CLI settings.json?#

Yes. Gemini CLI strips JSON comments before parsing, so // and /* */ comments are allowed in every settings.json layer, and trustedFolders.json is read the same way. Editors that validate against the schema may still flag comments unless the file is opened as JSON with comments (JSONC).

Why are my project settings ignored?#

Project settings in .gemini/settings.json apply only in trusted folders. In an untrusted folder Gemini CLI merges system and user settings and skips the project file, along with its hooks. Trust the folder when prompted, add it to ~/.gemini/trustedFolders.json, or start with --skip-trust for a single session.

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