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

docs: update documentation from starsandskies/patch-2 (#1143) 

Co-authored-by: starsandskies <nstock@google.com>
Co-authored-by: matt korwel <matt.korwel@gmail.com>
This commit is contained in:
N. Taylor Mullen 2025-06-17 22:02:07 -07:00 committed by GitHub
parent f3c1cbbabf
commit 7f189f4d5f
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
3 changed files with 105 additions and 186 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

129
docs/cli/commands.md
View File

@ -1,140 +1,117 @@
# 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 (`!`).
Gemini CLI supports several built-in commands to help you manage your session, customize the interface, and control its behavior. These commands are prefixed with a forward slash (`/`), an at symbol (`@`), or an exclamation mark (`!`).
## Slash Commands (`/`)
## Slash commands (`/`)
Slash commands provide meta-level control over the CLI itself. They can typically be executed by typing the command and pressing `Enter`.
Slash commands provide meta-level control over the CLI itself.
- **`/editor`**
- **Description:** Allows you to configure your external editor for actions such as modifying Gemini's proposed code change.
- **Action:** Opens a dialog for selecting supported editors.
- **Description:** Open a dialog for selecting supported editors.
- **`/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.
- **Description:** Display help information about the Gemini CLI, including available commands and their usage.
- **`/mcp`** (Toggle descriptions: **Ctrl+T**)
- **`/mcp`**
- **Description:** Lists configured Model Context Protocol (MCP) servers and their available tools.
- **Action:** Displays a formatted list of MCP servers with connection status indicators, server details, and available tools.
- **Description:** List configured Model Context Protocol (MCP) servers, their connection status, server details, and available tools.
- **Sub-commands:**
- **`desc`** or **`descriptions`**:
- **Description:** Shows detailed descriptions for MCP servers and tools.
- **Action:** Displays each tool's name with its full description, formatted for readability.
- **Description:** Show detailed descriptions for MCP servers and tools.
- **`nodesc`** or **`nodescriptions`**:
- **Description:** Hides tool descriptions, showing only the tool names.
- **Action:** Displays a compact list with only tool names.
- **Description:** Hide tool descriptions, showing only the tool names.
- **`schema`**:
- **Description:** Shows full schema of tool parameters.
- **Action:** Displays the full JSON schema for the tool's configured parameters.
- **Description:** Show the full JSON schema for the tool's configured parameters.
- **Keyboard Shortcut:** Press **Ctrl+T** at any time to toggle between showing and hiding tool descriptions.
- **`/clear`** (Shortcut: **Ctrl+L**)
- **`/clear`**
- **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.
- **Description:** Clear the terminal screen, including the visible session history and scrollback within the CLI. The underlying session data (for history recall) might be preserved depending on the exact implementation, but the visual display is cleared.
- **Keyboard shortcut:** Press **Ctrl+L** at any time to perform a clear action.
- [**`/theme`**](./themes.md)
- **Description:** Allows you to change the visual theme of the Gemini CLI.
- **Action:** Opens a dialog or prompt to select from available themes.
- **Description:** Open a dialog that lets you change the visual theme of Gemini CLI.
- **`/memory`**
- **Description:** Manages the AI's instructional context (hierarchical memory loaded from `GEMINI.md` files) and allows for adding ad-hoc memory entries.
- **Usage:** `/memory <sub_command> [text_for_add]`
- **Description:** Manage the AI's instructional context (hierarchical memory loaded from `GEMINI.md` files).
- **Sub-commands:**
- **`show`**:
- **Description:** Displays the full, concatenated content of the current hierarchical memory that has been loaded from all `GEMINI.md` files. This allows you to inspect the exact instructional context being provided to the Gemini model.
- **Action:** Outputs the combined content of all loaded `GEMINI.md` files, including separators that indicate the origin and path of each part of the memory. This is useful for verifying the loading order and final context.
- **Description:** Display the full, concatenated content of the current hierarchical memory that has been loaded from all `GEMINI.md` files. This lets you inspect the instructional context being provided to the Gemini model.
- **`refresh`**:
- **Description:** Reloads the hierarchical instructional context (memory) from all `GEMINI.md` files found in the configured locations (global, project/ancestors, and sub-directories). This command updates the AI's understanding based on the latest `GEMINI.md` content.
- **Action:** The CLI re-scans for all relevant `GEMINI.md` files and rebuilds its instructional memory. The number of loaded files is typically indicated in the CLI footer.
- **Description:** Reload the hierarchical instructional memory from all `GEMINI.md` files found in the configured locations (global, project/ancestors, and sub-directories). This command updates the model with the latest `GEMINI.md` content.
- **Note:** For more details on how `GEMINI.md` files contribute to hierarchical memory, see the [CLI Configuration documentation](./configuration.md#4-geminimd-files-hierarchical-instructional-context).
- **`/quit`** (or **`/exit`**)
- **Description:** Exits the Gemini CLI application.
- **Action:** Terminates the CLI process.
- **Description:** Exit Gemini CLI.
- **`/tools`**
- [**`/tools`**](../tools/index.md)
- **Description:** Displays a list of all the tools that are currently available to the model.
- **Action:** Outputs a list of the available tools.
- **Description:** Display a list of tools that are currently available within Gemini CLI.
- **Sub-commands:**
- **`desc`** or **`descriptions`**:
- **Description:** Shows detailed descriptions of each tool.
- **Action:** Displays each tool's name with its full description as provided to the model.
- **Description:** Show detailed descriptions of each tool, including each tool's name with its full description as provided to the model.
- **`nodesc`** or **`nodescriptions`**:
- **Description:** Hides tool descriptions, showing only the tool names.
- **Action:** Displays a compact list with only tool names.
- **Description:** Hide tool descriptions, showing only the tool names.
- **`/compress`**
- **Description:** Compresses the current context. This will save on tokens used for future tasks while retaining a high level summary of what has happened.
- **Action:** Replaces the entire chat context with a summary.
- **Description:** Replace the entire chat context with a summary. This saves on tokens used for future tasks while retaining a high level summary of what has happened.
## At Commands (`@`)
- **`/bug`**
At commands are used to quickly include the content of files or directories as part of your prompt to Gemini. These commands now feature git-aware filtering.
- **Description:** File an issue about Gemini CLI. By default, the issue is filed within the GitHub repository for Gemini CLI. The string you enter after `/bug` will become the headline for the bug being filed. The default `/bug` behavior can be modified using the `bugCommand` setting in your `.gemini/settings.json` files.
## At commands (`@`)
At commands are used to include the content of files or directories as part of your prompt to Gemini. These commands include git-aware filtering.
- **`@<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:**
- **Description:** Inject the content of the specified file or files into your current prompt. This is useful for asking questions about specific code, text, or collections of files.
- **Examples:**
- `@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/**`).
- If a path to a directory is provided, the command attempts to read the content of files within that directory and any subdirectories.
- 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.
- **Git-Aware Filtering:** By default, git-ignored files (like `node_modules/`, `dist/`, `.env`, `.git/`) are automatically excluded. This behavior can be configured via the `fileFiltering` settings.
- **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.
- The command uses the `read_many_files` tool internally. The content is fetched and then inserted into your query before being sent to the Gemini model.
- **Git-aware filtering:** By default, git-ignored files (like `node_modules/`, `dist/`, `.env`, `.git/`) are excluded. This behavior can be changed via the `fileFiltering` settings.
- **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 indicates if files were skipped.
- **Output:** The CLI will show a tool call message indicating that `read_many_files` was used, along with a message detailing the status 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.
- **`@` (Lone at symbol)**
- **Description:** If you type a lone `@` symbol without a path, the query is passed as-is to the Gemini model. This might be useful if you are specifically talking _about_ the `@` symbol in your prompt.
### Error Handling for `@` Commands
### 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 Mode & Passthrough Commands (`!`)
## Shell mode & passthrough commands (`!`)
The `!` prefix provides a powerful way to interact with your system's shell directly from within the Gemini CLI. It allows for both single command execution and a toggleable Shell Mode for a more persistent shell experience.
The `!` prefix lets you interact with your system's shell directly from within Gemini CLI.
- **`!<shell_command>`**
- **Description:** Executes the given `<shell_command>` in your system's default shell.
- **Usage:**
- `!ls -la` (executes `ls -la` and returns to normal CLI mode)
- `!git status` (executes `git status` and returns to normal CLI mode)
- **Action:** The command following the `!` is passed to the system shell for execution. Standard output and standard error are displayed in the CLI. After execution, the CLI typically returns to its standard conversational mode.
- **Description:** Execute the given `<shell_command>` in your system's default shell. Any output or errors from the command are displayed in the terminal.
- **Examples:**
- `!ls -la` (executes `ls -la` and returns to Gemini CLI)
- `!git status` (executes `git status` and returns to Gemini CLI)
- **`!` (Toggle Shell Mode)**
- **`!` (Toggle shell mode)**
- **Description:** Typing `!` on its own (without an immediately following command) toggles Shell Mode.
- **Action & Behavior:**
- **Entering Shell Mode:**
- The UI will update, often with different coloring and a "Shell Mode Indicator," to clearly show that Shell Mode is active.
- Most slash commands (e.g., `/help`, `/theme`) and AI-powered suggestions are disabled to provide an uninterrupted shell experience.
- Any text you type is interpreted directly as a shell command.
- **Exiting Shell Mode:**
- Typing `!` again while in Shell Mode will toggle it off.
- The UI will revert to its standard appearance.
- Slash commands and AI suggestions are re-enabled.
- **Usage:**
- Type `!` and press Enter to enter Shell Mode.
- Type your shell commands (e.g., `cd my_project`, `npm run dev`, `cat file.txt`).
- Type `!` and press Enter again to exit Shell Mode.
- **Description:** Typing `!` on its own toggles shell mode.
- **Entering shell mode:**
- When active, shell mode uses a different coloring and a "Shell Mode Indicator".
- While in shell mode, text you type is interpreted directly as a shell command.
- **Exiting shell mode:**
- When exited, the UI reverts to its standard appearance and normal Gemini CLI behavior resumes.
- **Caution for all `!` usage:** Be mindful of the commands you execute, as they have the same permissions and impact as if you ran them directly in your terminal. The Shell Mode feature does not inherently add extra sandboxing beyond what's already configured for the underlying `run_shell_command` tool.
This integrated shell capability allows for seamless switching between AI-assisted tasks and direct system interaction.
- **Caution for all `!` usage:** Commands you execute in shell mode have the same permissions and impact as if you ran them directly in your terminal.

