docs: update and reorganize documentation (#806)
This commit is contained in:
cperry-goog
GitHub
parent
dcaecde844
commit
63757d6a7a
|
|
@ -32,15 +32,17 @@ Slash commands provide meta-level control over the CLI itself. They can typicall
|
|||
- **`refresh`**:
|
||||
- **Description:** Reloads the hierarchical instructional context (memory) from all `GEMINI.md` files found in the configured locations (global, project/ancestors, and sub-directories). This command updates the AI's understanding based on the latest `GEMINI.md` content.
|
||||
- **Action:** The CLI re-scans for all relevant `GEMINI.md` files and rebuilds its instructional memory. The number of loaded files is typically indicated in the CLI footer.
|
||||
- **`delete_all_added`**:
|
||||
- **Description:** Removes all ad-hoc memory entries that were added during the current session via `/memory add`. This does not affect memory loaded from `GEMINI.md` files.
|
||||
- **Action:** All user-added memory entries for the current session are cleared.
|
||||
- **Note:** For more details on how `GEMINI.md` files contribute to hierarchical memory, see the [CLI Configuration documentation](./configuration.md#4-geminimd-files-hierarchical-instructional-context).
|
||||
- **Note:** For more details on how `GEMINI.md` files contribute to hierarchical memory, see the [CLI Configuration documentation](./configuration.md#4-geminimd-files-hierarchical-instructional-context).
|
||||
|
||||
- **`/quit`** (or **`/exit`**)
|
||||
|
||||
- **Description:** Exits the Gemini CLI application.
|
||||
- **Action:** Terminates the CLI process.
|
||||
|
||||
- **`/tools`**
|
||||
- **Description:** Displays a list of all the tools that are currently available to the model.
|
||||
- **Action:** Outputs a list of the available tools.
|
||||
|
||||
## At Commands (`@`)
|
||||
|
||||
At commands are used to quickly include the content of files or directories as part of your prompt to Gemini. These commands now feature git-aware filtering.
|
||||
|
|
|
|||
|
|
@ -208,6 +208,10 @@ The CLI automatically loads environment variables from an `.env` file. The loadi
|
|||
- `<profile_name>`: Uses a custom profile. To define a custom profile, create a file named `sandbox-macos-<profile_name>.sb` in your project's `.gemini/` directory (e.g., `my-project/.gemini/sandbox-macos-custom.sb`).
|
||||
- **`DEBUG` or `DEBUG_MODE`** (often used by underlying libraries or the CLI itself):
|
||||
- Set to `true` or `1` to enable verbose debug logging, which can be helpful for troubleshooting.
|
||||
- **`NO_COLOR`**:
|
||||
- Set to any value to disable all color output in the CLI.
|
||||
- **`CLI_TITLE`**:
|
||||
- Set to a string to customize the title of the CLI.
|
||||
|
||||
## 3. Command-Line Arguments
|
||||
|
||||
|
|
|
|||
|
|
@ -1,10 +1,6 @@
|
|||
# Gemini CLI
|
||||
|
||||
Welcome to the documentation for the Gemini CLI. This section provides an overview of the CLI's features, how to interact with it, and how to customize your experience.
|
||||
|
||||
## What is the Gemini CLI?
|
||||
|
||||
The Gemini CLI (`packages/cli`) is the primary way users interact with the Gemini AI model and its associated tools directly from their terminal. It offers an interactive Read-Eval-Print Loop (REPL) environment where you can send prompts to Gemini, receive responses, and see the results of any tools Gemini uses to fulfill your requests.
|
||||
The Gemini CLI (`packages/cli`) is the primary way users interact with the Gemini AI model and its associated tools directly from their terminal. For a general overview of the Gemini CLI, see the [main documentation page](../index.md).
|
||||
|
||||
## Core Features
|
||||
|
||||
|
|
@ -36,4 +32,20 @@ The Gemini CLI (`packages/cli`) is the primary way users interact with the Gemin
|
|||
- **[Themes](./themes.md)**: A guide to customizing the CLI's appearance with different themes.
|
||||
- **[Tutorials](tutorials.md)**: A guide for mastering use of the CLI to automate your development tasks.
|
||||
|
||||
This documentation will help you become proficient in using the Gemini CLI for a wide range of tasks.
|
||||
## Non-Interactive Mode
|
||||
|
||||
The Gemini CLI can be run in a non-interactive mode, which is useful for scripting and automation. In this mode, you can pipe input to the CLI and it will execute the command and exit.
|
||||
|
||||
To use the non-interactive mode, you can pipe a command to the CLI. For example:
|
||||
|
||||
```bash
|
||||
echo "What is fine tuning?" | gemini
|
||||
```
|
||||
|
||||
You can achieve the same result with the `--prompt` or `p` argument. For example:
|
||||
|
||||
```bash
|
||||
gemini -p "What is fine tuning?"
|
||||
```
|
||||
|
||||
In both cases this will execute the command and print the output to the console.
|
||||
|
|
|
|||
|
|
@ -1,111 +0,0 @@
|
|||
# Gemini CLI Core: Configuration
|
||||
|
||||
Configuration for the Gemini CLI core component (`packages/core`) is critical for its operation, dictating how it connects to the Gemini API, which model it uses, how tools are executed, and more. Many of these settings are shared with or derived from the main CLI configuration when the CLI initializes the core backend.
|
||||
|
||||
## Primary Configuration Sources
|
||||
|
||||
The core's configuration is primarily established when the `Config` object (from `packages/core/src/config/config.ts`) is instantiated. The values come from a combination of:
|
||||
|
||||
1. **Hardcoded Defaults:** Fallback values defined within the core and CLI packages.
|
||||
2. **Settings Files (`settings.json` via CLI):** Persistent settings that the CLI reads (User settings `~/.gemini/settings.json`, then Workspace settings `.gemini/settings.json`) and then passes relevant parts to the core configuration.
|
||||
3. **Environment Variables (potentially from `.env` files):** System-wide or session-specific variables. The CLI loads `.env` files (checking current directory, then ancestors, then `~/.env`) and these variables influence the core config.
|
||||
4. **Command-Line Arguments (passed from CLI):** Settings chosen by the user at launch time, which have the highest precedence for many options.
|
||||
|
||||
## Key Configuration Parameters for the Core
|
||||
|
||||
These are the main pieces of information the core `Config` object holds and uses:
|
||||
|
||||
- **`apiKey` (string):**
|
||||
|
||||
- **Source:** Primarily `process.env.GEMINI_API_KEY` (loaded from the environment or `.env` files).
|
||||
- **Importance:** Absolutely essential for connecting to the Gemini API. (If using Vertex AI, authentication is handled differently, typically via Application Default Credentials - see README.md).
|
||||
|
||||
- **`model` (string):**
|
||||
|
||||
- **Source:** Command-line argument (`--model`), environment variable (`GEMINI_MODEL`), or a default value (e.g., `gemini-2.5-pro-preview-06-05`).
|
||||
- **Purpose:** Specifies which Gemini model the core should use. (For Vertex AI model names and usage, refer to the main README.md).
|
||||
|
||||
- **`sandbox` (boolean | string):**
|
||||
|
||||
- **Source:** Command-line argument (`--sandbox`), environment variable (`GEMINI_SANDBOX`), or `settings.json` (`sandbox` key).
|
||||
- **Purpose:** Determines if and how tools (especially `execute_bash_command`) are sandboxed. This is crucial for security.
|
||||
- `true`: Use a default sandboxing method.
|
||||
- `false`: No sandboxing (less secure).
|
||||
- `"docker"`, `"podman"`, or a custom command string: Specific sandboxing method.
|
||||
|
||||
- **`targetDir` (string):**
|
||||
|
||||
- **Source:** Typically `process.cwd()` (the current working directory from which the CLI was launched).
|
||||
- **Purpose:** Provides a base directory context for tools that operate on the file system (e.g., `read_file`, `list_directory`). Paths used in tool calls are often resolved relative to this directory.
|
||||
|
||||
- **`debugMode` (boolean):**
|
||||
|
||||
- **Source:** Command-line argument (`--debug_mode`) or environment variables (e.g., `DEBUG=true`, `DEBUG_MODE=true`).
|
||||
- **Purpose:** Enables verbose logging within the core and its tools, which is helpful for development and troubleshooting.
|
||||
|
||||
- **`question` (string | undefined):**
|
||||
|
||||
- **Source:** Command-line argument (`--question`), usually when input is piped to the CLI.
|
||||
- **Purpose:** Allows a direct question to be passed to the core for processing without interactive input.
|
||||
|
||||
- **`fullContext` (boolean):**
|
||||
|
||||
- **Source:** Command-line argument (`--all_files`).
|
||||
- **Purpose:** If true, instructs relevant tools (like `read_many_files` when used implicitly by the model) to gather a broad context from the `targetDir`.
|
||||
|
||||
- **`toolDiscoveryCommand` (string | undefined):** see under [CLI settings](../cli/configuration.md#available-settings-in-settingsjson).
|
||||
|
||||
- **`toolCallCommand` (string | undefined)**: see under [CLI settings](../cli/configuration.md#available-settings-in-settingsjson).
|
||||
|
||||
- `mcpServers` (object | undefined):
|
||||
- **Source:** `settings.json` (`mcpServers` key), passed from the CLI.
|
||||
- **Purpose:** Advanced setting for configuring connections to one or more Model-Context Protocol (MCP) servers. This allows the Gemini CLI to discover and utilize tools exposed by these external servers.
|
||||
- **Structure:** An object where each key is a unique server name (alias) and the value is an object containing:
|
||||
- `command` (string, required): The command to execute to start the MCP server.
|
||||
- `args` (array of strings, optional): Arguments for the command.
|
||||
- `env` (object, optional): Environment variables for the server process.
|
||||
- `cwd` (string, optional): Working directory for the server.
|
||||
- `timeout` (number, optional): Request timeout in milliseconds.
|
||||
- **Behavior:** The core will attempt to connect to each configured MCP server. Tool names from these servers might be prefixed with the server alias to prevent naming collisions. The core may also adapt tool schemas from MCP servers for internal compatibility.
|
||||
- `mcpServerCommand` (string | undefined, **deprecated**):
|
||||
|
||||
- **Source:** `settings.json` (`mcpServerCommand` key).
|
||||
- **Purpose:** Legacy setting for a single MCP server. Superseded by `mcpServers`.
|
||||
|
||||
- **`userAgent` (string):**
|
||||
|
||||
- **Source:** Automatically generated by the CLI, often including CLI package name, version, and Node.js environment details.
|
||||
- **Purpose:** Sent with API requests to help identify the client making requests to the Gemini API.
|
||||
|
||||
- **`userMemory` (string):**
|
||||
|
||||
- **Source:** Loaded from the hierarchical `GEMINI.md` files by the CLI (Global, Project Root/Ancestors, Sub-directory) and passed to the core config.
|
||||
- **Purpose:** Contains the combined instructional context provided to the Gemini model.
|
||||
- **Mutability:** This can be updated if the memory is refreshed by the user (e.g., via the `/memory refresh` command in the CLI).
|
||||
|
||||
- **`geminiMdFileCount` (number):**
|
||||
- **Source:** Count of all `GEMINI.md` files successfully loaded by the CLI.
|
||||
- **Purpose:** Metadata about the loaded instructional context, visible in the CLI footer.
|
||||
|
||||
## Environment File (`.env`) Loading
|
||||
|
||||
The CLI configuration logic, which precedes core initialization, includes loading an `.env` file. The search order is:
|
||||
|
||||
1. `.env` in the current working directory.
|
||||
2. `.env` in parent directories, up to the project root (containing `.git`) or home directory.
|
||||
3. `~/.env` (in the user's home directory).
|
||||
|
||||
This file is a common place to store the `GEMINI_API_KEY` and other environment-specific settings like `GEMINI_MODEL` or `DEBUG` flags.
|
||||
|
||||
```
|
||||
# Example .env file
|
||||
GEMINI_API_KEY="YOUR_ACTUAL_API_KEY_HERE"
|
||||
GEMINI_MODEL="gemini-1.5-flash-latest"
|
||||
# DEBUG=true
|
||||
```
|
||||
|
||||
## Tool Registry Initialization
|
||||
|
||||
Upon initialization, the core's `Config` object is also used to create and populate a `ToolRegistry`. This registry is then aware of the `targetDir` and `sandbox` settings, which are vital for the correct and secure operation of tools like `ReadFileTool`, `ShellTool`, etc. The `ToolRegistry` is responsible for making tool schemas available to the Gemini model and for executing tool calls.
|
||||
|
||||
Proper core configuration, derived from these various sources, is essential for the Gemini CLI to function correctly, securely, and according to the user's intent.
|
||||
|
|
@ -1,6 +1,11 @@
|
|||
# Gemini CLI Core
|
||||
|
||||
This section delves into the core component of the Gemini CLI (`packages/core`). The core acts as the backend engine, handling communication with the Gemini API, managing tools, and processing requests from the CLI client.
|
||||
The Gemini CLI Core (`packages/core`) acts as the backend engine for the Gemini CLI, handling communication with the Gemini API, managing tools, and processing requests from the CLI client. For a general overview of the Gemini CLI, see the [main documentation page](../index.md).
|
||||
|
||||
## Navigating this Section
|
||||
|
||||
- **[Core Configuration](../cli/configuration.md):** Details on how to configure the core component, including environment variables and specific settings.
|
||||
- **[Core Tools API](./tools-api.md):** Information on how tools are defined, registered, and used by the core.
|
||||
|
||||
## Role of the Core
|
||||
|
||||
|
|
@ -44,9 +49,28 @@ The core plays a vital role in security:
|
|||
- **API Key Management:** It handles the `GEMINI_API_KEY` and ensures it is used securely when communicating with the Gemini API.
|
||||
- **Tool Execution:** When tools interact with the local system (e.g., `execute_bash_command`), the core (and its underlying tool implementations) must do so with appropriate caution, often involving sandboxing mechanisms to prevent unintended side effects.
|
||||
|
||||
## Navigating this Section
|
||||
## Chat History Compression
|
||||
|
||||
- **[Core Configuration](./configuration.md):** Details on how to configure the core component, including environment variables and specific settings.
|
||||
- **[Core Tools API](./tools-api.md):** Information on how tools are defined, registered, and used by the core.
|
||||
To ensure that long conversations don't exceed the token limits of the Gemini model, the CLI includes a chat history compression feature.
|
||||
|
||||
Understanding the core's role and architecture is key to comprehending the full capabilities and operational flow of the Gemini CLI.
|
||||
When a conversation approaches the token limit for the configured model, the CLI will automatically compress the conversation history before sending it to the model. This compression is designed to be lossless in terms of the information conveyed, but it reduces the overall number of tokens used.
|
||||
|
||||
You can find the token limits for each model in the [Google AI documentation](https://ai.google.dev/gemini-api/docs/models).
|
||||
|
||||
## Model Fallback
|
||||
|
||||
The Gemini CLI includes a model fallback mechanism to ensure that you can continue to use the CLI even if the default "pro" model is rate-limited.
|
||||
|
||||
If you are using the default "pro" model and the CLI detects that you are being rate-limited, it will automatically switch to the "flash" model for the current session. This allows you to continue working without interruption.
|
||||
|
||||
## File Discovery Service
|
||||
|
||||
The file discovery service is responsible for finding files in the project that are relevant to the current context. It is used by the `@` command and other tools that need to access files.
|
||||
|
||||
## Memory Discovery Service
|
||||
|
||||
The memory discovery service is responsible for finding and loading the `GEMINI.md` files that provide context to the model. It searches for these files in a hierarchical manner, starting from the current working directory and moving up to the project root and the user's home directory. It also searches in subdirectories.
|
||||
|
||||
This allows you to have global, project-level, and component-level context files, which are all combined to provide the model with the most relevant information.
|
||||
|
||||
You can use the `/memory show` command to see the combined content of all loaded `GEMINI.md` files, and the `/memory refresh` command to reload them.
|
||||
|
|
|
|||
|
|
@ -21,13 +21,17 @@ Add this line to enable telemetry by in workspace (`.gemini/settings.json`) or u
|
|||
|
||||
```json
|
||||
{
|
||||
"telemetry": true
|
||||
"telemetry": {
|
||||
"enabled": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
You can also control telemetry with the `GEMINI_TELEMETRY_ENABLED` environment variable.
|
||||
|
||||
#### Mode 1: Console Output (Default)
|
||||
|
||||
If you only set `"telemetry": true` and do nothing else, the CLI will output all telemetry data directly to your console. This is the simplest way to inspect events, metrics, and traces without any external tools.
|
||||
If you only set `"enabled": true` and do nothing else, the CLI will output all telemetry data directly to your console. This is the simplest way to inspect events, metrics, and traces without any external tools.
|
||||
|
||||
#### Mode 2: Sending to a Collector
|
||||
|
||||
|
|
|
|||
|
|
@ -6,6 +6,10 @@ This documentation provides a comprehensive guide to installing, using, and deve
|
|||
|
||||
The Gemini CLI is a tool designed to bring the capabilities of Gemini models to your terminal. It consists of a client-side application (`packages/cli`) that communicates with a local server (`packages/core`), which in turn interacts with the Gemini API. The CLI supports a variety of tools for file system operations, code execution, web fetching, and more, enhancing your workflow with AI-powered assistance.
|
||||
|
||||
The `packages/cli` is the primary way users interact with the Gemini AI model and its associated tools directly from their terminal. It offers an interactive Read-Eval-Print Loop (REPL) environment where you can send prompts to Gemini, receive responses, and see the results of any tools Gemini uses to fulfill your requests.
|
||||
|
||||
The `packages/core` acts as the backend engine, handling communication with the Gemini API, managing tools, and processing requests from the CLI client.
|
||||
|
||||
## Navigating the Documentation
|
||||
|
||||
This documentation is organized into the following sections:
|
||||
|
|
@ -23,7 +27,8 @@ This documentation is organized into the following sections:
|
|||
- **[Tools Overview](./tools/index.md):** A general look at the available tools.
|
||||
- **[File System Tools](./tools/file-system.md):** Documentation for tools like `read_file`, `edit_file`, etc.
|
||||
- **[Shell Tool](./tools/shell.md):** Using the `execute_bash_command` tool.
|
||||
- **[Web Fetch Tool](./tools/web.md):** Using the `web_fetch` tool.
|
||||
- **[Web Fetch Tool](./tools/web-fetch.md):** Using the `web_fetch` tool.
|
||||
- **[Web Search Tool](./tools/web-search.md):** Using the `google_web_search` tool.
|
||||
- **[Multi-File Read Tool](./tools/multi-file.md):** Using the `read_many_files` tool.
|
||||
- **[Contributing & Development Guide](../CONTRIBUTING.md):** Information for contributors and developers, including setup, building, testing, and coding conventions.
|
||||
- **[Troubleshooting Guide](./troubleshooting.md):** Find solutions to common problems and FAQs.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
Loading…
Reference in New Issue