settings.json Reference

Gemini CLI uses JSON settings files for persistent configuration. Settings can be configured at multiple levels with different scopes and precedence.

Settings File Locations

Gemini CLI loads settings from multiple locations in order of precedence:

System Defaults

Provides base layer of system-wide default settingsLocations:

Linux: /etc/gemini-cli/system-defaults.json
Windows: C:\ProgramData\gemini-cli\system-defaults.json
macOS: /Library/Application Support/GeminiCli/system-defaults.json

Override with: GEMINI_CLI_SYSTEM_DEFAULTS_PATH environment variable

User Settings

Global settings for the current userLocation: ~/.gemini/settings.jsonApplies to all Gemini CLI sessions for the current user. Overrides system defaults.

Project Settings

Project-specific settingsLocation: .gemini/settings.json in your project rootApplies only when running Gemini CLI from that specific project. Overrides user settings.

System Settings

System-wide overrides (highest precedence)Locations:

Linux: /etc/gemini-cli/settings.json
Windows: C:\ProgramData\gemini-cli\settings.json
macOS: /Library/Application Support/GeminiCli/settings.json

Override with: GEMINI_CLI_SYSTEM_SETTINGS_PATH environment variable

JSON-aware editors can use autocomplete and validation by pointing to the schema at: https://raw.githubusercontent.com/google-gemini/gemini-cli/main/schemas/settings.schema.json

Environment Variable Substitution

String values in settings.json can reference environment variables using $VAR_NAME or ${VAR_NAME} syntax:

{
  "apiKey": "$MY_API_TOKEN",
  "model": {
    "name": "${GEMINI_MODEL}"
  }
}

General Settings

general.vimMode

boolean

default:"false"

Enable Vim keybindings in the CLI interface

general.defaultApprovalMode

enum

default:"default"

Default approval mode for tool executionOptions:

default - Prompts for approval on each tool call
auto_edit - Auto-approves edit tools
plan - Read-only mode (requires experimental planning)

general.preferredEditor

string

default:"undefined"

The preferred editor to open files in (e.g., code, vim, nano)

general.enableAutoUpdate

boolean

default:"true"

Enable automatic updates for Gemini CLI

general.enableNotifications

boolean

default:"false"

Enable run-event notifications for action-required prompts and session completion (macOS only)

general.maxAttempts

number

default:"10"

Maximum number of attempts for requests to the main chat model (cannot exceed 10)

general.plan.directory

string

default:"undefined"

Directory where planning artifacts are stored. Defaults to system temporary directory if not specified.

general.plan.modelRouting

boolean

default:"true"

Automatically switch between Pro and Flash models based on Plan Mode status

general.sessionRetention.enabled

boolean

default:"true"

Enable automatic session cleanup

general.sessionRetention.maxAge

string

default:"30d"

Automatically delete chats older than this time periodExamples: "30d", "7d", "24h", "1w"

UI Settings

ui.theme

string

default:"undefined"

Color theme for the UI. See the CLI themes guide for available options.

ui.autoThemeSwitching

boolean

default:"true"

Automatically switch between default light and dark themes based on terminal background color

ui.hideBanner

boolean

default:"false"

Hide the application banner at startup

ui.hideTips

boolean

default:"false"

Hide helpful tips in the UI

ui.hideContextSummary

boolean

default:"false"

Hide the context summary (GEMINI.md, MCP servers) above the input

ui.hideFooter

boolean

default:"false"

Hide the footer from the UI

ui.showLineNumbers

boolean

default:"true"

Show line numbers in the chat

ui.dynamicWindowTitle

boolean

default:"true"

Update the terminal window title with current status icons

Ready: ◇
Action Required: ✋
Working: ✦

ui.useAlternateBuffer

boolean

default:"false"

Use an alternate screen buffer for the UI, preserving shell history (requires restart)

ui.loadingPhrases

enum

default:"tips"

What to show while the model is workingOptions: tips, witty, all, off

