gemini-cli/docs/tools/shell.md

Shell Tool (run_shell_command)

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. On Windows, the command will be executed with cmd.exe /c. On other platforms, the command will be 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.

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:

• Command: The command that was executed.
• Directory: The directory where the command was run.
• Stdout: Output from the standard output stream.
• Stderr: Output from the standard error stream.
• Error: Any error message reported by the subprocess.
• Exit Code: The exit code of the command.
• Signal: The signal number if the command was terminated by a signal.
• Background PIDs: A list of PIDs for any background processes started.

Usage:

run_shell_command(command="Your commands.", description="Your description of the command.", directory="Your execution directory.")

run_shell_command examples

List files in the current directory:

run_shell_command(command="ls -la")

Run a script in a specific directory:

run_shell_command(command="./my_script.sh", directory="scripts", description="Run my custom script")

Start a background server:

run_shell_command(command="npm run dev &", description="Start development server in background")

Important notes

• 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.