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

package/dist/docs/sidebar.json

@@ -0,0 +1,297 @@
+[
+  {
+    "label": "Overview",
+    "items": [
+      {
+        "label": "Introduction",
+        "slug": "docs"
+      },
+      {
+        "label": "Architecture overview",
+        "slug": "docs/architecture"
+      },
+      {
+        "label": "Contribution guide",
+        "slug": "docs/contributing"
+      }
+    ]
+  },
+  {
+    "label": "Get started",
+    "items": [
+      {
+        "label": "Gemini CLI quickstart",
+        "slug": "docs/get-started"
+      },
+      {
+        "label": "Gemini 3 on Gemini CLI",
+        "slug": "docs/get-started/gemini-3"
+      },
+      {
+        "label": "Authentication",
+        "slug": "docs/get-started/authentication"
+      },
+      {
+        "label": "Configuration",
+        "slug": "docs/get-started/configuration"
+      },
+      {
+        "label": "Installation",
+        "slug": "docs/get-started/installation"
+      },
+      {
+        "label": "Examples",
+        "slug": "docs/get-started/examples"
+      }
+    ]
+  },
+  {
+    "label": "CLI",
+    "items": [
+      {
+        "label": "Introduction",
+        "slug": "docs/cli"
+      },
+      {
+        "label": "Commands",
+        "slug": "docs/cli/commands"
+      },
+      {
+        "label": "Checkpointing",
+        "slug": "docs/cli/checkpointing"
+      },
+      {
+        "label": "Custom commands",
+        "slug": "docs/cli/custom-commands"
+      },
+      {
+        "label": "Enterprise",
+        "slug": "docs/cli/enterprise"
+      },
+      {
+        "label": "Headless mode",
+        "slug": "docs/cli/headless"
+      },
+      {
+        "label": "Keyboard shortcuts",
+        "slug": "docs/cli/keyboard-shortcuts"
+      },
+      {
+        "label": "Model selection",
+        "slug": "docs/cli/model"
+      },
+      {
+        "label": "Sandbox",
+        "slug": "docs/cli/sandbox"
+      },
+      {
+        "label": "Session Management",
+        "slug": "docs/cli/session-management"
+      },
+      {
+        "label": "Settings",
+        "slug": "docs/cli/settings"
+      },
+      {
+        "label": "Telemetry",
+        "slug": "docs/cli/telemetry"
+      },
+      {
+        "label": "Themes",
+        "slug": "docs/cli/themes"
+      },
+      {
+        "label": "Token caching",
+        "slug": "docs/cli/token-caching"
+      },
+      {
+        "label": "Trusted Folders",
+        "slug": "docs/cli/trusted-folders"
+      },
+      {
+        "label": "Tutorials",
+        "slug": "docs/cli/tutorials"
+      },
+      {
+        "label": "Uninstall",
+        "slug": "docs/cli/uninstall"
+      },
+      {
+        "label": "System prompt override",
+        "slug": "docs/cli/system-prompt"
+      }
+    ]
+  },
+  {
+    "label": "Core",
+    "items": [
+      {
+        "label": "Introduction",
+        "slug": "docs/core"
+      },
+      {
+        "label": "Tools API",
+        "slug": "docs/core/tools-api"
+      },
+      {
+        "label": "Memory Import Processor",
+        "slug": "docs/core/memport"
+      },
+      {
+        "label": "Policy Engine",
+        "slug": "docs/core/policy-engine"
+      }
+    ]
+  },
+  {
+    "label": "Tools",
+    "items": [
+      {
+        "label": "Introduction",
+        "slug": "docs/tools"
+      },
+      {
+        "label": "File system",
+        "slug": "docs/tools/file-system"
+      },
+      {
+        "label": "Shell",
+        "slug": "docs/tools/shell"
+      },
+      {
+        "label": "Web fetch",
+        "slug": "docs/tools/web-fetch"
+      },
+      {
+        "label": "Web search",
+        "slug": "docs/tools/web-search"
+      },
+      {
+        "label": "Memory",
+        "slug": "docs/tools/memory"
+      },
+      {
+        "label": "Todos",
+        "slug": "docs/tools/todos"
+      },
+      {
+        "label": "MCP servers",
+        "slug": "docs/tools/mcp-server"
+      }
+    ]
+  },
+  {
+    "label": "Extensions",
+    "items": [
+      {
+        "label": "Introduction",
+        "slug": "docs/extensions"
+      },
+      {
+        "label": "Get started with extensions",
+        "slug": "docs/extensions/getting-started-extensions"
+      },
+      {
+        "label": "Extension releasing",
+        "slug": "docs/extensions/extension-releasing"
+      }
+    ]
+  },
+  {
+    "label": "Hooks",
+    "items": [
+      {
+        "label": "Introduction",
+        "slug": "docs/hooks"
+      },
+      {
+        "label": "Writing hooks",
+        "slug": "docs/hooks/writing-hooks"
+      },
+      {
+        "label": "Hooks reference",
+        "slug": "docs/hooks/reference"
+      },
+      {
+        "label": "Best practices",
+        "slug": "docs/hooks/best-practices"
+      }
+    ]
+  },
+  {
+    "label": "IDE integration",
+    "items": [
+      {
+        "label": "Introduction",
+        "slug": "docs/ide-integration"
+      },
+      {
+        "label": "IDE companion spec",
+        "slug": "docs/ide-integration/ide-companion-spec"
+      }
+    ]
+  },
+  {
+    "label": "Development",
+    "items": [
+      {
+        "label": "NPM",
+        "slug": "docs/npm"
+      },
+      {
+        "label": "Releases",
+        "slug": "docs/releases"
+      },
+      {
+        "label": "Integration tests",
+        "slug": "docs/integration-tests"
+      },
+      {
+        "label": "Issue and PR automation",
+        "slug": "docs/issue-and-pr-automation"
+      }
+    ]
+  },
+  {
+    "label": "Releases",
+    "items": [
+      {
+        "label": "Release notes",
+        "slug": "docs/changelogs/"
+      },
+      {
+        "label": "Latest release",
+        "slug": "docs/changelogs/latest"
+      },
+      {
+        "label": "Preview release",
+        "slug": "docs/changelogs/preview"
+      },
+      {
+        "label": "Changelog",
+        "slug": "docs/changelogs/releases"
+      }
+    ]
+  },
+  {
+    "label": "Support",
+    "items": [
+      {
+        "label": "FAQ",
+        "slug": "docs/faq"
+      },
+      {
+        "label": "Troubleshooting",
+        "slug": "docs/troubleshooting"
+      },
+      {
+        "label": "Quota and pricing",
+        "slug": "docs/quota-and-pricing"
+      },
+      {
+        "label": "Terms of service",
+        "slug": "docs/tos-privacy"
+      }
+    ]
+  }
+]

