@google/gemini-cli-core 0.21.0-nightly.20251218.739c02bd6 → 0.21.0-nightly.20251220.41a1a3eed

package/dist/docs/get-started/configuration.md

@@ -0,0 +1,1444 @@
+# Gemini CLI configuration
+
+> **Note on configuration format, 9/17/25:** The format of the `settings.json`
+> file has been updated to a new, more organized structure.
+>
+> - The new format will be supported in the stable release starting
+>   **[09/10/25]**.
+> - Automatic migration from the old format to the new format will begin on
+>   **[09/17/25]**.
+>
+> For details on the previous format, please see the
+> [v1 Configuration documentation](./configuration-v1.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 layers
+
+Configuration is applied in the following order of precedence (lower numbers are
+overridden by higher numbers):
+
+1.  **Default values:** Hardcoded defaults within the application.
+2.  **System defaults file:** System-wide default settings that can be
+    overridden by other settings files.
+3.  **User settings file:** Global settings for the current user.
+4.  **Project settings file:** Project-specific settings.
+5.  **System settings file:** System-wide settings that override all other
+    settings files.
+6.  **Environment variables:** System-wide or session-specific variables,
+    potentially loaded from `.env` files.
+7.  **Command-line arguments:** Values passed when launching the CLI.
+
+## Settings files
+
+Gemini CLI uses JSON settings files for persistent configuration. There are four
+locations for these files:
+
+> **Tip:** JSON-aware editors can use autocomplete and validation by pointing to
+> the generated schema at `schemas/settings.schema.json` in this repository.
+> When working outside the repo, reference the hosted schema at
+> `https://raw.githubusercontent.com/google-gemini/gemini-cli/main/schemas/settings.schema.json`.
+
+- **System defaults file:**
+  - **Location:** `/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.
+  - **Scope:** Provides a base layer of system-wide default settings. These
+    settings have the lowest precedence and are intended to be overridden by
+    user, project, or system override settings.
+- **User settings file:**
+  - **Location:** `~/.gemini/settings.json` (where `~` is your home directory).
+  - **Scope:** Applies to all Gemini CLI sessions for the current user. User
+    settings override system defaults.
+- **Project settings file:**
+  - **Location:** `.gemini/settings.json` within your project's root directory.
+  - **Scope:** Applies only when running Gemini CLI from that specific project.
+    Project settings override user settings and system defaults.
+- **System settings file:**
+  - **Location:** `/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.
+  - **Scope:** Applies to all Gemini CLI sessions on the system, for all users.
+    System settings act as overrides, taking precedence over all other settings
+    files. May be useful for system administrators at enterprises to have
+    controls over users' Gemini CLI setups.
+
+**Note on environment variables in settings:** String values within your
+`settings.json` and `gemini-extension.json` files can reference environment
+variables using either `$VAR_NAME` or `${VAR_NAME}` 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"`. 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, please see the
+> [Enterprise Configuration](../cli/enterprise.md) documentation.
+
+### The `.gemini` directory in your project
+
+In 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:
+
+- [Custom sandbox profiles](#sandboxing) (e.g.,
+  `.gemini/sandbox-macos-custom.sb`, `.gemini/sandbox.Dockerfile`).
+
+### Available settings in `settings.json`
+
+Settings are organized into categories. All settings should be placed within
+their corresponding top-level category object in your `settings.json` file.
+
+<!-- SETTINGS-AUTOGEN:START -->
+
+#### `general`
+
+- **`general.previewFeatures`** (boolean):
+  - **Description:** Enable preview features (e.g., preview models).
+  - **Default:** `false`
+
+- **`general.preferredEditor`** (string):
+  - **Description:** The preferred editor to open files in.
+  - **Default:** `undefined`
+
+- **`general.vimMode`** (boolean):
+  - **Description:** Enable Vim keybindings
+  - **Default:** `false`
+
+- **`general.disableAutoUpdate`** (boolean):
+  - **Description:** Disable automatic updates
+  - **Default:** `false`
+
+- **`general.disableUpdateNag`** (boolean):
+  - **Description:** Disable update notification prompts.
+  - **Default:** `false`
+
+- **`general.checkpointing.enabled`** (boolean):
+  - **Description:** Enable session checkpointing for recovery
+  - **Default:** `false`
+  - **Requires restart:** Yes
+
+- **`general.enablePromptCompletion`** (boolean):
+  - **Description:** Enable AI-powered prompt completion suggestions while
+    typing.
+  - **Default:** `false`
+  - **Requires restart:** Yes
+
+- **`general.retryFetchErrors`** (boolean):
+  - **Description:** Retry on "exception TypeError: fetch failed sending
+    request" errors.
+  - **Default:** `false`
+
+- **`general.debugKeystrokeLogging`** (boolean):
+  - **Description:** Enable debug logging of keystrokes to the console.
+  - **Default:** `false`
+
+- **`general.sessionRetention.enabled`** (boolean):
+  - **Description:** Enable automatic session cleanup
+  - **Default:** `false`
+
+- **`general.sessionRetention.maxAge`** (string):
+  - **Description:** Maximum age of sessions to keep (e.g., "30d", "7d", "24h",
+    "1w")
+  - **Default:** `undefined`
+
+- **`general.sessionRetention.maxCount`** (number):
+  - **Description:** Alternative: Maximum number of sessions to keep (most
+    recent)
+  - **Default:** `undefined`
+
+- **`general.sessionRetention.minRetention`** (string):
+  - **Description:** Minimum retention period (safety limit, defaults to "1d")
+  - **Default:** `"1d"`
+
+#### `output`
+
+- **`output.format`** (enum):
+  - **Description:** The format of the CLI output.
+  - **Default:** `"text"`
+  - **Values:** `"text"`, `"json"`
+
+#### `ui`
+
+- **`ui.theme`** (string):
+  - **Description:** The color theme for the UI. See the CLI themes guide for
+    available options.
+  - **Default:** `undefined`
+
+- **`ui.customThemes`** (object):
+  - **Description:** Custom theme definitions.
+  - **Default:** `{}`
+
+- **`ui.hideWindowTitle`** (boolean):
+  - **Description:** Hide the window title bar
+  - **Default:** `false`
+  - **Requires restart:** Yes
+
+- **`ui.showStatusInTitle`** (boolean):
+  - **Description:** Show Gemini CLI status and thoughts in the terminal window
+    title
+  - **Default:** `false`
+
+- **`ui.hideTips`** (boolean):
+  - **Description:** Hide helpful tips in the UI
+  - **Default:** `false`
+
+- **`ui.hideBanner`** (boolean):
+  - **Description:** Hide the application banner
+  - **Default:** `false`
+
+- **`ui.hideContextSummary`** (boolean):
+  - **Description:** Hide the context summary (GEMINI.md, MCP servers) above the
+    input.
+  - **Default:** `false`
+
+- **`ui.footer.hideCWD`** (boolean):
+  - **Description:** Hide the current working directory path in the footer.
+  - **Default:** `false`
+
+- **`ui.footer.hideSandboxStatus`** (boolean):
+  - **Description:** Hide the sandbox status indicator in the footer.
+  - **Default:** `false`
+
+- **`ui.footer.hideModelInfo`** (boolean):
+  - **Description:** Hide the model name and context usage in the footer.
+  - **Default:** `false`
+
+- **`ui.footer.hideContextPercentage`** (boolean):
+  - **Description:** Hides the context window remaining percentage.
+  - **Default:** `true`
+
+- **`ui.hideFooter`** (boolean):
+  - **Description:** Hide the footer from the UI
+  - **Default:** `false`
+
+- **`ui.showMemoryUsage`** (boolean):
+  - **Description:** Display memory usage information in the UI
+  - **Default:** `false`
+
+- **`ui.showLineNumbers`** (boolean):
+  - **Description:** Show line numbers in the chat.
+  - **Default:** `true`
+
+- **`ui.showCitations`** (boolean):
+  - **Description:** Show citations for generated text in the chat.
+  - **Default:** `false`
+
+- **`ui.showModelInfoInChat`** (boolean):
+  - **Description:** Show the model name in the chat for each model turn.
+  - **Default:** `false`
+
+- **`ui.useFullWidth`** (boolean):
+  - **Description:** Use the entire width of the terminal for output.
+  - **Default:** `true`
+
+- **`ui.useAlternateBuffer`** (boolean):
+  - **Description:** Use an alternate screen buffer for the UI, preserving shell
+    history.
+  - **Default:** `false`
+  - **Requires restart:** Yes
+
+- **`ui.incrementalRendering`** (boolean):
+  - **Description:** Enable incremental rendering for the UI. This option will
+    reduce flickering but may cause rendering artifacts. Only supported when
+    useAlternateBuffer is enabled.
+  - **Default:** `true`
+  - **Requires restart:** Yes
+
+- **`ui.customWittyPhrases`** (array):
+  - **Description:** Custom witty phrases to display during loading. When
+    provided, the CLI cycles through these instead of the defaults.
+  - **Default:** `[]`
+
+- **`ui.accessibility.disableLoadingPhrases`** (boolean):
+  - **Description:** Disable loading phrases for accessibility
+  - **Default:** `false`
+  - **Requires restart:** Yes
+
+- **`ui.accessibility.screenReader`** (boolean):
+  - **Description:** Render output in plain-text to be more screen reader
+    accessible
+  - **Default:** `false`
+  - **Requires restart:** Yes
+
+#### `ide`
+
+- **`ide.enabled`** (boolean):
+  - **Description:** Enable IDE integration mode
+  - **Default:** `false`
+  - **Requires restart:** Yes
+
+- **`ide.hasSeenNudge`** (boolean):
+  - **Description:** Whether the user has seen the IDE integration nudge.
+  - **Default:** `false`
+
+#### `privacy`
+
+- **`privacy.usageStatisticsEnabled`** (boolean):
+  - **Description:** Enable collection of usage statistics
+  - **Default:** `true`
+  - **Requires restart:** Yes
+
+#### `model`
+
+- **`model.name`** (string):
+  - **Description:** The Gemini model to use for conversations.
+  - **Default:** `undefined`
+
+- **`model.maxSessionTurns`** (number):
+  - **Description:** Maximum number of user/model/tool turns to keep in a
+    session. -1 means unlimited.
+  - **Default:** `-1`
+
+- **`model.summarizeToolOutput`** (object):
+  - **Description:** Enables or disables summarization of tool output. Configure
+    per-tool token budgets (for example {"run_shell_command": {"tokenBudget":
+    2000}}). Currently only the run_shell_command tool supports summarization.
+  - **Default:** `undefined`
+
+- **`model.compressionThreshold`** (number):
+  - **Description:** The fraction of context usage at which to trigger context
+    compression (e.g. 0.2, 0.3).
+  - **Default:** `0.5`
+  - **Requires restart:** Yes
+
+- **`model.skipNextSpeakerCheck`** (boolean):
+  - **Description:** Skip the next speaker check.
+  - **Default:** `true`
+
+#### `modelConfigs`
+
+- **`modelConfigs.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:**
+
+    ```json
+    {
+      "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"
+        }
+      },
+      "gemini-2.5-flash-base": {
+        "extends": "base",
+        "modelConfig": {
+          "model": "gemini-2.5-flash"
+        }
+      },
+      "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
+            }
+          }
+        }
+      },
+      "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-2.5-flash-base",
+        "modelConfig": {
+          "generateContentConfig": {
+            "tools": [
+              {
+                "googleSearch": {}
+              }
+            ]
+          }
+        }
+      },
+      "web-fetch": {
+        "extends": "gemini-2.5-flash-base",
+        "modelConfig": {
+          "generateContentConfig": {
+            "tools": [
+              {
+                "urlContext": {}
+              }
+            ]
+          }
+        }
+      },
+      "web-fetch-fallback": {
+        "extends": "gemini-2.5-flash-base",
+        "modelConfig": {}
+      },
+      "loop-detection": {
+        "extends": "gemini-2.5-flash-base",
+        "modelConfig": {}
+      },
+      "loop-detection-double-check": {
+        "extends": "base",
+        "modelConfig": {
+          "model": "gemini-2.5-pro"
+        }
+      },
+      "llm-edit-fixer": {
+        "extends": "gemini-2.5-flash-base",
+        "modelConfig": {}
+      },
+      "next-speaker-checker": {
+        "extends": "gemini-2.5-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-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-2.5-pro"
+        }
+      }
+    }
+    ```
+
+- **`modelConfigs.customAliases`** (object):
+  - **Description:** Custom named presets for model configs. These are merged
+    with (and override) the built-in aliases.
+  - **Default:** `{}`
+
+- **`modelConfigs.customOverrides`** (array):
+  - **Description:** Custom model config overrides. These are merged with (and
+    added to) the built-in overrides.
+  - **Default:** `[]`
+
+- **`modelConfigs.overrides`** (array):
+  - **Description:** Apply specific configuration overrides based on matches,
+    with a primary key of model (or alias). The most specific match will be
+    used.
+  - **Default:** `[]`
+
+#### `context`
+
+- **`context.fileName`** (string | string[]):
+  - **Description:** The name of the context file or files to load into memory.
+    Accepts either a single string or an array of strings.
+  - **Default:** `undefined`
+
+- **`context.importFormat`** (string):
+  - **Description:** The format to use when importing memory.
+  - **Default:** `undefined`
+
+- **`context.discoveryMaxDirs`** (number):
+  - **Description:** Maximum number of directories to search for memory.
+  - **Default:** `200`
+
+- **`context.includeDirectories`** (array):
+  - **Description:** Additional directories to include in the workspace context.
+    Missing directories will be skipped with a warning.
+  - **Default:** `[]`
+
+- **`context.loadMemoryFromIncludeDirectories`** (boolean):
+  - **Description:** Controls how /memory refresh loads GEMINI.md files. When
+    true, include directories are scanned; when false, only the current
+    directory is used.
+  - **Default:** `false`
+
+- **`context.fileFiltering.respectGitIgnore`** (boolean):
+  - **Description:** Respect .gitignore files when searching
+  - **Default:** `true`
+  - **Requires restart:** Yes
+
+- **`context.fileFiltering.respectGeminiIgnore`** (boolean):
+  - **Description:** Respect .geminiignore files when searching
+  - **Default:** `true`
+  - **Requires restart:** Yes
+
+- **`context.fileFiltering.enableRecursiveFileSearch`** (boolean):
+  - **Description:** Enable recursive file search functionality when completing
+    @ references in the prompt.
+  - **Default:** `true`
+  - **Requires restart:** Yes
+
+- **`context.fileFiltering.disableFuzzySearch`** (boolean):
+  - **Description:** Disable fuzzy search when searching for files.
+  - **Default:** `false`
+  - **Requires restart:** Yes
+
+#### `tools`
+
+- **`tools.sandbox`** (boolean | string):
+  - **Description:** Sandbox execution environment. Set to a boolean to enable
+    or disable the sandbox, or provide a string path to a sandbox profile.
+  - **Default:** `undefined`
+  - **Requires restart:** Yes
+
+- **`tools.shell.enableInteractiveShell`** (boolean):
+  - **Description:** Use node-pty for an interactive shell experience. Fallback
+    to child_process still applies.
+  - **Default:** `true`
+  - **Requires restart:** Yes
+
+- **`tools.shell.pager`** (string):
+  - **Description:** The pager command to use for shell output. Defaults to
+    `cat`.
+  - **Default:** `"cat"`
+
+- **`tools.shell.showColor`** (boolean):
+  - **Description:** Show color in shell output.
+  - **Default:** `false`
+
+- **`tools.shell.inactivityTimeout`** (number):
+  - **Description:** The maximum time in seconds allowed without output from the
+    shell command. Defaults to 5 minutes.
+  - **Default:** `300`
+
+- **`tools.autoAccept`** (boolean):
+  - **Description:** Automatically accept and execute tool calls that are
+    considered safe (e.g., read-only operations).
+  - **Default:** `false`
+
+- **`tools.core`** (array):
+  - **Description:** Restrict the set of built-in tools with an allowlist. Match
+    semantics mirror tools.allowed; see the built-in tools documentation for
+    available names.
+  - **Default:** `undefined`
+  - **Requires restart:** Yes
+
+- **`tools.allowed`** (array):
+  - **Description:** Tool names that bypass the confirmation dialog. Useful for
+    trusted commands (for example ["run_shell_command(git)",
+    "run_shell_command(npm test)"]). See shell tool command restrictions for
+    matching details.
+  - **Default:** `undefined`
+  - **Requires restart:** Yes
+
+- **`tools.exclude`** (array):
+  - **Description:** Tool names to exclude from discovery.
+  - **Default:** `undefined`
+  - **Requires restart:** Yes
+
+- **`tools.discoveryCommand`** (string):
+  - **Description:** Command to run for tool discovery.
+  - **Default:** `undefined`
+  - **Requires restart:** Yes
+
+- **`tools.callCommand`** (string):
+  - **Description:** Defines a custom shell command for invoking discovered
+    tools. The command must take the tool name as the first argument, read JSON
+    arguments from stdin, and emit JSON results on stdout.
+  - **Default:** `undefined`
+  - **Requires restart:** Yes
+
+- **`tools.useRipgrep`** (boolean):
+  - **Description:** Use ripgrep for file content search instead of the fallback
+    implementation. Provides faster search performance.
+  - **Default:** `true`
+
+- **`tools.enableToolOutputTruncation`** (boolean):
+  - **Description:** Enable truncation of large tool outputs.
+  - **Default:** `true`
+  - **Requires restart:** Yes
+
+- **`tools.truncateToolOutputThreshold`** (number):
+  - **Description:** Truncate tool output if it is larger than this many
+    characters. Set to -1 to disable.
+  - **Default:** `4000000`
+  - **Requires restart:** Yes
+
+- **`tools.truncateToolOutputLines`** (number):
+  - **Description:** The number of lines to keep when truncating tool output.
+  - **Default:** `1000`
+  - **Requires restart:** Yes
+
+- **`tools.enableMessageBusIntegration`** (boolean):
+  - **Description:** Enable policy-based tool confirmation via message bus
+    integration. When enabled, tools automatically respect policy engine
+    decisions (ALLOW/DENY/ASK_USER) without requiring individual tool
+    implementations.
+  - **Default:** `true`
+  - **Requires restart:** Yes
+
+- **`tools.enableHooks`** (boolean):
+  - **Description:** Enable the hooks system for intercepting and customizing
+    Gemini CLI behavior. When enabled, hooks configured in settings will execute
+    at appropriate lifecycle events (BeforeTool, AfterTool, BeforeModel, etc.).
+    Requires MessageBus integration.
+  - **Default:** `false`
+  - **Requires restart:** Yes
+
+#### `mcp`
+
+- **`mcp.serverCommand`** (string):
+  - **Description:** Command to start an MCP server.
+  - **Default:** `undefined`
+  - **Requires restart:** Yes
+
+- **`mcp.allowed`** (array):
+  - **Description:** A list of MCP servers to allow.
+  - **Default:** `undefined`
+  - **Requires restart:** Yes
+
+- **`mcp.excluded`** (array):
+  - **Description:** A list of MCP servers to exclude.
+  - **Default:** `undefined`
+  - **Requires restart:** Yes
+
+#### `useSmartEdit`
+
+- **`useSmartEdit`** (boolean):
+  - **Description:** Enable the smart-edit tool instead of the replace tool.
+  - **Default:** `true`
+
+#### `useWriteTodos`
+
+- **`useWriteTodos`** (boolean):
+  - **Description:** Enable the write_todos tool.
+  - **Default:** `true`
+
+#### `security`
+
+- **`security.disableYoloMode`** (boolean):
+  - **Description:** Disable YOLO mode, even if enabled by a flag.
+  - **Default:** `false`
+  - **Requires restart:** Yes
+
+- **`security.enablePermanentToolApproval`** (boolean):
+  - **Description:** Enable the "Allow for all future sessions" option in tool
+    confirmation dialogs.
+  - **Default:** `false`
+
+- **`security.blockGitExtensions`** (boolean):
+  - **Description:** Blocks installing and loading extensions from Git.
+  - **Default:** `false`
+  - **Requires restart:** Yes
+
+- **`security.folderTrust.enabled`** (boolean):
+  - **Description:** Setting to track whether Folder trust is enabled.
+  - **Default:** `false`
+  - **Requires restart:** Yes
+
+- **`security.auth.selectedType`** (string):
+  - **Description:** The currently selected authentication type.
+  - **Default:** `undefined`
+  - **Requires restart:** Yes
+
+- **`security.auth.enforcedType`** (string):
+  - **Description:** The required auth type. If this does not match the selected
+    auth type, the user will be prompted to re-authenticate.
+  - **Default:** `undefined`
+  - **Requires restart:** Yes
+
+- **`security.auth.useExternal`** (boolean):
+  - **Description:** Whether to use an external authentication flow.
+  - **Default:** `undefined`
+  - **Requires restart:** Yes
+
+#### `advanced`
+
+- **`advanced.autoConfigureMemory`** (boolean):
+  - **Description:** Automatically configure Node.js memory limits
+  - **Default:** `false`
+  - **Requires restart:** Yes
+
+- **`advanced.dnsResolutionOrder`** (string):
+  - **Description:** The DNS resolution order.
+  - **Default:** `undefined`
+  - **Requires restart:** Yes
+
+- **`advanced.excludedEnvVars`** (array):
+  - **Description:** Environment variables to exclude from project context.
+  - **Default:**
+
+    ```json
+    ["DEBUG", "DEBUG_MODE"]
+    ```
+
+- **`advanced.bugCommand`** (object):
+  - **Description:** Configuration for the bug report command.
+  - **Default:** `undefined`
+
+#### `experimental`
+
+- **`experimental.enableAgents`** (boolean):
+  - **Description:** Enable local and remote subagents. Warning: Experimental
+    feature, uses YOLO mode for subagents
+  - **Default:** `false`
+  - **Requires restart:** Yes
+
+- **`experimental.extensionManagement`** (boolean):
+  - **Description:** Enable extension management features.
+  - **Default:** `true`
+  - **Requires restart:** Yes
+
+- **`experimental.extensionReloading`** (boolean):
+  - **Description:** Enables extension loading/unloading within the CLI session.
+  - **Default:** `false`
+  - **Requires restart:** Yes
+
+- **`experimental.jitContext`** (boolean):
+  - **Description:** Enable Just-In-Time (JIT) context loading.
+  - **Default:** `false`
+  - **Requires restart:** Yes
+
+- **`experimental.codebaseInvestigatorSettings.enabled`** (boolean):
+  - **Description:** Enable the Codebase Investigator agent.
+  - **Default:** `true`
+  - **Requires restart:** Yes
+
+- **`experimental.codebaseInvestigatorSettings.maxNumTurns`** (number):
+  - **Description:** Maximum number of turns for the Codebase Investigator
+    agent.
+  - **Default:** `10`
+  - **Requires restart:** Yes
+
+- **`experimental.codebaseInvestigatorSettings.maxTimeMinutes`** (number):
+  - **Description:** Maximum time for the Codebase Investigator agent (in
+    minutes).
+  - **Default:** `3`
+  - **Requires restart:** Yes
+
+- **`experimental.codebaseInvestigatorSettings.thinkingBudget`** (number):
+  - **Description:** The thinking budget for the Codebase Investigator agent.
+  - **Default:** `8192`
+  - **Requires restart:** Yes
+
+- **`experimental.codebaseInvestigatorSettings.model`** (string):
+  - **Description:** The model to use for the Codebase Investigator agent.
+  - **Default:** `"auto"`
+  - **Requires restart:** Yes
+
+- **`experimental.introspectionAgentSettings.enabled`** (boolean):
+  - **Description:** Enable the Introspection Agent.
+  - **Default:** `false`
+  - **Requires restart:** Yes
+
+#### `hooks`
+
+- **`hooks.disabled`** (array):
+  - **Description:** List of hook names (commands) that should be disabled.
+    Hooks in this list will not execute even if configured.
+  - **Default:** `[]`
+
+- **`hooks.BeforeTool`** (array):
+  - **Description:** Hooks that execute before tool execution. Can intercept,
+    validate, or modify tool calls.
+  - **Default:** `[]`
+
+- **`hooks.AfterTool`** (array):
+  - **Description:** Hooks that execute after tool execution. Can process
+    results, log outputs, or trigger follow-up actions.
+  - **Default:** `[]`
+
+- **`hooks.BeforeAgent`** (array):
+  - **Description:** Hooks that execute before agent loop starts. Can set up
+    context or initialize resources.
+  - **Default:** `[]`
+
+- **`hooks.AfterAgent`** (array):
+  - **Description:** Hooks that execute after agent loop completes. Can perform
+    cleanup or summarize results.
+  - **Default:** `[]`
+
+- **`hooks.Notification`** (array):
+  - **Description:** Hooks that execute on notification events (errors,
+    warnings, info). Can log or alert on specific conditions.
+  - **Default:** `[]`
+
+- **`hooks.SessionStart`** (array):
+  - **Description:** Hooks that execute when a session starts. Can initialize
+    session-specific resources or state.
+  - **Default:** `[]`
+
+- **`hooks.SessionEnd`** (array):
+  - **Description:** Hooks that execute when a session ends. Can perform cleanup
+    or persist session data.
+  - **Default:** `[]`
+
+- **`hooks.PreCompress`** (array):
+  - **Description:** Hooks that execute before chat history compression. Can
+    back up or analyze conversation before compression.
+  - **Default:** `[]`
+
+- **`hooks.BeforeModel`** (array):
+  - **Description:** Hooks that execute before LLM requests. Can modify prompts,
+    inject context, or control model parameters.
+  - **Default:** `[]`
+
+- **`hooks.AfterModel`** (array):
+  - **Description:** Hooks that execute after LLM responses. Can process
+    outputs, extract information, or log interactions.
+  - **Default:** `[]`
+
+- **`hooks.BeforeToolSelection`** (array):
+  - **Description:** Hooks that execute before tool selection. Can filter or
+    prioritize available tools dynamically.
+  - **Default:** `[]`
+  <!-- SETTINGS-AUTOGEN:END -->
+
+#### `mcpServers`
+
+Configures 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. If multiple MCP servers
+expose a tool with the same name, the tool names will be prefixed with the
+server alias you defined in the configuration (e.g.,
+`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`.
+
+- **`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.
+
+#### `telemetry`
+
+Configures logging and metrics collection for Gemini CLI. For more information,
+see [Telemetry](../cli/telemetry.md).
+
+- **Properties:**
+  - **`enabled`** (boolean): Whether or not telemetry is enabled.
+  - **`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.
+
+### Example `settings.json`
+
+Here is an example of a `settings.json` file with the nested structure, new as
+of v0.3.0:
+
+```json
+{
+  "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"]
+  }
+}
+```
+
+## Shell history
+
+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.
+
+- **Location:** `~/.gemini/tmp/<project_hash>/shell_history`
+  - `<project_hash>` is a unique identifier generated from your project's root
+    path.
+  - The history is stored in a file named `shell_history`.
+
+## Environment variables and `.env` files
+
+Environment 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](./authentication.md) which covers all available
+authentication methods.
+
+The CLI automatically loads environment variables from an `.env` file. The
+loading order is:
+
+1.  `.env` file in the current working directory.
+2.  If not found, it searches upwards in parent directories until it finds an
+    `.env` file or reaches the project root (identified by a `.git` folder) or
+    the home directory.
+3.  If still not found, it looks for `~/.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`**:
+  - Your API key for the Gemini API.
+  - One of several available [authentication methods](./authentication.md).
+  - Set this in your shell profile (e.g., `~/.bashrc`, `~/.zshrc`) or an `.env`
+    file.
+- **`GEMINI_MODEL`**:
+  - Specifies the default Gemini model to use.
+  - Overrides the hardcoded default
+  - Example: `export GEMINI_MODEL="gemini-2.5-flash"`
+- **`GOOGLE_API_KEY`**:
+  - Your Google Cloud API key.
+  - Required for using Vertex AI in express mode.
+  - Ensure you have the necessary permissions.
+  - Example: `export GOOGLE_API_KEY="YOUR_GOOGLE_API_KEY"`.
+- **`GOOGLE_CLOUD_PROJECT`**:
+  - Your Google Cloud Project ID.
+  - Required for using Code Assist or Vertex AI.
+  - If using Vertex AI, ensure you have the necessary permissions in this
+    project.
+  - **Cloud Shell note:** When running in a Cloud Shell environment, this
+    variable defaults to a special project allocated for Cloud Shell users. If
+    you have `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.
+  - Example: `export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"`.
+- **`GOOGLE_APPLICATION_CREDENTIALS`** (string):
+  - **Description:** The path to your Google Application Credentials JSON file.
+  - **Example:**
+    `export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/credentials.json"`
+- **`OTLP_GOOGLE_CLOUD_PROJECT`**:
+  - Your Google Cloud Project ID for Telemetry in Google Cloud
+  - Example: `export OTLP_GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"`.
+- **`GEMINI_TELEMETRY_ENABLED`**:
+  - Set to `true` or `1` to enable telemetry. Any other value is treated as
+    disabling it.
+  - Overrides the `telemetry.enabled` setting.
+- **`GEMINI_TELEMETRY_TARGET`**:
+  - Sets the telemetry target (`local` or `gcp`).
+  - Overrides the `telemetry.target` setting.
+- **`GEMINI_TELEMETRY_OTLP_ENDPOINT`**:
+  - Sets the OTLP endpoint for telemetry.
+  - Overrides the `telemetry.otlpEndpoint` setting.
+- **`GEMINI_TELEMETRY_OTLP_PROTOCOL`**:
+  - Sets the OTLP protocol (`grpc` or `http`).
+  - Overrides the `telemetry.otlpProtocol` setting.
+- **`GEMINI_TELEMETRY_LOG_PROMPTS`**:
+  - Set to `true` or `1` to enable or disable logging of user prompts. Any other
+    value is treated as disabling it.
+  - Overrides the `telemetry.logPrompts` setting.
+- **`GEMINI_TELEMETRY_OUTFILE`**:
+  - Sets the file path to write telemetry to when the target is `local`.
+  - Overrides the `telemetry.outfile` setting.
+- **`GEMINI_TELEMETRY_USE_COLLECTOR`**:
+  - Set to `true` or `1` to enable or disable using an external OTLP collector.
+    Any other value is treated as disabling it.
+  - Overrides the `telemetry.useCollector` setting.
+- **`GOOGLE_CLOUD_LOCATION`**:
+  - Your Google Cloud Project Location (e.g., us-central1).
+  - Required for using Vertex AI in non-express mode.
+  - Example: `export GOOGLE_CLOUD_LOCATION="YOUR_PROJECT_LOCATION"`.
+- **`GEMINI_SANDBOX`**:
+  - Alternative to the `sandbox` setting in `settings.json`.
+  - Accepts `true`, `false`, `docker`, `podman`, or a custom command string.
+- **`GEMINI_SYSTEM_MD`**:
+  - Replaces the built‑in system prompt with content from a Markdown file.
+  - `true`/`1`: Use project default path `./.gemini/system.md`.
+  - Any other string: Treat as a path (relative/absolute supported, `~`
+    expands).
+  - `false`/`0` or unset: Use the built‑in prompt. See
+    [System Prompt Override](../cli/system-prompt.md).
+- **`GEMINI_WRITE_SYSTEM_MD`**:
+  - Writes the current built‑in system prompt to a file for review.
+  - `true`/`1`: Write to `./.gemini/system.md`. Otherwise treat the value as a
+    path.
+  - Run the CLI once with this set to generate the file.
+- **`SEATBELT_PROFILE`** (macOS specific):
+  - Switches the Seatbelt (`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.
+  - `strict`: Uses a strict profile that declines operations by default.
+  - `<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 (e.g., `my-project/.gemini/sandbox-macos-custom.sb`).
+- **`DEBUG` or `DEBUG_MODE`** (often used by underlying libraries or the CLI
+  itself):
+  - Set to `true` or `1` to enable verbose debug logging, which can be helpful
+    for troubleshooting.
+  - **Note:** These variables are automatically excluded from project `.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`**:
+  - Set to any value to disable all color output in the CLI.
+- **`CLI_TITLE`**:
+  - Set to a string to customize the title of the CLI.
+- **`CODE_ASSIST_ENDPOINT`**:
+  - Specifies the endpoint for the code assist server.
+  - This is useful for development and testing.
+
+## Command-line arguments
+
+Arguments passed directly when running the CLI can override other configurations
+for that specific session.
+
+- **`--model <model_name>`** (**`-m <model_name>`**):
+  - Specifies the Gemini model to use for this session.
+  - Example: `npm start -- --model gemini-1.5-pro-latest`
+- **`--prompt <your_prompt>`** (**`-p <your_prompt>`**):
+  - Used to pass a prompt directly to the command. This invokes Gemini CLI in a
+    non-interactive mode.
+  - For scripting examples, use the `--output-format json` flag to get
+    structured output.
+- **`--prompt-interactive <your_prompt>`** (**`-i <your_prompt>`**):
+  - Starts an interactive session with the provided prompt as the initial input.
+  - The prompt is processed within the interactive session, not before it.
+  - Cannot be used when piping input from stdin.
+  - Example: `gemini -i "explain this code"`
+- **`--output-format <format>`**:
+  - **Description:** Specifies the format of the CLI output for non-interactive
+    mode.
+  - **Values:**
+    - `text`: (Default) The standard human-readable output.
+    - `json`: A machine-readable JSON output.
+    - `stream-json`: A streaming JSON output that emits real-time events.
+  - **Note:** For structured output and scripting, use the
+    `--output-format json` or `--output-format stream-json` flag.
+- **`--sandbox`** (**`-s`**):
+  - Enables sandbox mode for this session.
+- **`--debug`** (**`-d`**):
+  - Enables debug mode for this session, providing more verbose output.
+
+- **`--help`** (or **`-h`**):
+  - Displays help information about command-line arguments.
+- **`--yolo`**:
+  - Enables YOLO mode, which automatically approves all tool calls.
+- **`--approval-mode <mode>`**:
+  - Sets the approval mode for tool calls. Available modes:
+    - `default`: Prompt for approval on each tool call (default behavior)
+    - `auto_edit`: Automatically approve edit tools (replace, write_file) while
+      prompting for others
+    - `yolo`: Automatically approve all tool calls (equivalent to `--yolo`)
+  - Cannot be used together with `--yolo`. Use `--approval-mode=yolo` instead of
+    `--yolo` for the new unified approach.
+  - Example: `gemini --approval-mode auto_edit`
+- **`--allowed-tools <tool1,tool2,...>`**:
+  - A comma-separated list of tool names that will bypass the confirmation
+    dialog.
+  - Example: `gemini --allowed-tools "ShellTool(git status)"`
+- **`--extensions <extension_name ...>`** (**`-e <extension_name ...>`**):
+  - Specifies a list of extensions to use for the session. If not provided, all
+    available extensions are used.
+  - Use the special term `gemini -e none` to disable all extensions.
+  - Example: `gemini -e my-extension -e my-other-extension`
+- **`--list-extensions`** (**`-l`**):
+  - Lists all available extensions and exits.
+- **`--resume [session_id]`** (**`-r [session_id]`**):
+  - Resume a previous chat session. Use "latest" for the most recent session,
+    provide a session index number, or provide a full session UUID.
+  - If no session_id is provided, defaults to "latest".
+  - Example: `gemini --resume 5` or `gemini --resume latest` or
+    `gemini --resume a1b2c3d4-e5f6-7890-abcd-ef1234567890` or `gemini --resume`
+  - See [Session Management](../cli/session-management.md) for more details.
+- **`--list-sessions`**:
+  - List all available chat sessions for the current project and exit.
+  - Shows session indices, dates, message counts, and preview of first user
+    message.
+  - Example: `gemini --list-sessions`
+- **`--delete-session <identifier>`**:
+  - Delete a specific chat session by its index number or full session UUID.
+  - Use `--list-sessions` first to see available sessions, their indices, and
+    UUIDs.
+  - Example: `gemini --delete-session 3` or
+    `gemini --delete-session a1b2c3d4-e5f6-7890-abcd-ef1234567890`
+- **`--include-directories <dir1,dir2,...>`**:
+  - Includes additional directories in the workspace for multi-directory
+    support.
+  - Can be specified multiple times or as comma-separated values.
+  - 5 directories can be added at maximum.
+  - Example: `--include-directories /path/to/project1,/path/to/project2` or
+    `--include-directories /path/to/project1 --include-directories /path/to/project2`
+- **`--screen-reader`**:
+  - Enables screen reader mode, which adjusts the TUI for better compatibility
+    with screen readers.
+- **`--version`**:
+  - Displays the version of the CLI.
+- **`--experimental-acp`**:
+  - Starts the agent in ACP mode.
+- **`--allowed-mcp-server-names`**:
+  - Allowed MCP server names.
+- **`--fake-responses`**:
+  - Path to a file with fake model responses for testing.
+- **`--record-responses`**:
+  - Path to a file to record model responses for testing.
+
+## Context files (hierarchical instructional context)
+
+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 allows you to 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.
+
+- **Purpose:** These Markdown files contain instructions, guidelines, or context
+  that you want the Gemini model to be aware of during your interactions. The
+  system is designed to manage this instructional context hierarchically.
+
+### Example context file content (e.g., `GEMINI.md`)
+
+Here's a conceptual example of what a context file at the root of a TypeScript
+project might contain:
+
+```markdown
+# Project: My Awesome TypeScript Library
+
+## General Instructions:
+
+- When generating new TypeScript code, please 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` (e.g., `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, please 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.
+
+- **Hierarchical loading and precedence:** The CLI implements a sophisticated
+  hierarchical memory system by loading context files (e.g., `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:
+  1.  **Global context file:**
+      - Location: `~/.gemini/<configured-context-filename>` (e.g.,
+        `~/.gemini/GEMINI.md` in your user home directory).
+      - Scope: Provides default instructions for all your projects.
+  2.  **Project root and ancestors context files:**
+      - Location: The CLI searches for the configured context file in the
+        current working directory and then in each parent directory up to either
+        the project root (identified by a `.git` folder) or your home directory.
+      - Scope: Provides context relevant to the entire project or a significant
+        portion of it.
+  3.  **Sub-directory context files (contextual/local):**
+      - Location: The CLI also scans for the configured context file in
+        subdirectories _below_ the current working directory (respecting common
+        ignore patterns like `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.
+      - Scope: Allows for highly specific instructions relevant to a particular
+        component, module, or subsection of your project.
+- **Concatenation and UI indication:** The contents of all found context files
+  are concatenated (with separators indicating their origin and path) and
+  provided as part of the system prompt to the Gemini model. The CLI footer
+  displays the count of loaded context files, giving you a quick visual cue
+  about the active instructional context.
+- **Importing content:** You can modularize your context files by importing
+  other Markdown files using the `@path/to/file.md` syntax. For more details,
+  see the [Memory Import Processor documentation](../core/memport.md).
+- **Commands for memory management:**
+  - Use `/memory refresh` to force a re-scan and reload of all context files
+    from all configured locations. This updates the AI's instructional context.
+  - Use `/memory show` to display the combined instructional context currently
+    loaded, allowing you to verify the hierarchy and content being used by the
+    AI.
+  - See the [Commands documentation](../cli/commands.md#memory) for full details
+    on the `/memory` command and its sub-commands (`show` and `refresh`).
+
+By understanding and utilizing these configuration layers and the hierarchical
+nature of context files, you can effectively manage the AI's memory and tailor
+the Gemini CLI's responses to your specific needs and projects.
+
+## Sandboxing
+
+The 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:
+
+- Using `--sandbox` or `-s` flag.
+- Setting `GEMINI_SANDBOX` environment variable.
+- Sandbox is enabled when using `--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:
+
+```dockerfile
+FROM gemini-cli-sandbox
+
+# Add your custom dependencies or configurations here
+# For example:
+# RUN apt-get update && apt-get install -y some-package
+# 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:
+
+```bash
+BUILD_SANDBOX=1 gemini -s
+```
+
+## Usage statistics
+
+To help us improve the 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:**
+
+- **Tool calls:** We log the names of the tools that are called, whether they
+  succeed or fail, and how long they take to execute. We do not collect the
+  arguments passed to the tools or any data returned by them.
+- **API requests:** We log the Gemini model used for each request, the duration
+  of the request, and whether it was successful. We do not collect the content
+  of the prompts or responses.
+- **Session information:** We collect information about the configuration of the
+  CLI, such as the enabled tools and the approval mode.
+
+**What we DON'T collect:**
+
+- **Personally identifiable information (PII):** We do not collect any personal
+  information, such as your name, email address, or API keys.
+- **Prompt and response content:** We do not log the content of your prompts or
+  the responses from the Gemini model.
+- **File content:** We do not log the content of any files that are read or
+  written by the CLI.
+
+**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:
+
+```json
+{
+  "privacy": {
+    "usageStatisticsEnabled": false
+  }
+}
+```