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

package/dist/docs/tools/memory.md

@@ -0,0 +1,54 @@
+# Memory tool (`save_memory`)
+
+This document describes the `save_memory` tool for the Gemini CLI.
+
+## Description
+
+Use `save_memory` to save and recall information across your Gemini CLI
+sessions. With `save_memory`, you can direct the CLI to remember key details
+across sessions, providing personalized and directed assistance.
+
+### Arguments
+
+`save_memory` takes one argument:
+
+- `fact` (string, required): The specific fact or piece of information to
+  remember. This should be a clear, self-contained statement written in natural
+  language.
+
+## How to use `save_memory` with the Gemini CLI
+
+The tool appends the provided `fact` to a special `GEMINI.md` file located in
+the user's home directory (`~/.gemini/GEMINI.md`). This file can be configured
+to have a different name.
+
+Once added, the facts are stored under a `## Gemini Added Memories` section.
+This file is loaded as context in subsequent sessions, allowing the CLI to
+recall the saved information.
+
+Usage:
+
+```
+save_memory(fact="Your fact here.")
+```
+
+### `save_memory` examples
+
+Remember a user preference:
+
+```
+save_memory(fact="My preferred programming language is Python.")
+```
+
+Store a project-specific detail:
+
+```
+save_memory(fact="The project I'm currently working on is called 'gemini-cli'.")
+```
+
+## Important notes
+
+- **General usage:** This tool should be used for concise, important facts. It
+  is not intended for storing large amounts of data or conversational history.
+- **Memory file:** The memory file is a plain text Markdown file, so you can
+  view and edit it manually if needed.

package/dist/docs/tools/shell.md

