MediaMetz/gemini-cli
1
0
Fork 0
mirror of https://github.com/google-gemini/gemini-cli.git synced 2026-04-18 09:11:55 -07:00
Code Issues Packages Projects Releases Wiki Activity

Automated documentation audit results (#22755)

Browse Source
This commit is contained in:
Sam Roberts
2026-04-09 19:07:00 -07:00
committed by GitHub
parent 69bf2d75ef
commit e09410b6e5
55 changed files with 404 additions and 382 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -15,7 +15,7 @@ confirmation.
Each question object has the following properties:
- `question` (string, required): The complete question text.
- `header` (string, required): A short label (max 16 chars) displayed as a
chip/tag (e.g., "Auth", "Database").
chip/tag (for example, "Auth", "Database").
- `type` (string, optional): The type of question. Defaults to `'choice'`.
- `'choice'`: Multiple-choice with options (supports multi-select).
- `'text'`: Free-form text input.
@@ -35,7 +35,7 @@ confirmation.
- Returns the user's answers to the model.
- **Output (`llmContent`):** A JSON string containing the user's answers,
indexed by question position (e.g.,
indexed by question position (for example,
`{"answers":{"0": "Option A", "1": "Some text"}}`).
- **Confirmation:** Yes. The tool inherently involves user interaction.
@@ -75,7 +75,7 @@ confirmation.
"header": "Project Name",
"question": "What is the name of your new project?",
"type": "text",
"placeholder": "e.g., my-awesome-app"
"placeholder": "for example, my-awesome-app"
}
]
}

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

