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

package/dist/docs/cli/themes.md

@@ -0,0 +1,237 @@
+# Themes
+
+Gemini CLI supports a variety of themes to customize its color scheme and
+appearance. You can change the theme to suit your preferences via the `/theme`
+command or `"theme":` configuration setting.
+
+## Available themes
+
+Gemini CLI comes with a selection of pre-defined themes, which you can list
+using the `/theme` command within Gemini CLI:
+
+- **Dark themes:**
+  - `ANSI`
+  - `Atom One`
+  - `Ayu`
+  - `Default`
+  - `Dracula`
+  - `GitHub`
+- **Light themes:**
+  - `ANSI Light`
+  - `Ayu Light`
+  - `Default Light`
+  - `GitHub Light`
+  - `Google Code`
+  - `Xcode`
+
+### Changing themes
+
+1.  Enter `/theme` into Gemini CLI.
+2.  A dialog or selection prompt appears, listing the available themes.
+3.  Using the arrow keys, select a theme. Some interfaces might offer a live
+    preview or highlight as you select.
+4.  Confirm your selection to apply the theme.
+
+**Note:** If a theme is defined in your `settings.json` file (either by name or
+by a file path), you must remove the `"theme"` setting from the file before you
+can change the theme using the `/theme` command.
+
+### Theme persistence
+
+Selected themes are saved in Gemini CLI's
+[configuration](../get-started/configuration.md) so your preference is
+remembered across sessions.
+
+---
+
+## Custom color themes
+
+Gemini CLI allows you to create your own custom color themes by specifying them
+in your `settings.json` file. This gives you full control over the color palette
+used in the CLI.
+
+### How to define a custom theme
+
+Add a `customThemes` block to your user, project, or system `settings.json`
+file. Each custom theme is defined as an object with a unique name and a set of
+color keys. For example:
+
+```json
+{
+  "ui": {
+    "customThemes": {
+      "MyCustomTheme": {
+        "name": "MyCustomTheme",
+        "type": "custom",
+        "Background": "#181818",
+        ...
+      }
+    }
+  }
+}
+```
+
+**Color keys:**
+
+- `Background`
+- `Foreground`
+- `LightBlue`
+- `AccentBlue`
+- `AccentPurple`
+- `AccentCyan`
+- `AccentGreen`
+- `AccentYellow`
+- `AccentRed`
+- `Comment`
+- `Gray`
+- `DiffAdded` (optional, for added lines in diffs)
+- `DiffRemoved` (optional, for removed lines in diffs)
+- `DiffModified` (optional, for modified lines in diffs)
+
+You can also override individual UI text roles by adding a nested `text` object.
+This object supports the keys `primary`, `secondary`, `link`, `accent`, and
+`response`. When `text.response` is provided it takes precedence over
+`text.primary` for rendering model responses in chat.
+
+**Required properties:**
+
+- `name` (must match the key in the `customThemes` object and be a string)
+- `type` (must be the string `"custom"`)
+- `Background`
+- `Foreground`
+- `LightBlue`
+- `AccentBlue`
+- `AccentPurple`
+- `AccentCyan`
+- `AccentGreen`
+- `AccentYellow`
+- `AccentRed`
+- `Comment`
+- `Gray`
+
+You can use either hex codes (e.g., `#FF0000`) **or** standard CSS color names
+(e.g., `coral`, `teal`, `blue`) for any color value. See
+[CSS color names](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#color_keywords)
+for a full list of supported names.
+
+You can define multiple custom themes by adding more entries to the
+`customThemes` object.
+
+### Loading themes from a file
+
+In addition to defining custom themes in `settings.json`, you can also load a
+theme directly from a JSON file by specifying the file path in your
+`settings.json`. This is useful for sharing themes or keeping them separate from
+your main configuration.
+
+To load a theme from a file, set the `theme` property in your `settings.json` to
+the path of your theme file:
+
+```json
+{
+  "ui": {
+    "theme": "/path/to/your/theme.json"
+  }
+}
+```
+
+The theme file must be a valid JSON file that follows the same structure as a
+custom theme defined in `settings.json`.
+
+**Example `my-theme.json`:**
+
+```json
+{
+  "name": "My File Theme",
+  "type": "custom",
+  "Background": "#282A36",
+  "Foreground": "#F8F8F2",
+  "LightBlue": "#82AAFF",
+  "AccentBlue": "#61AFEF",
+  "AccentPurple": "#BD93F9",
+  "AccentCyan": "#8BE9FD",
+  "AccentGreen": "#50FA7B",
+  "AccentYellow": "#F1FA8C",
+  "AccentRed": "#FF5555",
+  "Comment": "#6272A4",
+  "Gray": "#ABB2BF",
+  "DiffAdded": "#A6E3A1",
+  "DiffRemoved": "#F38BA8",
+  "DiffModified": "#89B4FA",
+  "GradientColors": ["#4796E4", "#847ACE", "#C3677F"]
+}
+```
+
+**Security note:** For your safety, Gemini CLI will only load theme files that
+are located within your home directory. If you attempt to load a theme from
+outside your home directory, a warning will be displayed and the theme will not
+be loaded. This is to prevent loading potentially malicious theme files from
+untrusted sources.
+
+### Example custom theme
+
+<img src="../assets/theme-custom.png" alt="Custom theme example" width="600" />
+
+### Using your custom theme
+
+- Select your custom theme using the `/theme` command in Gemini CLI. Your custom
+  theme will appear in the theme selection dialog.
+- Or, set it as the default by adding `"theme": "MyCustomTheme"` to the `ui`
+  object in your `settings.json`.
+- Custom themes can be set at the user, project, or system level, and follow the
+  same [configuration precedence](../get-started/configuration.md) as other
+  settings.
+
+---
+
+## Dark themes
+
+### ANSI
+
+<img src="/assets/theme-ansi.png" alt="ANSI theme" width="600" />
+
+### Atom OneDark
+
+<img src="/assets/theme-atom-one.png" alt="Atom One theme" width="600">
+
+### Ayu
+
+<img src="/assets/theme-ayu.png" alt="Ayu theme" width="600">
+
+### Default
+
+<img src="/assets/theme-default.png" alt="Default theme" width="600">
+
+### Dracula
+
+<img src="/assets/theme-dracula.png" alt="Dracula theme" width="600">
+
+### GitHub
+
+<img src="/assets/theme-github.png" alt="GitHub theme" width="600">
+
+## Light themes
+
+### ANSI Light
+
+<img src="/assets/theme-ansi-light.png" alt="ANSI Light theme" width="600">
+
+### Ayu Light
+
+<img src="/assets/theme-ayu-light.png" alt="Ayu Light theme" width="600">
+
+### Default Light
+
+<img src="/assets/theme-default-light.png" alt="Default Light theme" width="600">
+
+### GitHub Light
+
+<img src="/assets/theme-github-light.png" alt="GitHub Light theme" width="600">
+
+### Google Code
+
+<img src="/assets/theme-google-light.png" alt="Google Code theme" width="600">
+
+### Xcode
+
+<img src="/assets/theme-xcode-light.png" alt="Xcode Light theme" width="600">

package/dist/docs/cli/token-caching.md

@@ -0,0 +1,20 @@
+# Token caching and cost optimization
+
+Gemini CLI automatically optimizes API costs through token caching when using
+API key authentication (Gemini API key or Vertex AI). This feature reuses
+previous system instructions and context to reduce the number of tokens
+processed in subsequent requests.
+
+**Token caching is available for:**
+
+- API key users (Gemini API key)
+- Vertex AI users (with project and location setup)
+
+**Token caching is not available for:**
+
+- OAuth users (Google Personal/Enterprise accounts) - the Code Assist API does
+  not support cached content creation at this time
+
+You can view your token usage and cached token savings using the `/stats`
+command. When cached tokens are available, they will be displayed in the stats
+output.

package/dist/docs/cli/trusted-folders.md

@@ -0,0 +1,95 @@
+# Trusted Folders
+
+The Trusted Folders feature is a security setting that gives you control over
+which projects can use the full capabilities of the Gemini CLI. It prevents
+potentially malicious code from running by asking you to approve a folder before
+the CLI loads any project-specific configurations from it.
+
+## Enabling the feature
+
+The Trusted Folders feature is **disabled by default**. To use it, you must
+first enable it in your settings.
+
+Add the following to your user `settings.json` file:
+
+```json
+{
+  "security": {
+    "folderTrust": {
+      "enabled": true
+    }
+  }
+}
+```
+
+## How it works: The trust dialog
+
+Once the feature is enabled, the first time you run the Gemini CLI from a
+folder, a dialog will automatically appear, prompting you to make a choice:
+
+- **Trust folder**: Grants full trust to the current folder (e.g.,
+  `my-project`).
+- **Trust parent folder**: Grants trust to the parent directory (e.g.,
+  `safe-projects`), which automatically trusts all of its subdirectories as
+  well. This is useful if you keep all your safe projects in one place.
+- **Don't trust**: Marks the folder as untrusted. The CLI will operate in a
+  restricted "safe mode."
+
+Your choice is saved in a central file (`~/.gemini/trustedFolders.json`), so you
+will only be asked once per folder.
+
+## Why trust matters: The impact of an untrusted workspace
+
+When a folder is **untrusted**, the Gemini CLI runs in a restricted "safe mode"
+to protect you. In this mode, the following features are disabled:
+
+1.  **Workspace settings are ignored**: The CLI will **not** load the
+    `.gemini/settings.json` file from the project. This prevents the loading of
+    custom tools and other potentially dangerous configurations.
+
+2.  **Environment variables are ignored**: The CLI will **not** load any `.env`
+    files from the project.
+
+3.  **Extension management is restricted**: You **cannot install, update, or
+    uninstall** extensions.
+
+4.  **Tool auto-acceptance is disabled**: You will always be prompted before any
+    tool is run, even if you have auto-acceptance enabled globally.
+
+5.  **Automatic memory loading is disabled**: The CLI will not automatically
+    load files into context from directories specified in local settings.
+
+6.  **MCP servers do not connect**: The CLI will not attempt to connect to any
+    [Model Context Protocol (MCP)](../tools/mcp-server.md) servers.
+
+7.  **Custom commands are not loaded**: The CLI will not load any custom
+    commands from .toml files, including both project-specific and global user
+    commands.
+
+Granting trust to a folder unlocks the full functionality of the Gemini CLI for
+that workspace.
+
+## Managing your trust settings
+
+If you need to change a decision or see all your settings, you have a couple of
+options:
+
+- **Change the current folder's trust**: Run the `/permissions` command from
+  within the CLI. This will bring up the same interactive dialog, allowing you
+  to change the trust level for the current folder.
+
+- **View all trust rules**: To see a complete list of all your trusted and
+  untrusted folder rules, you can inspect the contents of the
+  `~/.gemini/trustedFolders.json` file in your home directory.
+
+## The trust check process (advanced)
+
+For advanced users, it's helpful to know the exact order of operations for how
+trust is determined:
+
+1.  **IDE trust signal**: If you are using the
+    [IDE Integration](../ide-integration/index.md), the CLI first asks the IDE
+    if the workspace is trusted. The IDE's response takes highest priority.
+
+2.  **Local trust file**: If the IDE is not connected, the CLI checks the
+    central `~/.gemini/trustedFolders.json` file.

package/dist/docs/cli/tutorials.md

@@ -0,0 +1,83 @@
+# Tutorials
+
+This page contains tutorials for interacting with Gemini CLI.
+
+## Setting up a Model Context Protocol (MCP) server
+
+> [!CAUTION] Before using a third-party MCP server, ensure you trust its source
+> and understand the tools it provides. Your use of third-party servers is at
+> your own risk.
+
+This tutorial demonstrates how to set up an MCP server, using the
+[GitHub MCP server](https://github.com/github/github-mcp-server) as an example.
+The GitHub MCP server provides tools for interacting with GitHub repositories,
+such as creating issues and commenting on pull requests.
+
+### Prerequisites
+
+Before you begin, ensure you have the following installed and configured:
+
+- **Docker:** Install and run [Docker].
+- **GitHub Personal Access Token (PAT):** Create a new [classic] or
+  [fine-grained] PAT with the necessary scopes.
+
+[Docker]: https://www.docker.com/
+[classic]: https://github.com/settings/tokens/new
+[fine-grained]: https://github.com/settings/personal-access-tokens/new
+
+### Guide
+
+#### Configure the MCP server in `settings.json`
+
+In your project's root directory, create or open the
+[`.gemini/settings.json` file](../get-started/configuration.md). Within the
+file, add the `mcpServers` configuration block, which provides instructions for
+how to launch the GitHub MCP server.
+
+```json
+{
+  "mcpServers": {
+    "github": {
+      "command": "docker",
+      "args": [
+        "run",
+        "-i",
+        "--rm",
+        "-e",
+        "GITHUB_PERSONAL_ACCESS_TOKEN",
+        "ghcr.io/github/github-mcp-server"
+      ],
+      "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_PERSONAL_ACCESS_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+#### Set your GitHub token
+
+> [!CAUTION] Using a broadly scoped personal access token that has access to
+> personal and private repositories can lead to information from the private
+> repository being leaked into the public repository. We recommend using a
+> fine-grained access token that doesn't share access to both public and private
+> repositories.
+
+Use an environment variable to store your GitHub PAT:
+
+```bash
+GITHUB_PERSONAL_ACCESS_TOKEN="pat_YourActualGitHubTokenHere"
+```
+
+Gemini CLI uses this value in the `mcpServers` configuration that you defined in
+the `settings.json` file.
+
+#### Launch Gemini CLI and verify the connection
+
+When you launch Gemini CLI, it automatically reads your configuration and
+launches the GitHub MCP server in the background. You can then use natural
+language prompts to ask Gemini CLI to perform GitHub actions. For example:
+
+```bash
+"get all open issues assigned to me in the 'foo/bar' repo and prioritize them"
+```

package/dist/docs/cli/uninstall.md

@@ -0,0 +1,47 @@
+# Uninstalling the CLI
+
+Your uninstall method depends on how you ran the CLI. Follow the instructions
+for either npx or a global npm installation.
+
+## Method 1: Using npx
+
+npx runs packages from a temporary cache without a permanent installation. To
+"uninstall" the CLI, you must clear this cache, which will remove gemini-cli and
+any other packages previously executed with npx.
+
+The npx cache is a directory named `_npx` inside your main npm cache folder. You
+can find your npm cache path by running `npm config get cache`.
+
+**For macOS / Linux**
+
+```bash
+# The path is typically ~/.npm/_npx
+rm -rf "$(npm config get cache)/_npx"
+```
+
+**For Windows**
+
+_Command Prompt_
+
+```cmd
+:: The path is typically %LocalAppData%\npm-cache\_npx
+rmdir /s /q "%LocalAppData%\npm-cache\_npx"
+```
+
+_PowerShell_
+
+```powershell
+# The path is typically $env:LocalAppData\npm-cache\_npx
+Remove-Item -Path (Join-Path $env:LocalAppData "npm-cache\_npx") -Recurse -Force
+```
+
+## Method 2: Using npm (global install)
+
+If you installed the CLI globally (e.g., `npm install -g @google/gemini-cli`),
+use the `npm uninstall` command with the `-g` flag to remove it.
+
+```bash
+npm uninstall -g @google/gemini-cli
+```
+
+This command completely removes the package from your system.

package/dist/docs/core/index.md

@@ -0,0 +1,101 @@
+# Gemini CLI core
+
+Gemini CLI's core package (`packages/core`) is the backend portion of Gemini
+CLI, handling communication with the Gemini API, managing tools, and processing
+requests sent from `packages/cli`. For a general overview of Gemini CLI, see the
+[main documentation page](../index.md).
+
+## Navigating this section
+
+- **[Core tools API](./tools-api.md):** Information on how tools are defined,
+  registered, and used by the core.
+- **[Memory Import Processor](./memport.md):** Documentation for the modular
+  GEMINI.md import feature using @file.md syntax.
+- **[Policy Engine](./policy-engine.md):** Use the Policy Engine for
+  fine-grained control over tool execution.
+
+## Role of the core
+
+While the `packages/cli` portion of Gemini CLI provides the user interface,
+`packages/core` is responsible for:
+
+- **Gemini API interaction:** Securely communicating with the Google Gemini API,
+  sending user prompts, and receiving model responses.
+- **Prompt engineering:** Constructing effective prompts for the Gemini model,
+  potentially incorporating conversation history, tool definitions, and
+  instructional context from `GEMINI.md` files.
+- **Tool management & orchestration:**
+  - Registering available tools (e.g., file system tools, shell command
+    execution).
+  - Interpreting tool use requests from the Gemini model.
+  - Executing the requested tools with the provided arguments.
+  - Returning tool execution results to the Gemini model for further processing.
+- **Session and state management:** Keeping track of the conversation state,
+  including history and any relevant context required for coherent interactions.
+- **Configuration:** Managing core-specific configurations, such as API key
+  access, model selection, and tool settings.
+
+## Security considerations
+
+The core plays a vital role in security:
+
+- **API key management:** It handles the `GEMINI_API_KEY` and ensures it's used
+  securely when communicating with the Gemini API.
+- **Tool execution:** When tools interact with the local system (e.g.,
+  `run_shell_command`), the core (and its underlying tool implementations) must
+  do so with appropriate caution, often involving sandboxing mechanisms to
+  prevent unintended modifications.
+
+## Chat history compression
+
+To ensure that long conversations don't exceed the token limits of the Gemini
+model, the core includes a chat history compression feature.
+
+When a conversation approaches the token limit for the configured model, the
+core automatically compresses the conversation history before sending it to the
+model. This compression is designed to be lossless in terms of the information
+conveyed, but it reduces the overall number of tokens used.
+
+You can find the token limits for each model in the
+[Google AI documentation](https://ai.google.dev/gemini-api/docs/models).
+
+## Model fallback
+
+Gemini CLI includes a model fallback mechanism to ensure that you can continue
+to use the CLI even if the default "pro" model is rate-limited.
+
+If you are using the default "pro" model and the CLI detects that you are being
+rate-limited, it automatically switches to the "flash" model for the current
+session. This allows you to continue working without interruption.
+
+## File discovery service
+
+The file discovery service is responsible for finding files in the project that
+are relevant to the current context. It is used by the `@` command and other
+tools that need to access files.
+
+## Memory discovery service
+
+The memory discovery service is responsible for finding and loading the
+`GEMINI.md` files that provide context to the model. It searches for these files
+in a hierarchical manner, starting from the current working directory and moving
+up to the project root and the user's home directory. It also searches in
+subdirectories.
+
+This allows you to have global, project-level, and component-level context
+files, which are all combined to provide the model with the most relevant
+information.
+
+You can use the [`/memory` command](../cli/commands.md) to `show`, `add`, and
+`refresh` the content of loaded `GEMINI.md` files.
+
+## Citations
+
+When Gemini finds it is reciting text from a source it appends the citation to
+the output. It is enabled by default but can be disabled with the
+ui.showCitations setting.
+
+- When proposing an edit the citations display before giving the user the option
+  to accept.
+- Citations are always shown at the end of the model’s turn.
+- We deduplicate citations and display them in alphabetical order.