@@ -0,0 +1,260 @@
+# Shell tool (`run_shell_command`)
+
+This document describes the `run_shell_command` tool for the Gemini CLI.
+
+## Description
+
+Use `run_shell_command` to interact with the underlying system, run scripts, or
+perform command-line operations. `run_shell_command` executes a given shell
+command, including interactive commands that require user input (e.g., `vim`,
+`git rebase -i`) if the `tools.shell.enableInteractiveShell` setting is set to
+`true`.
+
+On Windows, commands are executed with `powershell.exe -NoProfile -Command`
+(unless you explicitly point `ComSpec` at another shell). On other platforms,
+they are executed with `bash -c`.
+
+### Arguments
+
+`run_shell_command` takes the following arguments:
+
+- `command` (string, required): The exact shell command to execute.
+- `description` (string, optional): A brief description of the command's
+  purpose, which will be shown to the user.
+- `directory` (string, optional): The directory (relative to the project root)
+  in which to execute the command. If not provided, the command runs in the
+  project root.
+
+## How to use `run_shell_command` with the Gemini CLI
+
+When using `run_shell_command`, the command is executed as a subprocess.
+`run_shell_command` can start background processes using `&`. The tool returns
+detailed information about the execution, including:
+
+- `Command`: The command that was executed.
+- `Directory`: The directory where the command was run.
+- `Stdout`: Output from the standard output stream.
+- `Stderr`: Output from the standard error stream.
+- `Error`: Any error message reported by the subprocess.
+- `Exit Code`: The exit code of the command.
+- `Signal`: The signal number if the command was terminated by a signal.
+- `Background PIDs`: A list of PIDs for any background processes started.
+
+Usage:
+
+```
+run_shell_command(command="Your commands.", description="Your description of the command.", directory="Your execution directory.")
+```
+
+## `run_shell_command` examples
+
+List files in the current directory:
+
+```
+run_shell_command(command="ls -la")
+```
+
+Run a script in a specific directory:
+
+```
+run_shell_command(command="./my_script.sh", directory="scripts", description="Run my custom script")
+```
+
+Start a background server:
+
+```
+run_shell_command(command="npm run dev &", description="Start development server in background")
+```
+
+## Configuration
+
+You can configure the behavior of the `run_shell_command` tool by modifying your
+`settings.json` file or by using the `/settings` command in the Gemini CLI.
+
+### Enabling interactive commands
+
+To enable interactive commands, you need to set the
+`tools.shell.enableInteractiveShell` setting to `true`. This will use `node-pty`
+for shell command execution, which allows for interactive sessions. If
+`node-pty` is not available, it will fall back to the `child_process`
+implementation, which does not support interactive commands.
+
+**Example `settings.json`:**
+
+```json
+{
+  "tools": {
+    "shell": {
+      "enableInteractiveShell": true
+    }
+  }
+}
+```
+
+### Showing color in output
+
+To show color in the shell output, you need to set the `tools.shell.showColor`
+setting to `true`. **Note: This setting only applies when
+`tools.shell.enableInteractiveShell` is enabled.**
+
+**Example `settings.json`:**
+
+```json
+{
+  "tools": {
+    "shell": {
+      "showColor": true
+    }
+  }
+}
+```
+
+### Setting the pager
+
+You can set a custom pager for the shell output by setting the
+`tools.shell.pager` setting. The default pager is `cat`. **Note: This setting
+only applies when `tools.shell.enableInteractiveShell` is enabled.**
+
+**Example `settings.json`:**
+
+```json
+{
+  "tools": {
+    "shell": {
+      "pager": "less"
+    }
+  }
+}
+```
+
+## Interactive commands
+
+The `run_shell_command` tool now supports interactive commands by integrating a
+pseudo-terminal (pty). This allows you to run commands that require real-time
+user input, such as text editors (`vim`, `nano`), terminal-based UIs (`htop`),
+and interactive version control operations (`git rebase -i`).
+
+When an interactive command is running, you can send input to it from the Gemini
+CLI. To focus on the interactive shell, press `ctrl+f`. The terminal output,
+including complex TUIs, will be rendered correctly.
+
+## Important notes
+
+- **Security:** Be cautious when executing commands, especially those
+  constructed from user input, to prevent security vulnerabilities.
+- **Error handling:** Check the `Stderr`, `Error`, and `Exit Code` fields to
+  determine if a command executed successfully.
+- **Background processes:** When a command is run in the background with `&`,
+  the tool will return immediately and the process will continue to run in the
+  background. The `Background PIDs` field will contain the process ID of the
+  background process.
+
+## Environment variables
+
+When `run_shell_command` executes a command, it sets the `GEMINI_CLI=1`
+environment variable in the subprocess's environment. This allows scripts or
+tools to detect if they are being run from within the Gemini CLI.
+
+## Command restrictions
+
+You can restrict the commands that can be executed by the `run_shell_command`
+tool by using the `tools.core` and `tools.exclude` settings in your
+configuration file.
+
+- `tools.core`: To restrict `run_shell_command` to a specific set of commands,
+  add entries to the `core` list under the `tools` category in the format
+  `run_shell_command(<command>)`. For example,
+  `"tools": {"core": ["run_shell_command(git)"]}` will only allow `git`
+  commands. Including the generic `run_shell_command` acts as a wildcard,
+  allowing any command not explicitly blocked.
+- `tools.exclude`: To block specific commands, add entries to the `exclude` list
+  under the `tools` category in the format `run_shell_command(<command>)`. For
+  example, `"tools": {"exclude": ["run_shell_command(rm)"]}` will block `rm`
+  commands.
+
+The validation logic is designed to be secure and flexible:
+
+1.  **Command chaining disabled**: The tool automatically splits commands
+    chained with `&&`, `||`, or `;` and validates each part separately. If any
+    part of the chain is disallowed, the entire command is blocked.
+2.  **Prefix matching**: The tool uses prefix matching. For example, if you
+    allow `git`, you can run `git status` or `git log`.
+3.  **Blocklist precedence**: The `tools.exclude` list is always checked first.
+    If a command matches a blocked prefix, it will be denied, even if it also
+    matches an allowed prefix in `tools.core`.
+
+### Command restriction examples
+
+**Allow only specific command prefixes**
+
+To allow only `git` and `npm` commands, and block all others:
+
+```json
+{
+  "tools": {
+    "core": ["run_shell_command(git)", "run_shell_command(npm)"]
+  }
+}
+```
+
+- `git status`: Allowed
+- `npm install`: Allowed
+- `ls -l`: Blocked
+
+**Block specific command prefixes**
+
+To block `rm` and allow all other commands:
+
+```json
+{
+  "tools": {
+    "core": ["run_shell_command"],
+    "exclude": ["run_shell_command(rm)"]
+  }
+}
+```
+
+- `rm -rf /`: Blocked
+- `git status`: Allowed
+- `npm install`: Allowed
+
+**Blocklist takes precedence**
+
+If a command prefix is in both `tools.core` and `tools.exclude`, it will be
+blocked.
+
+```json
+{
+  "tools": {
+    "core": ["run_shell_command(git)"],
+    "exclude": ["run_shell_command(git push)"]
+  }
+}
+```
+
+- `git push origin main`: Blocked
+- `git status`: Allowed
+
+**Block all shell commands**
+
+To block all shell commands, add the `run_shell_command` wildcard to
+`tools.exclude`:
+
+```json
+{
+  "tools": {
+    "exclude": ["run_shell_command"]
+  }
+}
+```
+
+- `ls -l`: Blocked
+- `any other command`: Blocked
+
+## Security note for `excludeTools`
+
+Command-specific restrictions in `excludeTools` for `run_shell_command` are
+based on simple string matching and can be easily bypassed. This feature is
+**not a security mechanism** and should not be relied upon to safely execute
+untrusted code. It is recommended to use `coreTools` to explicitly select
+commands that can be executed.

