From 01ebea3b467019df6ea20e034c606f33ca0aced1 Mon Sep 17 00:00:00 2001 From: g-samroberts <158088236+g-samroberts@users.noreply.github.com> Date: Fri, 10 Apr 2026 19:52:40 +0000 Subject: [PATCH] docs: weekly audit results for 24261164273 --- docs/cli/cli-reference.md | 24 ++++++++++----- docs/reference/configuration.md | 53 ++++++++++++++++----------------- 2 files changed, 43 insertions(+), 34 deletions(-) diff --git a/docs/cli/cli-reference.md b/docs/cli/cli-reference.md index e8217e226e..a8e7ad9b2a 100644 --- a/docs/cli/cli-reference.md +++ b/docs/cli/cli-reference.md @@ -1,7 +1,7 @@ # Gemini CLI cheatsheet -This page provides a reference for commonly used Gemini CLI commands, options, -and parameters. +Use this page as a reference for commonly used Gemini CLI commands, options, and +parameters. ## CLI commands @@ -18,6 +18,11 @@ and parameters. | `gemini update` | Update to latest version | `gemini update` | | `gemini extensions` | Manage extensions | See [Extensions Management](#extensions-management) | | `gemini mcp` | Configure MCP servers | See [MCP Server Management](#mcp-server-management) | +| `gemini rewind` | Manage session checkpoints | `gemini rewind --list` | +| `gemini sandbox` | Manage sandbox environments | `gemini sandbox --status` | +| `gemini settings` | Manage configuration | `gemini settings --list` | +| `gemini telemetry` | Manage telemetry data | `gemini telemetry --status` | +| `gemini token-caching` | Manage token caches | `gemini token-caching --list` | ### Positional arguments @@ -37,6 +42,11 @@ These commands are available within the interactive REPL. | `/memory reload` | Reload context files (for example, `GEMINI.md`) | | `/mcp reload` | Restart and reload MCP servers | | `/extensions reload` | Reload all active extensions | +| `/rewind` | Rewind the current session to a previous state | +| `/sandbox` | Manage the current sandbox environment | +| `/settings` | View or modify settings interactively | +| `/telemetry` | View telemetry status | +| `/token-caching` | Manage token caching for the current session | | `/help` | Show help for all commands | | `/quit` | Exit the interactive session | @@ -50,7 +60,7 @@ These commands are available within the interactive REPL. | `--model` | `-m` | string | `auto` | Model to use. See [Model Selection](#model-selection) for available values. | | `--prompt` | `-p` | string | - | Prompt text. Appended to stdin input if provided. Forces non-interactive mode. | | `--prompt-interactive` | `-i` | string | - | Execute prompt and continue in interactive mode | -| `--worktree` | `-w` | string | - | Start Gemini in a new git worktree. If no name is provided, one is generated automatically. Requires `experimental.worktrees: true` in settings. | +| `--worktree` | `-w` | string | - | Start Gemini in a new git worktree. If you don't provide a name, Gemini CLI generates one automatically. Requires `experimental.worktrees: true` in settings. | | `--sandbox` | `-s` | boolean | `false` | Run in a sandboxed environment for safer execution | | `--approval-mode` | - | string | `default` | Approval mode for tool execution. Choices: `default`, `auto_edit`, `yolo`, `plan` | | `--yolo` | `-y` | boolean | `false` | **Deprecated.** Auto-approve all actions. Use `--approval-mode=yolo` instead. | @@ -58,9 +68,9 @@ These commands are available within the interactive REPL. | `--experimental-zed-integration` | - | boolean | - | Run in Zed editor integration mode. **Experimental feature.** | | `--allowed-mcp-server-names` | - | array | - | Allowed MCP server names (comma-separated or multiple flags) | | `--allowed-tools` | - | array | - | **Deprecated.** Use the [Policy Engine](../reference/policy-engine.md) instead. Tools that are allowed to run without confirmation (comma-separated or multiple flags) | -| `--extensions` | `-e` | array | - | List of extensions to use. If not provided, all extensions are enabled (comma-separated or multiple flags) | +| `--extensions` | `-e` | array | - | List of extensions to use. If you don't provide this, all extensions are enabled (comma-separated or multiple flags) | | `--list-extensions` | `-l` | boolean | - | List all available extensions and exit | -| `--resume` | `-r` | string | - | Resume a previous session. Use `"latest"` for most recent or index number (for example `--resume 5`) | +| `--resume` | `-r` | string | - | Resume a previous session. Use `"latest"` for most recent or an index number (for example, `--resume 5`). | | `--list-sessions` | - | boolean | - | List available sessions for the current project and exit | | `--delete-session` | - | string | - | Delete a session by index number (use `--list-sessions` to see available sessions) | | `--include-directories` | - | array | - | Additional directories to include in the workspace (comma-separated or multiple flags) | @@ -78,8 +88,8 @@ These are convenient shortcuts that map to specific models: | Alias | Resolves To | Description | | ------------ | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- | -| `auto` | `gemini-2.5-pro` or `gemini-3-pro-preview` | **Default.** Resolves to the preview model if preview features are enabled, otherwise resolves to the standard pro model. | -| `pro` | `gemini-2.5-pro` or `gemini-3-pro-preview` | For complex reasoning tasks. Uses preview model if enabled. | +| `auto` | `gemini-3-pro-preview` or `gemini-2.5-pro` | **Default.** Resolves to the preview model if preview features are enabled, otherwise resolves to the standard pro model. | +| `pro` | `gemini-3-pro-preview` or `gemini-2.5-pro` | For complex reasoning tasks. Uses preview model if enabled. | | `flash` | `gemini-2.5-flash` | Fast, balanced model for most tasks. | | `flash-lite` | `gemini-2.5-flash-lite` | Fastest model for simple tasks. | diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md index 05368f20fe..5e058a5323 100644 --- a/docs/reference/configuration.md +++ b/docs/reference/configuration.md @@ -1,24 +1,24 @@ # Gemini CLI configuration -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. +Configure Gemini CLI using 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): +Gemini CLI applies configuration in the following order of precedence (higher +numbers override lower 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. +2. **System defaults file:** System-wide default settings that you can override + with 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. +7. **Command-line arguments:** Values you pass when launching the CLI. ## Settings files @@ -27,48 +27,47 @@ 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. +> JSON-aware editors can provide autocomplete and validation if you point them +> 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. + `/Library/Application Support/GeminiCli/system-defaults.json` (macOS). + Override the path 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. + settings have the lowest precedence and you can override them with 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. + - **Scope:** Applies only when you run 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. + `/Library/Application Support/GeminiCli/settings.json` (macOS). Override the + path 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. + files. This scope is useful for system administrators to manage Gemini CLI + setups across an organization. **Note on environment variables in settings:** String values within your -`settings.json` and `gemini-extension.json` files can reference environment +`settings.json` and `gemini-extension.json` files 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 +syntax. Gemini CLI automatically resolves these variables when it loads the +settings. For example, if you have an environment variable `MY_API_TOKEN`, you +can 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. +Additionally, each extension has its own `.env` file in its directory, which +loads automatically. **Note for Enterprise Users:** For guidance on deploying and managing Gemini CLI in a corporate environment, see the