MediaMetz/gemini-cli
1
0
Fork 0
mirror of https://github.com/google-gemini/gemini-cli.git synced 2026-03-10 14:10:37 -07:00
Code Issues Packages Projects Releases Wiki Activity

Docs: Refresh docs to organize and standardize reference materials. (#18403)

Browse Source
This commit is contained in:
Jenna Inouye
2026-02-13 14:09:17 -08:00
committed by GitHub
parent f76e24c00f
commit c7237f0c79
37 changed files with 2343 additions and 1676 deletions
Download Patch File Download Diff File Expand all files Collapse all files

43
docs/tools/activate-skill.md Normal file
View File

@@ -0,0 +1,43 @@
# Activate skill tool (`activate_skill`)
The `activate_skill` tool lets Gemini CLI load specialized procedural expertise
and resources when they are relevant to your request.
## Description
Skills are packages of instructions and tools designed for specific engineering
tasks, such as reviewing code or creating pull requests. Gemini CLI uses this
tool to "activate" a skill, which provides it with detailed guidelines and
specialized tools tailored to that task.
### Arguments
`activate_skill` takes one argument:
- `name` (enum, required): The name of the skill to activate (for example,
`code-reviewer`, `pr-creator`, or `docs-writer`).
## Usage
The `activate_skill` tool is used exclusively by the Gemini agent. You cannot
invoke this tool manually.
When the agent identifies that a task matches a discovered skill, it requests to
activate that skill. Once activated, the agent's behavior is guided by the
skill's specific instructions until the task is complete.
## Behavior
The agent uses this tool to provide professional-grade assistance:
- **Specialized logic:** Skills contain expert-level procedures for complex
workflows.
- **Dynamic capability:** Activating a skill can grant the agent access to new,
task-specific tools.
- **Contextual awareness:** Skills help the agent focus on the most relevant
standards and conventions for a particular task.
## Next steps
- Learn how to [Use Agent Skills](../cli/skills.md).
- See the [Creating Agent Skills](../cli/creating-skills.md) guide.

2
docs/tools/ask-user.md
View File

@@ -1,6 +1,6 @@
# Ask User Tool
The `ask_user` tool allows the agent to ask you one or more questions to gather
The `ask_user` tool lets Gemini CLI ask you one or more questions to gather
preferences, clarify requirements, or make decisions. It supports multiple
question types including multiple-choice, free-form text, and Yes/No
confirmation.

172
docs/tools/file-system.md
View File

@@ -1,99 +1,49 @@
# Gemini CLI file system tools
# File system tools reference
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.
The Gemini CLI core provides a suite of tools for interacting with the local
file system. These tools allow the model to explore and modify your codebase.
**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.
## Technical reference
## 1. `list_directory` (ReadFolder)
All file system tools operate within a `rootDirectory` (the current working
directory or workspace root) for security.
`list_directory` lists the names of files and subdirectories directly within a
specified directory path. It can optionally ignore entries matching provided
glob patterns.
### `list_directory` (ReadFolder)
Lists the names of files and subdirectories directly within a specified path.
- **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.
- **Arguments:**
- `dir_path` (string, required): Absolute or relative path to the directory.
- `ignore` (array, optional): Glob patterns to exclude.
- `file_filtering_options` (object, optional): Configuration for `.gitignore`
and `.geminiignore` compliance.
## 2. `read_file` (ReadFile)
### `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.
Reads and returns the content of a specific file. Supports text, images, audio,
and PDF.
- **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.
- **Arguments:**
- `file_path` (string, required): Path to the file.
- `offset` (number, optional): Start line for text files (0-based).
- `limit` (number, optional): Maximum lines to read.
## 3. `write_file` (WriteFile)
### `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.
Writes content to a specified file, overwriting it if it exists or creating it
if not.
- **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.
- **Arguments:**
- `file_path` (string, required): Path to the file.
- `content` (string, required): Data to write.
- **Confirmation:** Requires manual user approval.
## 4. `glob` (FindFiles)
### `glob` (FindFiles)
`glob` finds files matching specific glob patterns (e.g., `src/**/*.ts`,
`*.md`), returning absolute paths sorted by modification time (newest first).
Finds files matching specific glob patterns across the workspace.
- **Tool name:** `glob`
- **Display name:** FindFiles
@@ -161,56 +111,16 @@ 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.
- **Arguments:**
- `file_path` (string, required): Path to the file.
- `instruction` (string, required): Semantic description of the change.
- `old_string` (string, required): Exact literal text to find.
- `new_string` (string, required): Exact literal text to replace with.
- **Confirmation:** Requires manual user approval.
**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.
## Next steps
- `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.
- Follow the [File management tutorial](../cli/tutorials/file-management.md) for
practical examples.
- Learn about [Trusted folders](../cli/trusted-folders.md) to manage access
permissions.

165
docs/tools/index.md
View File

@@ -1,101 +1,102 @@
# 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.
Gemini CLI uses tools to interact with your local environment, access
information, and perform actions on your behalf. These tools extend the model's
capabilities beyond text generation, letting it read files, execute commands,
and search the web.
## Overview of Gemini CLI tools
## User-triggered 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.
You can directly trigger these tools using special syntax in your prompts.
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.
- **[File access](./file-system.md#read_many_files) (`@`):** Use the `@` symbol
followed by a file or directory path to include its content in your prompt.
This triggers the `read_many_files` tool.
- **[Shell commands](./shell.md) (`!`):** Use the `!` symbol followed by a
system command to execute it directly. This triggers the `run_shell_command`
tool.
These tools provide the following capabilities:
## Model-triggered tools
- **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.
The Gemini model automatically requests these tools when it needs to perform
specific actions or gather information to fulfill your requests. You do not call
these tools manually.
## How to use Gemini CLI tools
### File management
To use Gemini CLI tools, provide a prompt to the Gemini CLI. The process works
as follows:
These tools let the model explore and modify your local codebase.
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.
- **[Directory listing](./file-system.md#list_directory) (`list_directory`):**
Lists files and subdirectories.
- **[File reading](./file-system.md#read_file) (`read_file`):** Reads the
content of a specific file.
- **[File writing](./file-system.md#write_file) (`write_file`):** Creates or
overwrites a file with new content.
- **[File search](./file-system.md#glob) (`glob`):** Finds files matching a glob
pattern.
- **[Text search](./file-system.md#search_file_content)
(`search_file_content`):** Searches for text within files using grep or
ripgrep.
- **[Text replacement](./file-system.md#replace) (`replace`):** Performs precise
edits within a file.
You will typically see messages in the CLI indicating when a tool is being
called and whether it succeeded or failed.
### Agent coordination
These tools help the model manage its plan and interact with you.
- **Ask user (`ask_user`):** Requests clarification or missing information from
you via an interactive dialog.
- **[Memory](./memory.md) (`save_memory`):** Saves important facts to your
long-term memory (`GEMINI.md`).
- **[Todos](./todos.md) (`write_todos`):** Manages a list of subtasks for
complex plans.
- **[Agent Skills](../cli/skills.md) (`activate_skill`):** Loads specialized
procedural expertise when needed.
- **Internal docs (`get_internal_docs`):** Accesses Gemini CLI's own
documentation to help answer your questions.
### Information gathering
These tools provide the model with access to external data.
- **[Web fetch](./web-fetch.md) (`web_fetch`):** Retrieves and processes content
from specific URLs.
- **[Web search](./web-search.md) (`google_web_search`):** Performs a Google
Search to find up-to-date information.
## How to use tools
You use tools indirectly by providing natural language prompts to Gemini CLI.
1. **Prompt:** You enter a request or use syntax like `@` or `!`.
2. **Request:** The model analyzes your request and identifies if a tool is
required.
3. **Validation:** If a tool is needed, the CLI validates the parameters and
checks your security settings.
4. **Confirmation:** For sensitive operations (like writing files), the CLI
prompts you for approval.
5. **Execution:** The tool runs, and its output is sent back to the model.
6. **Response:** The model uses the results to generate a final, grounded
answer.
## 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:
Safety is a core part of the tool system. To protect your system, Gemini CLI
implements several safeguards.
- **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.
- **User confirmation:** You must manually approve tools that modify files or
execute shell commands. The CLI shows you a diff or the exact command before
you confirm.
- **Sandboxing:** You can run tool executions in secure, containerized
environments to isolate changes from your host system. For more details, see
the [Sandboxing](../cli/sandbox.md) guide.
- **Trusted folders:** You can configure which directories allow the model to
use system tools.
It's important to always review confirmation prompts carefully before allowing a
tool to proceed.
Always review confirmation prompts carefully before allowing a tool to execute.
## Learn more about Gemini CLI's tools
## Next steps
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
- Learn how to [Provide context](../cli/gemini-md.md) to guide tool use.
- Explore the [Command reference](../cli/commands.md) for tool-related slash
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.
- **[Planning Tools](./planning.md):** For entering and exiting Plan Mode.
- **[Ask User Tool](./ask-user.md) (`ask_user`):** For gathering user input and
making decisions.
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.
- **[Agent Skills](../cli/skills.md)**: On-demand expertise packages that are
activated via the `activate_skill` tool to provide specialized guidance and
resources.
- **[Sandboxing](../cli/sandbox.md)**: Sandboxing isolates the model and its
changes from your environment to reduce potential risk.

46
docs/tools/internal-docs.md Normal file
View File

@@ -0,0 +1,46 @@
# Internal documentation tool (`get_internal_docs`)
The `get_internal_docs` tool lets Gemini CLI access its own technical
documentation to provide more accurate answers about its capabilities and usage.
## Description
This tool is used when Gemini CLI needs to verify specific details about Gemini
CLI's internal features, built-in commands, or configuration options. It
provides direct access to the Markdown files in the `docs/` directory.
### Arguments
`get_internal_docs` takes one optional argument:
- `path` (string, optional): The relative path to a specific documentation file
(for example, `cli/commands.md`). If omitted, the tool returns a list of all
available documentation paths.
## Usage
The `get_internal_docs` tool is used exclusively by Gemini CLI. You cannot
invoke this tool manually.
When Gemini CLI uses this tool, it retrieves the content of the requested
documentation file and processes it to answer your question. This ensures that
the information provided by the AI is grounded in the latest project
documentation.
## Behavior
Gemini CLI uses this tool to ensure technical accuracy:
- **Capability discovery:** If Gemini CLI is unsure how a feature works, it can
lookup the corresponding documentation.
- **Reference lookup:** Gemini CLI can verify slash command sub-commands or
specific setting names.
- **Self-correction:** Gemini CLI can use the documentation to correct its
understanding of Gemini CLI's system logic.
## Next steps
- Explore the [Command reference](../cli/commands.md) for a detailed guide to
slash commands.
- See the [Configuration guide](../get-started/configuration.md) for settings
reference.

4
docs/tools/mcp-server.md
View File

@@ -101,8 +101,8 @@ execution.
#### Global MCP settings (`mcp`)
The `mcp` object in your `settings.json` allows you to define global rules for
all MCP servers.
The `mcp` object in your `settings.json` lets you define global rules for all
MCP servers.
- **`mcp.serverCommand`** (string): A global command to start an MCP server.
- **`mcp.allowed`** (array of strings): A list of MCP server names to allow. If

61
docs/tools/memory.md
View File

@@ -1,54 +1,35 @@
# Memory tool (`save_memory`)
This document describes the `save_memory` tool for the Gemini CLI.
The `save_memory` tool allows the Gemini agent to persist specific facts, user
preferences, and project details across sessions.
## Description
## Technical reference
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.
This tool appends information to the `## Gemini Added Memories` section of your
global `GEMINI.md` file (typically located at `~/.gemini/GEMINI.md`).
### 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
- `fact` (string, required): A clear, self-contained statement in natural
language.
## How to use `save_memory` with the Gemini CLI
## Technical behavior
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.
- **Storage:** Appends to the global context file in the user's home directory.
- **Loading:** The stored facts are automatically included in the hierarchical
context system for all future sessions.
- **Format:** Saves data as a bulleted list item within a dedicated Markdown
section.
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.
## Use cases
Usage:
- Persisting user preferences (for example, "I prefer functional programming").
- Saving project-wide architectural decisions.
- Storing frequently used aliases or system configurations.
```
save_memory(fact="Your fact here.")
```
## Next steps
### `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.
- Follow the [Memory management guide](../cli/tutorials/memory-management.md)
for practical examples.
- Learn how the [Project context (GEMINI.md)](../cli/gemini-md.md) system loads
this information.

123
docs/tools/shell.md
View File

@@ -1,70 +1,33 @@
# Shell tool (`run_shell_command`)
This document describes the `run_shell_command` tool for the Gemini CLI.
The `run_shell_command` tool allows the Gemini model to execute commands
directly on your system's shell. It is the primary mechanism for the agent to
interact with your environment beyond simple file edits.
## Description
## Technical reference
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`.
On Windows, commands execute with `powershell.exe -NoProfile -Command`. On other
platforms, they execute 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.
- `description` (string, optional): A brief description shown to the user for
confirmation.
- `dir_path` (string, optional): The absolute path or relative path from
workspace root where the command runs.
- `is_background` (boolean, optional): Whether to move the process to the
background immediately after starting.
## How to use `run_shell_command` with the Gemini CLI
### Return values
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:
The tool returns a JSON object containing:
- `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")
```
- `Command`: The executed string.
- `Directory`: The execution path.
- `Stdout` / `Stderr`: The output streams.
- `Exit Code`: The process return code.
- `Background PIDs`: PIDs of any started background processes.
## Configuration
@@ -224,38 +187,30 @@ To block `rm` and allow all other commands:
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)"]
}
}
```
- **`tools.shell.enableInteractiveShell`**: (boolean) Uses `node-pty` for
real-time interaction.
- **`tools.shell.showColor`**: (boolean) Preserves ANSI colors in output.
- **`tools.shell.inactivityTimeout`**: (number) Seconds to wait for output
before killing the process.
- `git push origin main`: Blocked
- `git status`: Allowed
### Command restrictions
**Block all shell commands**
You can limit which commands the agent is allowed to request using these
settings:
To block all shell commands, add the `run_shell_command` wildcard to
`tools.exclude`:
- **`tools.core`**: An allowlist of command prefixes (for example,
`["git", "npm test"]`).
- **`tools.exclude`**: A blocklist of command prefixes.
```json
{
"tools": {
"exclude": ["run_shell_command"]
}
}
```
## Use cases
- `ls -l`: Blocked
- `any other command`: Blocked
- Running build scripts and test suites.
- Initializing or managing version control systems.
- Installing project dependencies.
- Starting development servers or background watchers.
## Security note for `excludeTools`
## Next steps
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.
- Follow the [Shell commands tutorial](../cli/tutorials/shell-commands.md) for
practical examples.
- Learn about [Sandboxing](../cli/sandbox.md) to isolate command execution.

66
docs/tools/todos.md
View File

@@ -1,57 +1,35 @@
# Todo tool (`write_todos`)
This document describes the `write_todos` tool for the Gemini CLI.
The `write_todos` tool allows the Gemini agent to maintain an internal list of
subtasks for multi-step requests.
## Description
## Technical reference
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.
The agent uses this tool to manage its execution plan and provide progress
updates to the CLI interface.
### Arguments
`write_todos` takes one argument:
- `todos` (array of objects, required): The complete list of tasks. Each object
includes:
- `description` (string): Technical description of the task.
- `status` (enum): `pending`, `in_progress`, `completed`, or `cancelled`.
- `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`).
## Technical behavior
## Behavior
- **Interface:** Updates the progress indicator above the CLI input prompt.
- **Exclusivity:** Only one task can be marked `in_progress` at any time.
- **Persistence:** Todo state is scoped to the current session.
- **Interaction:** Users can toggle the full list view using **Ctrl+T**.
The agent uses this tool to break down complex multi-step requests into a clear
plan.
## Use cases
- **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.
- Breaking down a complex feature implementation into manageable steps.
- Coordinating multi-file refactoring tasks.
- Providing visibility into the agent's current focus during long-running tasks.
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`.
## Next steps
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.
- Follow the [Task planning tutorial](../cli/tutorials/task-planning.md) for
usage details.
- Learn about [Session management](../cli/session-management.md) for context.

68
docs/tools/web-fetch.md
View File

@@ -1,59 +1,35 @@
# Web fetch tool (`web_fetch`)
This document describes the `web_fetch` tool for the Gemini CLI.
The `web_fetch` tool allows the Gemini agent to retrieve and process content
from specific URLs provided in your prompt.
## Description
## Technical reference
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.
The agent uses this tool when you include URLs in your prompt and request
specific operations like summarization or extraction.
### Arguments
`web_fetch` takes one argument:
- `prompt` (string, required): A request containing up to 20 valid URLs
(starting with `http://` or `https://`) and instructions on how to process
them.
- `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://`.
## Technical behavior
## How to use `web_fetch` with the Gemini CLI
- **Confirmation:** Triggers a confirmation dialog showing the converted URLs.
- **Processing:** Uses the Gemini API's `urlContext` for retrieval.
- **Fallback:** If API access fails, the tool attempts to fetch raw content
directly from your local machine.
- **Formatting:** Returns a synthesized response with source attribution.
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`.
## Use cases
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.
- Summarizing technical articles or blog posts.
- Comparing data between two or more web pages.
- Extracting specific information from a documentation site.
Usage:
## Next steps
```
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.
- Follow the [Web tools guide](../cli/tutorials/web-tools.md) for practical
usage examples.
- See the [Web search tool reference](./web-search.md) for general queries.

