docs/reference/configuration.md
Gemini CLI offers several ways to configure its behavior, including environment variables, command-line arguments, and settings files. This document outlines the different configuration methods and available settings.
Configuration is applied in the following order of precedence (lower numbers are overridden by higher numbers):
.env files.Gemini CLI uses JSON settings files for persistent configuration. There are four locations for these files:
<!-- prettier-ignore -->[!TIP] JSON-aware editors can use autocomplete and validation by pointing to the generated schema at
schemas/settings.schema.jsonin this repository. When working outside the repo, reference the hosted schema athttps://raw.githubusercontent.com/google-gemini/gemini-cli/main/schemas/settings.schema.json.
/etc/gemini-cli/system-defaults.json (Linux),
C:\ProgramData\gemini-cli\system-defaults.json (Windows) or
/Library/Application Support/GeminiCli/system-defaults.json (macOS). The
path can be overridden using the GEMINI_CLI_SYSTEM_DEFAULTS_PATH
environment variable.~/.gemini/settings.json (where ~ is your home directory)..gemini/settings.json within your project's root directory./etc/gemini-cli/settings.json (Linux),
C:\ProgramData\gemini-cli\settings.json (Windows) or
/Library/Application Support/GeminiCli/settings.json (macOS). The path can
be overridden using the GEMINI_CLI_SYSTEM_SETTINGS_PATH environment
variable.Note on environment variables in settings: String values within your
settings.json and gemini-extension.json files can reference environment
variables using $VAR_NAME, ${VAR_NAME}, or ${VAR_NAME:-DEFAULT_VALUE}
syntax. These variables will be automatically resolved when the settings are
loaded. For example, if you have an environment variable MY_API_TOKEN, you
could use it in settings.json like this: "apiKey": "$MY_API_TOKEN". If you
want to provide a fallback value, use ${MY_API_TOKEN:-default-token}.
Additionally, each extension can have its own .env file in its directory,
which will be loaded automatically.
Note for Enterprise Users: For guidance on deploying and managing Gemini CLI in a corporate environment, see the Enterprise Configuration documentation.
.gemini directory in your projectIn addition to a project settings file, a project's .gemini directory can
contain other project-specific files related to Gemini CLI's operation, such as:
.gemini/sandbox-macos-custom.sb, .gemini/sandbox.Dockerfile).settings.jsonSettings are organized into categories. All settings should be placed within
their corresponding top-level category object in your settings.json file.
policyPathspolicyPaths (array):
[]adminPolicyPathsadminPolicyPaths (array):
[]generalgeneral.preferredEditor (string):
undefinedgeneral.vimMode (boolean):
falsegeneral.defaultApprovalMode (enum):
"default""default", "auto_edit", "plan"general.devtools (boolean):
falsegeneral.enableAutoUpdate (boolean):
truegeneral.enableAutoUpdateNotification (boolean):
truegeneral.enableNotifications (boolean):
falsegeneral.notificationMethod (enum):
"auto""auto", "osc9", "osc777", "bell"general.checkpointing.enabled (boolean):
falsegeneral.plan.enabled (boolean):
truegeneral.plan.directory (string):
undefinedgeneral.plan.modelRouting (boolean):
truegeneral.retryFetchErrors (boolean):
truegeneral.maxAttempts (number):
10general.debugKeystrokeLogging (boolean):
falsegeneral.sessionRetention.enabled (boolean):
truegeneral.sessionRetention.maxAge (string):
"30d"general.sessionRetention.maxCount (number):
undefinedgeneral.sessionRetention.minRetention (string):
"1d"general.topicUpdateNarration (boolean):
trueoutputoutput.format (enum):
text or json."text""text", "json"uiui.debugRainbow (boolean):
falseui.theme (string):
undefinedui.autoThemeSwitching (boolean):
trueui.terminalBackgroundPollingInterval (number):
60ui.customThemes (object):
{}ui.hideWindowTitle (boolean):
falseui.inlineThinkingMode (enum):
"off""off", "full"ui.showStatusInTitle (boolean):
falseui.dynamicWindowTitle (boolean):
trueui.showHomeDirectoryWarning (boolean):
trueui.showCompatibilityWarnings (boolean):
trueui.hideTips (boolean):
falseui.escapePastedAtSymbols (boolean):
falseui.showShortcutsHint (boolean):
trueui.compactToolOutput (boolean):
trueui.hideBanner (boolean):
falseui.hideContextSummary (boolean):
falseui.footer.items (array):
undefinedui.footer.showLabels (boolean):
trueui.footer.hideCWD (boolean):
falseui.footer.hideSandboxStatus (boolean):
falseui.footer.hideModelInfo (boolean):
falseui.footer.hideContextPercentage (boolean):
trueui.hideFooter (boolean):
falseui.collapseDrawerDuringApproval (boolean):
trueui.showMemoryUsage (boolean):
falseui.showLineNumbers (boolean):
trueui.showCitations (boolean):
falseui.showModelInfoInChat (boolean):
falseui.showUserIdentity (boolean):
trueui.useAlternateBuffer (boolean):
falseui.renderProcess (boolean):
trueui.terminalBuffer (boolean):
falseui.useBackgroundColor (boolean):
trueui.incrementalRendering (boolean):
trueui.showSpinner (boolean):
trueui.loadingPhrases (enum):
"off""tips", "witty", "all", "off"ui.errorVerbosity (enum):
"low""low", "full"ui.customWittyPhrases (array):
[]ui.accessibility.enableLoadingPhrases (boolean):
trueui.accessibility.screenReader (boolean):
falseideide.enabled (boolean):
falseide.hasSeenNudge (boolean):
falseprivacyprivacy.usageStatisticsEnabled (boolean):
truebillingbilling.overageStrategy (enum):
"ask""ask", "always", "never"billing.vertexAi.requestType (enum):
undefined"dedicated", "shared"billing.vertexAi.sharedRequestType (enum):
undefined"priority", "flex"modelmodel.name (string):
undefinedmodel.maxSessionTurns (number):
-1model.summarizeToolOutput (object):
undefinedmodel.compressionThreshold (number):
0.5model.disableLoopDetection (boolean):
falsemodel.skipNextSpeakerCheck (boolean):
truemodelConfigsmodelConfigs.aliases (object):
Description: Named presets for model configs. Can be used in place of a
model name and can inherit from other aliases using an extends property.
Default:
{
"base": {
"modelConfig": {
"generateContentConfig": {
"temperature": 0,
"topP": 1
}
}
},
"chat-base": {
"extends": "base",
"modelConfig": {
"generateContentConfig": {
"thinkingConfig": {
"includeThoughts": true
},
"temperature": 1,
"topP": 0.95,
"topK": 64
}
}
},
"chat-base-2.5": {
"extends": "chat-base",
"modelConfig": {
"generateContentConfig": {
"thinkingConfig": {
"thinkingBudget": 8192
}
}
}
},
"chat-base-3": {
"extends": "chat-base",
"modelConfig": {
"generateContentConfig": {
"thinkingConfig": {
"thinkingLevel": "HIGH"
}
}
}
},
"gemini-3-pro-preview": {
"extends": "chat-base-3",
"modelConfig": {
"model": "gemini-3-pro-preview"
}
},
"gemini-3-flash-preview": {
"extends": "chat-base-3",
"modelConfig": {
"model": "gemini-3-flash-preview"
}
},
"gemini-2.5-pro": {
"extends": "chat-base-2.5",
"modelConfig": {
"model": "gemini-2.5-pro"
}
},
"gemini-2.5-flash": {
"extends": "chat-base-2.5",
"modelConfig": {
"model": "gemini-2.5-flash"
}
},
"gemini-2.5-flash-lite": {
"extends": "chat-base-2.5",
"modelConfig": {
"model": "gemini-2.5-flash-lite"
}
},
"gemma-4-31b-it": {
"extends": "chat-base-3",
"modelConfig": {
"model": "gemma-4-31b-it"
}
},
"gemma-4-26b-a4b-it": {
"extends": "chat-base-3",
"modelConfig": {
"model": "gemma-4-26b-a4b-it"
}
},
"gemini-2.5-flash-base": {
"extends": "base",
"modelConfig": {
"model": "gemini-2.5-flash"
}
},
"gemini-3-flash-base": {
"extends": "base",
"modelConfig": {
"model": "gemini-3-flash-preview"
}
},
"classifier": {
"extends": "base",
"modelConfig": {
"model": "gemini-2.5-flash-lite",
"generateContentConfig": {
"maxOutputTokens": 1024,
"thinkingConfig": {
"thinkingBudget": 512
}
}
}
},
"prompt-completion": {
"extends": "base",
"modelConfig": {
"model": "gemini-2.5-flash-lite",
"generateContentConfig": {
"temperature": 0.3,
"maxOutputTokens": 16000,
"thinkingConfig": {
"thinkingBudget": 0
}
}
}
},
"fast-ack-helper": {
"extends": "base",
"modelConfig": {
"model": "gemini-2.5-flash-lite",
"generateContentConfig": {
"temperature": 0.2,
"maxOutputTokens": 120,
"thinkingConfig": {
"thinkingBudget": 0
}
}
}
},
"edit-corrector": {
"extends": "base",
"modelConfig": {
"model": "gemini-2.5-flash-lite",
"generateContentConfig": {
"thinkingConfig": {
"thinkingBudget": 0
}
}
}
},
"summarizer-default": {
"extends": "base",
"modelConfig": {
"model": "gemini-2.5-flash-lite",
"generateContentConfig": {
"maxOutputTokens": 2000
}
}
},
"summarizer-shell": {
"extends": "base",
"modelConfig": {
"model": "gemini-2.5-flash-lite",
"generateContentConfig": {
"maxOutputTokens": 2000
}
}
},
"web-search": {
"extends": "gemini-3-flash-base",
"modelConfig": {
"generateContentConfig": {
"tools": [
{
"googleSearch": {}
}
]
}
}
},
"web-fetch": {
"extends": "gemini-3-flash-base",
"modelConfig": {
"generateContentConfig": {
"tools": [
{
"urlContext": {}
}
]
}
}
},
"web-fetch-fallback": {
"extends": "gemini-3-flash-base",
"modelConfig": {}
},
"loop-detection": {
"extends": "gemini-3-flash-base",
"modelConfig": {}
},
"loop-detection-double-check": {
"extends": "base",
"modelConfig": {
"model": "gemini-3-pro-preview"
}
},
"llm-edit-fixer": {
"extends": "gemini-3-flash-base",
"modelConfig": {}
},
"next-speaker-checker": {
"extends": "gemini-3-flash-base",
"modelConfig": {}
},
"chat-compression-3-pro": {
"modelConfig": {
"model": "gemini-3-pro-preview"
}
},
"chat-compression-3-flash": {
"modelConfig": {
"model": "gemini-3-flash-preview"
}
},
"chat-compression-3.1-flash-lite": {
"modelConfig": {
"model": "gemini-3.1-flash-lite-preview"
}
},
"chat-compression-2.5-pro": {
"modelConfig": {
"model": "gemini-2.5-pro"
}
},
"chat-compression-2.5-flash": {
"modelConfig": {
"model": "gemini-2.5-flash"
}
},
"chat-compression-2.5-flash-lite": {
"modelConfig": {
"model": "gemini-2.5-flash-lite"
}
},
"chat-compression-default": {
"modelConfig": {
"model": "gemini-3-pro-preview"
}
},
"agent-history-provider-summarizer": {
"modelConfig": {
"model": "gemini-3-flash-preview"
}
}
}
modelConfigs.customAliases (object):
{}modelConfigs.customOverrides (array):
[]modelConfigs.overrides (array):
[]modelConfigs.modelDefinitions (object):
Description: Registry of model metadata, including tier, family, and features.
Default:
{
"gemini-3.1-flash-lite-preview": {
"tier": "flash-lite",
"family": "gemini-3",
"isPreview": true,
"isVisible": true,
"features": {
"thinking": false,
"multimodalToolUse": true
}
},
"gemini-3.1-pro-preview": {
"tier": "pro",
"family": "gemini-3",
"isPreview": true,
"isVisible": true,
"features": {
"thinking": true,
"multimodalToolUse": true
}
},
"gemini-3.1-pro-preview-customtools": {
"tier": "pro",
"family": "gemini-3",
"isPreview": true,
"isVisible": false,
"features": {
"thinking": true,
"multimodalToolUse": true
}
},
"gemini-3-pro-preview": {
"tier": "pro",
"family": "gemini-3",
"isPreview": true,
"isVisible": true,
"features": {
"thinking": true,
"multimodalToolUse": true
}
},
"gemini-3-flash-preview": {
"tier": "flash",
"family": "gemini-3",
"isPreview": true,
"isVisible": true,
"features": {
"thinking": false,
"multimodalToolUse": true
}
},
"gemini-2.5-pro": {
"tier": "pro",
"family": "gemini-2.5",
"isPreview": false,
"isVisible": true,
"features": {
"thinking": false,
"multimodalToolUse": false
}
},
"gemini-2.5-flash": {
"tier": "flash",
"family": "gemini-2.5",
"isPreview": false,
"isVisible": true,
"features": {
"thinking": false,
"multimodalToolUse": false
}
},
"gemini-2.5-flash-lite": {
"tier": "flash-lite",
"family": "gemini-2.5",
"isPreview": false,
"isVisible": true,
"features": {
"thinking": false,
"multimodalToolUse": false
}
},
"gemma-4-31b-it": {
"displayName": "gemma-4-31b-it",
"tier": "custom",
"family": "gemma-4",
"isPreview": false,
"isVisible": true,
"features": {
"thinking": true,
"multimodalToolUse": false
}
},
"gemma-4-26b-a4b-it": {
"displayName": "gemma-4-26b-a4b-it",
"tier": "custom",
"family": "gemma-4",
"isPreview": false,
"isVisible": true,
"features": {
"thinking": true,
"multimodalToolUse": false
}
},
"auto": {
"tier": "auto",
"isPreview": true,
"isVisible": false,
"features": {
"thinking": true,
"multimodalToolUse": false
}
},
"pro": {
"tier": "pro",
"isPreview": false,
"isVisible": false,
"features": {
"thinking": true,
"multimodalToolUse": false
}
},
"flash": {
"tier": "flash",
"isPreview": false,
"isVisible": false,
"features": {
"thinking": false,
"multimodalToolUse": false
}
},
"flash-lite": {
"tier": "flash-lite",
"isPreview": false,
"isVisible": false,
"features": {
"thinking": false,
"multimodalToolUse": false
}
},
"auto-gemini-3": {
"displayName": "Auto (Gemini 3)",
"tier": "auto",
"isPreview": true,
"isVisible": true,
"dialogDescription": "Let Gemini CLI decide the best model for the task: gemini-3-pro, gemini-3-flash",
"features": {
"thinking": true,
"multimodalToolUse": false
}
},
"auto-gemini-2.5": {
"displayName": "Auto (Gemini 2.5)",
"tier": "auto",
"isPreview": false,
"isVisible": true,
"dialogDescription": "Let Gemini CLI decide the best model for the task: gemini-2.5-pro, gemini-2.5-flash",
"features": {
"thinking": false,
"multimodalToolUse": false
}
}
}
Requires restart: Yes
modelConfigs.modelIdResolutions (object):
Description: Rules for resolving requested model names to concrete model IDs based on context.
Default:
{
"gemma-4-31b-it": {
"default": "gemma-4-31b-it"
},
"gemma-4-26b-a4b-it": {
"default": "gemma-4-26b-a4b-it"
},
"gemini-3.1-pro-preview": {
"default": "gemini-3.1-pro-preview",
"contexts": [
{
"condition": {
"hasAccessToPreview": false
},
"target": "gemini-2.5-pro"
},
{
"condition": {
"useCustomTools": true
},
"target": "gemini-3.1-pro-preview-customtools"
}
]
},
"gemini-3.1-pro-preview-customtools": {
"default": "gemini-3.1-pro-preview-customtools",
"contexts": [
{
"condition": {
"hasAccessToPreview": false
},
"target": "gemini-2.5-pro"
}
]
},
"gemini-3-flash-preview": {
"default": "gemini-3-flash-preview",
"contexts": [
{
"condition": {
"hasAccessToPreview": false
},
"target": "gemini-2.5-flash"
}
]
},
"gemini-3-pro-preview": {
"default": "gemini-3-pro-preview",
"contexts": [
{
"condition": {
"hasAccessToPreview": false
},
"target": "gemini-2.5-pro"
},
{
"condition": {
"useGemini3_1": true,
"useCustomTools": true
},
"target": "gemini-3.1-pro-preview-customtools"
},
{
"condition": {
"useGemini3_1": true
},
"target": "gemini-3.1-pro-preview"
}
]
},
"auto-gemini-3": {
"default": "gemini-3-pro-preview",
"contexts": [
{
"condition": {
"hasAccessToPreview": false
},
"target": "gemini-2.5-pro"
},
{
"condition": {
"useGemini3_1": true,
"useCustomTools": true
},
"target": "gemini-3.1-pro-preview-customtools"
},
{
"condition": {
"useGemini3_1": true
},
"target": "gemini-3.1-pro-preview"
}
]
},
"auto": {
"default": "gemini-3-pro-preview",
"contexts": [
{
"condition": {
"hasAccessToPreview": false
},
"target": "gemini-2.5-pro"
},
{
"condition": {
"useGemini3_1": true,
"useCustomTools": true
},
"target": "gemini-3.1-pro-preview-customtools"
},
{
"condition": {
"useGemini3_1": true
},
"target": "gemini-3.1-pro-preview"
}
]
},
"pro": {
"default": "gemini-3-pro-preview",
"contexts": [
{
"condition": {
"hasAccessToPreview": false
},
"target": "gemini-2.5-pro"
},
{
"condition": {
"useGemini3_1": true,
"useCustomTools": true
},
"target": "gemini-3.1-pro-preview-customtools"
},
{
"condition": {
"useGemini3_1": true
},
"target": "gemini-3.1-pro-preview"
}
]
},
"auto-gemini-2.5": {
"default": "gemini-2.5-pro"
},
"gemini-3.1-flash-lite-preview": {
"default": "gemini-3.1-flash-lite-preview",
"contexts": [
{
"condition": {
"useGemini3_1FlashLite": false
},
"target": "gemini-2.5-flash-lite"
}
]
},
"flash": {
"default": "gemini-3-flash-preview",
"contexts": [
{
"condition": {
"hasAccessToPreview": false
},
"target": "gemini-2.5-flash"
}
]
},
"flash-lite": {
"default": "gemini-2.5-flash-lite",
"contexts": [
{
"condition": {
"useGemini3_1FlashLite": true
},
"target": "gemini-3.1-flash-lite-preview"
}
]
}
}
Requires restart: Yes
modelConfigs.classifierIdResolutions (object):
Description: Rules for resolving classifier tiers (flash, pro) to concrete model IDs.
Default:
{
"flash": {
"default": "gemini-3-flash-preview",
"contexts": [
{
"condition": {
"requestedModels": ["auto-gemini-2.5", "gemini-2.5-pro"]
},
"target": "gemini-2.5-flash"
},
{
"condition": {
"requestedModels": ["auto-gemini-3", "gemini-3-pro-preview"]
},
"target": "gemini-3-flash-preview"
}
]
},
"pro": {
"default": "gemini-3-pro-preview",
"contexts": [
{
"condition": {
"requestedModels": ["auto-gemini-2.5", "gemini-2.5-pro"]
},
"target": "gemini-2.5-pro"
},
{
"condition": {
"useGemini3_1": true,
"useCustomTools": true
},
"target": "gemini-3.1-pro-preview-customtools"
},
{
"condition": {
"useGemini3_1": true
},
"target": "gemini-3.1-pro-preview"
}
]
}
}
Requires restart: Yes
modelConfigs.modelChains (object):
Description: Availability policy chains defining fallback behavior for models.
Default:
{
"preview": [
{
"model": "gemini-3-pro-preview",
"actions": {
"terminal": "prompt",
"transient": "prompt",
"not_found": "prompt",
"unknown": "prompt"
},
"stateTransitions": {
"terminal": "terminal",
"transient": "sticky_retry",
"not_found": "terminal",
"unknown": "terminal"
}
},
{
"model": "gemini-3-flash-preview",
"isLastResort": true,
"actions": {
"terminal": "prompt",
"transient": "prompt",
"not_found": "prompt",
"unknown": "prompt"
},
"stateTransitions": {
"terminal": "terminal",
"transient": "sticky_retry",
"not_found": "terminal",
"unknown": "terminal"
}
}
],
"default": [
{
"model": "gemini-2.5-pro",
"actions": {
"terminal": "prompt",
"transient": "prompt",
"not_found": "prompt",
"unknown": "prompt"
},
"stateTransitions": {
"terminal": "terminal",
"transient": "sticky_retry",
"not_found": "terminal",
"unknown": "terminal"
}
},
{
"model": "gemini-2.5-flash",
"isLastResort": true,
"actions": {
"terminal": "prompt",
"transient": "prompt",
"not_found": "prompt",
"unknown": "prompt"
},
"stateTransitions": {
"terminal": "terminal",
"transient": "sticky_retry",
"not_found": "terminal",
"unknown": "terminal"
}
}
],
"lite": [
{
"model": "gemini-2.5-flash-lite",
"actions": {
"terminal": "silent",
"transient": "silent",
"not_found": "silent",
"unknown": "silent"
},
"stateTransitions": {
"terminal": "terminal",
"transient": "sticky_retry",
"not_found": "terminal",
"unknown": "terminal"
}
},
{
"model": "gemini-2.5-flash",
"actions": {
"terminal": "silent",
"transient": "silent",
"not_found": "silent",
"unknown": "silent"
},
"stateTransitions": {
"terminal": "terminal",
"transient": "sticky_retry",
"not_found": "terminal",
"unknown": "terminal"
}
},
{
"model": "gemini-2.5-pro",
"isLastResort": true,
"actions": {
"terminal": "silent",
"transient": "silent",
"not_found": "silent",
"unknown": "silent"
},
"stateTransitions": {
"terminal": "terminal",
"transient": "sticky_retry",
"not_found": "terminal",
"unknown": "terminal"
}
}
]
}
Requires restart: Yes
agentsagents.overrides (object):
{}agents.browser.sessionMode (enum):
"persistent""persistent", "isolated", "existing"agents.browser.headless (boolean):
falseagents.browser.profilePath (string):
undefinedagents.browser.visualModel (string):
undefinedagents.browser.allowedDomains (array):
Description: A list of allowed domains for the browser agent (e.g., ["github.com", "*.google.com"]).
Default:
["github.com", "*.google.com", "localhost"]
Requires restart: Yes
agents.browser.disableUserInput (boolean):
trueagents.browser.maxActionsPerTask (number):
100agents.browser.confirmSensitiveActions (boolean):
falseagents.browser.blockFileUploads (boolean):
falsecontextcontext.fileName (string | string[]):
undefinedcontext.importFormat (string):
undefinedcontext.includeDirectoryTree (boolean):
truecontext.discoveryMaxDirs (number):
200context.memoryBoundaryMarkers (array):
Description: File or directory names that mark the boundary for GEMINI.md discovery. The upward traversal stops at the first directory containing any of these markers. An empty array disables parent traversal.
Default:
[".git"]
Requires restart: Yes
context.includeDirectories (array):
[]context.loadMemoryFromIncludeDirectories (boolean):
falsecontext.fileFiltering.respectGitIgnore (boolean):
truecontext.fileFiltering.respectGeminiIgnore (boolean):
truecontext.fileFiltering.enableFileWatcher (boolean):
falsecontext.fileFiltering.enableRecursiveFileSearch (boolean):
truecontext.fileFiltering.enableFuzzySearch (boolean):
truecontext.fileFiltering.customIgnoreFilePaths (array):
[]toolstools.sandbox (string):
undefinedtools.sandboxAllowedPaths (array):
[]tools.sandboxNetworkAccess (boolean):
falsetools.shell.enableInteractiveShell (boolean):
truetools.shell.backgroundCompletionBehavior (enum):
"silent""silent", "inject", "notify"tools.shell.pager (string):
cat."cat"tools.shell.showColor (boolean):
truetools.shell.inactivityTimeout (number):
300tools.shell.enableShellOutputEfficiency (boolean):
truetools.core (array):
undefinedtools.allowed (array):
undefinedtools.confirmationRequired (array):
undefinedtools.exclude (array):
undefinedtools.discoveryCommand (string):
undefinedtools.callCommand (string):
undefinedtools.useRipgrep (boolean):
truetools.truncateToolOutputThreshold (number):
40000tools.disableLLMCorrection (boolean):
truemcpmcp.serverCommand (string):
undefinedmcp.allowed (array):
undefinedmcp.excluded (array):
undefineduseWriteTodosuseWriteTodos (boolean):
truesecuritysecurity.toolSandboxing (boolean):
falsesecurity.disableYoloMode (boolean):
falsesecurity.disableAlwaysAllow (boolean):
falsesecurity.enablePermanentToolApproval (boolean):
falsesecurity.autoAddToPolicyByDefault (boolean):
falsesecurity.blockGitExtensions (boolean):
falsesecurity.allowedExtensions (array):
[]security.folderTrust.enabled (boolean):
truesecurity.environmentVariableRedaction.allowed (array):
[]security.environmentVariableRedaction.blocked (array):
[]security.environmentVariableRedaction.enabled (boolean):
falsesecurity.auth.selectedType (string):
undefinedsecurity.auth.enforcedType (string):
undefinedsecurity.auth.useExternal (boolean):
undefinedsecurity.enableConseca (boolean):
falseadvancedadvanced.autoConfigureMemory (boolean):
trueadvanced.dnsResolutionOrder (string):
undefinedadvanced.excludedEnvVars (array):
Description: Environment variables to exclude from project context.
Default:
["DEBUG", "DEBUG_MODE"]
advanced.bugCommand (object):
undefinedexperimentalexperimental.gemma (boolean):
falseexperimental.voiceMode (boolean):
falseexperimental.voice.activationMode (enum):
"push-to-talk""push-to-talk", "toggle"experimental.voice.backend (enum):
"gemini-live""gemini-live", "whisper"experimental.voice.whisperModel (enum):
"ggml-base.en.bin""ggml-tiny.en.bin", "ggml-base.en.bin",
"ggml-large-v3-turbo-q5_0.bin", "ggml-large-v3-turbo-q8_0.bin"experimental.voice.stopGracePeriodMs (number):
1000experimental.adk.agentSessionNoninteractiveEnabled (boolean):
falseexperimental.adk.agentSessionInteractiveEnabled (boolean):
falseexperimental.enableAgents (boolean):
trueexperimental.worktrees (boolean):
falseexperimental.extensionManagement (boolean):
trueexperimental.extensionConfig (boolean):
trueexperimental.extensionRegistry (boolean):
falseexperimental.extensionRegistryURI (string):
"https://geminicli.com/extensions.json"experimental.extensionReloading (boolean):
falseexperimental.jitContext (boolean):
trueexperimental.useOSC52Paste (boolean):
falseexperimental.useOSC52Copy (boolean):
falseexperimental.taskTracker (boolean):
falseexperimental.modelSteering (boolean):
falseexperimental.directWebFetch (boolean):
falseexperimental.dynamicModelConfiguration (boolean):
falseexperimental.gemmaModelRouter.enabled (boolean):
falseexperimental.gemmaModelRouter.autoStartServer (boolean):
falseexperimental.gemmaModelRouter.binaryPath (string):
""experimental.gemmaModelRouter.classifier.host (string):
"http://localhost:9379"experimental.gemmaModelRouter.classifier.model (string):
gemma3-1b-gpu-custom."gemma3-1b-gpu-custom"experimental.memoryV2 (boolean):
trueexperimental.stressTestProfile (boolean):
falseexperimental.autoMemory (boolean):
falseexperimental.generalistProfile (boolean):
falseexperimental.contextManagement (boolean):
falseexperimental.topicUpdateNarration (boolean):
falseskillsskills.enabled (boolean):
trueskills.disabled (array):
[]hooksConfighooksConfig.enabled (boolean):
truehooksConfig.disabled (array):
[]hooksConfig.notifications (boolean):
truehookshooks.BeforeTool (array):
[]hooks.AfterTool (array):
[]hooks.BeforeAgent (array):
[]hooks.AfterAgent (array):
[]hooks.Notification (array):
[]hooks.SessionStart (array):
[]hooks.SessionEnd (array):
[]hooks.PreCompress (array):
[]hooks.BeforeModel (array):
[]hooks.AfterModel (array):
[]hooks.BeforeToolSelection (array):
[]contextManagementcontextManagement.historyWindow.maxTokens (number):
150000contextManagement.historyWindow.retainedTokens (number):
40000contextManagement.messageLimits.normalMaxTokens (number):
2500contextManagement.messageLimits.retainedMaxTokens (number):
12000contextManagement.messageLimits.normalizationHeadRatio (number):
0.25contextManagement.tools.distillation.maxOutputTokens (number):
10000contextManagement.tools.distillation.summarizationThresholdTokens
(number):
20000contextManagement.tools.outputMasking.protectionThresholdTokens
(number):
50000contextManagement.tools.outputMasking.minPrunableThresholdTokens
(number):
30000contextManagement.tools.outputMasking.protectLatestTurn (boolean):
trueadminadmin.secureModeEnabled (boolean):
falseadmin.extensions.enabled (boolean):
trueadmin.mcp.enabled (boolean):
trueadmin.mcp.config (object):
{}admin.mcp.requiredConfig (object):
{}admin.skills.enabled (boolean):
truemcpServersConfigures connections to one or more Model-Context Protocol (MCP) servers for
discovering and using custom tools. Gemini CLI attempts to connect to each
configured MCP server to discover available tools. Every discovered tool is
prepended with the mcp_ prefix and its server alias to form a fully qualified
name (FQN) (for example, mcp_serverAlias_actualToolName) to avoid conflicts.
Note that the system might strip certain schema properties from MCP tool
definitions for compatibility. At least one of command, url, or httpUrl
must be provided. If multiple are specified, the order of precedence is
httpUrl, then url, then command.
[!WARNING] Avoid using underscores (
_) in your server aliases (for example, usemy-serverinstead ofmy_server). The underlying policy engine parses Fully Qualified Names (mcp_server_tool) using the first underscore after themcp_prefix. An underscore in your server alias will cause the parser to misidentify the server name, which can cause security policies to fail silently.
mcpServers.<SERVER_NAME> (object): The server parameters for the named
server.
command (string, optional): The command to execute to start the MCP server
via standard I/O.args (array of strings, optional): Arguments to pass to the command.env (object, optional): Environment variables to set for the server
process.cwd (string, optional): The working directory in which to start the
server.url (string, optional): The URL of an MCP server that uses Server-Sent
Events (SSE) for communication.httpUrl (string, optional): The URL of an MCP server that uses streamable
HTTP for communication.headers (object, optional): A map of HTTP headers to send with requests to
url or httpUrl.timeout (number, optional): Timeout in milliseconds for requests to this
MCP server.trust (boolean, optional): Trust this server and bypass all tool call
confirmations.description (string, optional): A brief description of the server, which
may be used for display purposes.includeTools (array of strings, optional): List of tool names to include
from this MCP server. When specified, only the tools listed here will be
available from this server (allowlist behavior). If not specified, all tools
from the server are enabled by default.excludeTools (array of strings, optional): List of tool names to exclude
from this MCP server. Tools listed here will not be available to the model,
even if they are exposed by the server. Note: excludeTools takes
precedence over includeTools - if a tool is in both lists, it will be
excluded.telemetryConfigures logging and metrics collection for Gemini CLI. For more information, see Telemetry.
enabled (boolean): Whether or not telemetry is enabled.traces (boolean): Whether detailed traces with large attributes (like
tool outputs and file reads) are captured. Defaults to false.target (string): The destination for collected telemetry. Supported
values are local and gcp.otlpEndpoint (string): The endpoint for the OTLP Exporter.otlpProtocol (string): The protocol for the OTLP Exporter (grpc or
http).logPrompts (boolean): Whether or not to include the content of user
prompts in the logs.outfile (string): The file to write telemetry to when target is
local.useCollector (boolean): Whether to use an external OTLP collector.settings.jsonHere is an example of a settings.json file with the nested structure, new as
of v0.3.0:
{
"general": {
"vimMode": true,
"preferredEditor": "code",
"sessionRetention": {
"enabled": true,
"maxAge": "30d",
"maxCount": 100
}
},
"ui": {
"theme": "GitHub",
"hideBanner": true,
"hideTips": false,
"customWittyPhrases": [
"You forget a thousand things every day. Make sure this is one of ’em",
"Connecting to AGI"
]
},
"tools": {
"sandbox": "docker",
"discoveryCommand": "bin/get_tools",
"callCommand": "bin/call_tool",
"exclude": ["write_file"]
},
"mcpServers": {
"mainServer": {
"command": "bin/mcp_server.py"
},
"anotherServer": {
"command": "node",
"args": ["mcp_server.js", "--verbose"]
}
},
"telemetry": {
"enabled": true,
"target": "local",
"otlpEndpoint": "http://localhost:4317",
"logPrompts": true
},
"privacy": {
"usageStatisticsEnabled": true
},
"model": {
"name": "gemini-1.5-pro-latest",
"maxSessionTurns": 10,
"summarizeToolOutput": {
"run_shell_command": {
"tokenBudget": 100
}
}
},
"context": {
"fileName": ["CONTEXT.md", "GEMINI.md"],
"includeDirectories": ["path/to/dir1", "~/path/to/dir2", "../path/to/dir3"],
"loadFromIncludeDirectories": true,
"fileFiltering": {
"respectGitIgnore": false
}
},
"advanced": {
"excludedEnvVars": ["DEBUG", "DEBUG_MODE", "NODE_ENV"]
}
}
The CLI keeps a history of shell commands you run. To avoid conflicts between different projects, this history is stored in a project-specific directory within your user's home folder.
~/.gemini/tmp/<project_hash>/shell_history
<project_hash> is a unique identifier generated from your project's root
path.shell_history..env filesEnvironment variables are a common way to configure applications, especially for sensitive information like API keys or for settings that might change between environments. For authentication setup, see the Authentication documentation which covers all available authentication methods.
The CLI automatically loads environment variables from an .env file. The
loading order is:
.env file in the current working directory..env file or reaches the project root (identified by a .git folder) or
the home directory.~/.env (in the user's home directory).Environment variable exclusion: Some environment variables (like DEBUG and
DEBUG_MODE) are automatically excluded from being loaded from project .env
files to prevent interference with gemini-cli behavior. Variables from
.gemini/.env files are never excluded. You can customize this behavior using
the advanced.excludedEnvVars setting in your settings.json file.
GEMINI_API_KEY:
~/.bashrc, ~/.zshrc) or an
.env file.GEMINI_MODEL:
export GEMINI_MODEL="gemini-3-flash-preview" (Windows PowerShell:
$env:GEMINI_MODEL="gemini-3-flash-preview")GEMINI_CLI_TRUST_WORKSPACE:
"true", trusts the current workspace for the duration of the
session, bypassing the folder trust check.GEMINI_CLI_TRUSTED_FOLDERS_PATH:
trustedFolders.json file.~/.gemini/.GEMINI_CLI_IDE_PID:
GEMINI_CLI_HOME:
.gemini folder inside this directory.export GEMINI_CLI_HOME="/path/to/user/config" (Windows
PowerShell: $env:GEMINI_CLI_HOME="C:\path\to\user\config")GEMINI_CLI_SURFACE:
User-Agent header for API
traffic reporting.export GEMINI_CLI_SURFACE="my-custom-tool" (Windows PowerShell:
$env:GEMINI_CLI_SURFACE="my-custom-tool")GOOGLE_API_KEY:
export GOOGLE_API_KEY="YOUR_GOOGLE_API_KEY" (Windows PowerShell:
$env:GOOGLE_API_KEY="YOUR_GOOGLE_API_KEY").GOOGLE_CLOUD_PROJECT:
GOOGLE_CLOUD_PROJECT set in your global environment in Cloud
Shell, it will be overridden by this default. To use a different project in
Cloud Shell, you must define GOOGLE_CLOUD_PROJECT in a .env file.export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID" (Windows
PowerShell: $env:GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID").GOOGLE_APPLICATION_CREDENTIALS (string):
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/credentials.json"
(Windows PowerShell:
$env:GOOGLE_APPLICATION_CREDENTIALS="C:\path\to\your\credentials.json")GOOGLE_GENAI_API_VERSION:
export GOOGLE_GENAI_API_VERSION="v1" (Windows PowerShell:
$env:GOOGLE_GENAI_API_VERSION="v1")GOOGLE_GEMINI_BASE_URL:
gemini-api-key authentication).localhost (or 127.0.0.1 / [::1]).export GOOGLE_GEMINI_BASE_URL="https://my-proxy.com" (Windows
PowerShell: $env:GOOGLE_GEMINI_BASE_URL="https://my-proxy.com")GOOGLE_VERTEX_BASE_URL:
vertex-ai authentication).localhost (or 127.0.0.1 / [::1]).export GOOGLE_VERTEX_BASE_URL="https://my-vertex-proxy.com"
(Windows PowerShell:
$env:GOOGLE_VERTEX_BASE_URL="https://my-vertex-proxy.com")OTLP_GOOGLE_CLOUD_PROJECT:
export OTLP_GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID" (Windows
PowerShell: $env:OTLP_GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID").GEMINI_TELEMETRY_ENABLED:
true or 1 to enable telemetry. Any other value is treated as
disabling it.telemetry.enabled setting.GEMINI_TELEMETRY_TRACES_ENABLED:
true or 1 to enable detailed tracing with large attributes. Any
other value is treated as disabling it.telemetry.traces setting.GEMINI_TELEMETRY_TARGET:
local or gcp).telemetry.target setting.GEMINI_TELEMETRY_OTLP_ENDPOINT:
telemetry.otlpEndpoint setting.GEMINI_TELEMETRY_OTLP_PROTOCOL:
grpc or http).telemetry.otlpProtocol setting.GEMINI_TELEMETRY_LOG_PROMPTS:
true or 1 to enable or disable logging of user prompts. Any other
value is treated as disabling it.telemetry.logPrompts setting.GEMINI_TELEMETRY_OUTFILE:
local.telemetry.outfile setting.GEMINI_TELEMETRY_USE_COLLECTOR:
true or 1 to enable or disable using an external OTLP collector.
Any other value is treated as disabling it.telemetry.useCollector setting.GOOGLE_CLOUD_LOCATION:
export GOOGLE_CLOUD_LOCATION="YOUR_PROJECT_LOCATION" (Windows
PowerShell: $env:GOOGLE_CLOUD_LOCATION="YOUR_PROJECT_LOCATION").GEMINI_SANDBOX:
sandbox setting in settings.json.true, false, docker, podman, or a custom command string.GEMINI_SYSTEM_MD:
true/1: Use project default path ./.gemini/system.md.~
expands).false/0 or unset: Use the built‑in prompt. See
System Prompt Override.GEMINI_WRITE_SYSTEM_MD:
true/1: Write to ./.gemini/system.md. Otherwise treat the value as a
path.SEATBELT_PROFILE (macOS specific):
sandbox-exec) profile on macOS.permissive-open: (Default) Restricts writes to the project folder (and a
few other folders, see
packages/cli/src/utils/sandbox-macos-permissive-open.sb) but allows other
operations.restrictive-open: Declines operations by default, allows network.strict-open: Restricts both reads and writes to the working directory,
allows network.strict-proxied: Same as strict-open but routes network through proxy.<profile_name>: Uses a custom profile. To define a custom profile, create
a file named sandbox-macos-<profile_name>.sb in your project's .gemini/
directory (for example, my-project/.gemini/sandbox-macos-custom.sb).DEBUG or DEBUG_MODE (often used by underlying libraries or the CLI
itself):
true or 1 to enable verbose debug logging, which can be helpful
for troubleshooting..env
files by default to prevent interference with gemini-cli behavior. Use
.gemini/.env files if you need to set these for gemini-cli specifically.NO_COLOR:
CLI_TITLE:
CODE_ASSIST_ENDPOINT:
To prevent accidental leakage of sensitive information, Gemini CLI automatically
redacts potential secrets from environment variables when executing tools (such
as shell commands). This "best effort" redaction applies to variables inherited
from the system or loaded from .env files.
Default Redaction Rules:
TOKEN, SECRET, PASSWORD, KEY, AUTH, CREDENTIAL, PRIVATE, or
CERT.CLIENT_ID, DB_URI,
DATABASE_URL, and CONNECTION_STRING are always redacted by default.Allowlist (Never Redacted):
PATH, HOME, USER, SHELL, TERM,
LANG).GEMINI_CLI_.Configuration:
You can customize this behavior in your settings.json file:
security.allowedEnvironmentVariables: A list of variable names to
never redact, even if they match sensitive patterns.security.blockedEnvironmentVariables: A list of variable names to
always redact, even if they don't match sensitive patterns.{
"security": {
"allowedEnvironmentVariables": ["MY_PUBLIC_KEY", "NOT_A_SECRET_TOKEN"],
"blockedEnvironmentVariables": ["INTERNAL_IP_ADDRESS"]
}
}
Arguments passed directly when running the CLI can override other configurations for that specific session.
--acp:
--allowed-mcp-server-names:
--allowed-tools <tool1,tool2,...>:
gemini --allowed-tools "ShellTool(git status)"--approval-mode <mode>:
default: Prompt for approval on each tool call (default behavior)auto_edit: Automatically approve edit tools (replace, write_file) while
prompting for othersyolo: Automatically approve all tool calls (equivalent to --yolo)plan: Read-only mode for tool calls (requires experimental planning to
be enabled).
Note: This mode is currently under development and not yet fully functional.
--yolo. Use --approval-mode=yolo instead of
--yolo for the new unified approach.gemini --approval-mode auto_edit--debug (-d):
--delete-session <identifier>:
--list-sessions first to see available sessions, their indices, and
UUIDs.gemini --delete-session 3 or
gemini --delete-session a1b2c3d4-e5f6-7890-abcd-ef1234567890--extensions <extension_name ...> (-e <extension_name ...>):
gemini -e none to disable all extensions.gemini -e my-extension -e my-other-extension--fake-responses:
--help (or -h):
--include-directories <dir1,dir2,...>:
--include-directories /path/to/project1,/path/to/project2 or
--include-directories /path/to/project1 --include-directories /path/to/project2--list-extensions (-l):
--list-sessions:
gemini --list-sessions--model <model_name> (-m <model_name>):
npm start -- --model gemini-3-pro-preview--output-format <format>:
text: (Default) The standard human-readable output.json: A machine-readable JSON output.stream-json: A streaming JSON output that emits real-time events.--output-format json or --output-format stream-json flag.--prompt <your_prompt> (-p <your_prompt>):
--prompt-interactive <your_prompt> (-i <your_prompt>):
gemini -i "explain this code"--record-responses:
--resume [session_id] (-r [session_id]):
gemini --resume 5 or gemini --resume latest or
gemini --resume a1b2c3d4-e5f6-7890-abcd-ef1234567890 or gemini --resume--sandbox (-s):
--screen-reader:
--version:
--yolo:
While not strictly configuration for the CLI's behavior, context files
(defaulting to GEMINI.md but configurable via the context.fileName setting)
are crucial for configuring the instructional context (also referred to as
"memory") provided to the Gemini model. This powerful feature lets you give
project-specific instructions, coding style guides, or any relevant background
information to the AI, making its responses more tailored and accurate to your
needs. The CLI includes UI elements, such as an indicator in the footer showing
the number of loaded context files, to keep you informed about the active
context.
GEMINI.md)Here's a conceptual example of what a context file at the root of a TypeScript project might contain:
# Project: My Awesome TypeScript Library
## General Instructions:
- When generating new TypeScript code, follow the existing coding style.
- Ensure all new functions and classes have JSDoc comments.
- Prefer functional programming paradigms where appropriate.
- All code should be compatible with TypeScript 5.0 and Node.js 20+.
## Coding Style:
- Use 2 spaces for indentation.
- Interface names should be prefixed with `I` (for example, `IUserService`).
- Private class members should be prefixed with an underscore (`_`).
- Always use strict equality (`===` and `!==`).
## Specific Component: `src/api/client.ts`
- This file handles all outbound API requests.
- When adding new API call functions, ensure they include robust error handling
and logging.
- Use the existing `fetchWithRetry` utility for all GET requests.
## Regarding Dependencies:
- Avoid introducing new external dependencies unless absolutely necessary.
- If a new dependency is required, state the reason.
This example demonstrates how you can provide general project context, specific coding conventions, and even notes about particular files or components. The more relevant and precise your context files are, the better the AI can assist you. Project-specific context files are highly encouraged to establish conventions and context.
GEMINI.md)
from several locations. Content from files lower in this list (more specific)
typically overrides or supplements content from files higher up (more
general). The exact concatenation order and final context can be inspected
using the /memory show command. The typical loading order is:
~/.gemini/<configured-context-filename> (for example,
~/.gemini/GEMINI.md in your user home directory)..git folder) or your home directory.node_modules, .git, etc.). The breadth of this
search is limited to 200 directories by default, but can be configured
with the context.discoveryMaxDirs setting in your settings.json
file.@path/to/file.md syntax. For more details,
see the Memory Import Processor documentation./memory refresh to force a re-scan and reload of all context files
from all configured locations. This updates the AI's instructional context./memory show to display the combined instructional context currently
loaded, allowing you to verify the hierarchy and content being used by the
AI./memory command and its sub-commands (show and reload).By understanding and utilizing these configuration layers and the hierarchical nature of context files, you can effectively manage the AI's memory and tailor Gemini CLI's responses to your specific needs and projects.
Gemini CLI can execute potentially unsafe operations (like shell commands and file modifications) within a sandboxed environment to protect your system.
Sandboxing is disabled by default, but you can enable it in a few ways:
--sandbox or -s flag.GEMINI_SANDBOX environment variable.--yolo or --approval-mode=yolo by default.By default, it uses a pre-built gemini-cli-sandbox Docker image.
For project-specific sandboxing needs, you can create a custom Dockerfile at
.gemini/sandbox.Dockerfile in your project's root directory. This Dockerfile
can be based on the base sandbox image:
FROM gemini-cli-sandbox
# Add your custom dependencies or configurations here.
# Note: The base image runs as the non-root 'node' user.
# You must switch to 'root' to install system packages.
# For example:
# USER root
# RUN apt-get update && apt-get install -y some-package
# USER node
# COPY ./my-config /app/my-config
When .gemini/sandbox.Dockerfile exists, you can use BUILD_SANDBOX
environment variable when running Gemini CLI to automatically build the custom
sandbox image:
BUILD_SANDBOX=1 gemini -s
Building a custom sandbox with BUILD_SANDBOX is only supported when running
Gemini CLI from source. If you installed the CLI with npm, build the Docker
image separately and reference that image in your sandbox configuration.
To help us improve Gemini CLI, we collect anonymized usage statistics. This data helps us understand how the CLI is used, identify common issues, and prioritize new features.
What we collect:
What we DON'T collect:
How to opt out:
You can opt out of usage statistics collection at any time by setting the
usageStatisticsEnabled property to false under the privacy category in
your settings.json file:
{
"privacy": {
"usageStatisticsEnabled": false
}
}