Render output in plain-text to be more screen reader accessible (requires restart)

Model Settings

model.name

string

default:"undefined"

The Gemini model to use for conversationsExamples: gemini-3-pro-preview, gemini-2.5-flash, gemini-2.5-pro

model.maxSessionTurns

number

default:"-1"

Maximum number of user/model/tool turns to keep in a session. -1 means unlimited.

model.compressionThreshold

number

default:"0.5"

The fraction of context usage at which to trigger context compressionExamples: 0.2, 0.3, 0.5 (requires restart)

model.disableLoopDetection

boolean

default:"false"

Disable automatic detection and prevention of infinite loops (requires restart)

Context Settings

context.fileName

string | string[]

default:"undefined"

The name of the context file(s) to load into memoryExamples:

"context": {
  "fileName": "GEMINI.md"
}

"context": {
  "fileName": ["AGENTS.md", "CONTEXT.md", "GEMINI.md"]
}

context.includeDirectoryTree

boolean

default:"true"

Whether to include the directory tree of the current working directory in the initial request

context.discoveryMaxDirs

number

default:"200"

Maximum number of directories to search for memory files

context.includeDirectories

array

default:"[]"

Additional directories to include in the workspace contextExample:

"context": {
  "includeDirectories": ["../lib", "../docs", "~/shared/utils"]
}

context.loadMemoryFromIncludeDirectories

boolean

default:"false"

Controls how /memory refresh loads GEMINI.md files. When true, include directories are scanned.

context.fileFiltering.respectGitIgnore

boolean

default:"true"

Respect .gitignore files when searching (requires restart)

context.fileFiltering.respectGeminiIgnore

boolean

default:"true"

Respect .geminiignore files when searching (requires restart)

context.fileFiltering.enableRecursiveFileSearch

boolean

default:"true"

Enable recursive file search when completing @ references in the prompt (requires restart)

context.fileFiltering.customIgnoreFilePaths

array

default:"[]"

Additional ignore file paths to respect. Takes precedence over .geminiignore and .gitignore.Example:

"context": {
  "fileFiltering": {
    "customIgnoreFilePaths": [".myignore", "config/.exclude"]
  }
}

Tools Settings

tools.sandbox

boolean | string

default:"undefined"

Sandbox execution environment. Set to boolean to enable/disable, or provide a string path to a sandbox profile.Examples: true, false, "docker", "podman", "/path/to/profile"(Requires restart)

tools.shell.enableInteractiveShell

boolean

default:"true"

Use node-pty for an interactive shell experience (requires restart)

tools.shell.showColor

boolean

default:"false"

Show color in shell output

tools.useRipgrep

boolean

default:"true"

Use ripgrep for file content search instead of fallback implementation

tools.truncateToolOutputThreshold

number

default:"40000"

Maximum characters to show when truncating large tool outputs. Set to 0 or negative to disable.

tools.disableLLMCorrection

boolean

default:"true"

Disable LLM-based error correction for edit tools. When enabled, tools fail immediately if exact string matches are not found.

Security Settings

security.disableYoloMode

boolean

default:"false"

Disable YOLO mode, even if enabled by a flag (requires restart)

security.enablePermanentToolApproval

boolean

default:"false"

Enable the “Allow for all future sessions” option in tool confirmation dialogs

security.blockGitExtensions

boolean

default:"false"

Blocks installing and loading extensions from Git (requires restart)

security.folderTrust.enabled

boolean

default:"true"

Enable folder trust system (requires restart)

security.environmentVariableRedaction.enabled

boolean

default:"false"

Enable redaction of environment variables that may contain secrets (requires restart)

security.enableConseca

boolean

default:"false"

Enable context-aware security checker. Uses an LLM to dynamically generate and enforce security policies.

MCP Servers

Configure connections to Model-Context Protocol (MCP) servers for discovering custom tools.

mcpServers.<SERVER_NAME>

object