package/dist/docs/tools/file-system.md

@@ -0,0 +1,217 @@
+# Gemini CLI file system tools
+
+The Gemini CLI provides a comprehensive suite of tools for interacting with the
+local file system. These tools allow the Gemini model to read from, write to,
+list, search, and modify files and directories, all under your control and
+typically with confirmation for sensitive operations.
+
+**Note:** All file system tools operate within a `rootDirectory` (usually the
+current working directory where you launched the CLI) for security. Paths that
+you provide to these tools are generally expected to be absolute or are resolved
+relative to this root directory.
+
+## 1. `list_directory` (ReadFolder)
+
+`list_directory` lists the names of files and subdirectories directly within a
+specified directory path. It can optionally ignore entries matching provided
+glob patterns.
+
+- **Tool name:** `list_directory`
+- **Display name:** ReadFolder
+- **File:** `ls.ts`
+- **Parameters:**
+  - `path` (string, required): The absolute path to the directory to list.
+  - `ignore` (array of strings, optional): A list of glob patterns to exclude
+    from the listing (e.g., `["*.log", ".git"]`).
+  - `respect_git_ignore` (boolean, optional): Whether to respect `.gitignore`
+    patterns when listing files. Defaults to `true`.
+- **Behavior:**
+  - Returns a list of file and directory names.
+  - Indicates whether each entry is a directory.
+  - Sorts entries with directories first, then alphabetically.
+- **Output (`llmContent`):** A string like:
+  `Directory listing for /path/to/your/folder:\n[DIR] subfolder1\nfile1.txt\nfile2.png`
+- **Confirmation:** No.
+
+## 2. `read_file` (ReadFile)
+
+`read_file` reads and returns the content of a specified file. This tool handles
+text, images (PNG, JPG, GIF, WEBP, SVG, BMP), audio files (MP3, WAV, AIFF, AAC,
+OGG, FLAC), and PDF files. For text files, it can read specific line ranges.
+Other binary file types are generally skipped.
+
+- **Tool name:** `read_file`
+- **Display name:** ReadFile
+- **File:** `read-file.ts`
+- **Parameters:**
+  - `path` (string, required): The absolute path to the file to read.
+  - `offset` (number, optional): For text files, the 0-based line number to
+    start reading from. Requires `limit` to be set.
+  - `limit` (number, optional): For text files, the maximum number of lines to
+    read. If omitted, reads a default maximum (e.g., 2000 lines) or the entire
+    file if feasible.
+- **Behavior:**
+  - For text files: Returns the content. If `offset` and `limit` are used,
+    returns only that slice of lines. Indicates if content was truncated due to
+    line limits or line length limits.
+  - For image, audio, and PDF files: Returns the file content as a
+    base64-encoded data structure suitable for model consumption.
+  - For other binary files: Attempts to identify and skip them, returning a
+    message indicating it's a generic binary file.
+- **Output:** (`llmContent`):
+  - For text files: The file content, potentially prefixed with a truncation
+    message (e.g.,
+    `[File content truncated: showing lines 1-100 of 500 total lines...]\nActual file content...`).
+  - For image/audio/PDF files: An object containing `inlineData` with `mimeType`
+    and base64 `data` (e.g.,
+    `{ inlineData: { mimeType: 'image/png', data: 'base64encodedstring' } }`).
+  - For other binary files: A message like
+    `Cannot display content of binary file: /path/to/data.bin`.
+- **Confirmation:** No.
+
+## 3. `write_file` (WriteFile)
+
+`write_file` writes content to a specified file. If the file exists, it will be
+overwritten. If the file doesn't exist, it (and any necessary parent
+directories) will be created.
+
+- **Tool name:** `write_file`
+- **Display name:** WriteFile
+- **File:** `write-file.ts`
+- **Parameters:**
+  - `file_path` (string, required): The absolute path to the file to write to.
+  - `content` (string, required): The content to write into the file.
+- **Behavior:**
+  - Writes the provided `content` to the `file_path`.
+  - Creates parent directories if they don't exist.
+- **Output (`llmContent`):** A success message, e.g.,
+  `Successfully overwrote file: /path/to/your/file.txt` or
+  `Successfully created and wrote to new file: /path/to/new/file.txt`.
+- **Confirmation:** Yes. Shows a diff of changes and asks for user approval
+  before writing.
+
+## 4. `glob` (FindFiles)
+
+`glob` finds files matching specific glob patterns (e.g., `src/**/*.ts`,
+`*.md`), returning absolute paths sorted by modification time (newest first).
+
+- **Tool name:** `glob`
+- **Display name:** FindFiles
+- **File:** `glob.ts`
+- **Parameters:**
+  - `pattern` (string, required): The glob pattern to match against (e.g.,
+    `"*.py"`, `"src/**/*.js"`).
+  - `path` (string, optional): The absolute path to the directory to search
+    within. If omitted, searches the tool's root directory.
+  - `case_sensitive` (boolean, optional): Whether the search should be
+    case-sensitive. Defaults to `false`.
+  - `respect_git_ignore` (boolean, optional): Whether to respect .gitignore
+    patterns when finding files. Defaults to `true`.
+- **Behavior:**
+  - Searches for files matching the glob pattern within the specified directory.
+  - Returns a list of absolute paths, sorted with the most recently modified
+    files first.
+  - Ignores common nuisance directories like `node_modules` and `.git` by
+    default.
+- **Output (`llmContent`):** A message like:
+  `Found 5 file(s) matching "*.ts" within src, sorted by modification time (newest first):\nsrc/file1.ts\nsrc/subdir/file2.ts...`
+- **Confirmation:** No.
+
+## 5. `search_file_content` (SearchText)
+
+`search_file_content` searches for a regular expression pattern within the
+content of files in a specified directory. Can filter files by a glob pattern.
+Returns the lines containing matches, along with their file paths and line
+numbers.
+
+- **Tool name:** `search_file_content`
+- **Display name:** SearchText
+- **File:** `grep.ts`
+- **Parameters:**
+  - `pattern` (string, required): The regular expression (regex) to search for
+    (e.g., `"function\s+myFunction"`).
+  - `path` (string, optional): The absolute path to the directory to search
+    within. Defaults to the current working directory.
+  - `include` (string, optional): A glob pattern to filter which files are
+    searched (e.g., `"*.js"`, `"src/**/*.{ts,tsx}"`). If omitted, searches most
+    files (respecting common ignores).
+- **Behavior:**
+  - Uses `git grep` if available in a Git repository for speed; otherwise, falls
+    back to system `grep` or a JavaScript-based search.
+  - Returns a list of matching lines, each prefixed with its file path (relative
+    to the search directory) and line number.
+- **Output (`llmContent`):** A formatted string of matches, e.g.:
+  ```
+  Found 3 matches for pattern "myFunction" in path "." (filter: "*.ts"):
+  ---
+  File: src/utils.ts
+  L15: export function myFunction() {
+  L22:   myFunction.call();
+  ---
+  File: src/index.ts
+  L5: import { myFunction } from './utils';
+  ---
+  ```
+- **Confirmation:** No.
+
+## 6. `replace` (Edit)
+
+`replace` replaces text within a file. By default, replaces a single occurrence,
+but can replace multiple occurrences when `expected_replacements` is specified.
+This tool is designed for precise, targeted changes and requires significant
+context around the `old_string` to ensure it modifies the correct location.
+
+- **Tool name:** `replace`
+- **Display name:** Edit
+- **File:** `edit.ts`
+- **Parameters:**
+  - `file_path` (string, required): The absolute path to the file to modify.
+  - `old_string` (string, required): The exact literal text to replace.
+
+    **CRITICAL:** This string must uniquely identify the single instance to
+    change. It should include at least 3 lines of context _before_ and _after_
+    the target text, matching whitespace and indentation precisely. If
+    `old_string` is empty, the tool attempts to create a new file at `file_path`
+    with `new_string` as content.
+
+  - `new_string` (string, required): The exact literal text to replace
+    `old_string` with.
+  - `expected_replacements` (number, optional): The number of occurrences to
+    replace. Defaults to `1`.
+
+- **Behavior:**
+  - If `old_string` is empty and `file_path` does not exist, creates a new file
+    with `new_string` as content.
+  - If `old_string` is provided, it reads the `file_path` and attempts to find
+    exactly one occurrence of `old_string`.
+  - If one occurrence is found, it replaces it with `new_string`.
+  - **Enhanced reliability (multi-stage edit correction):** To significantly
+    improve the success rate of edits, especially when the model-provided
+    `old_string` might not be perfectly precise, the tool incorporates a
+    multi-stage edit correction mechanism.
+    - If the initial `old_string` isn't found or matches multiple locations, the
+      tool can leverage the Gemini model to iteratively refine `old_string` (and
+      potentially `new_string`).
+    - This self-correction process attempts to identify the unique segment the
+      model intended to modify, making the `replace` operation more robust even
+      with slightly imperfect initial context.
+- **Failure conditions:** Despite the correction mechanism, the tool will fail
+  if:
+  - `file_path` is not absolute or is outside the root directory.
+  - `old_string` is not empty, but the `file_path` does not exist.
+  - `old_string` is empty, but the `file_path` already exists.
+  - `old_string` is not found in the file after attempts to correct it.
+  - `old_string` is found multiple times, and the self-correction mechanism
+    cannot resolve it to a single, unambiguous match.
+- **Output (`llmContent`):**
+  - On success:
+    `Successfully modified file: /path/to/file.txt (1 replacements).` or
+    `Created new file: /path/to/new_file.txt with provided content.`
+  - On failure: An error message explaining the reason (e.g.,
+    `Failed to edit, 0 occurrences found...`,
+    `Failed to edit, expected 1 occurrences but found 2...`).
+- **Confirmation:** Yes. Shows a diff of the proposed changes and asks for user
+  approval before writing to the file.
+
+These file system tools provide a foundation for the Gemini CLI to understand
+and interact with your local project context.

