@google/gemini-cli-core 0.22.0 → 0.23.0-preview.0

package/dist/docs/cli/index.md

@@ -0,0 +1,63 @@
+# Gemini CLI
+
+Within Gemini CLI, `packages/cli` is the frontend for users to send and receive
+prompts with the Gemini AI model and its associated tools. For a general
+overview of Gemini CLI, see the [main documentation page](../index.md).
+
+## Basic features
+
+- **[Commands](./commands.md):** A reference for all built-in slash commands
+- **[Custom commands](./custom-commands.md):** Create your own commands and
+  shortcuts for frequently used prompts.
+- **[Headless mode](./headless.md):** Use Gemini CLI programmatically for
+  scripting and automation.
+- **[Model selection](./model.md):** Configure the Gemini AI model used by the
+  CLI.
+- **[Settings](./settings.md):** Configure various aspects of the CLI's behavior
+  and appearance.
+- **[Themes](./themes.md):** Customizing the CLI's appearance with different
+  themes.
+- **[Keyboard shortcuts](./keyboard-shortcuts.md):** A reference for all
+  keyboard shortcuts to improve your workflow.
+- **[Tutorials](./tutorials.md):** Step-by-step guides for common tasks.
+
+## Advanced features
+
+- **[Checkpointing](./checkpointing.md):** Automatically save and restore
+  snapshots of your session and files.
+- **[Enterprise configuration](./enterprise.md):** Deploying and manage Gemini
+  CLI in an enterprise environment.
+- **[Sandboxing](./sandbox.md):** Isolate tool execution in a secure,
+  containerized environment.
+- **[Telemetry](./telemetry.md):** Configure observability to monitor usage and
+  performance.
+- **[Token caching](./token-caching.md):** Optimize API costs by caching tokens.
+- **[Trusted folders](./trusted-folders.md):** A security feature to control
+  which projects can use the full capabilities of the CLI.
+- **[Ignoring files (.geminiignore)](./gemini-ignore.md):** Exclude specific
+  files and directories from being accessed by tools.
+- **[Context files (GEMINI.md)](./gemini-md.md):** Provide persistent,
+  hierarchical context to the model.
+- **[System prompt override](./system-prompt.md):** Replace the built‑in system
+  instructions using `GEMINI_SYSTEM_MD`.
+
+## Non-interactive mode
+
+Gemini CLI can be run in a non-interactive mode, which is useful for scripting
+and automation. In this mode, you pipe input to the CLI, it executes the
+command, and then it exits.
+
+The following example pipes a command to Gemini CLI from your terminal:
+
+```bash
+echo "What is fine tuning?" | gemini
+```
+
+You can also use the `--prompt` or `-p` flag:
+
+```bash
+gemini -p "What is fine tuning?"
+```
+
+For comprehensive documentation on headless usage, scripting, automation, and
+advanced examples, see the **[Headless mode](./headless.md)** guide.

package/dist/docs/cli/keyboard-shortcuts.md