Configuration for a named MCP server

Show Server Configuration Properties

command (string, optional): Command to execute to start the MCP server
args (array of strings, optional): Arguments to pass to the command
env (object, optional): Environment variables for the server process
cwd (string, optional): Working directory for the server
url (string, optional): URL of an MCP server using Server-Sent Events (SSE)
httpUrl (string, optional): URL of an MCP server using streamable HTTP
headers (object, optional): HTTP headers to send with requests
timeout (number, optional): Timeout in milliseconds for requests
trust (boolean, optional): Trust this server and bypass tool confirmations
includeTools (array of strings, optional): Allowlist of tool names to include
excludeTools (array of strings, optional): Blocklist of tool names to exclude

Example:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "$GITHUB_TOKEN"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/files"]
    }
  }
}

Telemetry Settings

Configure logging and metrics collection for Gemini CLI.

telemetry.enabled

boolean

default:"false"

Whether telemetry is enabled

telemetry.target

string

default:"local"

Destination for collected telemetryOptions: local, gcp

telemetry.otlpEndpoint

string

The endpoint for the OTLP Exporter

telemetry.otlpProtocol

string

The protocol for the OTLP ExporterOptions: grpc, http

telemetry.logPrompts

boolean

default:"false"

Whether to include the content of user prompts in the logs

telemetry.outfile

string

File to write telemetry to when target is local

Skills & Hooks

skills.enabled

boolean

default:"true"

Enable Agent Skills (requires restart)

hooksConfig.enabled

boolean

default:"true"

Enable the hooks system. When disabled, no hooks will be executed. (requires restart)

hooksConfig.notifications

boolean

default:"true"

Show visual indicators when hooks are executing

Example Configuration

{
  "general": {
    "vimMode": true,
    "preferredEditor": "code",
    "sessionRetention": {
      "enabled": true,
      "maxAge": "30d",
      "maxCount": 100
    }
  },
  "ui": {
    "theme": "GitHub",
    "hideBanner": true,
    "hideTips": false,
    "customWittyPhrases": [
      "Connecting to AGI",
      "Optimizing neural pathways"
    ]
  },
  "model": {
    "name": "gemini-2.5-pro",
    "maxSessionTurns": 10,
    "compressionThreshold": 0.3
  },
  "context": {
    "fileName": ["CONTEXT.md", "GEMINI.md"],
    "includeDirectories": ["../lib", "~/shared/utils"],
    "fileFiltering": {
      "respectGitIgnore": true
    }
  },
  "tools": {
    "sandbox": "docker",
    "shell": {
      "showColor": true
    }
  },
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "$GITHUB_TOKEN"
      }
    }
  }
}

Environment Variables

Configure Gemini CLI using environment variables

GEMINI.md Files

Provide context with GEMINI.md files

MCP Server Setup

Integrate custom tools via MCP

Command Reference

All available slash commands

Command Reference

Configuration

Development

settings.json Reference

Settings File Locations

Environment Variable Substitution

General Settings

UI Settings

Model Settings

Context Settings

Tools Settings

Security Settings

MCP Servers

Telemetry Settings

Skills & Hooks

Example Configuration

Environment Variables

GEMINI.md Files

MCP Server Setup

Command Reference

Build docs developers (and LLMs) love

Command Reference

Configuration

Development

​Settings File Locations

​Environment Variable Substitution

​General Settings

​UI Settings

​Model Settings

​Context Settings

​Tools Settings

​Security Settings

​MCP Servers

​Telemetry Settings

​Skills & Hooks

​Example Configuration

​Related Resources

Environment Variables

GEMINI.md Files

MCP Server Setup

Command Reference

Build docs developers (and LLMs) love

Settings File Locations

Environment Variable Substitution

General Settings

UI Settings

Model Settings

Context Settings

Tools Settings

Security Settings

MCP Servers

Telemetry Settings

Skills & Hooks

Example Configuration

Related Resources