diff options
Diffstat (limited to 'docs/tools')
| -rw-r--r-- | docs/tools/file-system.md | 33 | ||||
| -rw-r--r-- | docs/tools/index.md | 4 | ||||
| -rw-r--r-- | docs/tools/memory.md | 25 | ||||
| -rw-r--r-- | docs/tools/multi-file.md | 1 | ||||
| -rw-r--r-- | docs/tools/shell.md | 1 | ||||
| -rw-r--r-- | docs/tools/web-fetch.md | 25 | ||||
| -rw-r--r-- | docs/tools/web-search.md | 20 | ||||
| -rw-r--r-- | docs/tools/web.md | 26 |
8 files changed, 101 insertions, 34 deletions
diff --git a/docs/tools/file-system.md b/docs/tools/file-system.md index 4a6b3734..585db0f8 100644 --- a/docs/tools/file-system.md +++ b/docs/tools/file-system.md @@ -13,6 +13,7 @@ All file system tools operate within a `rootDirectory` (usually the current work - **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. @@ -39,9 +40,24 @@ All file system tools operate within a `rootDirectory` (usually the current work - For image/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. -- **Confirmation:** No. -## 3. `glob` (FindFiles) +## 3. `write_file` (WriteFile) + +- **Tool Name:** `write_file` +- **Display Name:** WriteFile +- **File:** `write-file.ts` +- **Description:** Writes content to a specified file. If the file exists, it will be overwritten. If it doesn't exist, it (and any necessary parent directories) will be created. +- **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. + - **Self-correction:** Before writing, the tool may use the Gemini model to correct the provided content to ensure it is valid and well-formed. +- **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) - **Tool Name:** `glob` - **Display Name:** FindFiles @@ -50,6 +66,8 @@ All file system tools operate within a `rootDirectory` (usually the current work - **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. @@ -57,7 +75,7 @@ All file system tools operate within a `rootDirectory` (usually the current work - **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. -## 4. `search_file_content` (SearchText) +## 5. `search_file_content` (SearchText) - **Tool Name:** `search_file_content` - **Display Name:** SearchText @@ -84,16 +102,17 @@ All file system tools operate within a `rootDirectory` (usually the current work ``` - **Confirmation:** No. -## 5. `edit_file` (EditFile) +## 6. `edit_file` (EditFile) - **Tool Name:** `edit_file` - **Display Name:** EditFile - **File:** `edit.ts` -- **Description:** Modifies files with precise text replacements or creates new files. Supports batch operations for making multiple edits to the same file efficiently. This tool is designed for precise, targeted changes. +- **Description:** 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. It can also be used to create new files if `old_string` is empty and the `file_path` does not exist. - **Parameters:** - `file_path` (string, required): The absolute path to the file to modify. - - `edits` (array, required): Array of edit operations. Each edit contains `old_string` and `new_string`. - - `expected_replacements` (number, optional): Number of replacements expected. Defaults to 1 if not specified. Use when you want to replace multiple occurrences. + - `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:** - **Modifying existing files**: Replaces exact text matches. File must exist unless the first edit has an empty `old_string` (indicating file creation). - **Creating new files**: Use an empty `old_string` in the first edit to create a new file with `new_string` as the content. diff --git a/docs/tools/index.md b/docs/tools/index.md index 9e815f08..614dc16a 100644 --- a/docs/tools/index.md +++ b/docs/tools/index.md @@ -43,7 +43,9 @@ The 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):** For executing shell commands. -- **[Web Fetch Tool](./web.md):** For retrieving content from URLs. +- **[Web Fetch Tool](./web-fetch.md):** For retrieving content from URLs. +- **[Web Search Tool](./web-search.md):** For searching the web. - **[Multi-File Read Tool](./multi-file.md):** A specialized tool for reading content from multiple files or directories, often used by the `@` command. +- **[Memory Tool](./memory.md):** For saving and recalling information across sessions. Understanding the available tools and how they work will help you make the most effective use of the Gemini CLI. diff --git a/docs/tools/memory.md b/docs/tools/memory.md new file mode 100644 index 00000000..b134b948 --- /dev/null +++ b/docs/tools/memory.md @@ -0,0 +1,25 @@ +# Memory Tool + +This document provides details on the `save_memory` tool. + +## `save_memory` + +- **Purpose:** Saves a specific piece of information or fact to your long-term memory. This allows the CLI to remember key details across sessions, providing more personalized and effective assistance. +- **Arguments:** + - `fact` (string, required): The specific fact or piece of information to remember. This should be a clear, self-contained statement. +- **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. + - 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. +- **Examples:** + - Remembering a user preference: + ``` + save_memory(fact="My preferred programming language is Python.") + ``` + - Storing a project-specific detail: + ``` + save_memory(fact="The project I'm currently working on is called 'gemini-cli'.") + ``` +- **Important Notes:** + - This tool should be used for concise, important facts. It is not intended for storing large amounts of data or conversational history. + - The memory file is a plain text Markdown file, so you can view and edit it manually if needed. diff --git a/docs/tools/multi-file.md b/docs/tools/multi-file.md index 6347a374..9ee66ab7 100644 --- a/docs/tools/multi-file.md +++ b/docs/tools/multi-file.md @@ -11,6 +11,7 @@ This document provides details on the `read_many_files` tool. - `include` (list[string], optional): Additional glob patterns to include. These are merged with `paths` (e.g., `["*.test.ts"]` to specifically add test files if they were broadly excluded, or `["images/*.jpg"]` to include specific image types). - `recursive` (boolean, optional): Whether to search recursively. This is primarily controlled by `**` in glob patterns. Defaults to `true`. - `useDefaultExcludes` (boolean, optional): Whether to apply a list of default exclusion patterns (e.g., `node_modules`, `.git`, non image/pdf binary files). Defaults to `true`. + - `respect_git_ignore` (boolean, optional): Whether to respect .gitignore patterns when finding files. Defaults to true. - **Behavior:** - The tool searches for files matching the provided `paths` and `include` patterns, while respecting `exclude` patterns and default excludes (if enabled). - For text files: it reads the content of each matched file (attempting to skip binary files not explicitly requested as image/PDF) and concatenates it into a single string, with a separator `--- {filePath} ---` between the content of each file. Uses UTF-8 encoding by default. diff --git a/docs/tools/shell.md b/docs/tools/shell.md index 5b8e8c9d..3c14c657 100644 --- a/docs/tools/shell.md +++ b/docs/tools/shell.md @@ -38,3 +38,4 @@ This document provides details on the shell tool. - **Security:** Be cautious when executing commands, especially those constructed from user input, to prevent security vulnerabilities. - **Interactive Commands:** Avoid commands that require interactive user input, as this can cause the tool to hang. Use non-interactive flags if available (e.g., `npm init -y`). - **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. diff --git a/docs/tools/web-fetch.md b/docs/tools/web-fetch.md new file mode 100644 index 00000000..70dbb70f --- /dev/null +++ b/docs/tools/web-fetch.md @@ -0,0 +1,25 @@ +# Web Fetch Tool + +This document describes the `web_fetch` tool. + +## `web_fetch` + +- **Purpose:** Processes content from one or more URLs (up to 20) embedded in a prompt. This tool is ideal for tasks that require summarizing, comparing, or extracting specific information from web pages. +- **Arguments:** + - `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://`. +- **Behavior:** + - The tool sends the prompt and the specified URLs to the Gemini API. + - The API fetches the content of the URLs, processes it according to the instructions in the prompt, and returns a consolidated response. + - The tool formats the response, including source attribution with citations, and returns it to the user. +- **Examples:** + - Summarizing a single article: + ``` + web_fetch(prompt="Can you summarize the main points of https://example.com/news/latest") + ``` + - Comparing 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:** + - This tool relies on the Gemini API's ability to access and process the given URLs. + - The quality of the output depends on the clarity of the instructions in the prompt. diff --git a/docs/tools/web-search.md b/docs/tools/web-search.md new file mode 100644 index 00000000..da2e3315 --- /dev/null +++ b/docs/tools/web-search.md @@ -0,0 +1,20 @@ +# Google Web Search Tool + +This document describes the `google_web_search` tool. + +## `google_web_search` + +- **Purpose:** Performs a web search using Google Search (via the Gemini API) and returns a summary of the results with sources. This tool is useful for finding up-to-date information on the internet. +- **Arguments:** + - `query` (string, required): The search query. +- **Behavior:** + - The tool sends the query to the Gemini API, which performs a Google Search. + - It returns a generated response based on the search results, complete with citations and a list of sources. +- **Examples:** + - Getting information on a topic: + ``` + google_web_search(query="latest advancements in AI-powered code generation") + ``` +- **Important Notes:** + - The tool returns a processed summary, not a raw list of search results. + - The response includes citations to the sources used to generate the summary. diff --git a/docs/tools/web.md b/docs/tools/web.md deleted file mode 100644 index 5832fab4..00000000 --- a/docs/tools/web.md +++ /dev/null @@ -1,26 +0,0 @@ -# Web Fetch Tool - -This document describes the `web_fetch` tool. - -## `web_fetch` - -- **Purpose:** Fetches text content from a given URL. This is useful for retrieving data from web pages, APIs, or other online resources. -- **Arguments:** - - `url` (string, required): The absolute URL to fetch (e.g., `https://example.com/data.txt`). -- **Behavior:** - - The tool attempts to retrieve the content from the specified URL. - - It handles potential network errors (e.g., DNS resolution failure, connection timeout) and non-success HTTP status codes (e.g., 404 Not Found, 500 Internal Server Error). - - The returned content is expected to be text-based. For binary files, the behavior might be undefined or result in garbled text. -- **Examples:** - - Fetching a plain text file: - ``` - web_fetch(url="https://example.com/robots.txt") - ``` - - Retrieving data from a simple API endpoint: - ``` - web_fetch(url="https://api.example.com/items/123") - ``` -- **Important Notes:** - - **Content Type:** This tool is primarily designed for text-based content. It may not be suitable for fetching binary files like images or executables. - - **Error Handling:** Always check the tool's output for error messages or status indicators to ensure the fetch was successful and the content is as expected. - - **Rate Limiting/Authentication:** Be mindful of website terms of service, rate limits, and authentication requirements. This tool does not inherently handle complex authentication mechanisms. |