package/dist/docs/tools/index.md

@@ -0,0 +1,95 @@
+# Gemini CLI tools
+
+The Gemini CLI includes built-in tools that the Gemini model uses to interact
+with your local environment, access information, and perform actions. These
+tools enhance the CLI's capabilities, enabling it to go beyond text generation
+and assist with a wide range of tasks.
+
+## Overview of Gemini CLI tools
+
+In the context of the Gemini CLI, tools are specific functions or modules that
+the Gemini model can request to be executed. For example, if you ask Gemini to
+"Summarize the contents of `my_document.txt`," the model will likely identify
+the need to read that file and will request the execution of the `read_file`
+tool.
+
+The core component (`packages/core`) manages these tools, presents their
+definitions (schemas) to the Gemini model, executes them when requested, and
+returns the results to the model for further processing into a user-facing
+response.
+
+These tools provide the following capabilities:
+
+- **Access local information:** Tools allow Gemini to access your local file
+  system, read file contents, list directories, etc.
+- **Execute commands:** With tools like `run_shell_command`, Gemini can run
+  shell commands (with appropriate safety measures and user confirmation).
+- **Interact with the web:** Tools can fetch content from URLs.
+- **Take actions:** Tools can modify files, write new files, or perform other
+  actions on your system (again, typically with safeguards).
+- **Ground responses:** By using tools to fetch real-time or specific local
+  data, Gemini's responses can be more accurate, relevant, and grounded in your
+  actual context.
+
+## How to use Gemini CLI tools
+
+To use Gemini CLI tools, provide a prompt to the Gemini CLI. The process works
+as follows:
+
+1.  You provide a prompt to the Gemini CLI.
+2.  The CLI sends the prompt to the core.
+3.  The core, along with your prompt and conversation history, sends a list of
+    available tools and their descriptions/schemas to the Gemini API.
+4.  The Gemini model analyzes your request. If it determines that a tool is
+    needed, its response will include a request to execute a specific tool with
+    certain parameters.
+5.  The core receives this tool request, validates it, and (often after user
+    confirmation for sensitive operations) executes the tool.
+6.  The output from the tool is sent back to the Gemini model.
+7.  The Gemini model uses the tool's output to formulate its final answer, which
+    is then sent back through the core to the CLI and displayed to you.
+
+You will typically see messages in the CLI indicating when a tool is being
+called and whether it succeeded or failed.
+
+## Security and confirmation
+
+Many tools, especially those that can modify your file system or execute
+commands (`write_file`, `edit`, `run_shell_command`), are designed with safety
+in mind. The Gemini CLI will typically:
+
+- **Require confirmation:** Prompt you before executing potentially sensitive
+  operations, showing you what action is about to be taken.
+- **Utilize sandboxing:** All tools are subject to restrictions enforced by
+  sandboxing (see [Sandboxing in the Gemini CLI](../cli/sandbox.md)). This means
+  that when operating in a sandbox, any tools (including MCP servers) you wish
+  to use must be available _inside_ the sandbox environment. For example, to run
+  an MCP server through `npx`, the `npx` executable must be installed within the
+  sandbox's Docker image or be available in the `sandbox-exec` environment.
+
+It's important to always review confirmation prompts carefully before allowing a
+tool to proceed.
+
+## Learn more about Gemini CLI's tools
+
+Gemini CLI's built-in tools can be broadly categorized as follows:
+
+- **[File System Tools](./file-system.md):** For interacting with files and
+  directories (reading, writing, listing, searching, etc.).
+- **[Shell Tool](./shell.md) (`run_shell_command`):** For executing shell
+  commands.
+- **[Web Fetch Tool](./web-fetch.md) (`web_fetch`):** For retrieving content
+  from URLs.
+- **[Web Search Tool](./web-search.md) (`google_web_search`):** For searching
+  the web.
+- **[Memory Tool](./memory.md) (`save_memory`):** For saving and recalling
+  information across sessions.
+- **[Todo Tool](./todos.md) (`write_todos`):** For managing subtasks of complex
+  requests.
+
+Additionally, these tools incorporate:
+
+- **[MCP servers](./mcp-server.md)**: MCP servers act as a bridge between the
+  Gemini model and your local environment or other services like APIs.
+- **[Sandboxing](../cli/sandbox.md)**: Sandboxing isolates the model and its
+  changes from your environment to reduce potential risk.