package/dist/docs/tools/todos.md

@@ -0,0 +1,57 @@
+# Todo tool (`write_todos`)
+
+This document describes the `write_todos` tool for the Gemini CLI.
+
+## Description
+
+The `write_todos` tool allows the Gemini agent to create and manage a list of
+subtasks for complex user requests. This provides you, the user, with greater
+visibility into the agent's plan and its current progress. It also helps with
+alignment where the agent is less likely to lose track of its current goal.
+
+### Arguments
+
+`write_todos` takes one argument:
+
+- `todos` (array of objects, required): The complete list of todo items. This
+  replaces the existing list. Each item includes:
+  - `description` (string): The task description.
+  - `status` (string): The current status (`pending`, `in_progress`,
+    `completed`, or `cancelled`).
+
+## Behavior
+
+The agent uses this tool to break down complex multi-step requests into a clear
+plan.
+
+- **Progress tracking:** The agent updates this list as it works, marking tasks
+  as `completed` when done.
+- **Single focus:** Only one task will be marked `in_progress` at a time,
+  indicating exactly what the agent is currently working on.
+- **Dynamic updates:** The plan may evolve as the agent discovers new
+  information, leading to new tasks being added or unnecessary ones being
+  cancelled.
+
+When active, the current `in_progress` task is displayed above the input box,
+keeping you informed of the immediate action. You can toggle the full view of
+the todo list at any time by pressing `Ctrl+T`.
+
+Usage example (internal representation):
+
+```javascript
+write_todos({
+  todos: [
+    { description: 'Initialize new React project', status: 'completed' },
+    { description: 'Implement state management', status: 'in_progress' },
+    { description: 'Create API service', status: 'pending' },
+  ],
+});
+```
+
+## Important notes
+
+- **Enabling:** This tool is enabled by default. You can disable it in your
+  `settings.json` file by setting `"useWriteTodos": false`.
+
+- **Intended use:** This tool is primarily used by the agent for complex,
+  multi-turn tasks. It is generally not used for simple, single-turn questions.

package/dist/docs/tools/web-fetch.md

