clone/gemini-cli
1
0
Fork 0
mirror of https://github.com/google-gemini/gemini-cli.git synced 2026-02-01 22:48:03 +00:00
Code Issues Packages Projects Releases Wiki Activity

cleanup(markdown): Prettier format all markdown @ 80 char width (#10714)

Browse Source
This commit is contained in:
Richie Foreman
2025-10-09 08:17:37 -04:00
committed by GitHub
parent 0cd490a9b8
commit a08938010c
60 changed files with 4796 additions and 1733 deletions
Download Patch File Download Diff File Expand all files Collapse all files

101
docs/tools/shell.md
View File

@@ -4,21 +4,31 @@ This document describes the `run_shell_command` tool for the Gemini CLI.
## Description
Use `run_shell_command` to interact with the underlying system, run scripts, or perform command-line operations. `run_shell_command` executes a given shell command, including interactive commands that require user input (e.g., `vim`, `git rebase -i`) if the `tools.shell.enableInteractiveShell` setting is set to `true`.
Use `run_shell_command` to interact with the underlying system, run scripts, or
perform command-line operations. `run_shell_command` executes a given shell
command, including interactive commands that require user input (e.g., `vim`,
`git rebase -i`) if the `tools.shell.enableInteractiveShell` setting is set to
`true`.
On Windows, commands are executed with `cmd.exe /c`. On other platforms, they are executed with `bash -c`.
On Windows, commands are executed with `cmd.exe /c`. On other platforms, they
are executed with `bash -c`.
### Arguments
`run_shell_command` takes the following arguments:
- `command` (string, required): The exact shell command to execute.
- `description` (string, optional): A brief description of the command's purpose, which will be shown to the user.
- `directory` (string, optional): The directory (relative to the project root) in which to execute the command. If not provided, the command runs in the project root.
- `description` (string, optional): A brief description of the command's
purpose, which will be shown to the user.
- `directory` (string, optional): The directory (relative to the project root)
in which to execute the command. If not provided, the command runs in the
project root.
## How to use `run_shell_command` with the Gemini CLI
When using `run_shell_command`, the command is executed as a subprocess. `run_shell_command` can start background processes using `&`. The tool returns detailed information about the execution, including:
When using `run_shell_command`, the command is executed as a subprocess.
`run_shell_command` can start background processes using `&`. The tool returns
detailed information about the execution, including:
- `Command`: The command that was executed.
- `Directory`: The directory where the command was run.
@@ -57,11 +67,16 @@ run_shell_command(command="npm run dev &", description="Start development server
## 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.
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
To enable interactive commands, you need to set the `tools.shell.enableInteractiveShell` setting to `true`. This will use `node-pty` for shell command execution, which allows for interactive sessions. If `node-pty` is not available, it will fall back to the `child_process` implementation, which does not support interactive commands.
To enable interactive commands, you need to set the
`tools.shell.enableInteractiveShell` setting to `true`. This will use `node-pty`
for shell command execution, which allows for interactive sessions. If
`node-pty` is not available, it will fall back to the `child_process`
implementation, which does not support interactive commands.
**Example `settings.json`:**
@@ -77,7 +92,9 @@ To enable interactive commands, you need to set the `tools.shell.enableInteracti
### 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 `tools.shell.enableInteractiveShell` is enabled.**
To show color in the shell output, you need to set the `tools.shell.showColor`
setting to `true`. **Note: This setting only applies when
`tools.shell.enableInteractiveShell` is enabled.**
**Example `settings.json`:**
@@ -93,7 +110,9 @@ To show color in the shell output, you need to set the `tools.shell.showColor` s
### 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 only applies when `tools.shell.enableInteractiveShell` is enabled.**
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
only applies when `tools.shell.enableInteractiveShell` is enabled.**
**Example `settings.json`:**
@@ -109,32 +128,59 @@ You can set a custom pager for the shell output by setting the `tools.shell.page
## 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`).
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`).
When an interactive command is running, you can send input to it from the Gemini CLI. To focus on the interactive shell, press `ctrl+f`. The terminal output, including complex TUIs, will be rendered correctly.
When an interactive command is running, you can send input to it from the Gemini
CLI. To focus on the interactive shell, press `ctrl+f`. The terminal output,
including complex TUIs, will be rendered correctly.
## Important notes
- **Security:** Be cautious when executing commands, especially those constructed from user input, to prevent security vulnerabilities.
- **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.
- **Security:** Be cautious when executing commands, especially those
constructed from user input, to prevent security vulnerabilities.
- **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.
## 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.
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
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 configuration file.
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
configuration file.
- `tools.core`: To restrict `run_shell_command` to a specific set of commands, add entries to the `core` list under the `tools` category in the format `run_shell_command(<command>)`. For example, `"tools": {"core": ["run_shell_command(git)"]}` will only allow `git` commands. Including the generic `run_shell_command` acts as a wildcard, allowing any command not explicitly blocked.
- `tools.exclude`: To block specific commands, add entries to the `exclude` list under the `tools` category in the format `run_shell_command(<command>)`. For example, `"tools": {"exclude": ["run_shell_command(rm)"]}` will block `rm` commands.
- `tools.core`: To restrict `run_shell_command` to a specific set of commands,
add entries to the `core` list under the `tools` category in the format
`run_shell_command(<command>)`. For example,
`"tools": {"core": ["run_shell_command(git)"]}` will only allow `git`
commands. Including the generic `run_shell_command` acts as a wildcard,
allowing any command not explicitly blocked.
- `tools.exclude`: To block specific commands, add entries to the `exclude` list
under the `tools` category in the format `run_shell_command(<command>)`. For
example, `"tools": {"exclude": ["run_shell_command(rm)"]}` will block `rm`
commands.
The validation logic is designed to be secure and flexible:
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 allow `git`, you can run `git status` or `git log`.
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`.
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
allow `git`, you can run `git status` or `git log`.
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
@@ -173,7 +219,8 @@ To block `rm` and allow all other commands:
**Blocklist takes precedence**
If a command prefix is in both `tools.core` and `tools.exclude`, it will be blocked.
If a command prefix is in both `tools.core` and `tools.exclude`, it will be
blocked.
```json
{
@@ -189,7 +236,8 @@ If a command prefix is in both `tools.core` and `tools.exclude`, it will be bloc
**Block all shell commands**
To block all shell commands, add the `run_shell_command` wildcard to `tools.exclude`:
To block all shell commands, add the `run_shell_command` wildcard to
`tools.exclude`:
```json
{
@@ -204,5 +252,8 @@ To block all shell commands, add the `run_shell_command` wildcard to `tools.excl
## 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 **not a security mechanism** and should not be relied upon to safely execute untrusted code. It is recommended to use `coreTools` to explicitly select commands
that can be executed.
Command-specific restrictions in `excludeTools` for `run_shell_command` are
based on simple string matching and can be easily bypassed. This feature is
**not a security mechanism** and should not be relied upon to safely execute
untrusted code. It is recommended to use `coreTools` to explicitly select
commands that can be executed.