48
docs/tools/web-search.md
View File

@@ -1,42 +1,32 @@
# Web search tool (`google_web_search`)
This document describes the `google_web_search` tool.
The `google_web_search` tool allows the Gemini agent to retrieve up-to-date
information, news, and facts from the internet via Google Search.
## Description
## Technical reference
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.
The agent uses this tool when your request requires knowledge of current events
or specific online documentation not available in its internal training data.
### Arguments
`google_web_search` takes one argument:
- `query` (string, required): The search query to be executed.
- `query` (string, required): The search query.
## Technical behavior
## How to use `google_web_search` with the Gemini CLI
- **Grounding:** Returns a generated summary based on search results.
- **Citations:** Includes source URIs and titles for factual grounding.
- **Processing:** The Gemini API processes the search results before returning a
synthesized response to the agent.
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.
## Use cases
Usage:
- Researching the latest version of a software library or API.
- Finding solutions to recent software bugs or security vulnerabilities.
- Retrieving news or documentation updated after the model's knowledge cutoff.
```
google_web_search(query="Your query goes here.")
```
## Next steps
## `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.
- Follow the [Web tools guide](../cli/tutorials/web-tools.md) for practical
usage examples.
- Explore the [Web fetch tool reference](./web-fetch.md) for direct URL access.