@@ -1,7 +1,7 @@
# File system tools reference
The Gemini CLI core provides a suite of tools for interacting with the local
file system. These tools allow the model to explore and modify your codebase.
Gemini CLI core provides a suite of tools for interacting with the local file
system. These tools allow the model to explore and modify your codebase.
## Technical reference
@@ -49,8 +49,8 @@ Finds files matching specific glob patterns across the workspace.
- **Display name:** FindFiles
- **File:** `glob.ts`
- **Parameters:**
- `pattern` (string, required): The glob pattern to match against (e.g.,
`"*.py"`, `"src/**/*.js"`).
- `pattern` (string, required): The glob pattern to match against (for
example, `"*.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
@@ -78,18 +78,18 @@ lines containing matches, along with their file paths and line numbers.
- **File:** `grep.ts`
- **Parameters:**
- `pattern` (string, required): The regular expression (regex) to search for
(e.g., `"function\s+myFunction"`).
(for example, `"function\s+myFunction"`).
- `path` (string, optional): The absolute path to the directory to search
within. Defaults to the current working directory.
- `include` (string, optional): A glob pattern to filter which files are
searched (e.g., `"*.js"`, `"src/**/*.{ts,tsx}"`). If omitted, searches most
files (respecting common ignores).
searched (for example, `"*.js"`, `"src/**/*.{ts,tsx}"`). If omitted,
searches most files (respecting common ignores).
- **Behavior:**
- Uses `git grep` if available in a Git repository for speed; otherwise, falls
back to system `grep` or a JavaScript-based search.
- Returns a list of matching lines, each prefixed with its file path (relative
to the search directory) and line number.
- **Output (`llmContent`):** A formatted string of matches, e.g.:
- **Output (`llmContent`):** A formatted string of matches, for example:
```
Found 3 matches for pattern "myFunction" in path "." (filter: "*.ts"):
---

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

@@ -1,7 +1,7 @@
# MCP servers with the Gemini CLI
# MCP servers with Gemini CLI
This document provides a guide to configuring and using Model Context Protocol
(MCP) servers with the Gemini CLI.
(MCP) servers with Gemini CLI.
## What is an MCP server?
@@ -10,7 +10,7 @@ CLI through the Model Context Protocol, allowing it to interact with external
systems and data sources. MCP servers act as a bridge between the Gemini model
and your local environment or other services like APIs.
An MCP server enables the Gemini CLI to:
An MCP server enables Gemini CLI to:
- **Discover tools:** List available tools, their descriptions, and parameters
through standardized schema definitions.
@@ -19,13 +19,13 @@ An MCP server enables the Gemini CLI to:
- **Access resources:** Read data from specific resources that the server
exposes (files, API payloads, reports, etc.).
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.
With an MCP server, you can extend 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
The Gemini CLI integrates with MCP servers through a sophisticated discovery and
Gemini CLI integrates with MCP servers through a sophisticated discovery and
execution system built into the core package (`packages/core/src/tools/`):
### Discovery Layer (`mcp-client.ts`)
@@ -54,7 +54,7 @@ Each discovered MCP tool is wrapped in a `DiscoveredMCPTool` instance that:
### Transport mechanisms
The Gemini CLI supports three MCP transport types:
Gemini CLI supports three MCP transport types:
- **Stdio Transport:** Spawns a subprocess and communicates via stdin/stdout
- **SSE Transport:** Connects to Server-Sent Events endpoints
@@ -88,9 +88,9 @@ in the conversation.
## How to set up your MCP server
The Gemini CLI uses the `mcpServers` configuration in your `settings.json` file
to locate and connect to MCP servers. This configuration supports multiple
servers with different transport mechanisms.
Gemini CLI uses the `mcpServers` configuration in your `settings.json` file to
locate and connect to MCP servers. This configuration supports multiple servers
with different transport mechanisms.
### Configure the MCP server in settings.json
@@ -155,7 +155,8 @@ Each server configuration supports the following properties:
#### Required (one of the following)
- **`command`** (string): Path to the executable for Stdio transport
- **`url`** (string): SSE endpoint URL (e.g., `"http://localhost:8080/sse"`)
- **`url`** (string): SSE endpoint URL (for example,
`"http://localhost:8080/sse"`)
- **`httpUrl`** (string): HTTP streaming endpoint URL
#### Optional
@@ -188,7 +189,7 @@ Each server configuration supports the following properties:
### Environment variable expansion
Gemini CLI automatically expands environment variables in the `env` block of
your MCP server configuration. This allows you to securely reference variables
your MCP server configuration. This lets you securely reference variables
defined in your shell or environment without hardcoding sensitive information
directly in your `settings.json` file.
@@ -241,13 +242,14 @@ specific data with that server.
<!-- prettier-ignore -->
> [!NOTE]
> Even when explicitly defined, you should avoid hardcoding secrets.
> Instead, use environment variable expansion (e.g., `"MY_KEY": "$MY_KEY"`) to
> securely pull the value from your host environment at runtime.
> Instead, use environment variable expansion
> (for example, `"MY_KEY": "$MY_KEY"`) to securely pull the value from your host
> environment at runtime.
### 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
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
@@ -403,7 +405,7 @@ then be used to authenticate with the MCP server.
5. **Grant all users and groups** who will access the MCP Server the necessary
permissions to
[impersonate the service account](https://cloud.google.com/docs/authentication/use-service-account-impersonation)
(i.e., `roles/iam.serviceAccountTokenCreator`).
(for example, `roles/iam.serviceAccountTokenCreator`).
6. **[Enable](https://console.cloud.google.com/apis/library/iamcredentials.googleapis.com)
the IAM Credentials API** for your project.
@@ -532,8 +534,8 @@ then be used to authenticate with the MCP server.
## Discovery process deep dive
When the Gemini CLI starts, it performs MCP server discovery through the
following detailed process:
When Gemini CLI starts, it performs MCP server discovery through the following
detailed process:
### 1. Server iteration and connection
@@ -583,7 +585,7 @@ every discovered MCP tool is assigned a strict namespace.
<!-- prettier-ignore -->
> [!WARNING]
> Do not use underscores (`_`) in your MCP server names (e.g., use
> Do not use underscores (`_`) in your MCP server names (for example, use
> `my-server` rather than `my_server`). The policy parser splits Fully Qualified
> Names (`mcp_server_tool`) on the _first_ underscore following the `mcp_`
> prefix. If your server name contains an underscore, the parser will
@@ -888,7 +890,7 @@ use.
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
single tool response. This allows you to build powerful tools that can provide
single tool response. This lets you build powerful tools that can provide
diverse information to the model in a single turn.
All data returned from the tool is processed and sent to the model as context
@@ -901,8 +903,8 @@ To return rich content, your tool's response must adhere to the MCP
specification for a
[`CallToolResult`](https://modelcontextprotocol.io/specification/2025-06-18/server/tools#tool-result).
The `content` field of the result should be an array of `ContentBlock` objects.
The Gemini CLI will correctly process this array, separating text from binary
data and packaging it for the model.
Gemini CLI will correctly process this array, separating text from binary data
and packaging it for the model.
You can mix and match different content block types in the `content` array. The
supported block types include:
@@ -938,7 +940,7 @@ text description and an image:
}
```
When the Gemini CLI receives this response, it will:
When Gemini CLI receives this response, it will:
1. Extract all the text and combine it into a single `functionResponse` part
for the model.
@@ -952,8 +954,8 @@ context to the Gemini model.
## 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.
executed as slash commands within Gemini CLI. This lets you create shortcuts for
common or complex queries that can be easily invoked by name.
### Defining prompts on the server
@@ -1021,8 +1023,8 @@ or, using positional arguments:
/poem-writer "Gemini CLI" reverent
```
When you run this command, the Gemini CLI executes the `prompts/get` method on
the MCP server with the provided arguments. The server is responsible for
When you run this command, Gemini CLI executes the `prompts/get` method on the
MCP server with the provided arguments. The server is responsible for
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.
@@ -1030,10 +1032,10 @@ provides a convenient way to automate and share common workflows.
## 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
manage your server configurations programmatically. These commands streamline
the process of adding, listing, and removing MCP servers without needing to
directly edit JSON files.
`settings.json` file, Gemini CLI provides a convenient set of commands to 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`)
@@ -1056,9 +1058,9 @@ gemini mcp add [options] <name> <commandOrUrl> [args...]
- `-s, --scope`: Configuration scope (user or project). [default: "project"]
- `-t, --transport`: Transport type (stdio, sse, http). [default: "stdio"]
- `-e, --env`: Set environment variables (e.g. -e KEY=value).
- `-H, --header`: Set HTTP headers for SSE and HTTP transports (e.g. -H
"X-Api-Key: abc123" -H "Authorization: Bearer abc123").
- `-e, --env`: Set environment variables (for example, `-e KEY=value`).
- `-H, --header`: Set HTTP headers for SSE and HTTP transports (for example,
`-H "X-Api-Key: abc123" -H "Authorization: Bearer abc123"`).
- `--timeout`: Set connection timeout in milliseconds.
- `--trust`: Trust the server (bypass all tool call confirmation prompts).
- `--description`: Set the description for the server.

10
docs/tools/shell.md
View File

@@ -32,7 +32,7 @@ The tool returns a JSON object containing:
## Configuration
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.
`settings.json` file or by using the `/settings` command in Gemini CLI.
### Enabling interactive commands
@@ -93,9 +93,9 @@ applies when `tools.shell.enableInteractiveShell` is enabled.
## 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
user input, such as text editors (`vim`, `nano`), terminal-based UIs (`htop`),
and interactive version control operations (`git rebase -i`).
pseudo-terminal (pty). This lets you run commands that require real-time user
input, such as text editors (`vim`, `nano`), terminal-based UIs (`htop`), and
interactive version control operations (`git rebase -i`).
When an interactive command is running, you can send input to it from the Gemini
CLI. To focus on the interactive shell, press `Tab`. The terminal output,
@@ -116,7 +116,7 @@ including complex TUIs, will be rendered correctly.
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.
tools to detect if they are being run from within Gemini CLI.
## Command restrictions