121
docs/deployment.md
View File

@ -1,18 +1,18 @@
# Gemini CLI Execution and Deployment
This document outlines the various methods for running the Gemini CLI and the deployment architecture that supports them. Understanding these options is crucial for both users and developers.
This document describes how to run Gemini CLI and explains the deployment architecture that Gemini CLI uses.
## How to Run the Gemini CLI
## Running Gemini CLI
There are several ways to run the Gemini CLI, each catering to different needs, from stable end-user consumption to active development and testing.
There are several ways to run Gemini CLI. The option you choose depends on how you intend to use Gemini CLI.
---
### 1. Standard Installation (Recommended for Users)
### 1. Standard installation (Recommended for typical users)
This is the most common and recommended way for end-users to run the Gemini CLI. It involves installing the CLI from the NPM registry.
This is the recommended way for end-users to install Gemini CLI. It involves downloading the Gemini CLI package from the NPM registry.
- **Global Install:**
- **Global install:**
```bash
# Install the CLI globally
@ -22,19 +22,17 @@ This is the most common and recommended way for end-users to run the Gemini CLI.
gemini
```
- **NPX Execution:**
- **NPX execution:**
```bash
# Execute the latest version from NPM without a global install
npx @gemini-cli/cli
```
**Underlying Mechanism:** Both of these methods download the `@gemini-cli/cli` package from NPM. This package contains the application's source code transpiled into JavaScript using the TypeScript Compiler (tsc), which is then run by the Node.js runtime.
---
### 2. Running in a Sandbox (Docker/Podman)
### 2. Running in a sandbox (Docker/Podman)
For security and isolation, the Gemini CLI can be run inside a container. This is the default way that the CLI executes tools that might have side effects.
For security and isolation, Gemini CLI can be run inside a container. This is the default way that the CLI executes tools that might have side effects.
- **Directly from the Registry:**
You can run the published sandbox image directly. This is useful for environments where you only have Docker and want to run the CLI.
@ -43,27 +41,25 @@ For security and isolation, the Gemini CLI can be run inside a container. This i
docker run --rm -it us-docker.pkg.dev/gemini-code-dev/gemini-cli/sandbox:0.1.0
```
- **Using the `--sandbox` flag:**
When you have the CLI installed locally (using the standard method above), you can instruct it to run itself inside the sandbox container.
If you have Gemini CLI installed locally (using the standard installation described above), you can instruct it to run inside the sandbox container.
```bash
gemini --sandbox "your prompt here"
```
**Underlying Mechanism:** The CLI installed inside the sandbox is installed globally within the container image, in a similar fashion to the "Global Install" method. The local development sandbox is named `gemini-cli-sandbox`, while the published one has a longer, versioned name.
---
### 3. Running from Source (For Developers)
### 3. Running from source (Recommended for Gemini CLI contributors)
Contributors to the project will want to run the CLI directly from the source code.
- **Development Mode:**
This method provides hot-reloading and is ideal for active development.
This method provides hot-reloading and is useful for active development.
```bash
# From the root of the repository
npm run start
```
- **Production-like Mode (Linked Package):**
This method simulates a global installation by linking your local package. It's useful for testing a local build in a production user workflow.
- **Production-like mode (Linked package):**
This method simulates a global installation by linking your local package. It's useful for testing a local build in a production workflow.
```bash
# Link the local cli package to your global node_modules
@ -75,97 +71,46 @@ Contributors to the project will want to run the CLI directly from the source co
---
### 4. Running the Latest Version from GitHub (Early Access)
### 4. Running the latest Gemini CLI commit from GitHub
You can run the very latest, unreleased version of the CLI directly from the GitHub repository. This is useful for testing cutting-edge features or bug fixes.
You can run the most recently committed version of Gemini CLI directly from the GitHub repository. This is useful for testing features still in developement.
```bash
# Execute the CLI directly from the main branch on GitHub
npx https://github.com/google/gemini-cli
```
**Underlying Mechanism & Motivation:** This method was created for our early access program to provide a simple distribution mechanism for external testers who did not have access to our internal artifact registry. When you use `npx` with the GitHub repository URL, `npm` fetches the repository, runs the `prepare` script (which builds the application into a single, bundled file using `esbuild`), and then executes the newly built bundle. This happens on-the-fly on your machine.
## Deployment architecture
## Deployment Architecture
The execution methods described above are made possible by the following architectural components and processes:
The execution methods described above are made possible by the following architectural components and processes.
**NPM packages**
### 1. NPM Packages
The project is a monorepo that publishes two core packages to the NPM registry:
Gemini CLI project is a monorepo that publishes two core packages to the NPM registry:
- `@gemini-cli/core`: The backend, handling logic and tool execution.
- `@gemini-cli/cli`: The user-facing frontend.
These packages are the foundation for the Standard Installation and Source-based execution methods.
These packages are used when performing the standard installation and when running Gemini CLI from the source.
### 2. Build and Packaging Processes
**Build and packaging processes**
There are two distinct build processes used, depending on the distribution channel:
- **NPM Publication (`tsc`):** For publishing to the NPM registry, the TypeScript source code in `@gemini-cli/core` and `@gemini-cli/cli` is transpiled into standard JavaScript using the TypeScript Compiler (`tsc`). The resulting `dist/` directory is what gets published in the NPM package. This is a standard approach for TypeScript libraries.
- **NPM publication:** For publishing to the NPM registry, the TypeScript source code in `@gemini-cli/core` and `@gemini-cli/cli` is transpiled into standard JavaScript using the TypeScript Compiler (`tsc`). The resulting `dist/` directory is what gets published in the NPM package. This is a standard approach for TypeScript libraries.
- **GitHub `npx` Execution (`esbuild`):** For the `npx <github_repo>` use case, a different process is triggered by the `prepare` script in `package.json`. This script uses `esbuild` to bundle the entire application and its dependencies into a single, self-contained JavaScript file. This bundle is created on-the-fly on the user's machine and is not checked into the repository.
- **GitHub `npx` execution:** When running the latest version of Gemini CLI directly from GitHub, a different process is triggered by the `prepare` script in `package.json`. This script uses `esbuild` to bundle the entire application and its dependencies into a single, self-contained JavaScript file. This bundle is created on-the-fly on the user's machine and is not checked into the repository.
### 3. Docker Sandbox Image
**Docker sandbox image**
The Docker-based execution method is supported by a container image (`gemini-cli-sandbox`). This image is published to a container registry and contains a pre-installed, global version of the CLI. The `scripts/prepare-cli-packagejson.js` script dynamically injects the URI of this image into the CLI's `package.json` before publishing, so the CLI knows which image to pull when the `--sandbox` flag is used.
The Docker-based execution method is supported by the `gemini-cli-sandbox` container image. This image is published to a container registry and contains a pre-installed, global version of Gemini CLI. The `scripts/prepare-cli-packagejson.js` script dynamically injects the URI of this image into the CLI's `package.json` before publishing, so the CLI knows which image to pull when the `--sandbox` flag is used.
## The Release Process
## Release process
A unified script, `npm run publish:release`, orchestrates the entire release process, tying all the deployment methods together:
A unified script, `npm run publish:release`, orchestrates the release process. The script performs the following actions:
1. **Builds** the NPM packages using `tsc`.
2. **Updates** the CLI's `package.json` with the Docker image URI.
3. **Builds and tags** the `gemini-cli-sandbox` Docker image.
4. **Pushes** the Docker image to the container registry.
5. **Publishes** the NPM packages to the artifact registry.
---
### Addendum: Bundling vs. Transpiling for Distribution
A consequence of the project's fast, iterative development is the use of two different build outputs: a multi-file distribution for NPM (`tsc`) and a single-file bundle for direct execution from GitHub (`esbuild`). While not a deliberate initial architectural decision, this addendum explores the trade-offs of each approach.
**Single-File Bundle (e.g., `esbuild`)**
This approach packages the entire application, including its dependencies, into one self-contained JavaScript file.
- **Pros:**
- **Portability and Simplicity:** The entire application is a single file, making it extremely easy to distribute and execute. There are no external `node_modules` dependencies to manage, which eliminates a common source of versioning conflicts and "works on my machine" issues.
- **Faster Execution for `npx`:** For one-off executions via `npx`, downloading and running a single file can be faster than `npm` resolving, downloading, and linking a complex dependency tree.
- **Dependency Encapsulation:** All dependencies are locked into the bundle, ensuring that the application runs with the exact versions it was tested with. This prevents issues from unexpected updates to transitive dependencies.
- **Optimized Footprint:** Bundlers can perform whole-program optimizations. Tree-shaking eliminates unused code from dependencies, and minification reduces the size of the final distributable binary, often resulting in a smaller total footprint than a comparable `node_modules` directory.
- **Cons:**
- **Larger Initial Download:** The single file is necessarily larger than any individual file in a multi-file distribution, as it contains all dependencies.
- **Dependency Duplication:** If a user has multiple tools that bundle the same dependencies (e.g., two different CLIs that both bundle `chalk`), those dependencies are downloaded and stored multiple times on their system, whereas `npm` would de-duplicate them.
- **Slower Rebuilds:** Bundling can be a more complex and slower process than simple transpilation, which can affect development and CI/CD loop times.
- **Lack of Transparency and Debugging Complexity:** The bundling process can obscure the relationship between the source code and the final output. Global Node.js or ECMAScript utilities that are expected to be defined can disappear, requiring unintuitive script injections (see this project's `esbuild.config.js`) to align the bundle's behavior with the source code's intent. Direct transpilation, in contrast, keeps the output closer to the source, often making it easier to debug discrepancies.
- **A New Kind of Dependency Hell:** While bundling avoids `node_modules` conflicts, it introduces a new set of challenges. For instance, if a dependency relies on static assets (like `.wasm` or image files), the bundler may not know to include them. When the dependency then tries to reference these assets using file paths, the paths become invalid because everything has been packaged into a single file. This highlights how bundlers can make false assumptions about how nested dependencies expect to be used, trading one form of complexity for another.
**Multi-File Distribution (e.g., `tsc` with `package.json`)**
This is the standard approach for most NPM packages. The TypeScript code is transpiled to JavaScript, but dependencies are left as `import` statements, to be managed by the package manager (`npm`, `yarn`, etc.).
- **Pros:**
- **Ecosystem Compatibility:** This is the standard, expected format for the NPM ecosystem. It works seamlessly with `npm`, `yarn`, and other package managers.
- **Dependency Management:** `npm` handles dependency de-duplication and version resolution. This is highly efficient, as shared dependencies are stored only once.
- **Transparency and Auditing:** It is easy for users to see the exact dependency tree (`npm ls`), audit for vulnerabilities (`npm audit`), and even override specific dependency versions if needed (`overrides` in `package.json`).
- **Faster Incremental Builds:** `tsc` can perform faster incremental builds during development, as it only needs to re-transpile changed files.
- **Cons:**
- **Dependency Hell:** The primary drawback. It can lead to complex dependency resolution issues, version conflicts, and a large `node_modules` directory.
- **Slower `npx` Install:** For `npx`, resolving and installing the full dependency tree can be significantly slower than downloading a single pre-packaged file.
- **"Works on my machine" issues:** Slight differences in dependency trees between environments can lead to subtle bugs.
**Build & Distribution Considerations**
The project currently maintains both systems to serve two distinct use cases:
1. The **`tsc` build** is ideal for the stable, versioned **NPM release**, where users benefit from `npm`'s robust dependency management.
2. The **`esbuild` bundle** is perfect for the **`npx <github_repo>`** scenario, providing a fast, portable, and hassle-free way for testers to run the latest version without a formal installation.
While the current dual-strategy provides a good experience for both end-users and developers/testers, the project would likely benefit from consolidating to a single, cohesive publishing story in the future.
1. Build the NPM packages using `tsc`.
2. Update the CLI's `package.json` with the Docker image URI.
3. Build and tag the `gemini-cli-sandbox` Docker image.
4. Push the Docker image to the container registry.
5. Publish the NPM packages to the artifact registry.

41
docs/index.md
View File

@ -1,36 +1,33 @@
# Welcome to the Gemini CLI Documentation
# Welcome to 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.
This documentation provides a comprehensive guide to installing, using, and developing Gemini CLI. This tool lets you interact with Gemini models through a 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/core`), 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.
Gemini CLI brings the capabilities of Gemini models to your terminal in an interactive Read-Eval-Print Loop (REPL) environment. Gemini CLI consists of a client-side application (`packages/cli`) that communicates with a local server (`packages/core`), which in turn manages requests to the Gemini API and its AI models. Gemini CLI also contains a variety of tools for tasks such as performing file system operations, running shells, and web fetching, which are managed by `packages/core`.
The `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.
The `packages/core` acts as the backend engine, handling communication with the Gemini API, managing tools, and processing requests from the CLI client.
## Navigating the Documentation
## Navigating the documentation
This documentation is organized into the following sections:
- **[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.
- **[Configuration](./cli/configuration.md):** How to configure the CLI.
- **[Execution and Deployment](./deployment.md):** Information for running Gemini CLI.
- **[Architecture Overview](./architecture.md):** Understand the high-level design of Gemini CLI, including its components and how they interact.
- **CLI Usage:** Documentation for `packages/cli`.
- **[CLI Introduction](./cli/index.md):** Overview of the command-line interface.
- **[Commands](./cli/commands.md):** Description of available CLI commands.
- **[Configuration](./cli/configuration.md):** Information on configuring the CLI.
- **[Extensions](./extension.md):** How to extend the CLI with new functionality.
- **Core Details:**
- **[Core Introduction](./core/index.md):** An overview of the core component.
- **[Configuration](./core/configuration.md):** How to configure the core.
- **Core Details:** Documentation for `packages/core`.
- **[Core Introduction](./core/index.md):** Overview of the core component.
- **[Configuration](./core/configuration.md):** Information on configuring the core component.
- **[Tools API](./core/tools-api.md):** Information on how the core 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 `run_shell_command` tool.
- **[Web Fetch Tool](./tools/web-fetch.md):** Using the `web_fetch` tool.
- **[Web Search Tool](./tools/web-search.md):** Using the `google_web_search` tool.
- **[Multi-File Read Tool](./tools/multi-file.md):** Using the `read_many_files` tool.
- **[Tools Overview](./tools/index.md):** Overview of the available tools.
- **[File System Tools](./tools/file-system.md):** Documentation for the `read_file` and `write_file` tools.
- **[Multi-File Read Tool](./tools/multi-file.md):** Documentation for the `read_many_files` tool.
- **[Shell Tool](./tools/shell.md):** Documentation for the `run_shell_command` tool.
- **[Web Fetch Tool](./tools/web-fetch.md):** Documentation for the `web_fetch` tool.
- **[Web Search Tool](./tools/web-search.md):** Documentation for the `google_web_search` tool.
- **[Contributing & Development Guide](../CONTRIBUTING.md):** Information for contributors and developers, including setup, building, testing, and coding conventions.
- **[Troubleshooting Guide](./troubleshooting.md):** Find solutions to common problems and FAQs.