@@ -0,0 +1,59 @@
+# Web fetch tool (`web_fetch`)
+
+This document describes the `web_fetch` tool for the Gemini CLI.
+
+## Description
+
+Use `web_fetch` to summarize, compare, or extract information from web pages.
+The `web_fetch` tool processes content from one or more URLs (up to 20) embedded
+in a prompt. `web_fetch` takes a natural language prompt and returns a generated
+response.
+
+### Arguments
+
+`web_fetch` takes one argument:
+
+- `prompt` (string, required): A comprehensive prompt that includes the URL(s)
+  (up to 20) to fetch and specific instructions on how to process their content.
+  For example:
+  `"Summarize https://example.com/article and extract key points from https://another.com/data"`.
+  The prompt must contain at least one URL starting with `http://` or
+  `https://`.
+
+## How to use `web_fetch` with the Gemini CLI
+
+To use `web_fetch` with the Gemini CLI, provide a natural language prompt that
+contains URLs. The tool will ask for confirmation before fetching any URLs. Once
+confirmed, the tool will process URLs through Gemini API's `urlContext`.
+
+If the Gemini API cannot access the URL, the tool will fall back to fetching
+content directly from the local machine. The tool will format the response,
+including source attribution and citations where possible. The tool will then
+provide the response to the user.
+
+Usage:
+
+```
+web_fetch(prompt="Your prompt, including a URL such as https://google.com.")
+```
+
+## `web_fetch` examples
+
+Summarize a single article:
+
+```
+web_fetch(prompt="Can you summarize the main points of https://example.com/news/latest")
+```
+
+Compare two articles:
+
+```
+web_fetch(prompt="What are the differences in the conclusions of these two papers: https://arxiv.org/abs/2401.0001 and https://arxiv.org/abs/2401.0002?")
+```
+
+## Important notes
+
+- **URL processing:** `web_fetch` relies on the Gemini API's ability to access
+  and process the given URLs.
+- **Output quality:** The quality of the output will depend on the clarity of
+  the instructions in the prompt.

package/dist/docs/tools/web-search.md

@@ -0,0 +1,42 @@
+# Web search tool (`google_web_search`)
+
+This document describes the `google_web_search` tool.
+
+## Description
+
+Use `google_web_search` to perform a web search using Google Search via the
+Gemini API. The `google_web_search` tool returns a summary of web results with
+sources.
+
+### Arguments
+
+`google_web_search` takes one argument:
+
+- `query` (string, required): The search query.
+
+## How to use `google_web_search` with the Gemini CLI
+
+The `google_web_search` tool sends a query to the Gemini API, which then
+performs a web search. `google_web_search` will return a generated response
+based on the search results, including citations and sources.
+
+Usage:
+
+```
+google_web_search(query="Your query goes here.")
+```
+
+## `google_web_search` examples
+
+Get information on a topic:
+
+```
+google_web_search(query="latest advancements in AI-powered code generation")
+```
+
+## Important notes
+
+- **Response returned:** The `google_web_search` tool returns a processed
+  summary, not a raw list of search results.
+- **Citations:** The response includes citations to the sources used to generate
+  the summary.

package/dist/docs/tos-privacy.md

