Docs: Update CLI and Server documentation for recent features (#430)
This commit is contained in:
cperry-goog
GitHub
parent
ee702c3139
commit
d1210f2e0a
|
|
@ -21,15 +21,21 @@ Slash commands provide meta-level control over the CLI itself. They can typicall
|
|||
- **Description:** Allows you to change the visual theme of the Gemini CLI.
|
||||
- **Action:** Opens a dialog or prompt to select from available themes.
|
||||
|
||||
- **`/refreshmemory`**
|
||||
- **`/memory`**
|
||||
|
||||
- **Description:** Reloads instructional context from all `GEMINI.md` files found in the current directory hierarchy (project, user, and global).
|
||||
- **Action:** The CLI re-scans for `GEMINI.md` files and updates its instructional memory with their content.
|
||||
|
||||
- **`/showmemory`**
|
||||
|
||||
- **Description:** Displays the current hierarchical memory content that has been loaded from `GEMINI.md` files.
|
||||
- **Action:** Outputs the combined content of all loaded `GEMINI.md` files, showing the context being provided to the Gemini model.
|
||||
- **Description:** Manages the AI's instructional context (hierarchical memory loaded from `GEMINI.md` files) and allows for adding ad-hoc memory entries.
|
||||
- **Usage:** `/memory <sub_command> [text_for_add]`
|
||||
- **Sub-commands:**
|
||||
- **`show`**:
|
||||
- **Description:** Displays the full, concatenated content of the current hierarchical memory that has been loaded from all `GEMINI.md` files. This allows you to inspect the exact instructional context being provided to the Gemini model.
|
||||
- **Action:** Outputs the combined content of all loaded `GEMINI.md` files, including separators that indicate the origin and path of each part of the memory. This is useful for verifying the loading order and final context.
|
||||
- **`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).
|
||||
|
||||
- **`/quit`** (or **`/exit`**)
|
||||
- **Description:** Exits the Gemini CLI application.
|
||||
|
|
@ -63,18 +69,35 @@ At commands are used to quickly include the content of files or directories as p
|
|||
- If the path specified after `@` is not found or is invalid, an error message will be displayed, and the query might not be sent to the Gemini model, or it will be sent without the file content.
|
||||
- If the `read_many_files` tool encounters an error (e.g., permission issues), this will also be reported.
|
||||
|
||||
## Shell Passthrough Commands (`!`)
|
||||
## Shell Mode & Passthrough Commands (`!`)
|
||||
|
||||
Shell passthrough commands allow you to execute arbitrary shell commands directly from the Gemini CLI. This can be useful for quickly performing system tasks, listing files, or running scripts without leaving the CLI environment.
|
||||
The `!` prefix provides a powerful way to interact with your system's shell directly from within the Gemini CLI. It allows for both single command execution and a toggleable Shell Mode for a more persistent shell experience.
|
||||
|
||||
- **`!<shell_command>`**
|
||||
|
||||
- **Description:** Executes the given command in your system's default shell.
|
||||
- **Description:** Executes the given `<shell_command>` in your system's default shell.
|
||||
- **Usage:**
|
||||
- `!ls -la`
|
||||
- `!git status`
|
||||
- `!echo "Hello from the shell"`
|
||||
- **Action:** The command following the `!` is passed to the system shell for execution. The standard output and standard error from the command are then displayed directly within the Gemini CLI.
|
||||
- **Caution:** Be mindful of the commands you execute, as they have the same permissions and impact as if you ran them directly in your terminal.
|
||||
- `!ls -la` (executes `ls -la` and returns to normal CLI mode)
|
||||
- `!git status` (executes `git status` and returns to normal CLI mode)
|
||||
- **Action:** The command following the `!` is passed to the system shell for execution. Standard output and standard error are displayed in the CLI. After execution, the CLI typically returns to its standard conversational mode.
|
||||
|
||||
These commands provide a powerful way to interact with the Gemini CLI and integrate local file content seamlessly into your conversations with the AI.
|
||||
- **`!` (Toggle Shell Mode)**
|
||||
|
||||
- **Description:** Typing `!` on its own (without an immediately following command) toggles Shell Mode.
|
||||
- **Action & Behavior:**
|
||||
- **Entering Shell Mode:**
|
||||
- The UI will update, often with different coloring and a "Shell Mode Indicator," to clearly show that Shell Mode is active.
|
||||
- Most slash commands (e.g., `/help`, `/theme`) and AI-powered suggestions are disabled to provide an uninterrupted shell experience.
|
||||
- Any text you type is interpreted directly as a shell command.
|
||||
- **Exiting Shell Mode:**
|
||||
- Typing `!` again while in Shell Mode will toggle it off.
|
||||
- The UI will revert to its standard appearance.
|
||||
- Slash commands and AI suggestions are re-enabled.
|
||||
- **Usage:**
|
||||
- Type `!` and press Enter to enter Shell Mode.
|
||||
- Type your shell commands (e.g., `cd my_project`, `npm run dev`, `cat file.txt`).
|
||||
- Type `!` and press Enter again to exit Shell Mode.
|
||||
|
||||
- **Caution for all `!` usage:** Be mindful of the commands you execute, as they have the same permissions and impact as if you ran them directly in your terminal. The Shell Mode feature does not inherently add extra sandboxing beyond what's already configured for the underlying `execute_bash_command` tool.
|
||||
|
||||
This integrated shell capability allows for seamless switching between AI-assisted tasks and direct system interaction.
|
||||
|
|
|
|||
|
|
@ -25,15 +25,30 @@ The Gemini CLI uses `settings.json` files for persistent configuration. There ar
|
|||
|
||||
### The `.gemini` Directory in Your Project
|
||||
|
||||
When you create a `.gemini/settings.json` file for project-specific settings, or when the system needs to store project-specific information (like custom sandboxing profiles, e.g., `.gemini/sandbox-macos-custom.sb` or `.gemini/sandbox.Dockerfile`), this `.gemini` directory is used.
|
||||
When you create a `.gemini/settings.json` file for project-specific settings, or when the system needs to store project-specific information, this `.gemini` directory is used.
|
||||
|
||||
**Purpose:**
|
||||
|
||||
- Stores project-specific configuration for the Gemini CLI (in `settings.json`).
|
||||
- Can hold other project-specific files related to Gemini CLI's operation, such as custom sandbox profiles.
|
||||
- Can hold other project-specific files related to Gemini CLI's operation, such as:
|
||||
- Custom sandbox profiles (e.g., `.gemini/sandbox-macos-custom.sb`, `.gemini/sandbox.Dockerfile`).
|
||||
- A project-specific core system prompt override file (e.g., `.gemini/system.md`). If present, this file can be used to override the default system prompt for the project.
|
||||
|
||||
### Available Settings in `settings.json`:
|
||||
|
||||
- **`coreTools`** (array of strings, optional):
|
||||
- **Description:** Allows you to specify a list of core tool names that should be made available to the model. This can be used to restrict or customize the set of built-in tools.
|
||||
- **Example:** `"coreTools": ["ReadFileTool", "GlobTool", "SearchText"]` (Note: Use the internal tool names like `ReadFileTool`, `GlobTool`, `SearchText` (for Grep), `WriteFileTool`, `EditTool` (for replace), `LSTool`, `ShellTool`, `WebFetchTool`, `ReadManyFilesTool`).
|
||||
- **Behavior:** If this setting is provided, only the listed tools will be available for the model to use. If omitted, all default core tools are available.
|
||||
- **`autoAccept`** (boolean, optional):
|
||||
|
||||
- **Description:** Controls whether the CLI automatically accepts and executes tool calls that are considered safe (e.g., read-only operations) without explicit user confirmation.
|
||||
- **Default:** `false` (users will be prompted for most tool calls).
|
||||
- **Behavior:**
|
||||
- If set to `true`, the CLI will bypass the confirmation prompt for tools deemed safe. An indicator may be shown in the UI when auto-accept is active.
|
||||
- Potentially destructive or system-modifying tools (like `execute_bash_command` or `write_file`) will likely still require confirmation regardless of this setting.
|
||||
- **Example:** `"autoAccept": true`
|
||||
|
||||
- **`theme`** (string):
|
||||
- Specifies the visual theme for the CLI.
|
||||
- Example: `"theme": "VS2015"`
|
||||
|
|
@ -53,12 +68,32 @@ When you create a `.gemini/settings.json` file for project-specific settings, or
|
|||
- Must return JSON result of funcation call on `stdout`.
|
||||
- **`mcpServers`** (object, advanced):
|
||||
- Configures connections to one or more Model-Context Protocol (MCP) servers for discovering and using custom tools.
|
||||
- This is an object where each key is a server name and the value is an object defining the server's parameters:
|
||||
- This is an object where each key is a unique server name (alias) and the value is an object defining that server's parameters:
|
||||
- `command` (string, required): The command to execute to start the MCP server.
|
||||
- `args` (array of strings, optional): Arguments to pass to the command.
|
||||
- `env` (object, optional): Environment variables to set for the server process.
|
||||
- `cwd` (string, optional): The working directory in which to start the server.
|
||||
- Example: `"mcpServers": { "myServer": { "command": "python", "args": ["mcp_server.py", "--port", "8080"], "cwd": "./mcp_tools" } }`
|
||||
- `timeout` (number, optional): Timeout in milliseconds for requests to this MCP server.
|
||||
- **Behavior:**
|
||||
- The CLI will attempt to connect to each configured MCP server to discover available tools.
|
||||
- If multiple MCP servers expose a tool with the same name, the tool names will be prefixed with the server alias you defined in the configuration (e.g., `serverAlias__actualToolName`) to avoid conflicts.
|
||||
- The system may strip certain schema properties from MCP tool definitions for compatibility.
|
||||
- Example:
|
||||
```json
|
||||
"mcpServers": {
|
||||
"myPythonServer": {
|
||||
"command": "python",
|
||||
"args": ["mcp_server.py", "--port", "8080"],
|
||||
"cwd": "./mcp_tools/python",
|
||||
"timeout": 5000
|
||||
},
|
||||
"myNodeServer": {
|
||||
"command": "node",
|
||||
"args": ["mcp_server.js"],
|
||||
"cwd": "./mcp_tools/node"
|
||||
}
|
||||
}
|
||||
```
|
||||
- **`mcpServerCommand`** (string, advanced, **deprecated**):
|
||||
- Legacy setting for configuring a single MCP server. Please use `mcpServers` instead for better flexibility and support for multiple servers.
|
||||
|
||||
|
|
@ -131,9 +166,9 @@ Arguments passed directly when running the CLI can override other configurations
|
|||
|
||||
## 4. `GEMINI.md` Files (Hierarchical Instructional Context)
|
||||
|
||||
While not strictly configuration for the CLI's _behavior_, `GEMINI.md` files are crucial for configuring the _instructional context_ provided to the Gemini model. This allows you to give project-specific instructions, coding style guides, or any relevant background information to the AI.
|
||||
While not strictly configuration for the CLI's _behavior_, `GEMINI.md` files are crucial for configuring the _instructional context_ (also referred to as "memory") provided to the Gemini model. This powerful feature allows you to give project-specific instructions, coding style guides, or any relevant background information to the AI, making its responses more tailored and accurate to your needs. The CLI includes UI elements, such as an indicator in the footer showing the number of loaded `GEMINI.md` files, to keep you informed about the active context.
|
||||
|
||||
- **Purpose:** These Markdown files contain instructions, guidelines, or context that you want the Gemini model to be aware of during your interactions.
|
||||
- **Purpose:** These Markdown files contain instructions, guidelines, or context that you want the Gemini model to be aware of during your interactions. The system is designed to manage this instructional context hierarchically.
|
||||
|
||||
### Example `GEMINI.md` Content
|
||||
|
||||
|
|
@ -168,9 +203,9 @@ Here's a conceptual example of what a `GEMINI.md` file at the root of a TypeScri
|
|||
- If a new dependency is required, please state the reason.
|
||||
```
|
||||
|
||||
This example demonstrates how you can provide general project context, specific coding conventions, and even notes about particular files or components. The more relevant and precise your `GEMINI.md` files are, the better the AI can assist you.
|
||||
This example demonstrates how you can provide general project context, specific coding conventions, and even notes about particular files or components. The more relevant and precise your `GEMINI.md` files are, the better the AI can assist you. Project-specific `GEMINI.md` files are highly encouraged to establish conventions and context.
|
||||
|
||||
- **Hierarchical Loading and Precedence:** The CLI loads `GEMINI.md` files from several locations, forming a hierarchy. Content from files lower in this list (more specific) typically overrides or supplements content from files higher up (more general), though the exact concatenation order should be verified with `/showmemory`:
|
||||
- **Hierarchical Loading and Precedence:** The CLI implements a sophisticated hierarchical memory system by loading `GEMINI.md` files from several locations. Content from files lower in this list (more specific) typically overrides or supplements content from files higher up (more general). The exact concatenation order and final context can be inspected using the `/showmemory` command. The typical loading order is:
|
||||
1. **Global `GEMINI.md`:**
|
||||
- Location: `~/.gemini/GEMINI.md` (in your user home directory).
|
||||
- Scope: Provides default instructions for all your projects.
|
||||
|
|
@ -180,9 +215,10 @@ This example demonstrates how you can provide general project context, specific
|
|||
3. **Sub-directory `GEMINI.md` (Contextual/Local):**
|
||||
- Location: The CLI also scans for `GEMINI.md` files in subdirectories _below_ the current working directory (respecting common ignore patterns like `node_modules`, `.git`, etc.).
|
||||
- Scope: Allows for highly specific instructions relevant to a particular component, module, or sub-section of your project.
|
||||
- **Concatenation:** The contents of all found `GEMINI.md` files are concatenated (with separators indicating their origin and path) and provided as part of the system prompt to the Gemini model. You can see the exact combined content and loading order using the `/showmemory` command.
|
||||
- **Commands:**
|
||||
- Use `/refreshmemory` to force a re-scan and reload of all `GEMINI.md` files.
|
||||
- Use `/showmemory` to display the combined instructional context currently loaded.
|
||||
- **Concatenation & UI Indication:** The contents of all found `GEMINI.md` files are concatenated (with separators indicating their origin and path) and provided as part of the system prompt to the Gemini model. The CLI footer displays the count of loaded `GEMINI.md` files, giving you a quick visual cue about the active instructional context.
|
||||
- **Commands for Memory Management:**
|
||||
- Use `/memory refresh` to force a re-scan and reload of all `GEMINI.md` files from all configured locations. This updates the AI's instructional context.
|
||||
- Use `/memory show` to display the combined instructional context currently loaded, allowing you to verify the hierarchy and content being used by the AI.
|
||||
- See the [Commands documentation](./commands.md#memory) for full details on the `/memory` command and its sub-commands (`show` and `refresh`).
|
||||
|
||||
By understanding these configuration layers and the hierarchical nature of `GEMINI.md` files, you can effectively tailor the Gemini CLI and the AI's responses to your specific needs and projects.
|
||||
By understanding and utilizing these configuration layers and the hierarchical nature of `GEMINI.md` files, you can effectively manage the AI's memory and tailor the Gemini CLI's responses to your specific needs and projects.
|
||||
|
|
|
|||
|
|
@ -17,6 +17,7 @@ The Gemini CLI (`packages/cli`) is the primary way users interact with the Gemin
|
|||
- **Theming:** Customize the look and feel of the CLI to your preference. See the [Theming section in README.md](../../README.md#theming).
|
||||
- **Configuration:** Tailor the CLI's behavior through configuration files. See [CLI Configuration](./configuration.md).
|
||||
- **Special Commands:** Utilize built-in commands for tasks like managing history, memory, or display. See [Commands](./commands.md).
|
||||
- **Enhanced Input:** Support for multiline input editing and readline-like keybindings for a more comfortable and efficient command entry experience.
|
||||
|
||||
## Basic Interaction
|
||||
|
||||
|
|
|
|||
|
|
@ -18,12 +18,12 @@ These are the main pieces of information the server `Config` object holds and us
|
|||
- **`apiKey` (string):**
|
||||
|
||||
- **Source:** Primarily `process.env.GEMINI_API_KEY` (loaded from the environment or `.env` files).
|
||||
- **Importance:** Absolutely essential. The server cannot communicate with the Gemini API without it.
|
||||
- **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 the default value `gemini-2.5-pro-preview-05-06`.
|
||||
- **Purpose:** Specifies which Gemini model the server should use for generating responses.
|
||||
- **Source:** Command-line argument (`--model`), environment variable (`GEMINI_MODEL`), or a default value (e.g., `gemini-2.5-pro-preview-05-06`).
|
||||
- **Purpose:** Specifies which Gemini model the server should use. (For Vertex AI model names and usage, refer to the main README.md).
|
||||
|
||||
- **`sandbox` (boolean | string):**
|
||||
|
||||
|
|
@ -57,17 +57,19 @@ These are the main pieces of information the server `Config` object holds and us
|
|||
|
||||
- `toolCallCommand` (string | undefined):
|
||||
- `mcpServers` (object | undefined):
|
||||
- **Source:** `settings.json` (`mcpServers` key).
|
||||
- **Purpose:** Advanced setting for configuring connections to Model-Context Protocol (MCP) servers. This is an object where each key is a server name and the value is an object defining the server's parameters:
|
||||
- **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 to pass to the command.
|
||||
- `env` (object, optional): Environment variables to set for the server process.
|
||||
- `cwd` (string, optional): The working directory in which to start the server.
|
||||
- Allows discovery and use of tools from multiple MCP sources.
|
||||
- `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 server 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 server may also adapt tool schemas from MCP servers for internal compatibility.
|
||||
- `mcpServerCommand` (string | undefined, **deprecated**):
|
||||
|
||||
- **Source:** `settings.json` (`mcpServerCommand` key).
|
||||
- **Purpose:** Legacy setting for configuring a single MCP server. Please use `mcpServers` instead.
|
||||
- **Purpose:** Legacy setting for a single MCP server. Superseded by `mcpServers`.
|
||||
|
||||
- `userAgent` (string):
|
||||
|
||||
|
|
@ -78,7 +80,7 @@ These are the main pieces of information the server `Config` object holds and us
|
|||
|
||||
- **Source:** Loaded from the hierarchical `GEMINI.md` files by the CLI (Global, Project Root/Ancestors, Sub-directory) and passed to the server 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 `/refreshmemory` command in the CLI).
|
||||
- **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.
|
||||
|
|
|
|||
|
|
@ -110,13 +110,15 @@ All file system tools operate within a `rootDirectory` (usually the current work
|
|||
- 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:** The tool incorporates a multi-stage edit correction mechanism. If the initial `old_string` provided by the model doesn't perfectly match a unique segment in the file (e.g., it's not found, or matches multiple times), the tool can leverage the Gemini model to attempt to refine `old_string` (and potentially `new_string`). This iterative process aims to identify the correct unique segment for modification, significantly improving the reliability of edits even if the initial context isn't perfectly precise.
|
||||
- **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 from the AI.
|
||||
- **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.
|
||||
- `old_string` is found multiple times (and self-correction doesn't resolve it to a single match).
|
||||
- `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...`).
|
||||
|
|
|
|||
Loading…
Reference in New Issue