@@ -0,0 +1,143 @@
+# Gemini CLI keyboard shortcuts
+
+Gemini CLI ships with a set of default keyboard shortcuts for editing input,
+navigating history, and controlling the UI. Use this reference to learn the
+available combinations.
+
+<!-- KEYBINDINGS-AUTOGEN:START -->
+
+#### Basic Controls
+
+| Action                                       | Keys    |
+| -------------------------------------------- | ------- |
+| Confirm the current selection or choice.     | `Enter` |
+| Dismiss dialogs or cancel the current focus. | `Esc`   |
+
+#### Cursor Movement
+
+| Action                                    | Keys                   |
+| ----------------------------------------- | ---------------------- |
+| Move the cursor to the start of the line. | `Ctrl + A`<br />`Home` |
+| Move the cursor to the end of the line.   | `Ctrl + E`<br />`End`  |
+
+#### Editing
+
+| Action                                           | Keys                                      |
+| ------------------------------------------------ | ----------------------------------------- |
+| Delete from the cursor to the end of the line.   | `Ctrl + K`                                |
+| Delete from the cursor to the start of the line. | `Ctrl + U`                                |
+| Clear all text in the input field.               | `Ctrl + C`                                |
+| Delete the previous word.                        | `Ctrl + Backspace`<br />`Cmd + Backspace` |
+
+#### Screen Control
+
+| Action                                       | Keys       |
+| -------------------------------------------- | ---------- |
+| Clear the terminal screen and redraw the UI. | `Ctrl + L` |
+
+#### Scrolling
+
+| Action                   | Keys                 |
+| ------------------------ | -------------------- |
+| Scroll content up.       | `Shift + Up Arrow`   |
+| Scroll content down.     | `Shift + Down Arrow` |
+| Scroll to the top.       | `Home`               |
+| Scroll to the bottom.    | `End`                |
+| Scroll up by one page.   | `Page Up`            |
+| Scroll down by one page. | `Page Down`          |
+
+#### History & Search
+
+| Action                                       | Keys                  |
+| -------------------------------------------- | --------------------- |
+| Show the previous entry in history.          | `Ctrl + P (no Shift)` |
+| Show the next entry in history.              | `Ctrl + N (no Shift)` |
+| Start reverse search through history.        | `Ctrl + R`            |
+| Insert the selected reverse-search match.    | `Enter (no Ctrl)`     |
+| Accept a suggestion while reverse searching. | `Tab`                 |
+
+#### Navigation
+
+| Action                           | Keys                                        |
+| -------------------------------- | ------------------------------------------- |
+| Move selection up in lists.      | `Up Arrow (no Shift)`                       |
+| Move selection down in lists.    | `Down Arrow (no Shift)`                     |
+| Move up within dialog options.   | `Up Arrow (no Shift)`<br />`K (no Shift)`   |
+| Move down within dialog options. | `Down Arrow (no Shift)`<br />`J (no Shift)` |
+
+#### Suggestions & Completions
+
+| Action                                  | Keys                                               |
+| --------------------------------------- | -------------------------------------------------- |
+| Accept the inline suggestion.           | `Tab`<br />`Enter (no Ctrl)`                       |
+| Move to the previous completion option. | `Up Arrow (no Shift)`<br />`Ctrl + P (no Shift)`   |
+| Move to the next completion option.     | `Down Arrow (no Shift)`<br />`Ctrl + N (no Shift)` |
+| Expand an inline suggestion.            | `Right Arrow`                                      |
+| Collapse an inline suggestion.          | `Left Arrow`                                       |
+
+#### Text Input
+
+| Action                               | Keys                                                                                        |
+| ------------------------------------ | ------------------------------------------------------------------------------------------- |
+| Submit the current prompt.           | `Enter (no Ctrl, no Shift, no Cmd, not Paste)`                                              |
+| Insert a newline without submitting. | `Ctrl + Enter`<br />`Cmd + Enter`<br />`Paste + Enter`<br />`Shift + Enter`<br />`Ctrl + J` |
+
+#### External Tools
+
+| Action                                         | Keys                      |
+| ---------------------------------------------- | ------------------------- |
+| Open the current prompt in an external editor. | `Ctrl + X`                |
+| Paste from the clipboard.                      | `Ctrl + V`<br />`Cmd + V` |
+
+#### App Controls
+
+| Action                                                            | Keys       |
+| ----------------------------------------------------------------- | ---------- |
+| Toggle detailed error information.                                | `F12`      |
+| Toggle the full TODO list.                                        | `Ctrl + T` |
+| Toggle IDE context details.                                       | `Ctrl + G` |
+| Toggle Markdown rendering.                                        | `Cmd + M`  |
+| Toggle copy mode when the terminal is using the alternate buffer. | `Ctrl + S` |
+| Expand a height-constrained response to show additional lines.    | `Ctrl + S` |
+| Toggle focus between the shell and Gemini input.                  | `Ctrl + F` |
+
+#### Session Control
+
+| Action                                       | Keys       |
+| -------------------------------------------- | ---------- |
+| Cancel the current request or quit the CLI.  | `Ctrl + C` |
+| Exit the CLI when the input buffer is empty. | `Ctrl + D` |
+
+<!-- KEYBINDINGS-AUTOGEN:END -->
+
+## Additional context-specific shortcuts
+
+- `Ctrl+Y`: Toggle YOLO (auto-approval) mode for tool calls.
+- `Shift+Tab`: Toggle Auto Edit (auto-accept edits) mode.
+- `Option+M` (macOS): Entering `µ` with Option+M also toggles Markdown
+  rendering, matching `Cmd+M`.
+- `!` on an empty prompt: Enter or exit shell mode.
+- `\` (at end of a line) + `Enter`: Insert a newline without leaving single-line
+  mode.
+- `Ctrl+Delete` / `Meta+Delete`: Delete the word to the right of the cursor.
+- `Ctrl+B` or `Left Arrow`: Move the cursor one character to the left while
+  editing text.
+- `Ctrl+F` or `Right Arrow`: Move the cursor one character to the right; with an
+  embedded shell attached, `Ctrl+F` still toggles focus.
+- `Ctrl+D` or `Delete`: Remove the character immediately to the right of the
+  cursor.
+- `Ctrl+H` or `Backspace`: Remove the character immediately to the left of the
+  cursor.
+- `Ctrl+Left Arrow` / `Meta+Left Arrow` / `Meta+B`: Move one word to the left.
+- `Ctrl+Right Arrow` / `Meta+Right Arrow` / `Meta+F`: Move one word to the
+  right.
+- `Ctrl+W`: Delete the word to the left of the cursor (in addition to
+  `Ctrl+Backspace` / `Cmd+Backspace`).
+- `Ctrl+Z` / `Ctrl+Shift+Z`: Undo or redo the most recent text edit.
+- `Meta+Enter`: Open the current input in an external editor (alias for
+  `Ctrl+X`).
+- `Esc` pressed twice quickly: Clear the current input buffer.
+- `Up Arrow` / `Down Arrow`: When the cursor is at the top or bottom of a
+  single-line input, navigate backward or forward through prompt history.
+- `Number keys (1-9, multi-digit)` inside selection dialogs: Jump directly to
+  the numbered radio option and confirm when the full number is entered.

package/dist/docs/cli/model-routing.md

@@ -0,0 +1,37 @@
+## Model routing
+
+Gemini CLI includes a model routing feature that automatically switches to a
+fallback model in case of a model failure. This feature is enabled by default
+and provides resilience when the primary model is unavailable.
+
+## How it works
+
+Model routing is managed by the `ModelAvailabilityService`, which monitors model
+health and automatically routes requests to available models based on defined
+policies.
+
+1.  **Model failure:** If the currently selected model fails (e.g., due to quota
+    or server errors), the CLI will iniate the fallback process.
+
+2.  **User consent:** Depending on the failure and the model's policy, the CLI
+    may prompt you to switch to a fallback model (by default always prompts
+    you).
+
+3.  **Model switch:** If approved, or if the policy allows for silent fallback,
+    the CLI will use an available fallback model for the current turn or the
+    remainder of the session.
+
+### Model selection precedence
+
+The model used by Gemini CLI is determined by the following order of precedence:
+
+1.  **`--model` command-line flag:** A model specified with the `--model` flag
+    when launching the CLI will always be used.
+2.  **`GEMINI_MODEL` environment variable:** If the `--model` flag is not used,
+    the CLI will use the model specified in the `GEMINI_MODEL` environment
+    variable.
+3.  **`model.name` in `settings.json`:** If neither of the above are set, the
+    model specified in the `model.name` property of your `settings.json` file
+    will be used.
+4.  **Default model:** If none of the above are set, the default model will be
+    used. The default model is `auto`

package/dist/docs/cli/model.md

@@ -0,0 +1,62 @@
+# Gemini CLI model selection (`/model` command)
+
+Select your Gemini CLI model. The `/model` command lets you configure the model
+used by Gemini CLI, giving you more control over your results. Use **Pro**
+models for complex tasks and reasoning, **Flash** models for high speed results,
+or the (recommended) **Auto** setting to choose the best model for your tasks.
+
+> **Note:** The `/model` command (and the `--model` flag) does not override the
+> model used by sub-agents. Consequently, even when using the `/model` flag you
+> may see other models used in your model usage reports.
+
+## How to use the `/model` command
+
+Use the following command in Gemini CLI:
+
+```
+/model
+```
+
+Running this command will open a dialog with your options:
+
+| Option            | Description                                                    | Models                                                                 |
+| ----------------- | -------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| Auto (Gemini 3)   | Let the system choose the best Gemini 3 model for your task.   | gemini-3-pro-preview (if enabled), gemini-3-flash-preview (if enabled) |
+| Auto (Gemini 2.5) | Let the system choose the best Gemini 2.5 model for your task. | gemini-2.5-pro, gemini-2.5-flash                                       |
+| Manual            | Select a specific model.                                       | Any available model.                                                   |
+
+We recommend selecting one of the above **Auto** options. However, you can
+select **Manual** to select a specific model from those available.
+
+### Gemini 3 and preview features
+
+> **Note:** Gemini 3 is not currently available on all account types. To learn
+> more about Gemini 3 access, refer to
+> [Gemini 3 on Gemini CLI](../get-started/gemini-3.md).
+
+To enable Gemini 3 Pro and Gemini 3 Flash (if available), enable
+[**Preview Features** by using the `settings` command](../cli/settings.md).
+
+You can also use the `--model` flag to specify a particular Gemini model on
+startup. For more details, refer to the
+[configuration documentation](./configuration.md).
+
+Changes to these settings will be applied to all subsequent interactions with
+Gemini CLI.
+
+## Best practices for model selection
+
+- **Default to Auto.** For most users, the _Auto_ option model provides a
+  balance between speed and performance, automatically selecting the correct
+  model based on the complexity of the task. Example: Developing a web
+  application could include a mix of complex tasks (building architecture and
+  scaffolding the project) and simple tasks (generating CSS).
+
+- **Switch to Pro if you aren't getting the results you want.** If you think you
+  need your model to be a little "smarter," you can manually select Pro. Pro
+  will provide you with the highest levels of reasoning and creativity. Example:
+  A complex or multi-stage debugging task.
+
+- **Switch to Flash or Flash-Lite if you need faster results.** If you need a
+  simple response quickly, Flash or Flash-Lite is the best option. Example:
+  Converting a JSON object to a YAML string.

package/dist/docs/cli/sandbox.md

@@ -0,0 +1,171 @@
+# Sandboxing in the Gemini CLI
+
+This document provides a guide to sandboxing in the Gemini CLI, including
+prerequisites, quickstart, and configuration.
+
+## Prerequisites
+
+Before using sandboxing, you need to install and set up the Gemini CLI:
+
+```bash
+npm install -g @google/gemini-cli
+```
+
+To verify the installation
+
+```bash
+gemini --version
+```
+
+## Overview of sandboxing
+
+Sandboxing isolates potentially dangerous operations (such as shell commands or
+file modifications) from your host system, providing a security barrier between
+AI operations and your environment.
+
+The benefits of sandboxing include:
+
+- **Security**: Prevent accidental system damage or data loss.
+- **Isolation**: Limit file system access to project directory.
+- **Consistency**: Ensure reproducible environments across different systems.
+- **Safety**: Reduce risk when working with untrusted code or experimental
+  commands.
+
+## Sandboxing methods
+
+Your ideal method of sandboxing may differ depending on your platform and your
+preferred container solution.
+
+### 1. macOS Seatbelt (macOS only)
+
+Lightweight, built-in sandboxing using `sandbox-exec`.
+
+**Default profile**: `permissive-open` - restricts writes outside project
+directory but allows most other operations.
+
+### 2. Container-based (Docker/Podman)
+
+Cross-platform sandboxing with complete process isolation.
+
+**Note**: Requires building the sandbox image locally or using a published image
+from your organization's registry.
+
+## Quickstart
+
+```bash
+# Enable sandboxing with command flag
+gemini -s -p "analyze the code structure"
+
+# Use environment variable
+export GEMINI_SANDBOX=true
+gemini -p "run the test suite"
+
+# Configure in settings.json
+{
+  "tools": {
+    "sandbox": "docker"
+  }
+}
+```
+
+## Configuration
+
+### Enable sandboxing (in order of precedence)
+
+1. **Command flag**: `-s` or `--sandbox`
+2. **Environment variable**: `GEMINI_SANDBOX=true|docker|podman|sandbox-exec`
+3. **Settings file**: `"sandbox": true` in the `tools` object of your
+   `settings.json` file (e.g., `{"tools": {"sandbox": true}}`).
+
+### macOS Seatbelt profiles
+
+Built-in profiles (set via `SEATBELT_PROFILE` env var):
+
+- `permissive-open` (default): Write restrictions, network allowed
+- `permissive-closed`: Write restrictions, no network
+- `permissive-proxied`: Write restrictions, network via proxy
+- `restrictive-open`: Strict restrictions, network allowed
+- `restrictive-closed`: Maximum restrictions
+
+### Custom sandbox flags
+
+For container-based sandboxing, you can inject custom flags into the `docker` or
+`podman` command using the `SANDBOX_FLAGS` environment variable. This is useful
+for advanced configurations, such as disabling security features for specific
+use cases.
+
+**Example (Podman)**:
+
+To disable SELinux labeling for volume mounts, you can set the following:
+
+```bash
+export SANDBOX_FLAGS="--security-opt label=disable"
+```
+
+Multiple flags can be provided as a space-separated string:
+
+```bash
+export SANDBOX_FLAGS="--flag1 --flag2=value"
+```
+
+## Linux UID/GID handling
+
+The sandbox automatically handles user permissions on Linux. Override these
+permissions with:
+
+```bash
+export SANDBOX_SET_UID_GID=true   # Force host UID/GID
+export SANDBOX_SET_UID_GID=false  # Disable UID/GID mapping
+```
+
+## Troubleshooting
+
+### Common issues
+
+**"Operation not permitted"**
+
+- Operation requires access outside sandbox.
+- Try more permissive profile or add mount points.
+
+**Missing commands**
+
+- Add to custom Dockerfile.
+- Install via `sandbox.bashrc`.
+
+**Network issues**
+
+- Check sandbox profile allows network.
+- Verify proxy configuration.
+
+### Debug mode
+
+```bash
+DEBUG=1 gemini -s -p "debug command"
+```
+
+**Note:** If you have `DEBUG=true` in a project's `.env` file, it won't affect
+gemini-cli due to automatic exclusion. Use `.gemini/.env` files for gemini-cli
+specific debug settings.
+
+### Inspect sandbox
+
+```bash
+# Check environment
+gemini -s -p "run shell command: env | grep SANDBOX"
+
+# List mounts
+gemini -s -p "run shell command: mount | grep workspace"
+```
+
+## Security notes
+
+- Sandboxing reduces but doesn't eliminate all risks.
+- Use the most restrictive profile that allows your work.
+- Container overhead is minimal after first build.
+- GUI applications may not work in sandboxes.
+
+## Related documentation
+
+- [Configuration](../get-started/configuration.md): Full configuration options.
+- [Commands](./commands.md): Available commands.
+- [Troubleshooting](../troubleshooting.md): General troubleshooting.

package/dist/docs/cli/session-management.md

@@ -0,0 +1,158 @@
+# Session Management
+
+Gemini CLI includes robust session management features that automatically save
+your conversation history. This allows you to interrupt your work and resume
+exactly where you left off, review past interactions, and manage your
+conversation history effectively.
+
+## Automatic Saving
+
+Every time you interact with Gemini CLI, your session is automatically saved.
+This happens in the background without any manual intervention.
+
+- **What is saved:** The complete conversation history, including:
+  - Your prompts and the model's responses.
+  - All tool executions (inputs and outputs).
+  - Token usage statistics (input/output/cached, etc.).
+  - Assistant thoughts/reasoning summaries (when available).
+- **Location:** Sessions are stored in `~/.gemini/tmp/<project_hash>/chats/`.
+- **Scope:** Sessions are project-specific. Switching directories to a different
+  project will switch to that project's session history.
+
+## Resuming Sessions
+
+You can resume a previous session to continue the conversation with all prior
+context restored.
+
+### From the Command Line
+
+When starting the CLI, you can use the `--resume` (or `-r`) flag:
+
+- **Resume latest:**
+
+  ```bash
+  gemini --resume
+  ```
+
+  This immediately loads the most recent session.
+
+- **Resume by index:** First, list available sessions (see
+  [Listing Sessions](#listing-sessions)), then use the index number:
+
+  ```bash
+  gemini --resume 1
+  ```
+
+- **Resume by ID:** You can also provide the full session UUID:
+  ```bash
+  gemini --resume a1b2c3d4-e5f6-7890-abcd-ef1234567890
+  ```
+
+### From the Interactive Interface
+
+While the CLI is running, you can use the `/resume` slash command to open the
+**Session Browser**:
+
+```text
+/resume
+```
+
+This opens an interactive interface where you can:
+
+- **Browse:** Scroll through a list of your past sessions.
+- **Preview:** See details like the session date, message count, and the first
+  user prompt.
+- **Search:** Press `/` to enter search mode, then type to filter sessions by ID
+  or content.
+- **Select:** Press `Enter` to resume the selected session.
+
+## Managing Sessions
+
+### Listing Sessions
+
+To see a list of all available sessions for the current project from the command
+line:
+
+```bash
+gemini --list-sessions
+```
+
+Output example:
+
+```text
+Available sessions for this project (3):
+
+  1. Fix bug in auth (2 days ago) [a1b2c3d4]
+  2. Refactor database schema (5 hours ago) [e5f67890]
+  3. Update documentation (Just now) [abcd1234]
+```
+
+### Deleting Sessions
+
+You can remove old or unwanted sessions to free up space or declutter your
+history.
+
+**From the Command Line:** Use the `--delete-session` flag with an index or ID:
+
+```bash
+gemini --delete-session 2
+```
+
+**From the Session Browser:**
+
+1.  Open the browser with `/resume`.
+2.  Navigate to the session you want to remove.
+3.  Press `x`.
+
+## Configuration
+
+You can configure how Gemini CLI manages your session history in your
+`settings.json` file.
+
+### Session Retention
+
+To prevent your history from growing indefinitely, you can enable automatic
+cleanup policies.
+
+```json
+{
+  "general": {
+    "sessionRetention": {
+      "enabled": true,
+      "maxAge": "30d", // Keep sessions for 30 days
+      "maxCount": 50 // Keep the 50 most recent sessions
+    }
+  }
+}
+```
+
+- **`enabled`**: (boolean) Master switch for session cleanup. Default is
+  `false`.
+- **`maxAge`**: (string) Duration to keep sessions (e.g., "24h", "7d", "4w").
+  Sessions older than this will be deleted.
+- **`maxCount`**: (number) Maximum number of sessions to retain. The oldest
+  sessions exceeding this count will be deleted.
+- **`minRetention`**: (string) Minimum retention period (safety limit). Defaults
+  to `"1d"`; sessions newer than this period are never deleted by automatic
+  cleanup.
+
+### Session Limits
+
+You can also limit the length of individual sessions to prevent context windows
+from becoming too large and expensive.
+
+```json
+{
+  "model": {
+    "maxSessionTurns": 100
+  }
+}
+```
+
+- **`maxSessionTurns`**: (number) The maximum number of turns (user + model
+  exchanges) allowed in a single session. Set to `-1` for unlimited (default).
+
+  **Behavior when limit is reached:**
+  - **Interactive Mode:** The CLI shows an informational message and stops
+    sending requests to the model. You must manually start a new session.
+  - **Non-Interactive Mode:** The CLI exits with an error.