@@ -0,0 +1,96 @@
+# Gemini CLI: License, Terms of Service, and Privacy Notices
+
+Gemini CLI is an open-source tool that lets you interact with Google's powerful
+AI services directly from your command-line interface. The Gemini CLI software
+is licensed under the
+[Apache 2.0 license](https://github.com/google-gemini/gemini-cli/blob/main/LICENSE).
+When you use Gemini CLI to access or use Google’s services, the Terms of Service
+and Privacy Notices applicable to those services apply to such access and use.
+
+Your Gemini CLI Usage Statistics are handled in accordance with Google's Privacy
+Policy.
+
+**Note:** See [quotas and pricing](/docs/quota-and-pricing.md) for the quota and
+pricing details that apply to your usage of the Gemini CLI.
+
+## Supported authentication methods
+
+Your authentication method refers to the method you use to log into and access
+Google’s services with Gemini CLI. Supported authentication methods include:
+
+- Logging in with your Google account to Gemini Code Assist.
+- Using an API key with Gemini Developer API.
+- Using an API key with Vertex AI GenAI API.
+
+The Terms of Service and Privacy Notices applicable to the aforementioned Google
+services are set forth in the table below.
+
+If you log in with your Google account and you do not already have a Gemini Code
+Assist account associated with your Google account, you will be directed to the
+sign up flow for Gemini Code Assist for individuals. If your Google account is
+managed by your organization, your administrator may not permit access to Gemini
+Code Assist for individuals. Please see the
+[Gemini Code Assist for individuals FAQs](https://developers.google.com/gemini-code-assist/resources/faqs)
+for further information.
+
+| Authentication Method    | Service(s)                   | Terms of Service                                                                                        | Privacy Notice                                                                                |
+| :----------------------- | :--------------------------- | :------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------- |
+| Google Account           | Gemini Code Assist services  | [Terms of Service](https://developers.google.com/gemini-code-assist/resources/privacy-notices)          | [Privacy Notices](https://developers.google.com/gemini-code-assist/resources/privacy-notices) |
+| Gemini Developer API Key | Gemini API - Unpaid Services | [Gemini API Terms of Service - Unpaid Services](https://ai.google.dev/gemini-api/terms#unpaid-services) | [Google Privacy Policy](https://policies.google.com/privacy)                                  |
+| Gemini Developer API Key | Gemini API - Paid Services   | [Gemini API Terms of Service - Paid Services](https://ai.google.dev/gemini-api/terms#paid-services)     | [Google Privacy Policy](https://policies.google.com/privacy)                                  |
+| Vertex AI GenAI API Key  | Vertex AI GenAI API          | [Google Cloud Platform Terms of Service](https://cloud.google.com/terms/service-terms/)                 | [Google Cloud Privacy Notice](https://cloud.google.com/terms/cloud-privacy-notice)            |
+
+## 1. If you have logged in with your Google account to Gemini Code Assist
+
+For users who use their Google account to access
+[Gemini Code Assist](https://codeassist.google), these Terms of Service and
+Privacy Notice documents apply:
+
+- Gemini Code Assist for individuals:
+  [Google Terms of Service](https://policies.google.com/terms) and
+  [Gemini Code Assist for individuals Privacy Notice](https://developers.google.com/gemini-code-assist/resources/privacy-notice-gemini-code-assist-individuals).
+- Gemini Code Assist with Google AI Pro or Ultra subscription:
+  [Google Terms of Service](https://policies.google.com/terms),
+  [Google One Additional Terms of Service](https://one.google.com/terms-of-service)
+  and [Google Privacy Policy\*](https://policies.google.com/privacy).
+- Gemini Code Assist Standard and Enterprise editions:
+  [Google Cloud Platform Terms of Service](https://cloud.google.com/terms) and
+  [Google Cloud Privacy Notice](https://cloud.google.com/terms/cloud-privacy-notice).
+
+_\* If your account is also associated with an active subscription to Gemini
+Code Assist Standard or Enterprise edition, the terms and privacy policy of
+Gemini Code Assist Standard or Enterprise edition will apply to all your use of
+Gemini Code Assist._
+
+## 2. If you have logged in with a Gemini API key to the Gemini Developer API
+
+If you are using a Gemini API key for authentication with the
+[Gemini Developer API](https://ai.google.dev/gemini-api/docs), these Terms of
+Service and Privacy Notice documents apply:
+
+- Terms of Service: Your use of the Gemini CLI is governed by the
+  [Gemini API Terms of Service](https://ai.google.dev/gemini-api/terms). These
+  terms may differ depending on whether you are using an unpaid or paid service:
+  - For unpaid services, refer to the
+    [Gemini API Terms of Service - Unpaid Services](https://ai.google.dev/gemini-api/terms#unpaid-services).
+  - For paid services, refer to the
+    [Gemini API Terms of Service - Paid Services](https://ai.google.dev/gemini-api/terms#paid-services).
+- Privacy Notice: The collection and use of your data is described in the
+  [Google Privacy Policy](https://policies.google.com/privacy).
+
+## 3. If you have logged in with a Gemini API key to the Vertex AI GenAI API
+
+If you are using a Gemini API key for authentication with a
+[Vertex AI GenAI API](https://cloud.google.com/vertex-ai/generative-ai/docs/reference/rest)
+backend, these Terms of Service and Privacy Notice documents apply:
+
+- Terms of Service: Your use of the Gemini CLI is governed by the
+  [Google Cloud Platform Service Terms](https://cloud.google.com/terms/service-terms/).
+- Privacy Notice: The collection and use of your data is described in the
+  [Google Cloud Privacy Notice](https://cloud.google.com/terms/cloud-privacy-notice).
+
+## Usage statistics opt-out
+
+You may opt-out from sending Gemini CLI Usage Statistics to Google by following
+the instructions available here:
+[Usage Statistics Configuration](https://github.com/google-gemini/gemini-cli/blob/main/docs/get-started/configuration.md#usage-statistics).