mirror of
https://github.com/google-gemini/gemini-cli.git
synced 2026-03-10 14:10:37 -07:00
Updated ToC on docs intro; updated title casing to match Google style (#13717)
This commit is contained in:
David Huntsperger
committed by
GitHub
GitHub
parent
bde8b78a88
commit
26f050ff10
@@ -184,7 +184,7 @@ context around the `old_string` to ensure it modifies the correct location.
|
||||
- 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
|
||||
- **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.
|
||||
|
||||
@@ -23,7 +23,7 @@ With an MCP server, you can extend the Gemini CLI's capabilities to perform
|
||||
actions beyond its built-in features, such as interacting with databases, APIs,
|
||||
custom scripts, or specialized workflows.
|
||||
|
||||
## Core Integration Architecture
|
||||
## Core integration architecture
|
||||
|
||||
The Gemini CLI integrates with MCP servers through a sophisticated discovery and
|
||||
execution system built into the core package (`packages/core/src/tools/`):
|
||||
@@ -41,7 +41,7 @@ The discovery process is orchestrated by `discoverMcpTools()`, which:
|
||||
API
|
||||
5. **Registers tools** in the global tool registry with conflict resolution
|
||||
|
||||
### Execution Layer (`mcp-tool.ts`)
|
||||
### Execution layer (`mcp-tool.ts`)
|
||||
|
||||
Each discovered MCP tool is wrapped in a `DiscoveredMCPTool` instance that:
|
||||
|
||||
@@ -51,7 +51,7 @@ Each discovered MCP tool is wrapped in a `DiscoveredMCPTool` instance that:
|
||||
- **Processes responses** for both the LLM context and user display
|
||||
- **Maintains connection state** and handles timeouts
|
||||
|
||||
### Transport Mechanisms
|
||||
### Transport mechanisms
|
||||
|
||||
The Gemini CLI supports three MCP transport types:
|
||||
|
||||
@@ -72,7 +72,7 @@ through the top-level `mcpServers` object for specific server definitions, and
|
||||
through the `mcp` object for global settings that control server discovery and
|
||||
execution.
|
||||
|
||||
#### Global MCP Settings (`mcp`)
|
||||
#### Global MCP settings (`mcp`)
|
||||
|
||||
The `mcp` object in your `settings.json` allows you to define global rules for
|
||||
all MCP servers.
|
||||
@@ -95,12 +95,12 @@ all MCP servers.
|
||||
}
|
||||
```
|
||||
|
||||
#### Server-Specific Configuration (`mcpServers`)
|
||||
#### Server-specific configuration (`mcpServers`)
|
||||
|
||||
The `mcpServers` object is where you define each individual MCP server you want
|
||||
the CLI to connect to.
|
||||
|
||||
### Configuration Structure
|
||||
### Configuration structure
|
||||
|
||||
Add an `mcpServers` object to your `settings.json` file:
|
||||
|
||||
@@ -121,7 +121,7 @@ Add an `mcpServers` object to your `settings.json` file:
|
||||
}
|
||||
```
|
||||
|
||||
### Configuration Properties
|
||||
### Configuration properties
|
||||
|
||||
Each server configuration supports the following properties:
|
||||
|
||||
@@ -157,13 +157,13 @@ Each server configuration supports the following properties:
|
||||
Service Account to impersonate. Used with
|
||||
`authProviderType: 'service_account_impersonation'`.
|
||||
|
||||
### OAuth Support for Remote MCP Servers
|
||||
### OAuth support for remote MCP servers
|
||||
|
||||
The Gemini CLI supports OAuth 2.0 authentication for remote MCP servers using
|
||||
SSE or HTTP transports. This enables secure access to MCP servers that require
|
||||
authentication.
|
||||
|
||||
#### Automatic OAuth Discovery
|
||||
#### Automatic OAuth discovery
|
||||
|
||||
For servers that support OAuth discovery, you can omit the OAuth configuration
|
||||
and let the CLI discover it automatically:
|
||||
@@ -185,7 +185,7 @@ The CLI will automatically:
|
||||
- Perform dynamic client registration if supported
|
||||
- Handle the OAuth flow and token management
|
||||
|
||||
#### Authentication Flow
|
||||
#### Authentication flow
|
||||
|
||||
When connecting to an OAuth-enabled server:
|
||||
|
||||
@@ -196,7 +196,7 @@ When connecting to an OAuth-enabled server:
|
||||
5. **Tokens are stored** securely for future use
|
||||
6. **Connection retry** succeeds with valid tokens
|
||||
|
||||
#### Browser Redirect Requirements
|
||||
#### Browser redirect requirements
|
||||
|
||||
**Important:** OAuth authentication requires that your local machine can:
|
||||
|
||||
@@ -209,7 +209,7 @@ This feature will not work in:
|
||||
- Remote SSH sessions without X11 forwarding
|
||||
- Containerized environments without browser support
|
||||
|
||||
#### Managing OAuth Authentication
|
||||
#### Managing OAuth authentication
|
||||
|
||||
Use the `/mcp auth` command to manage OAuth authentication:
|
||||
|
||||
@@ -224,7 +224,7 @@ Use the `/mcp auth` command to manage OAuth authentication:
|
||||
/mcp auth serverName
|
||||
```
|
||||
|
||||
#### OAuth Configuration Properties
|
||||
#### OAuth configuration properties
|
||||
|
||||
- **`enabled`** (boolean): Enable OAuth for this server
|
||||
- **`clientId`** (string): OAuth client identifier (optional with dynamic
|
||||
@@ -239,7 +239,7 @@ Use the `/mcp auth` command to manage OAuth authentication:
|
||||
- **`tokenParamName`** (string): Query parameter name for tokens in SSE URLs
|
||||
- **`audiences`** (string[]): Audiences the token is valid for
|
||||
|
||||
#### Token Management
|
||||
#### Token management
|
||||
|
||||
OAuth tokens are automatically:
|
||||
|
||||
@@ -248,7 +248,7 @@ OAuth tokens are automatically:
|
||||
- **Validated** before each connection attempt
|
||||
- **Cleaned up** when invalid or expired
|
||||
|
||||
#### Authentication Provider Type
|
||||
#### Authentication provider type
|
||||
|
||||
You can specify the authentication provider type using the `authProviderType`
|
||||
property:
|
||||
@@ -265,7 +265,7 @@ property:
|
||||
accessing IAP-protected services (this was specifically designed for Cloud
|
||||
Run services).
|
||||
|
||||
#### Google Credentials
|
||||
#### Google credentials
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -281,7 +281,7 @@ property:
|
||||
}
|
||||
```
|
||||
|
||||
#### Service Account Impersonation
|
||||
#### Service account impersonation
|
||||
|
||||
To authenticate with a server using Service Account Impersonation, you must set
|
||||
the `authProviderType` to `service_account_impersonation` and provide the
|
||||
@@ -296,7 +296,7 @@ The CLI will use your local Application Default Credentials (ADC) to generate an
|
||||
OIDC ID token for the specified service account and audience. This token will
|
||||
then be used to authenticate with the MCP server.
|
||||
|
||||
#### Setup Instructions
|
||||
#### Setup instructions
|
||||
|
||||
1. **[Create](https://cloud.google.com/iap/docs/oauth-client-creation) or use an
|
||||
existing OAuth 2.0 client ID.** To use an existing OAuth 2.0 client ID,
|
||||
@@ -318,9 +318,9 @@ then be used to authenticate with the MCP server.
|
||||
6. **[Enable](https://console.cloud.google.com/apis/library/iamcredentials.googleapis.com)
|
||||
the IAM Credentials API** for your project.
|
||||
|
||||
### Example Configurations
|
||||
### Example configurations
|
||||
|
||||
#### Python MCP Server (Stdio)
|
||||
#### Python MCP server (stdio)
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -339,7 +339,7 @@ then be used to authenticate with the MCP server.
|
||||
}
|
||||
```
|
||||
|
||||
#### Node.js MCP Server (Stdio)
|
||||
#### Node.js MCP server (stdio)
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -354,7 +354,7 @@ then be used to authenticate with the MCP server.
|
||||
}
|
||||
```
|
||||
|
||||
#### Docker-based MCP Server
|
||||
#### Docker-based MCP server
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -379,7 +379,7 @@ then be used to authenticate with the MCP server.
|
||||
}
|
||||
```
|
||||
|
||||
#### HTTP-based MCP Server
|
||||
#### HTTP-based MCP server
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -392,7 +392,7 @@ then be used to authenticate with the MCP server.
|
||||
}
|
||||
```
|
||||
|
||||
#### HTTP-based MCP Server with Custom Headers
|
||||
#### HTTP-based MCP Server with custom headers
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -410,7 +410,7 @@ then be used to authenticate with the MCP server.
|
||||
}
|
||||
```
|
||||
|
||||
#### MCP Server with Tool Filtering
|
||||
#### MCP server with tool filtering
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -426,7 +426,7 @@ then be used to authenticate with the MCP server.
|
||||
}
|
||||
```
|
||||
|
||||
### SSE MCP Server with SA Impersonation
|
||||
### SSE MCP server with SA impersonation
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -441,12 +441,12 @@ then be used to authenticate with the MCP server.
|
||||
}
|
||||
```
|
||||
|
||||
## Discovery Process Deep Dive
|
||||
## Discovery process deep dive
|
||||
|
||||
When the Gemini CLI starts, it performs MCP server discovery through the
|
||||
following detailed process:
|
||||
|
||||
### 1. Server Iteration and Connection
|
||||
### 1. Server iteration and connection
|
||||
|
||||
For each configured server in `mcpServers`:
|
||||
|
||||
@@ -460,7 +460,7 @@ For each configured server in `mcpServers`:
|
||||
4. **Error handling:** Connection failures are logged and the server status is
|
||||
set to `DISCONNECTED`
|
||||
|
||||
### 2. Tool Discovery
|
||||
### 2. Tool discovery
|
||||
|
||||
Upon successful connection:
|
||||
|
||||
@@ -475,7 +475,7 @@ Upon successful connection:
|
||||
- Names longer than 63 characters are truncated with middle replacement
|
||||
(`___`)
|
||||
|
||||
### 3. Conflict Resolution
|
||||
### 3. Conflict resolution
|
||||
|
||||
When multiple servers expose tools with the same name:
|
||||
|
||||
@@ -486,7 +486,7 @@ When multiple servers expose tools with the same name:
|
||||
3. **Registry tracking:** The tool registry maintains mappings between server
|
||||
names and their tools
|
||||
|
||||
### 4. Schema Processing
|
||||
### 4. Schema processing
|
||||
|
||||
Tool parameter schemas undergo sanitization for Gemini API compatibility:
|
||||
|
||||
@@ -496,7 +496,7 @@ Tool parameter schemas undergo sanitization for Gemini API compatibility:
|
||||
compatibility)
|
||||
- **Recursive processing** applies to nested schemas
|
||||
|
||||
### 5. Connection Management
|
||||
### 5. Connection management
|
||||
|
||||
After discovery:
|
||||
|
||||
@@ -507,23 +507,23 @@ After discovery:
|
||||
- **Status updates:** Final server statuses are set to `CONNECTED` or
|
||||
`DISCONNECTED`
|
||||
|
||||
## Tool Execution Flow
|
||||
## Tool execution flow
|
||||
|
||||
When the Gemini model decides to use an MCP tool, the following execution flow
|
||||
occurs:
|
||||
|
||||
### 1. Tool Invocation
|
||||
### 1. Tool invocation
|
||||
|
||||
The model generates a `FunctionCall` with:
|
||||
|
||||
- **Tool name:** The registered name (potentially prefixed)
|
||||
- **Arguments:** JSON object matching the tool's parameter schema
|
||||
|
||||
### 2. Confirmation Process
|
||||
### 2. Confirmation process
|
||||
|
||||
Each `DiscoveredMCPTool` implements sophisticated confirmation logic:
|
||||
|
||||
#### Trust-based Bypass
|
||||
#### Trust-based bypass
|
||||
|
||||
```typescript
|
||||
if (this.trust) {
|
||||
@@ -531,14 +531,14 @@ if (this.trust) {
|
||||
}
|
||||
```
|
||||
|
||||
#### Dynamic Allow-listing
|
||||
#### Dynamic allow-listing
|
||||
|
||||
The system maintains internal allow-lists for:
|
||||
|
||||
- **Server-level:** `serverName` → All tools from this server are trusted
|
||||
- **Tool-level:** `serverName.toolName` → This specific tool is trusted
|
||||
|
||||
#### User Choice Handling
|
||||
#### User choice handling
|
||||
|
||||
When confirmation is required, users can choose:
|
||||
|
||||
@@ -566,7 +566,7 @@ Upon confirmation (or trust bypass):
|
||||
3. **Response processing:** Results are formatted for both LLM context and user
|
||||
display
|
||||
|
||||
### 4. Response Handling
|
||||
### 4. Response handling
|
||||
|
||||
The execution result contains:
|
||||
|
||||
@@ -576,7 +576,7 @@ The execution result contains:
|
||||
|
||||
## How to interact with your MCP server
|
||||
|
||||
### Using the `/mcp` Command
|
||||
### Using the `/mcp` command
|
||||
|
||||
The `/mcp` command provides comprehensive information about your MCP server
|
||||
setup:
|
||||
@@ -593,7 +593,7 @@ This displays:
|
||||
- **Available tools:** List of tools from each server with descriptions
|
||||
- **Discovery state:** Overall discovery process status
|
||||
|
||||
### Example `/mcp` Output
|
||||
### Example `/mcp` output
|
||||
|
||||
```
|
||||
MCP Servers Status:
|
||||
@@ -615,7 +615,7 @@ MCP Servers Status:
|
||||
Discovery State: COMPLETED
|
||||
```
|
||||
|
||||
### Tool Usage
|
||||
### Tool usage
|
||||
|
||||
Once discovered, MCP tools are available to the Gemini model like built-in
|
||||
tools. The model will automatically:
|
||||
@@ -625,27 +625,27 @@ tools. The model will automatically:
|
||||
3. **Execute tools** with proper parameters
|
||||
4. **Display results** in a user-friendly format
|
||||
|
||||
## Status Monitoring and Troubleshooting
|
||||
## Status monitoring and troubleshooting
|
||||
|
||||
### Connection States
|
||||
### Connection states
|
||||
|
||||
The MCP integration tracks several states:
|
||||
|
||||
#### Server Status (`MCPServerStatus`)
|
||||
#### Server status (`MCPServerStatus`)
|
||||
|
||||
- **`DISCONNECTED`:** Server is not connected or has errors
|
||||
- **`CONNECTING`:** Connection attempt in progress
|
||||
- **`CONNECTED`:** Server is connected and ready
|
||||
|
||||
#### Discovery State (`MCPDiscoveryState`)
|
||||
#### Discovery state (`MCPDiscoveryState`)
|
||||
|
||||
- **`NOT_STARTED`:** Discovery hasn't begun
|
||||
- **`IN_PROGRESS`:** Currently discovering servers
|
||||
- **`COMPLETED`:** Discovery finished (with or without errors)
|
||||
|
||||
### Common Issues and Solutions
|
||||
### Common issues and solutions
|
||||
|
||||
#### Server Won't Connect
|
||||
#### Server won't connect
|
||||
|
||||
**Symptoms:** Server shows `DISCONNECTED` status
|
||||
|
||||
@@ -657,7 +657,7 @@ The MCP integration tracks several states:
|
||||
4. **Review logs:** Look for error messages in the CLI output
|
||||
5. **Verify permissions:** Ensure the CLI can execute the server command
|
||||
|
||||
#### No Tools Discovered
|
||||
#### No tools discovered
|
||||
|
||||
**Symptoms:** Server connects but no tools are available
|
||||
|
||||
@@ -669,7 +669,7 @@ The MCP integration tracks several states:
|
||||
3. **Review server logs:** Check stderr output for server-side errors
|
||||
4. **Test tool listing:** Manually test your server's tool discovery endpoint
|
||||
|
||||
#### Tools Not Executing
|
||||
#### Tools not executing
|
||||
|
||||
**Symptoms:** Tools are discovered but fail during execution
|
||||
|
||||
@@ -680,7 +680,7 @@ The MCP integration tracks several states:
|
||||
3. **Error handling:** Check if your tool is throwing unhandled exceptions
|
||||
4. **Timeout issues:** Consider increasing the `timeout` setting
|
||||
|
||||
#### Sandbox Compatibility
|
||||
#### Sandbox compatibility
|
||||
|
||||
**Symptoms:** MCP servers fail when sandboxing is enabled
|
||||
|
||||
@@ -693,7 +693,7 @@ The MCP integration tracks several states:
|
||||
4. **Environment variables:** Verify required environment variables are passed
|
||||
through
|
||||
|
||||
### Debugging Tips
|
||||
### Debugging tips
|
||||
|
||||
1. **Enable debug mode:** Run the CLI with `--debug` for verbose output
|
||||
2. **Check stderr:** MCP server stderr is captured and logged (INFO messages
|
||||
@@ -703,9 +703,9 @@ The MCP integration tracks several states:
|
||||
functionality
|
||||
5. **Use `/mcp` frequently:** Monitor server status during development
|
||||
|
||||
## Important Notes
|
||||
## Important notes
|
||||
|
||||
### Security Considerations
|
||||
### Security sonsiderations
|
||||
|
||||
- **Trust settings:** The `trust` option bypasses all confirmation dialogs. Use
|
||||
cautiously and only for servers you completely control
|
||||
@@ -716,7 +716,7 @@ The MCP integration tracks several states:
|
||||
- **Private data:** Using broadly scoped personal access tokens can lead to
|
||||
information leakage between repositories
|
||||
|
||||
### Performance and Resource Management
|
||||
### Performance and resource management
|
||||
|
||||
- **Connection persistence:** The CLI maintains persistent connections to
|
||||
servers that successfully register tools
|
||||
@@ -727,7 +727,7 @@ The MCP integration tracks several states:
|
||||
- **Resource monitoring:** MCP servers run as separate processes and consume
|
||||
system resources
|
||||
|
||||
### Schema Compatibility
|
||||
### Schema compatibility
|
||||
|
||||
- **Property stripping:** The system automatically removes certain schema
|
||||
properties (`$schema`, `additionalProperties`) for Gemini API compatibility
|
||||
@@ -740,7 +740,7 @@ This comprehensive integration makes MCP servers a powerful way to extend the
|
||||
Gemini CLI's capabilities while maintaining security, reliability, and ease of
|
||||
use.
|
||||
|
||||
## Returning Rich Content from Tools
|
||||
## Returning rich content from tools
|
||||
|
||||
MCP tools are not limited to returning simple text. You can return rich,
|
||||
multi-part content, including text, images, audio, and other binary data in a
|
||||
@@ -751,7 +751,7 @@ All data returned from the tool is processed and sent to the model as context
|
||||
for its next generation, enabling it to reason about or summarize the provided
|
||||
information.
|
||||
|
||||
### How It Works
|
||||
### How it works
|
||||
|
||||
To return rich content, your tool's response must adhere to the MCP
|
||||
specification for a
|
||||
@@ -769,7 +769,7 @@ supported block types include:
|
||||
- `resource` (embedded content)
|
||||
- `resource_link`
|
||||
|
||||
### Example: Returning Text and an Image
|
||||
### Example: Returning text and an image
|
||||
|
||||
Here is an example of a valid JSON response from an MCP tool that returns both a
|
||||
text description and an image:
|
||||
@@ -805,13 +805,13 @@ When the Gemini CLI receives this response, it will:
|
||||
This enables you to build sophisticated tools that can provide rich, multi-modal
|
||||
context to the Gemini model.
|
||||
|
||||
## MCP Prompts as Slash Commands
|
||||
## MCP prompts as slash commands
|
||||
|
||||
In addition to tools, MCP servers can expose predefined prompts that can be
|
||||
executed as slash commands within the Gemini CLI. This allows you to create
|
||||
shortcuts for common or complex queries that can be easily invoked by name.
|
||||
|
||||
### Defining Prompts on the Server
|
||||
### Defining prompts on the server
|
||||
|
||||
Here's a small example of a stdio MCP server that defines prompts:
|
||||
|
||||
@@ -862,7 +862,7 @@ This can be included in `settings.json` under `mcpServers` with:
|
||||
}
|
||||
```
|
||||
|
||||
### Invoking Prompts
|
||||
### Invoking prompts
|
||||
|
||||
Once a prompt is discovered, you can invoke it using its name as a slash
|
||||
command. The CLI will automatically handle parsing arguments.
|
||||
@@ -883,7 +883,7 @@ substituting the arguments into the prompt template and returning the final
|
||||
prompt text. The CLI then sends this prompt to the model for execution. This
|
||||
provides a convenient way to automate and share common workflows.
|
||||
|
||||
## Managing MCP Servers with `gemini mcp`
|
||||
## Managing MCP servers with `gemini mcp`
|
||||
|
||||
While you can always configure MCP servers by manually editing your
|
||||
`settings.json` file, the Gemini CLI provides a convenient set of commands to
|
||||
@@ -891,7 +891,7 @@ manage your server configurations programmatically. These commands streamline
|
||||
the process of adding, listing, and removing MCP servers without needing to
|
||||
directly edit JSON files.
|
||||
|
||||
### Adding a Server (`gemini mcp add`)
|
||||
### Adding a server (`gemini mcp add`)
|
||||
|
||||
The `add` command configures a new MCP server in your `settings.json`. Based on
|
||||
the scope (`-s, --scope`), it will be added to either the user config
|
||||
@@ -908,7 +908,7 @@ gemini mcp add [options] <name> <commandOrUrl> [args...]
|
||||
`http`/`sse`).
|
||||
- `[args...]`: Optional arguments for a `stdio` command.
|
||||
|
||||
**Options (Flags):**
|
||||
**Options (flags):**
|
||||
|
||||
- `-s, --scope`: Configuration scope (user or project). [default: "project"]
|
||||
- `-t, --transport`: Transport type (stdio, sse, http). [default: "stdio"]
|
||||
@@ -966,7 +966,7 @@ gemini mcp add --transport sse sse-server https://api.example.com/sse/
|
||||
gemini mcp add --transport sse --header "Authorization: Bearer abc123" secure-sse https://api.example.com/sse/
|
||||
```
|
||||
|
||||
### Listing Servers (`gemini mcp list`)
|
||||
### Listing servers (`gemini mcp list`)
|
||||
|
||||
To view all MCP servers currently configured, use the `list` command. It
|
||||
displays each server's name, configuration details, and connection status. This
|
||||
@@ -978,7 +978,7 @@ command has no flags.
|
||||
gemini mcp list
|
||||
```
|
||||
|
||||
**Example Output:**
|
||||
**Example output:**
|
||||
|
||||
```sh
|
||||
✓ stdio-server: command: python3 server.py (stdio) - Connected
|
||||
@@ -986,7 +986,7 @@ gemini mcp list
|
||||
✗ sse-server: https://api.example.com/sse (sse) - Disconnected
|
||||
```
|
||||
|
||||
### Removing a Server (`gemini mcp remove`)
|
||||
### Removing a server (`gemini mcp remove`)
|
||||
|
||||
To delete a server from your configuration, use the `remove` command with the
|
||||
server's name.
|
||||
@@ -997,7 +997,7 @@ server's name.
|
||||
gemini mcp remove <name>
|
||||
```
|
||||
|
||||
**Options (Flags):**
|
||||
**Options (flags):**
|
||||
|
||||
- `-s, --scope`: Configuration scope (user or project). [default: "project"]
|
||||
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# Memory Tool (`save_memory`)
|
||||
# Memory tool (`save_memory`)
|
||||
|
||||
This document describes the `save_memory` tool for the Gemini CLI.
|
||||
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# Shell Tool (`run_shell_command`)
|
||||
# Shell tool (`run_shell_command`)
|
||||
|
||||
This document describes the `run_shell_command` tool for the Gemini CLI.
|
||||
|
||||
@@ -71,7 +71,7 @@ run_shell_command(command="npm run dev &", description="Start development server
|
||||
You can configure the behavior of the `run_shell_command` tool by modifying your
|
||||
`settings.json` file or by using the `/settings` command in the Gemini CLI.
|
||||
|
||||
### Enabling Interactive Commands
|
||||
### Enabling interactive commands
|
||||
|
||||
To enable interactive commands, you need to set the
|
||||
`tools.shell.enableInteractiveShell` setting to `true`. This will use `node-pty`
|
||||
@@ -91,7 +91,7 @@ implementation, which does not support interactive commands.
|
||||
}
|
||||
```
|
||||
|
||||
### Showing Color in Output
|
||||
### Showing color in output
|
||||
|
||||
To show color in the shell output, you need to set the `tools.shell.showColor`
|
||||
setting to `true`. **Note: This setting only applies when
|
||||
@@ -109,7 +109,7 @@ setting to `true`. **Note: This setting only applies when
|
||||
}
|
||||
```
|
||||
|
||||
### Setting the Pager
|
||||
### Setting the pager
|
||||
|
||||
You can set a custom pager for the shell output by setting the
|
||||
`tools.shell.pager` setting. The default pager is `cat`. **Note: This setting
|
||||
@@ -127,7 +127,7 @@ only applies when `tools.shell.enableInteractiveShell` is enabled.**
|
||||
}
|
||||
```
|
||||
|
||||
## Interactive Commands
|
||||
## Interactive commands
|
||||
|
||||
The `run_shell_command` tool now supports interactive commands by integrating a
|
||||
pseudo-terminal (pty). This allows you to run commands that require real-time
|
||||
@@ -149,13 +149,13 @@ including complex TUIs, will be rendered correctly.
|
||||
background. The `Background PIDs` field will contain the process ID of the
|
||||
background process.
|
||||
|
||||
## Environment Variables
|
||||
## Environment variables
|
||||
|
||||
When `run_shell_command` executes a command, it sets the `GEMINI_CLI=1`
|
||||
environment variable in the subprocess's environment. This allows scripts or
|
||||
tools to detect if they are being run from within the Gemini CLI.
|
||||
|
||||
## Command Restrictions
|
||||
## Command restrictions
|
||||
|
||||
You can restrict the commands that can be executed by the `run_shell_command`
|
||||
tool by using the `tools.core` and `tools.exclude` settings in your
|
||||
@@ -174,16 +174,16 @@ configuration file.
|
||||
|
||||
The validation logic is designed to be secure and flexible:
|
||||
|
||||
1. **Command Chaining Disabled**: The tool automatically splits commands
|
||||
1. **Command chaining disabled**: The tool automatically splits commands
|
||||
chained with `&&`, `||`, or `;` and validates each part separately. If any
|
||||
part of the chain is disallowed, the entire command is blocked.
|
||||
2. **Prefix Matching**: The tool uses prefix matching. For example, if you
|
||||
2. **Prefix matching**: The tool uses prefix matching. For example, if you
|
||||
allow `git`, you can run `git status` or `git log`.
|
||||
3. **Blocklist Precedence**: The `tools.exclude` list is always checked first.
|
||||
3. **Blocklist precedence**: The `tools.exclude` list is always checked first.
|
||||
If a command matches a blocked prefix, it will be denied, even if it also
|
||||
matches an allowed prefix in `tools.core`.
|
||||
|
||||
### Command Restriction Examples
|
||||
### Command restriction examples
|
||||
|
||||
**Allow only specific command prefixes**
|
||||
|
||||
@@ -251,7 +251,7 @@ To block all shell commands, add the `run_shell_command` wildcard to
|
||||
- `ls -l`: Blocked
|
||||
- `any other command`: Blocked
|
||||
|
||||
## Security Note for `excludeTools`
|
||||
## Security note for `excludeTools`
|
||||
|
||||
Command-specific restrictions in `excludeTools` for `run_shell_command` are
|
||||
based on simple string matching and can be easily bypassed. This feature is
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# Todo Tool (`write_todos`)
|
||||
# Todo tool (`write_todos`)
|
||||
|
||||
This document describes the `write_todos` tool for the Gemini CLI.
|
||||
|
||||
@@ -24,11 +24,11 @@ alignment where the agent is less likely to lose track of its current goal.
|
||||
The agent uses this tool to break down complex multi-step requests into a clear
|
||||
plan.
|
||||
|
||||
- **Progress Tracking:** The agent updates this list as it works, marking tasks
|
||||
- **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,
|
||||
- **Single socus:** 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
|
||||
- **Dynamic updates:** The plan may evolve as the agent discovers new
|
||||
information, leading to new tasks being added or unnecessary ones being
|
||||
cancelled.
|
||||
|
||||
@@ -53,5 +53,5 @@ write_todos({
|
||||
- **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,
|
||||
- **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.
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# Web Fetch Tool (`web_fetch`)
|
||||
# Web fetch tool (`web_fetch`)
|
||||
|
||||
This document describes the `web_fetch` tool for the Gemini CLI.
|
||||
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# Web Search Tool (`google_web_search`)
|
||||
# Web search tool (`google_web_search`)
|
||||
|
||||
This document describes the `google_web_search` tool.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user