jcarr
/
gemini-cli
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Docs: Add initial project documentation structure and content (#368) 

Co-authored-by: Taylor Mullen <ntaylormullen@google.com>
This commit is contained in:
cperry-goog 2025-05-15 20:04:33 -07:00 committed by GitHub
parent 3674fb0c7e
commit 58ef39e2a9
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
16 changed files with 1151 additions and 25 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

114
CONTRIBUTING.md
View File

@ -23,7 +23,7 @@ sign a new one.
This project follows [Google's Open Source Community
Guidelines](https://opensource.google/conduct/).
## Contribution process
## Contribution Process
### Code Reviews
@ -31,29 +31,97 @@ All submissions, including submissions by project members, require review. We
use [GitHub pull requests](https://docs.github.com/articles/about-pull-requests)
for this purpose.
### gemini-cli alias
## Development Setup and Workflow
During development phase, you can use the following to create an alias for
the command line tool:
This section guides contributors on how to build, modify, and understand the development setup of this project.
### Setting Up the Development Environment
- **Prerequisites:**
- Node.js (version 18 or higher).
- npm (usually comes with Node.js).
- Git.
- **Cloning the Repository:**
```bash
git clone https://github.com/google-gemini/gemini-cli.git # Or your fork's URL
cd gemini-cli
```
- **Installing Dependencies:**
```bash
npm install
```
This command will install all necessary dependencies defined in `package.json` for both the server and CLI packages, as well as root dependencies.
### Build Process
To build the entire project (all packages):
```bash
$ npm run build
$ alias gemini-code="node /path/to/gemini-cli/packages/cli/dist/index.js"
$ gemini
██████╗ ███████╗███╗ ███╗██╗███╗ ██╗██╗
██╔════╝ ██╔════╝████╗ ████║██║████╗ ██║██║
██║ ███╗█████╗ ██╔████╔██║██║██╔██╗ ██║██║
██║ ██║██╔══╝ ██║╚██╔╝██║██║██║╚██╗██║██║
╚██████╔╝███████╗██║ ╚═╝ ██║██║██║ ╚████║██║
╚═════╝ ╚══════╝╚═╝ ╚═╝╚═╝╚═╝ ╚═══╝╚═╝
Tips for getting started:
1. /help for more information.
2. Ask coding questions, edit code or run commands.
3. Be specific for the best results.
cwd: /Users/jbd/gemini-cli
╭────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ > Enter your message or use tools... │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
npm run build
```
This command typically compiles TypeScript to JavaScript, bundles assets, and prepares the packages for execution. Refer to `scripts/build.sh` and `package.json` scripts for more details on what happens during the build.
### Running Tests
To execute the test suite for the project:
```bash
npm run test
```
This will run tests located in the `packages/server` and `packages/cli` directories. Ensure tests pass before submitting any changes.
### Linting and Preflight Checks
To ensure code quality, formatting consistency, and run final checks before committing:
```bash
npm run preflight
```
This command usually runs ESLint, Prettier, and potentially other checks as defined in the project's `package.json`.
### Coding Conventions
- Please adhere to the coding style, patterns, and conventions used throughout the existing codebase.
- Consult [GEMINI.md](https://github.com/google-gemini/gemini-cli/blob/main/GEMINI.md) (typically found in the project root) for specific instructions related to AI-assisted development, including conventions for React, comments, and Git usage.
- **Imports:** Pay special attention to import paths. The project uses `eslint-rules/no-relative-cross-package-imports.js` to enforce restrictions on relative imports between packages.
### Project Structure
- `packages/`: Contains the individual sub-packages of the project.
- `cli/`: The command-line interface.
- `server/`: The backend server that the CLI interacts with.
- `docs/`: Contains all project documentation.
- `scripts/`: Utility scripts for building, testing, and development tasks.
For more detailed architecture, see `docs/architecture.md`.
### Development Tip: `gemini-cli` Alias
During the development phase, you can use the following to create an alias for the command-line tool after building it:
```bash
# Example:
# npm run build # (if not already done)
# alias gemini-cli="node $(pwd)/packages/cli/dist/index.js"
# gemini-cli
#
# ██████╗ ███████╗███╗ ███╗██╗███╗ ██╗██╗
# ██╔════╝ ██╔════╝████╗ ████║██║████╗ ██║██║
# ██║ ███╗█████╗ ██╔████╔██║██║██╔██╗ ██║██║
# ██║ ██║██╔══╝ ██║╚██╔╝██║██║██║╚██╗██║██║
# ╚███████╝███████╗██║ ╚═╝ ██║██║██║ ╚████║██║
# ╚═════╝ ╚══════╝╚═╝ ╚═╝╚═╝╚═╝ ╚═══╝╚═╝
#
# Tips for getting started:
# 1. /help for more information.
# 2. Ask coding questions, edit code or run commands.
# 3. Be specific for the best results.
#
# cwd: /path/to/gemini-cli
# ╭────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
# │ > Enter your message or use tools... │
# ╰───────────────────────────────────────────────────────────────────────────────────────────<E29480><E29480><EFBFBD>────────────────────────╯
```

80
README.md
View File

@ -4,6 +4,8 @@
This repository contains the Gemini CLI tool.
For more comprehensive documentation, please see the [full documentation here](./docs/index.md).
## Setup
1. **Get a Gemini API Key:** Obtain your API key from Google AI Studio: [https://aistudio.google.com/app/apikey](https://aistudio.google.com/app/apikey)
@ -17,8 +19,10 @@ This repository contains the Gemini CLI tool.
source ~/.bashrc # Reload the config
```
Replace `"YOUR_API_KEY"` with your actual key.
3. **Install the Gemini CLI:**
_(Instructions for installing the CLI will be added here once packaging is finalized. For now, if you have access to the source code, you can run it directly after building the project as described below.)_
## Building
## Building (for contributors)
As with most Node projects, major development scripts can be found in the `package.json`. See that for the full list of commands.
@ -37,14 +41,86 @@ This command installs dependencies and builds the entire project, including the
## Running
To start the Gemini CLI, run the following command from the root directory:
To start the Gemini CLI from the source code (after building), run the following command from the root directory:
```bash
npm start
```
If you have installed the CLI globally, you can typically run it with:
```bash
gemini # Or the command name used during installation
```
This command starts the Gemini CLI.
## Quick Start: Your First Interaction
Once the CLI is running, you can start interacting with Gemini. Try a simple query:
```
> How can I build a web app?
```
Or ask it to perform a task using its tools:
```
> List files in the current directory.
```
## Next Steps
Congratulations! You've successfully set up and run the Gemini CLI.
- Explore the **[CLI Commands](./docs/cli/commands.md)** to learn about all available functionalities.
- If you encounter any issues, check the **[Troubleshooting Guide](./docs/troubleshooting.md)**.
## Theming
The Gemini CLI supports theming to customize its color scheme and appearance. Themes define colors for text, backgrounds, syntax highlighting, and other UI elements.
### Available Themes
The CLI comes with a selection of pre-defined themes. As seen in `theme-manager.ts`, these typically include:
- **Dark Themes:**
- `AtomOneDark`
- `Dracula`
- `VS2015` (Default)
- `GitHub` (Dark variant usually)
- **Light Themes:**
- `VS` (Visual Studio Light)
- `GoogleCode`
- `XCode` (Light variant usually)
- **ANSI:**
- `ANSI`: A theme that primarily uses the terminal's native ANSI color capabilities.
_(The exact list and their appearance can be confirmed by running the `/theme` command within the CLI.)_
### Changing Themes
1. Type the `/theme` command in the CLI.
2. A dialog or selection prompt (`ThemeDialog.tsx`) will appear, listing the available themes.
3. You can typically navigate (e.g., with arrow keys) and select a theme. Some interfaces might offer a live preview or highlight as you select.
4. Confirm your selection (often with Enter) to apply the theme. You can usually cancel out of the selection (e.g., with Escape).
### Theme Persistence
Selected themes are usually saved in the CLI's configuration (see [CLI Configuration](./docs/cli/configuration.md)) so your preference is remembered across sessions.
### Theme Not Found Handling
If a theme specified in your configuration is not found (e.g., due to a typo or removal), the CLI will typically revert to a default theme and may display a notification, ensuring the interface remains usable.
### Theme Structure (`theme.ts`)
Each theme is defined by a structure (likely an object or class) that specifies various color properties for different UI components, such as:
- General text and background colors.
- Colors for different message types (user, Gemini, tool, error).
- Syntax highlighting colors for various code token types (keywords, strings, comments, etc.), often based on common token categories found in code editors.
## Debugging
To debug the CLI application using VS Code:

76
docs/architecture.md Normal file
View File

@ -0,0 +1,76 @@
# Gemini CLI Architecture Overview
This document provides a high-level overview of the Gemini CLI's architecture. Understanding the main components and their interactions can be helpful for both users and developers.
## Core Components
The Gemini CLI is primarily composed of two main packages, along with a suite of tools that the system utilizes:
1. **CLI Package (`packages/cli`):**
- **Purpose:** This is the user-facing component. It provides the interactive command-line interface (REPL), handles user input, displays output from Gemini, and manages the overall user experience.
- **Key Features:**
- Input processing (parsing commands, text prompts).
- History management.
- Display rendering (including Markdown, code highlighting, and tool messages).
- Theme and UI customization.
- Communication with the Server package.
- Manages user configuration settings specific to the CLI.
2. **Server Package (`packages/server`):**
- **Purpose:** This acts as the backend for the CLI. It receives requests from the CLI, orchestrates interactions with the Gemini API, and manages the execution of available tools.
- **Key Features:**
- API client for communicating with the Google Gemini API.
- Prompt construction and management.
- Tool registration and execution logic.
- State management for conversations or sessions.
- Manages server-side configuration.
3. **Tools (`packages/server/src/tools/`):**
- **Purpose:** These are individual modules that extend the capabilities of the Gemini model, allowing it to interact with the local environment (e.g., file system, shell commands, web fetching).
- **Interaction:** The Server package invokes these tools based on requests from the Gemini model. The CLI then displays the results of tool execution.
## Interaction Flow
A typical interaction with the Gemini CLI follows this general flow:
1. **User Input:** The user types a prompt or command into the CLI (`packages/cli`).
2. **Request to Server:** The CLI package sends the user's input to the Server package (`packages/server`).
3. **Server Processes Request:** The Server package:
- Constructs an appropriate prompt for the Gemini API, possibly including conversation history and available tool definitions.
- Sends the prompt to the Gemini API.
4. **Gemini API Response:** The Gemini API processes the prompt and returns a response. This response might be a direct answer or a request to use one of the available tools.
5. **Tool Execution (if applicable):**
- If the Gemini API requests a tool, the Server package prepares to execute it.
- **User Confirmation for Potentially Impactful Tools:** If the requested tool can modify the file system (e.g., file edits, writes) or execute shell commands, the CLI (`packages/cli`) displays a confirmation prompt to the user. This prompt details the tool and its arguments, and the user must approve the execution. Read-only operations (e.g., reading files, listing directories) may not always require this explicit confirmation step.
- If confirmed (or if confirmation is not required for the specific tool), the Server package identifies and executes the relevant tool (e.g., `read_file`, `execute_bash_command`).
- The tool performs its action (e.g., reads a file from the disk).
- The result of the tool execution is sent back to the Gemini API by the Server.
- The Gemini API processes the tool result and generates a final response.
6. **Response to CLI:** The Server package sends the final response (or intermediate tool messages) back to the CLI package.
7. **Display to User:** The CLI package formats and displays the response to the user in the terminal.
## Diagram (Conceptual)
```mermaid
graph TD
User[User via Terminal] -- Input --> CLI[packages/cli]
CLI -- Request --> Server[packages/server]
Server -- Prompt/Tool Info --> GeminiAPI[Gemini API]
GeminiAPI -- Response/Tool Call --> Server
Server -- Tool Details --> CLI
CLI -- User Confirms --> Server
Server -- Execute Tool --> Tools[Tools e.g., read_file, shell]
Tools -- Tool Result --> Server
Server -- Final Response --> CLI
CLI -- Output --> User
```
## Key Design Principles
- **Modularity:** Separating the CLI (frontend) from the Server (backend) allows for independent development and potential future extensions (e.g., different frontends for the same server).
- **Extensibility:** The tool system is designed to be extensible, allowing new capabilities to be added.
- **User Experience:** The CLI focuses on providing a rich and interactive terminal experience.
This overview should provide a foundational understanding of the Gemini CLI's architecture. For more detailed information, refer to the specific documentation for each package and the development guides.

80
docs/cli/commands.md Normal file
View File

@ -0,0 +1,80 @@
# CLI Commands
The Gemini CLI supports several built-in commands to help you manage your session, customize the interface, and control its behavior. These commands are typically prefixed with a forward slash (`/`), an at symbol (`@`), or an exclamation mark (`!`).
## Slash Commands (`/`)
Slash commands provide meta-level control over the CLI itself. They can typically be executed by typing the command and pressing `Enter`.
- **`/help`** (or **`/?`**)
- **Description:** Displays help information about the Gemini CLI, including available commands and their usage.
- **Action:** Opens a help dialog or section within the CLI.
- **`/clear`** (Shortcut: **Ctrl+L**)
- **Description:** Clears the entire terminal screen, including the visible session history and scrollback within the CLI.
- **Action:** Wipes the terminal display. The underlying session data (for history recall) might be preserved depending on the exact implementation, but the visual display is cleared.
- **`/theme`**
- **Description:** Allows you to change the visual theme of the Gemini CLI.
- **Action:** Opens a dialog or prompt to select from available themes.
- **`/refreshmemory`**
- **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.
- **`/quit`** (or **`/exit`**)
- **Description:** Exits the Gemini CLI application.
- **Action:** Terminates the CLI process.
## At Commands (`@`)
At commands are used to quickly include the content of files or directories as part of your prompt to Gemini.
- **`@<path_to_file_or_directory>`**
- **Description:** Injects the content of the specified file or files within a directory into your current prompt. This is useful for asking questions about specific code, text, or collections of files.
- **Usage:**
- `@path/to/your/file.txt Explain this text.`
- `@src/my_project/ Summarize the code in this directory.`
- `What is this file about? @README.md`
- **Details:**
- If a path to a single file is provided, the content of that file is read.
- If a path to a directory is provided, the command attempts to read the content of files within that directory (often recursively, like `directory/**`).
- Spaces in paths should be escaped with a backslash (e.g., `@My\ Documents/file.txt`).
- The command uses the `read_many_files` tool internally. The content is fetched and then prepended or inserted into your query before being sent to the Gemini model.
- The text before and after the `@<path>` part of your query is preserved and sent along with the file content.
- **File Types:** The command is intended for text-based files. While it might attempt to read any file, binary files or very large files might be skipped or truncated by the underlying `read_many_files` tool to ensure performance and relevance. The tool will typically indicate if files were skipped.
- **Output:** The CLI will show a tool call message indicating that `read_many_files` was used, along with an improved display message detailing the status (e.g., number of files read, total size) and the path(s) that were processed.
- **`@` (Lone At Symbol)**
- **Description:** If you type a lone `@` symbol without a path, the entire query (including the `@`) is passed directly to the Gemini model. This might be useful if you are specifically talking _about_ the `@` symbol itself in your prompt.
### Error Handling for `@` Commands
- 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 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.
- **`!<shell_command>`**
- **Description:** Executes the given 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.
These commands provide a powerful way to interact with the Gemini CLI and integrate local file content seamlessly into your conversations with the AI.

179
docs/cli/configuration.md Normal file
View File

@ -0,0 +1,179 @@
# Gemini CLI Configuration
The Gemini CLI offers several ways to configure its behavior, from environment variables and command-line arguments to dedicated settings files. This document outlines the different configuration methods and available settings.
## Configuration Layers
Configuration is typically applied in the following order of precedence (lower numbers are overridden by higher numbers):
1. **Default Values:** Hardcoded defaults within the application.
2. **User Settings File:** Global settings for the current user.
3. **Project Settings File:** Project-specific settings.
4. **Environment Variables:** System-wide or session-specific variables, potentially loaded from `.env` files.
5. **Command-line Arguments:** Values passed when launching the CLI.
## 1. Settings Files (`settings.json`)
The Gemini CLI uses `settings.json` files for persistent configuration. There are two main locations for these files:
- **User Settings:**
- **Location:** `~/.gemini/settings.json` (where `~` is your home directory).
- **Scope:** Applies globally to all Gemini CLI sessions for the current user.
- **Project Settings:**
- **Location:** `.gemini/settings.json` within your project's root directory.
- **Scope:** Applies only when running Gemini CLI from that specific project. Project settings override User settings.
### 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 Seatbelt profiles, e.g., `.gemini/sandbox-macos-custom.sb`), 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.
**Version Control (`.gitignore`):**
- **Generally, it's recommended to add `.gemini/` to your project's `.gitignore` file.**
- **Reasoning:** This directory often contains user-specific preferences (like themes) or local sandbox configurations that might not be relevant or applicable to all collaborators on the project. Keeping it out of version control avoids imposing one user's local setup on others.
- **Exception:** If your team decides that certain project-specific configurations within `.gemini/` (e.g., a carefully crafted `sandbox-macos-custom.sb` profile that _all_ macOS users on the project should use) are essential for consistent project behavior, you might choose to commit specific files within `.gemini/` (e.g., `!.gemini/sandbox-macos-custom.sb`) or the entire directory. However, this should be a deliberate decision by the team.
- User-specific `settings.json` often contains local paths or preferences that should not be committed.
Always consider the nature of the files within `.gemini/` before deciding to include them in version control. For most common use cases, ignoring the entire directory is the safest approach.
### Available Settings in `settings.json`:
- **`theme`** (string):
- Specifies the visual theme for the CLI.
- Example: `"theme": "VS2015"`
- See the [UI Guide](./ui-guide.md#themes) for available theme names.
- **`sandbox`** (boolean or string):
- Controls whether and how to use sandboxing for tool execution.
- `true`: Enable default sandbox (e.g., Docker or Podman if configured, otherwise OS-level like Seatbelt on macOS).
- `false`: Disable sandboxing (less secure).
- `"docker"` or `"podman"`: Explicitly choose container-based sandboxing.
- `<command>`: Specify a custom command for sandboxing.
- Example: `"sandbox": true`
- **`toolDiscoveryCommand`** (string, advanced):
- Custom command for tool discovery (if applicable to your setup).
- **`toolCallCommand`** (string, advanced):
- Custom command for executing tool calls (if applicable to your setup).
- **`mcpServerCommand`** (string, advanced):
- Custom command for the MCP (Multi-Context Prompt) server (if applicable).
### Example `settings.json`:
```json
{
"theme": "VS2015",
"sandbox": "docker",
"toolDiscoveryCommand": "/usr/local/bin/my-custom-tool-discovery --json",
"toolCallCommand": "/usr/local/bin/my-custom-tool-executor",
"mcpServerCommand": "node /opt/mcp-server/dist/server.js --port 8080"
}
```
## 2. Environment Variables & `.env` Files
Environment variables are a common way to configure applications, especially for sensitive information like API keys or for settings that might change between environments.
The CLI automatically loads environment variables from an `.env` file. The loading order is:
1. `.env` file in the current working directory.
2. If not found, it searches upwards in parent directories until it finds an `.env` file or reaches the project root (identified by a `.git` folder) or the home directory.
3. If still not found, it looks for `~/.env` (in the user's home directory).
- **`GEMINI_API_KEY`** (Required):
- Your API key for the Gemini API.
- **Crucial for operation.** The CLI will not function without it.
- Set this in your shell profile (e.g., `~/.bashrc`, `~/.zshrc`) or an `.env` file.
- **`GEMINI_CODE_MODEL`**:
- Specifies the default Gemini model to use.
- Overrides the hardcoded default, which is currently `gemini-2.5-pro-preview-05-06`.
- Example: `export GEMINI_CODE_MODEL="gemini-1.5-flash-latest"`
- **`GEMINI_CODE_SANDBOX`**:
- Alternative to the `sandbox` setting in `settings.json`.
- Accepts `true`, `false`, `docker`, `podman`, or a custom command string.
- **`SEATBELT_PROFILE`** (macOS specific):
- Switches the Seatbelt (`sandbox-exec`) profile on macOS.
- `minimal`: (Default) Restricts writes to the project folder but allows other operations.
- `strict`: Uses a more restrictive profile that declines operations by default.
- `<profile_name>`: Uses a custom profile. To define a custom profile, create a file named `sandbox-macos-<profile_name>.sb` in your project's `.gemini/` directory (e.g., `my-project/.gemini/sandbox-macos-custom.sb`).
- **`DEBUG` or `DEBUG_MODE`** (often used by underlying libraries or the CLI itself):
- Set to `true` or `1` to enable verbose debug logging, which can be helpful for troubleshooting.
## 3. Command-Line Arguments
Arguments passed directly when running the CLI can override other configurations for that specific session.
- **`--model <model_name>`** (or **`-m <model_name>`**):
- Specifies the Gemini model to use for this session.
- Example: `npm start -- --model gemini-1.5-pro-latest`
- **`--sandbox`** (or **`-s`**):
- Enables sandbox mode for this session. The exact behavior might depend on other sandbox configurations (environment variables, settings files).
- **`--debug_mode`** (or **`-d`**):
- Enables debug mode for this session, providing more verbose output.
- **`--question <your_question>`** (or **`-q <your_question>`**):
- Used to pass a question directly to the command, especially when piping input to the CLI.
- **`--all_files`** (or **`-a`**):
- If set, recursively includes all files within the current directory as context for the prompt.
- **`--help`** (or **`-h`**):
- Displays help information about command-line arguments.
## 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.
- **Purpose:** These Markdown files contain instructions, guidelines, or context that you want the Gemini model to be aware of during your interactions.
### Example `GEMINI.md` Content
Here's a conceptual example of what a `GEMINI.md` file at the root of a TypeScript project might contain:
```markdown
# Project: My Awesome TypeScript Library
## General Instructions:
- When generating new TypeScript code, please follow the existing coding style.
- Ensure all new functions and classes have JSDoc comments.
- Prefer functional programming paradigms where appropriate.
- All code should be compatible with TypeScript 5.0 and Node.js 18+.
## Coding Style:
- Use 2 spaces for indentation.
- Interface names should be prefixed with `I` (e.g., `IUserService`).
- Private class members should be prefixed with an underscore (`_`).
- Always use strict equality (`===` and `!==`).
## Specific Component: `src/api/client.ts`
- This file handles all outbound API requests.
- When adding new API call functions, ensure they include robust error handling and logging.
- Use the existing `fetchWithRetry` utility for all GET requests.
## Regarding Dependencies:
- Avoid introducing new external dependencies unless absolutely necessary.
- 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.
- **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`:
1. **Global `GEMINI.md`:**
- Location: `~/.gemini/GEMINI.md` (in your user home directory).
- Scope: Provides default instructions for all your projects.
2. **Project Root & Ancestors `GEMINI.md`:**
- Location: The CLI searches for `GEMINI.md` in the current working directory and then in each parent directory up to either the project root (identified by a `.git` folder) or your home directory.
- Scope: Provides context relevant to the entire project or a significant portion of it.
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.
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.

38
docs/cli/index.md Normal file
View File

@ -0,0 +1,38 @@
# Gemini CLI
Welcome to the documentation for the Gemini CLI. This section provides an overview of the CLI's features, how to interact with it, and how to customize your experience.
## What is the Gemini CLI?
The Gemini CLI (`packages/cli`) is the primary way users interact with the Gemini AI model and its associated tools directly from their terminal. It offers an interactive Read-Eval-Print Loop (REPL) environment where you can send prompts to Gemini, receive responses, and see the results of any tools Gemini uses to fulfill your requests.
## Core Features
- **Interactive Prompt:** A familiar command-line prompt for entering your queries and commands.
- **Rich Output Display:**
- Formatted Markdown rendering for clear and readable text responses.
- Syntax highlighting for code blocks in various languages.
- Clear display of tool calls, inputs, and outputs.
- **Command History:** Easily access and re-run previous commands and prompts.
- **Suggestions:** (If applicable, describe suggestion features)
- **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).
## Basic Interaction
1. **Start the CLI:** Run `npm start` from the project root (or execute the installed CLI command directly). Refer to the main [README.md](../../README.md) for setup and running instructions.
2. **Enter a Prompt:** Type your question or instruction at the `>` prompt and press Enter.
```
> Explain quantum computing in simple terms.
```
3. **View Response:** Gemini's response will be displayed in the terminal. If Gemini needs to use a tool (e.g., to read a file you mentioned), you will see messages indicating the tool usage.
4. **Continue Conversation:** You can continue the conversation by asking follow-up questions or giving new instructions.
## Navigating this Section
- **[Commands](./commands.md):** A detailed reference for all built-in CLI commands (e.g., `/help`, `/history`, `/theme`).
- **[UI Guide](./ui-guide.md):** Learn more about the different parts of the CLI's user interface, including themes and display elements.
- **[Configuration](./configuration.md):** Understand how to configure various aspects of the CLI.
This documentation will help you become proficient in using the Gemini CLI for a wide range of tasks.

33
docs/index.md Normal file
View File

@ -0,0 +1,33 @@
# Welcome to the Gemini CLI Documentation
This documentation provides a comprehensive guide to installing, using, and developing the Gemini CLI tool. Gemini CLI allows you to interact with Gemini models through a powerful and flexible command-line interface.
## Overview
The Gemini CLI is a tool designed to bring the capabilities of Gemini models to your terminal. It consists of a client-side application (`packages/cli`) that communicates with a local server (`packages/server`), which in turn interacts with the Gemini API. The CLI supports a variety of tools for file system operations, code execution, web fetching, and more, enhancing your workflow with AI-powered assistance.
## Navigating the Documentation
This documentation is organized into the following sections:
- **[Getting Started](./getting-started.md):** Learn how to install, configure, and run the Gemini CLI for the first time.
- **[Architecture Overview](./architecture.md):** Understand the high-level design of the Gemini CLI, including its core components and how they interact.
- **CLI Usage:**
- **[CLI Introduction](./cli/index.md):** An overview of the command-line interface.
- **[Commands](./cli/commands.md):** Detailed descriptions of all available CLI commands.
- **[UI Guide](./cli/ui-guide.md):** Information on the terminal UI, themes, and customization.
- **[Configuration](./cli/configuration.md):** How to configure the CLI.
- **Server Details:**
- **[Server Introduction](./server/index.md):** An overview of the server component.
- **[Configuration](./server/configuration.md):** How to configure the server.
- **[Tools API](./server/tools-api.md):** Information on how the server manages and exposes tools.
- **Tools:**
- **[Tools Overview](./tools/index.md):** A general look at the available tools.
- **[File System Tools](./tools/file-system.md):** Documentation for tools like `read_file`, `write_file`, etc.
- **[Shell Tool](./tools/shell.md):** Using the `execute_bash_command` tool.
- **[Web Fetch Tool](./tools/web.md):** Using the `web_fetch` tool.
- **[Multi-File Read Tool](./tools/multi-file.md):** Using the `read_many_files` tool.
- **[Contributing & Development Guide](../CONTRIBUTING.md#development-setup-and-workflow):** Information for contributors and developers, including setup, building, testing, and coding conventions.
- **[Troubleshooting Guide](./troubleshooting.md):** Find solutions to common problems and FAQs.
We hope this documentation helps you make the most of the Gemini CLI!

99
docs/server/configuration.md Normal file
View File

@ -0,0 +1,99 @@
# Gemini CLI Server: Configuration
Configuration for the Gemini CLI server component (`packages/server`) is critical for its operation, dictating how it connects to the Gemini API, which model it uses, how tools are executed, and more. Many of these settings are shared with or derived from the main CLI configuration when the CLI initializes the server backend.
## Primary Configuration Sources
The server's configuration is primarily established when the `Config` object (from `packages/server/src/config/config.ts`) is instantiated. The values come from a combination of:
1. **Hardcoded Defaults:** Fallback values defined within the server and CLI packages.
2. **Settings Files (`settings.json` via CLI):** Persistent settings that the CLI reads (User settings `~/.gemini/settings.json`, then Workspace settings `.gemini/settings.json`) and then passes relevant parts to the server configuration.
3. **Environment Variables (potentially from `.env` files):** System-wide or session-specific variables. The CLI loads `.env` files (checking current directory, then ancestors, then `~/.env`) and these variables influence the server config.
4. **Command-Line Arguments (passed from CLI):** Settings chosen by the user at launch time, which have the highest precedence for many options.
## Key Configuration Parameters for the Server
These are the main pieces of information the server `Config` object holds and uses:
- **`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.
- **`model` (string):**
- **Source:** Command-line argument (`--model`), environment variable (`GEMINI_CODE_MODEL`), or the default value `gemini-2.5-pro-preview-05-06`.
- **Purpose:** Specifies which Gemini model the server should use for generating responses.
- **`sandbox` (boolean | string):**
- **Source:** Command-line argument (`--sandbox`), environment variable (`GEMINI_CODE_SANDBOX`), or `settings.json` (`sandbox` key).
- **Purpose:** Determines if and how tools (especially `execute_bash_command`) are sandboxed. This is crucial for security.
- `true`: Use a default sandboxing method.
- `false`: No sandboxing (less secure).
- `"docker"`, `"podman"`, or a custom command string: Specific sandboxing method.
- **`targetDir` (string):**
- **Source:** Typically `process.cwd()` (the current working directory from which the CLI was launched).
- **Purpose:** Provides a base directory context for tools that operate on the file system (e.g., `read_file`, `list_directory`). Paths used in tool calls are often resolved relative to this directory.
- **`debugMode` (boolean):**
- **Source:** Command-line argument (`--debug_mode`) or environment variables (e.g., `DEBUG=true`, `DEBUG_MODE=true`).
- **Purpose:** Enables verbose logging within the server and its tools, which is helpful for development and troubleshooting.
- **`question` (string | undefined):**
- **Source:** Command-line argument (`--question`), usually when input is piped to the CLI.
- **Purpose:** Allows a direct question to be passed to the server for processing without interactive input.
- **`fullContext` (boolean):**
- **Source:** Command-line argument (`--all_files`).
- **Purpose:** If true, instructs relevant tools (like `read_many_files` when used implicitly by the model) to gather a broad context from the `targetDir`.
- **`toolDiscoveryCommand` (string | undefined):**
- **`toolCallCommand` (string | undefined):**
- **`mcpServerCommand` (string | undefined):**
- **Source:** `settings.json` or environment variables.
- **Purpose:** Advanced settings for customizing how tools are discovered or how the server interacts with other potential components in a more complex setup.
- **`userAgent` (string):**
- **Source:** Automatically generated by the CLI, often including CLI package name, version, and Node.js environment details.
- **Purpose:** Sent with API requests to help identify the client making requests to the Gemini API.
- **`userMemory` (string):**
- **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).
- **`geminiMdFileCount` (number):**
- **Source:** Count of all `GEMINI.md` files successfully loaded by the CLI.
- **Purpose:** Metadata about the loaded instructional context, visible in the CLI footer.
## Environment File (`.env`) Loading
The CLI configuration logic, which precedes server initialization, includes loading an `.env` file. The search order is:
1. `.env` in the current working directory.
2. `.env` in parent directories, up to the project root (containing `.git`) or home directory.
3. `~/.env` (in the user's home directory).
This file is a common place to store the `GEMINI_API_KEY` and other environment-specific settings like `GEMINI_CODE_MODEL` or `DEBUG` flags.
```
# Example .env file
GEMINI_API_KEY="YOUR_ACTUAL_API_KEY_HERE"
GEMINI_CODE_MODEL="gemini-1.5-flash-latest"
# DEBUG=true
```
## Tool Registry Initialization
Upon initialization, the server's `Config` object is also used to create and populate a `ToolRegistry`. This registry is then aware of the `targetDir` and `sandbox` settings, which are vital for the correct and secure operation of tools like `ReadFileTool`, `ShellTool`, etc. The `ToolRegistry` is responsible for making tool schemas available to the Gemini model and for executing tool calls.
Proper server configuration, derived from these various sources, is essential for the Gemini CLI to function correctly, securely, and according to the user's intent.

52
docs/server/index.md Normal file
View File

@ -0,0 +1,52 @@
# Gemini CLI Server
This section delves into the server component of the Gemini CLI (`packages/server`). The server acts as the backend engine, handling communication with the Gemini API, managing tools, and processing requests from the CLI client.
## Role of the Server
The server package is a crucial part of the Gemini CLI ecosystem. While the CLI (`packages/cli`) provides the user interface, the server is responsible for:
- **API Interaction:** Securely communicating with the Google Gemini API, sending user prompts, and receiving model responses.
- **Prompt Engineering:** Constructing effective prompts for the Gemini model, potentially incorporating conversation history, tool definitions, and instructional context from `GEMINI.md` files.
- **Tool Management & Orchestration:**
- Registering available tools (e.g., file system tools, shell command execution).
- Interpreting tool use requests from the Gemini model.
- Executing the requested tools with the provided arguments.
- Returning tool execution results to the Gemini model for further processing.
- **Session and State Management:** Keeping track of the conversation state, including history and any relevant context required for coherent interactions.
- **Configuration:** Managing server-specific configurations, such as API key access, model selection, and tool settings.
## Key Components and Functionality
While the exact implementation details are within the `packages/server/src/` directory, key conceptual components include:
- **API Client (`client.ts`):** A module responsible for making HTTP requests to the Gemini API, handling authentication, and parsing responses.
- **Prompt Management (`prompts.ts`):** Logic for creating and formatting the prompts sent to the Gemini model. This includes integrating user queries, historical context, and tool specifications.
- \*\*Tool Registry and Execution (`tool-registry.ts`, `tools.ts`, individual tool files like `read-file.ts`, `shell.ts`):
- A system for discovering, registering, and describing available tools to the Gemini model.
- Code for executing each tool safely and effectively, often involving interaction with the operating system or external services.
- **Configuration (`config.ts`):** Handles loading and providing access to server-side configurations, including API keys, model choices, and potentially tool-specific settings.
- **Turn Management (`turn.ts`):** Manages the flow of a single conversational turn, from receiving user input to generating a final response, potentially involving multiple tool calls.
## Interaction with the CLI
The CLI and Server typically communicate over a local interface (e.g., standard input/output, or a local network connection if designed for broader use, though the current structure suggests a tightly coupled Node.js application).
1. The CLI captures user input and forwards it to the Server.
2. The Server processes the input, interacts with the Gemini API and tools as needed.
3. The Server sends responses (text, tool calls, errors) back to the CLI.
4. The CLI formats and displays these responses to the user.
## Security Considerations
The server plays a vital role in security:
- **API Key Management:** It handles the `GEMINI_API_KEY` and ensures it is used securely when communicating with the Gemini API.
- **Tool Execution:** When tools interact with the local system (e.g., `execute_bash_command`), the server (and its underlying tool implementations) must do so with appropriate caution, often involving sandboxing mechanisms to prevent unintended side effects.
## Navigating this Section
- **[Server Configuration](./configuration.md):** Details on how to configure the server component, including environment variables and specific settings.
- **[Server Tools API](./tools-api.md):** Information on how tools are defined, registered, and used by the server.
Understanding the server's role and architecture is key to comprehending the full capabilities and operational flow of the Gemini CLI.

72
docs/server/tools-api.md Normal file
View File

@ -0,0 +1,72 @@
# Gemini CLI Server: Tools API
The Gemini CLI server (`packages/server`) features a robust system for defining, registering, and executing tools. These tools extend the capabilities of the Gemini model, allowing it to interact with the local environment, fetch web content, and perform various actions beyond simple text generation.
## Core Concepts
- **Tool (`tools.ts`):** An interface and base class (`BaseTool`) that defines the contract for all tools. Each tool must have:
- `name`: A unique internal name (used in API calls to Gemini).
- `displayName`: A user-friendly name.
- `description`: A clear explanation of what the tool does, which is provided to the Gemini model.
- `parameterSchema`: A JSON schema defining the parameters the tool accepts. This is crucial for the Gemini model to understand how to call the tool correctly.
- `validateToolParams()`: A method to validate incoming parameters.
- `getDescription()`: A method to provide a human-readable description of what the tool will do with specific parameters before execution.
- `shouldConfirmExecute()`: A method to determine if user confirmation is required before execution (e.g., for potentially destructive operations).
- `execute()`: The core method that performs the tool's action and returns a `ToolResult`.
- **`ToolResult` (`tools.ts`):** An interface defining the structure of a tool's execution outcome:
- `llmContent`: The factual string content to be included in the history sent back to the LLM for context.
- `returnDisplay`: A user-friendly string (often Markdown) or a special object (like `FileDiff`) for display in the CLI.
- **Tool Registry (`tool-registry.ts`):** A class (`ToolRegistry`) responsible for:
- **Registering Tools:** Holding a collection of all available built-in tools (e.g., `ReadFileTool`, `ShellTool`).
- **Discovering Tools:** It can also discover tools dynamically:
- **Command-based Discovery:** If `toolDiscoveryCommand` is configured in settings, this command is executed. It's expected to output JSON describing custom tools, which are then registered as `DiscoveredTool` instances.
- **MCP-based Discovery:** If `mcpServerCommand` is configured, the registry can connect to a Model Context Protocol (MCP) server to list and register tools (`DiscoveredMCPTool`).
- **Providing Schemas:** Exposing the `FunctionDeclaration` schemas of all registered tools to the Gemini model, so it knows what tools are available and how to use them.
- **Retrieving Tools:** Allowing the server to get a specific tool by name for execution.
## Built-in Tools
The server comes with a suite of pre-defined tools, typically found in `packages/server/src/tools/`. These include:
- **File System Tools:**
- `LSTool` (`ls.ts`): Lists directory contents.
- `ReadFileTool` (`read-file.ts`): Reads the content of a single file.
- `WriteFileTool` (`write-file.ts`): Writes content to a file.
- `GrepTool` (`grep.ts`): Searches for patterns in files.
- `GlobTool` (`glob.ts`): Finds files matching glob patterns.
- `EditTool` (`edit.ts`): Performs in-place modifications to files (often requiring confirmation).
- `ReadManyFilesTool` (`read-many-files.ts`): Reads and concatenates content from multiple files or glob patterns (used by the `@` command in CLI).
- **Execution Tools:**
- `ShellTool` (`shell.ts`): Executes arbitrary shell commands (requires careful sandboxing and user confirmation).
- **Web Tools:**
- `WebFetchTool` (`web-fetch.ts`): Fetches content from a URL.
Each of these tools extends `BaseTool` and implements the required methods for its specific functionality.
## Tool Execution Flow
1. **Model Request:** The Gemini model, based on the user's prompt and the provided tool schemas, decides to use a tool and returns a `FunctionCall` part in its response, specifying the tool name and arguments.
2. **Server Receives Request:** The server parses this `FunctionCall`.
3. **Tool Retrieval:** It looks up the requested tool in the `ToolRegistry`.
4. **Parameter Validation:** The tool's `validateToolParams()` method is called.
5. **Confirmation (if needed):**
- The tool's `shouldConfirmExecute()` method is called.
- If it returns details for confirmation, the server communicates this back to the CLI, which prompts the user.
- The user's decision (e.g., proceed, cancel) is sent back to the server.
6. **Execution:** If validated and confirmed (or if no confirmation is needed), the server calls the tool's `execute()` method with the provided arguments and an `AbortSignal` (for potential cancellation).
7. **Result Processing:** The `ToolResult` from `execute()` is received by the server.
8. **Response to Model:** The `llmContent` from the `ToolResult` is packaged as a `FunctionResponse` and sent back to the Gemini model so it can continue generating a user-facing response.
9. **Display to User:** The `returnDisplay` from the `ToolResult` is sent to the CLI to show the user what the tool did.
## Extending with Custom Tools
While direct programmatic registration of new tools by users isn't explicitly detailed as a primary workflow in the provided files for typical end-users, the architecture supports extension through:
- **Command-based Discovery:** Advanced users or project administrators can define a `toolDiscoveryCommand` in `settings.json`. This command, when run by the Gemini CLI server, should output a JSON array of `FunctionDeclaration` objects. The server will then make these available as `DiscoveredTool` instances. The corresponding `toolCallCommand` would then be responsible for actually executing these custom tools.
- **MCP Server:** For more complex scenarios, an MCP server can be set up (configured via `mcpServerCommand`) to expose tools that the Gemini CLI server can then discover and use.
This tool system provides a flexible and powerful way to augment the Gemini model's capabilities, making the Gemini CLI a versatile assistant for a wide range of tasks.

125
docs/tools/file-system.md Normal file
View File

@ -0,0 +1,125 @@
# Gemini CLI: File System Tools
The Gemini CLI provides a comprehensive suite of tools for interacting with the local file system. These tools allow the Gemini model to read from, write to, list, search, and modify files and directories, all under your control and typically with confirmation for sensitive operations.
All file system tools operate within a `rootDirectory` (usually the current working directory where you launched the CLI) for security, preventing unintended access to other parts of your system. Paths provided to these tools are generally expected to be absolute or are resolved relative to this root directory.
## 1. `list_directory` (ReadFolder)
- **Tool Name:** `list_directory`
- **Display Name:** ReadFolder
- **File:** `ls.ts`
- **Description:** Lists the names of files and subdirectories directly within a specified directory path. It can optionally ignore entries matching provided glob patterns.
- **Parameters:**
- `path` (string, required): The absolute path to the directory to list.
- `ignore` (array of strings, optional): A list of glob patterns to exclude from the listing (e.g., `["*.log", ".git"]`).
- **Behavior:**
- Returns a list of file and directory names.
- Indicates whether each entry is a directory.
- Sorts entries with directories first, then alphabetically.
- **Output (`llmContent`):** A string like: `Directory listing for /path/to/your/folder:\n[DIR] subfolder1\nfile1.txt\nfile2.png`
- **Confirmation:** No.
## 2. `read_file` (ReadFile)
- **Tool Name:** `read_file`
- **Display Name:** ReadFile
- **File:** `read-file.ts`
- **Description:** Reads and returns the content of a specified file. It can handle large files by allowing reading of specific line ranges and will attempt to detect and skip binary files.
- **Parameters:**
- `path` (string, required): The absolute path to the file to read.
- `offset` (number, optional): The 0-based line number to start reading from. Requires `limit` to be set.
- `limit` (number, optional): The maximum number of lines to read. If omitted, reads a default maximum (e.g., 2000 lines).
- **Behavior:**
- Returns the content of the specified text file.
- If `offset` and `limit` are used, returns only that slice of lines.
- Indicates if the content was truncated due to line limits or line length limits.
- Attempts to identify binary files (images, executables) and returns a message indicating it's a binary file instead of its content.
- **Output (`llmContent`):** The file content, potentially prefixed with a truncation message (e.g., `[File truncated: showing lines 1-100 of 500 total lines...]\nActual file content...`). For binary files: `Binary file: /path/to/image.png (image)`.
- **Confirmation:** No.
## 3. `write_file` (WriteFile)
- **Tool Name:** `write_file`
- **Display Name:** WriteFile
- **File:** `write-file.ts`
- **Description:** Writes content to a specified file. If the file exists, it will be overwritten. If it doesn't exist, it (and any necessary parent directories) will be created.
- **Parameters:**
- `file_path` (string, required): The absolute path to the file to write to.
- `content` (string, required): The content to write into the file.
- **Behavior:**
- Writes the provided `content` to the `file_path`.
- Creates parent directories if they don't exist.
- **Output (`llmContent`):** A success message, e.g., `Successfully overwrote file: /path/to/your/file.txt` or `Successfully created and wrote to new file: /path/to/new/file.txt`.
- **Confirmation:** Yes. Shows a diff of changes and asks for user approval before writing.
## 4. `glob` (FindFiles)
- **Tool Name:** `glob`
- **Display Name:** FindFiles
- **File:** `glob.ts`
- **Description:** Efficiently finds files matching specific glob patterns (e.g., `src/**/*.ts`, `*.md`), returning absolute paths sorted by modification time (newest first).
- **Parameters:**
- `pattern` (string, required): The glob pattern to match against (e.g., `"*.py"`, `"src/**/*.js"`).
- `path` (string, optional): The absolute path to the directory to search within. If omitted, searches the tool's root directory.
- **Behavior:**
- Searches for files matching the glob pattern within the specified directory.
- Returns a list of absolute paths, sorted with the most recently modified files first.
- Ignores common nuisance directories like `node_modules` and `.git` by default.
- **Output (`llmContent`):** A message like: `Found 5 file(s) matching "*.ts" within src, sorted by modification time (newest first):\nsrc/file1.ts\nsrc/subdir/file2.ts...`
- **Confirmation:** No.
## 5. `search_file_content` (SearchText)
- **Tool Name:** `search_file_content`
- **Display Name:** SearchText
- **File:** `grep.ts`
- **Description:** Searches for a regular expression pattern within the content of files in a specified directory. Can filter files by a glob pattern. Returns the lines containing matches, along with their file paths and line numbers.
- **Parameters:**
- `pattern` (string, required): The regular expression (regex) to search for (e.g., `"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).
- **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.:
```
Found 3 match(es) for pattern "myFunction" in path "." (filter: "*.ts"):
---
File: src/utils.ts
L15: export function myFunction() {
L22: myFunction.call();
---
File: src/index.ts
L5: import { myFunction } from './utils';
---
```
- **Confirmation:** No.
## 6. `replace` (Edit)
- **Tool Name:** `replace`
- **Display Name:** Edit
- **File:** `edit.ts`
- **Description:** Replaces a single, unique occurrence of text within a file. This tool is designed for precise, targeted changes and requires significant context around the `old_string` to ensure it modifies the correct location. It can also be used to create new files if `old_string` is empty and the `file_path` does not exist.
- **Parameters:**
- `file_path` (string, required): The absolute path to the file to modify.
- `old_string` (string, required): The exact literal text to replace. **CRITICAL:** This string must uniquely identify the single instance to change. It should include at least 3 lines of context _before_ and _after_ the target text, matching whitespace and indentation precisely. If `old_string` is empty, the tool attempts to create a new file at `file_path` with `new_string` as content.
- `new_string` (string, required): The exact literal text to replace `old_string` with.
- **Behavior:**
- 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.
- **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).
- **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...`).
- **Confirmation:** Yes. Shows a diff of the proposed changes and asks for user approval before writing to the file.
These file system tools provide a robust foundation for the Gemini CLI to understand and interact with your local project context.

58
docs/tools/index.md Normal file
View File

@ -0,0 +1,58 @@
# Gemini CLI Tools: Overview
The Gemini CLI is equipped with a powerful set of built-in tools that the Gemini model can utilize to interact with your local environment, access information, and perform actions. These tools significantly enhance the CLI's capabilities, allowing it to go beyond text generation and assist with a wide range of tasks.
## What are Tools?
In the context of the Gemini CLI, tools are specific functions or modules that the Gemini model can request to be executed. For example, if you ask Gemini to "Summarize the contents of `my_document.txt`," the model will likely identify the need to read that file and will request the execution of the `read_file` tool.
The server component (`packages/server`) manages these tools, presents their definitions (schemas) to the Gemini model, executes them when requested, and returns the results to the model for further processing into a user-facing response.
## Why are Tools Important?
- **Access to Local Information:** Tools allow Gemini to access your local file system, read file contents, list directories, etc.
- **Execution of Commands:** With tools like `execute_bash_command`, Gemini can run shell commands (with appropriate safety measures and user confirmation).
- **Interaction with the Web:** Tools can fetch content from URLs.
- **Action Taking:** Tools can modify files, write new files, or perform other actions on your system (again, typically with safeguards).
- **Grounding Responses:** By using tools to fetch real-time or specific local data, Gemini's responses can be more accurate, relevant, and grounded in your actual context.
## How Tools are Used
1. You provide a prompt to the Gemini CLI.
2. The CLI sends the prompt to the server.
3. The server, along with your prompt and conversation history, sends a list of available tools and their descriptions/schemas to the Gemini API.
4. The Gemini model analyzes your request. If it determines that a tool is needed, its response will include a request to execute a specific tool with certain parameters.
5. The server receives this tool request, validates it, and (often after user confirmation for sensitive operations) executes the tool.
6. The output from the tool is sent back to the Gemini model.
7. The Gemini model uses the tool's output to formulate its final answer, which is then sent back through the server to the CLI and displayed to you.
You will typically see messages in the CLI indicating when a tool is being called and whether it succeeded or failed.
## Categories of Built-in Tools
The built-in tools can be broadly categorized as follows:
- **[File System Tools](./file-system.md):** For interacting with files and directories (reading, writing, listing, searching, etc.).
- **[Shell Tool](./shell.md):** For executing shell commands.
- **[Web Fetch Tool](./web.md):** For retrieving content from URLs.
- **[Multi-File Read Tool](./multi-file.md):** A specialized tool for reading content from multiple files or directories, often used by the `@` command.
## Security and Confirmation
Many tools, especially those that can modify your file system or execute commands (`write_file`, `edit`, `execute_bash_command`), are designed with safety in mind. The Gemini CLI will typically:
- **Require Confirmation:** Prompt you before executing potentially sensitive operations, showing you what action is about to be taken.
- **Utilize Sandboxing:** For tools like `execute_bash_command`, sandboxing mechanisms (configurable via settings) are employed to limit the potential impact of the command.
It's important to always review confirmation prompts carefully before allowing a tool to proceed.
## Detailed Tool Documentation
For detailed information on each specific tool, including its parameters and behavior, please refer to the individual pages in this section:
- **[File System Tools](./file-system.md)**
- **[Shell Tool (execute_bash_command)](./shell.md)**
- **[Web Fetch Tool](./web.md)**
- **[Multi-File Read Tool](./multi-file.md)**
Understanding the available tools and how they work will help you make the most effective use of the Gemini CLI.

36
docs/tools/multi-file.md Normal file
View File

@ -0,0 +1,36 @@
# Multi-File Read Tool
This document provides details on the `read_many_files` tool.
## `read_many_files`
- **Purpose:** Reads content from multiple text files specified by paths or glob patterns and concatenates them into a single string. This is useful for getting an overview of a codebase, finding where specific functionality is implemented, reviewing documentation, or gathering context from multiple configuration files.
- **Arguments:**
- `paths` (list[string], required): An array of glob patterns or paths relative to the tool's target directory (e.g., `["src/**/*.ts"]`, `["README.md", "docs/"]`).
- `exclude` (list[string], optional): Glob patterns for files/directories to exclude (e.g., `["**/*.log", "temp/"]`). These are added to default excludes if `useDefaultExcludes` is true.
- `include` (list[string], optional): Additional glob patterns to include. These are merged with `paths` (e.g., `["*.test.ts"]` to specifically add test files if they were broadly excluded).
- `recursive` (boolean, optional): Whether to search recursively. This is primarily controlled by `**` in glob patterns. Defaults to `true`.
- `useDefaultExcludes` (boolean, optional): Whether to apply a list of default exclusion patterns (e.g., `node_modules`, `.git`, binary files). Defaults to `true`.
- **Behavior:**
- The tool searches for files matching the provided `paths` and `include` patterns, while respecting `exclude` patterns and default excludes (if enabled).
- It reads the content of each matched text file (attempting to skip binary files).
- The content of all successfully read files is concatenated into a single string, with a separator `--- {filePath} ---` between the content of each file.
- Uses UTF-8 encoding by default.
- **Examples:**
- Reading all TypeScript files in the `src` directory:
```
read_many_files(paths=["src/**/*.ts"])
```
- Reading the main README and all Markdown files in the `docs` directory, excluding a specific file:
```
read_many_files(paths=["README.md", "docs/**/*.md"], exclude=["docs/OLD_README.md"])
```
- Reading all JavaScript files but explicitly including test files that might otherwise be excluded by a global pattern:
```
read_many_files(paths=["**/*.js"], include=["**/*.test.js"], useDefaultExcludes=False)
```
- **Important Notes:**
- **Binary Files:** This tool is designed for text files and attempts to skip binary files. Its behavior with binary content is not guaranteed.
- **Performance:** Reading a very large number of files or very large individual files can be resource-intensive.
- **Path Specificity:** Ensure paths and glob patterns are correctly specified relative to the tool's target directory.
- **Default Excludes:** Be aware of the default exclusion patterns (like `node_modules`, `.git`) and use `useDefaultExcludes=False` if you need to override them, but do so cautiously.

40
docs/tools/shell.md Normal file
View File

@ -0,0 +1,40 @@
# Shell Tool
This document provides details on the shell tool available.
## `execute_bash_command`
- **Purpose:** Executes a given shell command using `bash -c <command>`. This tool is essential for interacting with the underlying operating system, running scripts, or performing command-line operations.
- **Arguments:**
- `command` (string, required): The exact bash 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.
- **Behavior:**
- The command is executed as a subprocess.
- It 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.
- **Examples:**
- Listing files in the current directory:
```
execute_bash_command(command="ls -la")
```
- Running a script in a specific directory:
```
execute_bash_command(command="./my_script.sh", directory="scripts", description="Run my custom script")
```
- Starting a background server:
```
execute_bash_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.

26
docs/tools/web.md Normal file
View File

@ -0,0 +1,26 @@
# Web Fetch Tool
This document describes the `web_fetch` tool.
## `web_fetch`
- **Purpose:** Fetches text content from a given URL. This is useful for retrieving data from web pages, APIs, or other online resources.
- **Arguments:**
- `url` (string, required): The absolute URL to fetch (e.g., `https://example.com/data.txt`).
- **Behavior:**
- The tool attempts to retrieve the content from the specified URL.
- It handles potential network errors (e.g., DNS resolution failure, connection timeout) and non-success HTTP status codes (e.g., 404 Not Found, 500 Internal Server Error).
- The returned content is expected to be text-based. For binary files, the behavior might be undefined or result in garbled text.
- **Examples:**
- Fetching a plain text file:
```
web_fetch(url="https://example.com/robots.txt")
```
- Retrieving data from a simple API endpoint:
```
web_fetch(url="https://api.example.com/items/123")
```
- **Important Notes:**
- **Content Type:** This tool is primarily designed for text-based content. It may not be suitable for fetching binary files like images or executables.
- **Error Handling:** Always check the tool's output for error messages or status indicators to ensure the fetch was successful and the content is as expected.
- **Rate Limiting/Authentication:** Be mindful of website terms of service, rate limits, and authentication requirements. This tool does not inherently handle complex authentication mechanisms.

68
docs/troubleshooting.md Normal file
View File

@ -0,0 +1,68 @@
# Troubleshooting Guide
This guide provides solutions to common issues and debugging tips.
## Frequently Asked Questions (FAQs)
- **Q: How do I update the CLI to the latest version?**
- A: If installed globally via npm, you can usually update with `npm install -g <package-name>@latest`. If run from source, pull the latest changes from the repository and rebuild using `npm run build`.
- **Q: Where are the CLI configuration files stored?**
- A: The CLI configuration is typically managed within `packages/cli/src/config/`. Refer to `docs/cli/configuration.md` for more details.
- **Q: Where are the server configuration files stored?**
- A: The server configuration is typically managed within `packages/server/src/config/`. Refer to `docs/server/configuration.md` for more details.
## Common Error Messages and Solutions
- **Error: `EADDRINUSE` (Address already in use) when starting the server.**
- **Cause:** Another process is already using the port the server is trying to bind to.
- **Solution:**
1. Stop the other process using the port.
2. Configure the server to use a different port (see `docs/server/configuration.md`).
- **Error: Command not found (when using the CLI).**
- **Cause:** The CLI is not correctly installed or not in your system's PATH.
- **Solution:**
1. Ensure the CLI installation was successful.
2. If installed globally, check that your npm global binary directory is in your PATH.
3. If running from source, ensure you are using the correct command to invoke it (e.g., `node packages/cli/dist/index.js ...`).
- **Error: `MODULE_NOT_FOUND` or import errors.**
- **Cause:** Dependencies are not installed correctly, or the project hasn't been built.
- **Solution:**
1. Run `npm install` to ensure all dependencies are present.
2. Run `npm run build` to compile the project.
- **Error: MacOS Seatbelt "Operation not permitted" or similar.**
- **Cause:** The application is attempting an operation restricted by the MacOS Seatbelt profile it's running under. This is a security feature of MacOS.
- **Solution:** The specific Seatbelt profile (`sandbox-macos-minimal.sb` or `sandbox-macos-strict.sb` in `packages/cli/src/utils/`) may need to be adjusted to permit the required operation. This involves understanding the sandbox profile language and carefully considering the security implications of any changes. Modifying sandbox profiles can be complex and should be done with caution.
## Debugging Tips
- **CLI Debugging:**
- Use the `--verbose` flag (if available) with CLI commands for more detailed output.
- Check the CLI logs, often found in a user-specific configuration or cache directory.
- **Server Debugging:**
- Check the server console output for error messages or stack traces.
- Increase log verbosity if configurable.
- Use Node.js debugging tools (e.g., `node --inspect`) if you need to step through server-side code.
- **Tool Issues:**
- If a specific tool is failing, try to isolate the issue by running the simplest possible version of the command or operation the tool performs.
- For `execute_bash_command`, ensure the command works directly in your shell first.
- For file system tools, double-check paths and permissions.
- **Pre-flight Checks:**
- Always run `npm run preflight` before committing code. This can catch many common issues related to formatting, linting, and type errors.
If you encounter an issue not covered here, consider searching the project's issue tracker on GitHub or reporting a new issue with detailed information.