From 14dbda91458eece76c6da819c082bf3d1c8c7f94 Mon Sep 17 00:00:00 2001 From: Jenna Inouye Date: Wed, 1 Oct 2025 16:24:29 -0700 Subject: [PATCH] Docs IA update and Get Started section. (#10192) --- README.md | 97 +++---- docs/architecture.md | 6 +- docs/cli/authentication.md | 180 +------------ docs/{ => cli}/checkpointing.md | 0 docs/cli/commands.md | 249 +----------------- docs/cli/custom-commands.md | 240 +++++++++++++++++ docs/cli/enterprise.md | 6 +- docs/{ => cli}/gemini-ignore.md | 2 +- docs/cli/gemini-md.md | 85 ++++++ docs/{ => cli}/headless.md | 10 +- docs/cli/index.md | 29 +- docs/{ => cli}/keyboard-shortcuts.md | 0 docs/{ => cli}/sandbox.md | 6 +- docs/{ => cli}/telemetry.md | 2 +- docs/cli/themes.md | 4 +- docs/{ => cli}/trusted-folders.md | 2 +- docs/cli/tutorials.md | 2 +- docs/{Uninstall.md => cli/uninstall.md} | 0 docs/core/memport.md | 2 +- docs/{ => extensions}/extension-releasing.md | 4 +- docs/{extension.md => extensions/index.md} | 4 +- docs/faq.md | 105 ++++++++ docs/get-started/authentication.md | 209 +++++++++++++++ docs/{cli => get-started}/configuration-v1.md | 4 +- docs/{cli => get-started}/configuration.md | 26 +- docs/{ => get-started}/deployment.md | 16 +- docs/get-started/examples.md | 200 ++++++++++++++ docs/get-started/index.md | 54 ++++ .../ide-companion-spec.md | 0 .../index.md} | 0 docs/index.md | 78 ++++-- docs/releases.md | 4 +- docs/sidebar.json | 220 +++++++++++++--- docs/tools/index.md | 8 +- docs/tos-privacy.md | 4 +- docs/troubleshooting.md | 17 +- packages/cli/src/ui/components/Help.tsx | 2 +- 37 files changed, 1255 insertions(+), 622 deletions(-) rename docs/{ => cli}/checkpointing.md (100%) create mode 100644 docs/cli/custom-commands.md rename docs/{ => cli}/gemini-ignore.md (94%) create mode 100644 docs/cli/gemini-md.md rename docs/{ => cli}/headless.md (96%) rename docs/{ => cli}/keyboard-shortcuts.md (100%) rename docs/{ => cli}/sandbox.md (95%) rename docs/{ => cli}/telemetry.md (99%) rename docs/{ => cli}/trusted-folders.md (96%) rename docs/{Uninstall.md => cli/uninstall.md} (100%) rename docs/{ => extensions}/extension-releasing.md (98%) rename docs/{extension.md => extensions/index.md} (93%) create mode 100644 docs/faq.md create mode 100644 docs/get-started/authentication.md rename docs/{cli => get-started}/configuration-v1.md (99%) rename docs/{cli => get-started}/configuration.md (97%) rename docs/{ => get-started}/deployment.md (89%) create mode 100644 docs/get-started/examples.md create mode 100644 docs/get-started/index.md rename docs/{ => ide-integration}/ide-companion-spec.md (100%) rename docs/{ide-integration.md => ide-integration/index.md} (100%) diff --git a/README.md b/README.md index 9fc5246949..7de0400f0e 100644 --- a/README.md +++ b/README.md @@ -11,12 +11,12 @@ Gemini CLI is an open-source AI agent that brings the power of Gemini directly i ## ๐Ÿš€ Why Gemini CLI? -- **๐ŸŽฏ Free tier**: 60 requests/min and 1,000 requests/day with personal Google account -- **๐Ÿง  Powerful Gemini 2.5 Pro**: Access to 1M token context window -- **๐Ÿ”ง Built-in tools**: Google Search grounding, file operations, shell commands, web fetching -- **๐Ÿ”Œ Extensible**: MCP (Model Context Protocol) support for custom integrations -- **๐Ÿ’ป Terminal-first**: Designed for developers who live in the command line -- **๐Ÿ›ก๏ธ Open source**: Apache 2.0 licensed +- **๐ŸŽฏ Free tier**: 60 requests/min and 1,000 requests/day with personal Google account. +- **๐Ÿง  Powerful Gemini 2.5 Pro**: Access to 1M token context window. +- **๐Ÿ”ง Built-in tools**: Google Search grounding, file operations, shell commands, web fetching. +- **๐Ÿ”Œ Extensible**: MCP (Model Context Protocol) support for custom integrations. +- **๐Ÿ’ป Terminal-first**: Designed for developers who live in the command line. +- **๐Ÿ›ก๏ธ Open source**: Apache 2.0 licensed. ## ๐Ÿ“ฆ Installation @@ -109,20 +109,14 @@ Choose the authentication method that best fits your needs: ### Option 1: Login with Google (OAuth login using your Google Account) -**โœจ Best for:** - -- Individual developers. -- Google AI Pro and AI Ultra subscribers. -- Anyone who has a Gemini Code Assist license. - -_See [quota limits and terms of service](https://cloud.google.com/gemini/docs/quotas) for details._ +**โœจ Best for:** Individual developers as well as anyone who has a Gemini Code Assist License. (see [quota limits and terms of service](https://cloud.google.com/gemini/docs/quotas) for details) **Benefits:** -- **Free tier** with 60 requests/min and 1,000 requests/day -- **Gemini 2.5 Pro and Flash** with 1M token context window +- **Free tier**: 60 requests/min and 1,000 requests/day +- **Gemini 2.5 Pro** with 1M token context window - **No API key management** - just sign in with your Google account -- **Automatic updates** to our latest models +- **Automatic updates** to latest models #### Start Gemini CLI, then choose _Login with Google_ and follow the browser authentication flow when prompted @@ -171,7 +165,7 @@ export GOOGLE_GENAI_USE_VERTEXAI=true gemini ``` -For Google Workspace accounts and other authentication methods, see the [authentication guide](./docs/cli/authentication.md). +For Google Workspace accounts and other authentication methods, see the [authentication guide](./docs/get-started/authentication.md). ## ๐Ÿš€ Getting Started @@ -233,17 +227,18 @@ gemini ### Getting Started -- [**Quickstart Guide**](./docs/cli/index.md) - Get up and running quickly -- [**Authentication Setup**](./docs/cli/authentication.md) - Detailed auth configuration -- [**Configuration Guide**](./docs/cli/configuration.md) - Settings and customization -- [**Keyboard Shortcuts**](./docs/keyboard-shortcuts.md) - Productivity tips +- [**Quickstart Guide**](./docs/get-started/index.md) - Get up and running quickly. +- [**Authentication Setup**](./docs/get-started/authentication.md) - Detailed auth configuration. +- [**Configuration Guide**](./docs/get-started/configuration.md) - Settings and customization. +- [**Keyboard Shortcuts**](./docs/cli/keyboard-shortcuts.md) - Productivity tips. ### Core Features -- [**Commands Reference**](./docs/cli/commands.md) - All slash commands (`/help`, `/chat`, `/mcp`, etc.) -- [**Checkpointing**](./docs/checkpointing.md) - Save and resume conversations -- [**Memory Management**](./docs/tools/memory.md) - Using GEMINI.md context files -- [**Token Caching**](./docs/cli/token-caching.md) - Optimize token usage +- [**Commands Reference**](./docs/cli/commands.md) - All slash commands (`/help`, `/chat`, etc). +- [**Custom Commands**](./docs/cli/custom-commands.md) - Create your own reusable commands. +- [**Context Files (GEMINI.md)**](./docs/cli/gemini-md.md) - Provide persistent context to Gemini CLI. +- [**Checkpointing**](./docs/cli/checkpointing.md) - Save and resume conversations. +- [**Token Caching**](./docs/cli/token-caching.md) - Optimize token usage. ### Tools & Extensions @@ -251,31 +246,25 @@ gemini - [File System Operations](./docs/tools/file-system.md) - [Shell Commands](./docs/tools/shell.md) - [Web Fetch & Search](./docs/tools/web-fetch.md) - - [Multi-file Operations](./docs/tools/multi-file.md) -- [**MCP Server Integration**](./docs/tools/mcp-server.md) - Extend with custom tools -- [**Custom Extensions**](./docs/extension.md) - Build your own commands +- [**MCP Server Integration**](./docs/tools/mcp-server.md) - Extend with custom tools. +- [**Custom Extensions**](./docs/extensions/index.md) - Build and share your own commands. ### Advanced Topics -- [**Architecture Overview**](./docs/architecture.md) - How Gemini CLI works -- [**IDE Integration**](./docs/ide-integration.md) - VS Code companion -- [**Sandboxing & Security**](./docs/sandbox.md) - Safe execution environments -- [**Enterprise Deployment**](./docs/deployment.md) - Docker, system-wide config -- [**Telemetry & Monitoring**](./docs/telemetry.md) - Usage tracking -- [**Tools API Development**](./docs/core/tools-api.md) - Create custom tools - -### Configuration & Customization - -- [**Settings Reference**](./docs/cli/configuration.md) - All configuration options -- [**Theme Customization**](./docs/cli/themes.md) - Visual customization -- [**.gemini Directory**](./docs/gemini-ignore.md) - Project-specific settings -- [**Environment Variables**](./docs/cli/configuration.md#environment-variables) +- [**Headless Mode (Scripting)**](./docs/cli/headless.md) - Use Gemini CLI in automated workflows. +- [**Architecture Overview**](./docs/architecture.md) - How Gemini CLI works. +- [**IDE Integration**](./docs/ide-integration/index.md) - VS Code companion. +- [**Sandboxing & Security**](./docs/cli/sandbox.md) - Safe execution environments. +- [**Trusted Folders**](./docs/cli/trusted-folders.md) - Control execution policies by folder. +- [**Enterprise Guide**](./docs/cli/enterprise.md) - Deploy and manage in a corporate environment. +- [**Telemetry & Monitoring**](./docs/cli/telemetry.md) - Usage tracking. +- [**Tools API Development**](./docs/core/tools-api.md) - Create custom tools. ### Troubleshooting & Support -- [**Troubleshooting Guide**](./docs/troubleshooting.md) - Common issues and solutions -- [**FAQ**](./docs/troubleshooting.md#frequently-asked-questions) - Quick answers -- Use `/bug` command to report issues directly from the CLI +- [**Troubleshooting Guide**](./docs/troubleshooting.md) - Common issues and solutions. +- [**FAQ**](./docs/faq.md) - Frequently asked questions. +- Use `/bug` command to report issues directly from the CLI. ### Using MCP Servers @@ -293,25 +282,25 @@ See the [MCP Server Integration guide](./docs/tools/mcp-server.md) for setup ins We welcome contributions! Gemini CLI is fully open source (Apache 2.0), and we encourage the community to: -- Report bugs and suggest features -- Improve documentation -- Submit code improvements -- Share your MCP servers and extensions +- Report bugs and suggest features. +- Improve documentation. +- Submit code improvements. +- Share your MCP servers and extensions. See our [Contributing Guide](./CONTRIBUTING.md) for development setup, coding standards, and how to submit pull requests. -Check our [Official Roadmap](https://github.com/orgs/google-gemini/projects/11/) for planned features and priorities. +Check our [Official Roadmap](https://github.com/orgs/google-gemini/projects/11) for planned features and priorities. ## ๐Ÿ“– Resources -- **[Official Roadmap](./ROADMAP.md)** - See what's coming next -- **[NPM Package](https://www.npmjs.com/package/@google/gemini-cli)** - Package registry -- **[GitHub Issues](https://github.com/google-gemini/gemini-cli/issues)** - Report bugs or request features -- **[Security Advisories](https://github.com/google-gemini/gemini-cli/security/advisories)** - Security updates +- **[Official Roadmap](./ROADMAP.md)** - See what's coming next. +- **[NPM Package](https://www.npmjs.com/package/@google/gemini-cli)** - Package registry. +- **[GitHub Issues](https://github.com/google-gemini/gemini-cli/issues)** - Report bugs or request features. +- **[Security Advisories](https://github.com/google-gemini/gemini-cli/security/advisories)** - Security updates. ### Uninstall -See the [Uninstall Guide](docs/Uninstall.md) for removal instructions. +See the [Uninstall Guide](docs/cli/uninstall.md) for removal instructions. ## ๐Ÿ“„ Legal diff --git a/docs/architecture.md b/docs/architecture.md index b120cb2546..cb2841f67e 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -9,11 +9,11 @@ The Gemini CLI is primarily composed of two main packages, along with a suite of 1. **CLI package (`packages/cli`):** - **Purpose:** This contains the user-facing portion of the Gemini CLI, such as handling the initial user input, presenting the final output, and managing the overall user experience. - **Key functions contained in the package:** - - [Input processing](./cli/commands.md) + - [Input processing](../cli/commands.md) - History management - Display rendering - - [Theme and UI customization](./cli/themes.md) - - [CLI configuration settings](./cli/configuration.md) + - [Theme and UI customization](../cli/themes.md) + - [CLI configuration settings](../get-started/configuration.md) 2. **Core package (`packages/core`):** - **Purpose:** This acts as the backend for the Gemini CLI. It receives requests sent from `packages/cli`, orchestrates interactions with the Gemini API, and manages the execution of available tools. diff --git a/docs/cli/authentication.md b/docs/cli/authentication.md index 4d06690f23..c23bfe0930 100644 --- a/docs/cli/authentication.md +++ b/docs/cli/authentication.md @@ -1,181 +1,3 @@ # Authentication Setup -Gemini CLI requires you to authenticate with Google's AI services. On initial startup you'll need to configure **one** of the following authentication methods: - -1. **Login with Google** - 1. **Google AI Pro and AI Ultra subscribers** - - Use this option to log in with your Google account that you use with Google AI Pro and Ultra. - - During initial startup, Gemini CLI will direct you to a webpage for authentication. Once authenticated, your credentials will be cached locally so the web login can be skipped on subsequent runs. - - Note that the web login must be done in a browser that can communicate with the machine Gemini CLI is being run from. (Specifically, the browser will be redirected to a localhost URL that Gemini CLI will be listening on.) - 2. **Gemini Code Assist:** - - Use this option to log in with your Google account. - - During initial startup, Gemini CLI will direct you to a webpage for authentication. Once authenticated, your credentials will be cached locally so the web login can be skipped on subsequent runs. - - Note that the web login must be done in a browser that can communicate with the machine Gemini CLI is being run from. (Specifically, the browser will be redirected to a localhost url that Gemini CLI will be listening on.) - - Users may have to specify a GOOGLE_CLOUD_PROJECT if: - 1. You have a Google Workspace account. Google Workspace is a paid service for businesses and organizations that provides a suite of productivity tools, including a custom email domain (e.g. your-name@your-company.com), enhanced security features, and administrative controls. These accounts are often managed by an employer or school. - 1. You have received a Gemini Code Assist license through the [Google Developer Program](https://developers.google.com/program/plans-and-pricing) (including qualified Google Developer Experts). - 1. You have been assigned a license to a current Gemini Code Assist standard or enterprise subscription. - 1. You are using the product outside the [supported regions](https://developers.google.com/gemini-code-assist/resources/available-locations) for free individual usage. - 1. You are a Google account holder under the age of 18. - - If you fall into one of these categories, you must first configure a Google Cloud Project ID to use, [enable the Gemini for Cloud API](https://cloud.google.com/gemini/docs/discover/set-up-gemini#enable-api) and [configure access permissions](https://cloud.google.com/gemini/docs/discover/set-up-gemini#grant-iam). - - You can temporarily set the environment variable in your current shell session using the following command: - - ```bash - export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID" - ``` - - For repeated use, you can add the environment variable to your [.env file](#persisting-environment-variables-with-env-files) or your shell's configuration file (like `~/.bashrc`, `~/.zshrc`, or `~/.profile`). For example, the following command adds the environment variable to a `~/.bashrc` file: - - ```bash - echo 'export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"' >> ~/.bashrc - source ~/.bashrc - ``` - -2. **Gemini API key:** - - Obtain your API key from Google AI Studio: [https://aistudio.google.com/app/apikey](https://aistudio.google.com/app/apikey) - - Set the `GEMINI_API_KEY` environment variable. In the following methods, replace `YOUR_GEMINI_API_KEY` with the API key you obtained from Google AI Studio: - - You can temporarily set the environment variable in your current shell session using the following command: - ```bash - export GEMINI_API_KEY="YOUR_GEMINI_API_KEY" - ``` - - For repeated use, you can add the environment variable to your [.env file](#persisting-environment-variables-with-env-files). - - - Alternatively you can export the API key from your shell's configuration file (like `~/.bashrc`, `~/.zshrc`, or `~/.profile`). For example, the following command adds the environment variable to a `~/.bashrc` file: - - ```bash - echo 'export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"' >> ~/.bashrc - source ~/.bashrc - ``` - - :warning: Be advised that when you export your API key inside your shell configuration file, any other process executed from the shell can read it. - -3. **Vertex AI:** - - **API Key:** - - Obtain your Google Cloud API key: [Get an API Key](https://cloud.google.com/vertex-ai/generative-ai/docs/start/api-keys?usertype=newuser) - - Set the `GOOGLE_API_KEY` environment variable. In the following methods, replace `YOUR_GOOGLE_API_KEY` with your Vertex AI API key: - - You can temporarily set the environment variable in your current shell session using the following command: - ```bash - export GOOGLE_API_KEY="YOUR_GOOGLE_API_KEY" - ``` - - For repeated use, you can add the environment variable to your [.env file](#persisting-environment-variables-with-env-files) or your shell's configuration file (like `~/.bashrc`, `~/.zshrc`, or `~/.profile`). For example, the following command adds the environment variable to a `~/.bashrc` file: - - ```bash - echo 'export GOOGLE_API_KEY="YOUR_GOOGLE_API_KEY"' >> ~/.bashrc - source ~/.bashrc - ``` - - :warning: Be advised that when you export your API key inside your shell configuration file, any other process executed from the shell can read it. - - > **Note:** - > If you encounter an error like `"API keys are not supported by this API - Expected OAuth2 access token or other authentication credentials that assert a principal"`, it is likely that your organization has restricted the creation of service account API keys. In this case, please try the [service account JSON key](#service-account-json-key) method described below. - - - **Application Default Credentials (ADC):** - - > **Note:** - > If you have previously set the `GOOGLE_API_KEY` or `GEMINI_API_KEY` environment variables, you must unset them to use Application Default Credentials. - > - > ```bash - > unset GOOGLE_API_KEY GEMINI_API_KEY - > ``` - - **Using `gcloud` (for local development):** - - Ensure you have a Google Cloud project and have enabled the Vertex AI API. - - Log in with your user credentials: - ```bash - gcloud auth application-default login - ``` - For more information, see [Set up Application Default Credentials for Google Cloud](https://cloud.google.com/docs/authentication/provide-credentials-adc). - - **Using a Service Account (for applications or when service account API keys are restricted):** - - If you are unable to create an API key due to [organization policies](https://cloud.google.com/vertex-ai/generative-ai/docs/start/api-keys?usertype=existinguser#expandable-2), or if you are running in a non-interactive environment, you can authenticate using a service account key. - - [Create a service account and key](https://cloud.google.com/iam/docs/keys-create-delete), and download the JSON key file. The service account will need to be assigned the "Vertex AI User" role. - - Set the `GOOGLE_APPLICATION_CREDENTIALS` environment variable to the absolute path of the JSON file. - - You can temporarily set the environment variable in your current shell session: - ```bash - export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/keyfile.json" - ``` - - For repeated use, you can add the command to your shell's configuration file (e.g., `~/.bashrc`). - ```bash - echo 'export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/keyfile.json"' >> ~/.bashrc - source ~/.bashrc - ``` - :warning: Be advised that when you export service account credentials inside your shell configuration file, any other process executed from the shell can read it. - - - **Required Environment Variables for ADC:** - - When using ADC (either with `gcloud` or a service account), you must also set the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` environment variables. In the following methods, replace `YOUR_PROJECT_ID` and `YOUR_PROJECT_LOCATION` with the relevant values for your project: - - You can temporarily set these environment variables in your current shell session using the following commands: - ```bash - export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID" - export GOOGLE_CLOUD_LOCATION="YOUR_PROJECT_LOCATION" # e.g., us-central1 - ``` - - For repeated use, you can add the environment variables to your [.env file](#persisting-environment-variables-with-env-files) or your shell's configuration file (like `~/.bashrc`, `~/.zshrc`, or `~/.profile`). For example, the following commands add the environment variables to a `~/.bashrc` file: - ```bash - echo 'export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"' >> ~/.bashrc - echo 'export GOOGLE_CLOUD_LOCATION="YOUR_PROJECT_LOCATION"' >> ~/.bashrc - source ~/.bashrc - ``` - -4. **Cloud Shell:** - - This option is only available when running in a Google Cloud Shell environment. - - It automatically uses the credentials of the logged-in user in the Cloud Shell environment. - - This is the default authentication method when running in Cloud Shell and no other method is configured. - - :warning: Be advised that when you export your API key inside your shell configuration file, any other process executed from the shell can read it. - -### Persisting Environment Variables with `.env` Files - -You can create a **`.gemini/.env`** file in your project directory or in your home directory. Creating a plain **`.env`** file also works, but `.gemini/.env` is recommended to keep Gemini variables isolated from other tools. - -**Important:** Some environment variables (like `DEBUG` and `DEBUG_MODE`) are automatically excluded from project `.env` files to prevent interference with gemini-cli behavior. Use `.gemini/.env` files for gemini-cli specific variables. - -Gemini CLI automatically loads environment variables from the **first** `.env` file it finds, using the following search order: - -1. Starting in the **current directory** and moving upward toward `/`, for each directory it checks: - 1. `.gemini/.env` - 2. `.env` -2. If no file is found, it falls back to your **home directory**: - - `~/.gemini/.env` - - `~/.env` - -> **Important:** The search stops at the **first** file encounteredโ€”variables are **not merged** across multiple files. - -#### Examples - -**Project-specific overrides** (take precedence when you are inside the project): - -```bash -mkdir -p .gemini -echo 'GOOGLE_CLOUD_PROJECT="your-project-id"' >> .gemini/.env -``` - -**User-wide settings** (available in every directory): - -```bash -mkdir -p ~/.gemini -cat >> ~/.gemini/.env <<'EOF' -GOOGLE_CLOUD_PROJECT="your-project-id" -GEMINI_API_KEY="your-gemini-api-key" -EOF -``` - -## Non-Interactive Mode / Headless Environments - -When running the Gemini CLI in a non-interactive environment, you cannot use the interactive login flow. -Instead, you must configure authentication using environment variables. - -The CLI will automatically detect if it is running in a non-interactive terminal and will use one of the -following authentication methods if available: - -1. **Gemini API Key:** - - Set the `GEMINI_API_KEY` environment variable. - - The CLI will use this key to authenticate with the Gemini API. - -2. **Vertex AI:** - - Set the `GOOGLE_GENAI_USE_VERTEXAI=true` environment variable. - - **Using an API Key:** Set the `GOOGLE_API_KEY` environment variable. - - **Using Application Default Credentials (ADC):** - - Run `gcloud auth application-default login` in your environment to configure ADC. - - Ensure the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` environment variables are set. - -If none of these environment variables are set in a non-interactive session, the CLI will exit with an error. - -For comprehensive guidance on using Gemini CLI programmatically and in -automation workflows, see the [Headless Mode Guide](../headless.md). +See: [Getting Started - Authentication Setup](../get-started/authentication.md). diff --git a/docs/checkpointing.md b/docs/cli/checkpointing.md similarity index 100% rename from docs/checkpointing.md rename to docs/cli/checkpointing.md diff --git a/docs/cli/commands.md b/docs/cli/commands.md index a2de256709..7caeebf94c 100644 --- a/docs/cli/commands.md +++ b/docs/cli/commands.md @@ -21,7 +21,7 @@ Slash commands provide meta-level control over the CLI itself. - Linux/macOS: `~/.gemini/tmp//` - Windows: `C:\Users\\.gemini\tmp\\` - When you run `/chat list`, the CLI only scans these specific directories to find available checkpoints. - - **Note:** These checkpoints are for manually saving and resuming conversation states. For automatic checkpoints created before file modifications, see the [Checkpointing documentation](../checkpointing.md). + - **Note:** These checkpoints are for manually saving and resuming conversation states. For automatic checkpoints created before file modifications, see the [Checkpointing documentation](./checkpointing.md). - **`resume`** - **Description:** Resumes a conversation from a previous save. - **Usage:** `/chat resume ` @@ -62,7 +62,7 @@ Slash commands provide meta-level control over the CLI itself. - **Description:** Open a dialog for selecting supported editors. - **`/extensions`** - - **Description:** Lists all active extensions in the current Gemini CLI session. See [Gemini CLI Extensions](../extension.md). + - **Description:** Lists all active extensions in the current Gemini CLI session. See [Gemini CLI Extensions](../extensions/index.md). - **`/help`** (or **`/?`**) - **Description:** Display help information about Gemini CLI, including available commands and their usage. @@ -87,12 +87,12 @@ Slash commands provide meta-level control over the CLI itself. - **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:** 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). + - **Note:** For more details on how `GEMINI.md` files contribute to hierarchical memory, see the [CLI Configuration documentation](../get-started/configuration.md). - **`/restore`** - **Description:** Restores the project files to the state they were in just before a tool was executed. This is particularly useful for undoing file edits made by a tool. If run without a tool call ID, it will list available checkpoints to restore from. - **Usage:** `/restore [tool_call_id]` - - **Note:** Only available if the CLI is invoked with the `--checkpointing` option or configured via [settings](./configuration.md). See [Checkpointing documentation](../checkpointing.md) for more details. + - **Note:** Only available if the CLI is invoked with the `--checkpointing` option or configured via [settings](../get-started/configuration.md). See [Checkpointing documentation](../checkpointing.md) for more details. - **`/settings`** - **Description:** Open the settings editor to view and modify Gemini CLI settings. @@ -142,246 +142,7 @@ Slash commands provide meta-level control over the CLI itself. ### Custom Commands -For a quick start, see the [example](#example-a-pure-function-refactoring-command) below. - -Custom commands allow you to save and reuse your favorite or most frequently used prompts as personal shortcuts within Gemini CLI. You can create commands that are specific to a single project or commands that are available globally across all your projects, streamlining your workflow and ensuring consistency. - -#### File Locations & Precedence - -Gemini CLI discovers commands from two locations, loaded in a specific order: - -1. **User Commands (Global):** Located in `~/.gemini/commands/`. These commands are available in any project you are working on. -2. **Project Commands (Local):** Located in `/.gemini/commands/`. These commands are specific to the current project and can be checked into version control to be shared with your team. - -If a command in the project directory has the same name as a command in the user directory, the **project command will always be used.** This allows projects to override global commands with project-specific versions. - -#### Naming and Namespacing - -The name of a command is determined by its file path relative to its `commands` directory. Subdirectories are used to create namespaced commands, with the path separator (`/` or `\`) being converted to a colon (`:`). - -- A file at `~/.gemini/commands/test.toml` becomes the command `/test`. -- A file at `/.gemini/commands/git/commit.toml` becomes the namespaced command `/git:commit`. - -#### TOML File Format (v1) - -Your command definition files must be written in the TOML format and use the `.toml` file extension. - -##### Required Fields - -- `prompt` (String): The prompt that will be sent to the Gemini model when the command is executed. This can be a single-line or multi-line string. - -##### Optional Fields - -- `description` (String): A brief, one-line description of what the command does. This text will be displayed next to your command in the `/help` menu. **If you omit this field, a generic description will be generated from the filename.** - -#### Handling Arguments - -Custom commands support two powerful methods for handling arguments. The CLI automatically chooses the correct method based on the content of your command's `prompt`. - -##### 1. Context-Aware Injection with `{{args}}` - -If your `prompt` contains the special placeholder `{{args}}`, the CLI will replace that placeholder with the text the user typed after the command name. - -The behavior of this injection depends on where it is used: - -**A. Raw Injection (Outside Shell Commands)** - -When used in the main body of the prompt, the arguments are injected exactly as the user typed them. - -**Example (`git/fix.toml`):** - -```toml -# Invoked via: /git:fix "Button is misaligned" - -description = "Generates a fix for a given issue." -prompt = "Please provide a code fix for the issue described here: {{args}}." -``` - -The model receives: `Please provide a code fix for the issue described here: "Button is misaligned".` - -**B. Using Arguments in Shell Commands (Inside `!{...}` Blocks)** - -When you use `{{args}}` inside a shell injection block (`!{...}`), the arguments are automatically **shell-escaped** before replacement. This allows you to safely pass arguments to shell commands, ensuring the resulting command is syntactically correct and secure while preventing command injection vulnerabilities. - -**Example (`/grep-code.toml`):** - -```toml -prompt = """ -Please summarize the findings for the pattern `{{args}}`. - -Search Results: -!{grep -r {{args}} .} -""" -``` - -When you run `/grep-code It's complicated`: - -1. The CLI sees `{{args}}` used both outside and inside `!{...}`. -2. Outside: The first `{{args}}` is replaced raw with `It's complicated`. -3. Inside: The second `{{args}}` is replaced with the escaped version (e.g., on Linux: `"It's complicated"`). -4. The command executed is `grep -r "It's complicated" .`. -5. The CLI prompts you to confirm this exact, secure command before execution. -6. The final prompt is sent. - -##### 2. Default Argument Handling - -If your `prompt` does **not** contain the special placeholder `{{args}}`, the CLI uses a default behavior for handling arguments. - -If you provide arguments to the command (e.g., `/mycommand arg1`), the CLI will append the full command you typed to the end of the prompt, separated by two newlines. This allows the model to see both the original instructions and the specific arguments you just provided. - -If you do **not** provide any arguments (e.g., `/mycommand`), the prompt is sent to the model exactly as it is, with nothing appended. - -**Example (`changelog.toml`):** - -This example shows how to create a robust command by defining a role for the model, explaining where to find the user's input, and specifying the expected format and behavior. - -```toml -# In: /.gemini/commands/changelog.toml -# Invoked via: /changelog 1.2.0 added "Support for default argument parsing." - -description = "Adds a new entry to the project's CHANGELOG.md file." -prompt = """ -# Task: Update Changelog - -You are an expert maintainer of this software project. A user has invoked a command to add a new entry to the changelog. - -**The user's raw command is appended below your instructions.** - -Your task is to parse the ``, ``, and `` from their input and use the `write_file` tool to correctly update the `CHANGELOG.md` file. - -## Expected Format -The command follows this format: `/changelog ` -- `` must be one of: "added", "changed", "fixed", "removed". - -## Behavior -1. Read the `CHANGELOG.md` file. -2. Find the section for the specified ``. -3. Add the `` under the correct `` heading. -4. If the version or type section doesn't exist, create it. -5. Adhere strictly to the "Keep a Changelog" format. -""" -``` - -When you run `/changelog 1.2.0 added "New feature"`, the final text sent to the model will be the original prompt followed by two newlines and the command you typed. - -##### 3. Executing Shell Commands with `!{...}` - -You can make your commands dynamic by executing shell commands directly within your `prompt` and injecting their output. This is ideal for gathering context from your local environment, like reading file content or checking the status of Git. - -When a custom command attempts to execute a shell command, Gemini CLI will now prompt you for confirmation before proceeding. This is a security measure to ensure that only intended commands can be run. - -**How It Works:** - -1. **Inject Commands:** Use the `!{...}` syntax. -2. **Argument Substitution:** If `{{args}}` is present inside the block, it is automatically shell-escaped (see [Context-Aware Injection](#1-context-aware-injection-with-args) above). -3. **Robust Parsing:** The parser correctly handles complex shell commands that include nested braces, such as JSON payloads. **Note:** The content inside `!{...}` must have balanced braces (`{` and `}`). If you need to execute a command containing unbalanced braces, consider wrapping it in an external script file and calling the script within the `!{...}` block. -4. **Security Check and Confirmation:** The CLI performs a security check on the final, resolved command (after arguments are escaped and substituted). A dialog will appear showing the exact command(s) to be executed. -5. **Execution and Error Reporting:** The command is executed. If the command fails, the output injected into the prompt will include the error messages (stderr) followed by a status line, e.g., `[Shell command exited with code 1]`. This helps the model understand the context of the failure. - -**Example (`git/commit.toml`):** - -This command gets the staged git diff and uses it to ask the model to write a commit message. - -````toml -# In: /.gemini/commands/git/commit.toml -# Invoked via: /git:commit - -description = "Generates a Git commit message based on staged changes." - -# The prompt uses !{...} to execute the command and inject its output. -prompt = """ -Please generate a Conventional Commit message based on the following git diff: - -```diff -!{git diff --staged} -``` - -""" - -```` - -When you run `/git:commit`, the CLI first executes `git diff --staged`, then replaces `!{git diff --staged}` with the output of that command before sending the final, complete prompt to the model. - -##### 4. Injecting File Content with `@{...}` - -You can directly embed the content of a file or a directory listing into your prompt using the `@{...}` syntax. This is useful for creating commands that operate on specific files. - -**How It Works:** - -- **File Injection**: `@{path/to/file.txt}` is replaced by the content of `file.txt`. -- **Multimodal Support**: If the path points to a supported image (e.g., PNG, JPEG), PDF, audio, or video file, it will be correctly encoded and injected as multimodal input. Other binary files are handled gracefully and skipped. -- **Directory Listing**: `@{path/to/dir}` is traversed and each file present within the directory and all subdirectories are inserted into the prompt. This respects `.gitignore` and `.geminiignore` if enabled. -- **Workspace-Aware**: The command searches for the path in the current directory and any other workspace directories. Absolute paths are allowed if they are within the workspace. -- **Processing Order**: File content injection with `@{...}` is processed _before_ shell commands (`!{...}`) and argument substitution (`{{args}}`). -- **Parsing**: The parser requires the content inside `@{...}` (the path) to have balanced braces (`{` and `}`). - -**Example (`review.toml`):** - -This command injects the content of a _fixed_ best practices file (`docs/best-practices.md`) and uses the user's arguments to provide context for the review. - -```toml -# In: /.gemini/commands/review.toml -# Invoked via: /review FileCommandLoader.ts - -description = "Reviews the provided context using a best practice guide." -prompt = """ -You are an expert code reviewer. - -Your task is to review {{args}}. - -Use the following best practices when providing your review: - -@{docs/best-practices.md} -""" -``` - -When you run `/review FileCommandLoader.ts`, the `@{docs/best-practices.md}` placeholder is replaced by the content of that file, and `{{args}}` is replaced by the text you provided, before the final prompt is sent to the model. - ---- - -#### Example: A "Pure Function" Refactoring Command - -Let's create a global command that asks the model to refactor a piece of code. - -**1. Create the file and directories:** - -First, ensure the user commands directory exists, then create a `refactor` subdirectory for organization and the final TOML file. - -```bash -mkdir -p ~/.gemini/commands/refactor -touch ~/.gemini/commands/refactor/pure.toml -``` - -**2. Add the content to the file:** - -Open `~/.gemini/commands/refactor/pure.toml` in your editor and add the following content. We are including the optional `description` for best practice. - -```toml -# In: ~/.gemini/commands/refactor/pure.toml -# This command will be invoked via: /refactor:pure - -description = "Asks the model to refactor the current context into a pure function." - -prompt = """ -Please analyze the code I've provided in the current context. -Refactor it into a pure function. - -Your response should include: -1. The refactored, pure function code block. -2. A brief explanation of the key changes you made and why they contribute to purity. -""" -``` - -**3. Run the Command:** - -That's it! You can now run your command in the CLI. First, you might add a file to the context, and then invoke your command: - -``` -> @my-messy-function.js -> /refactor:pure -``` - -Gemini CLI will then execute the multi-line prompt defined in your TOML file. +Custom commands allow you to create personalized shortcuts for your most-used prompts. For detailed instructions on how to create, manage, and use them, please see the dedicated [Custom Commands documentation](./custom-commands.md). ## Input Prompt Shortcuts diff --git a/docs/cli/custom-commands.md b/docs/cli/custom-commands.md new file mode 100644 index 0000000000..b245e420eb --- /dev/null +++ b/docs/cli/custom-commands.md @@ -0,0 +1,240 @@ +### Custom Commands + +Custom commands let you save and reuse your favorite or most frequently used prompts as personal shortcuts within Gemini CLI. You can create commands that are specific to a single project or commands that are available globally across all your projects, streamlining your workflow and ensuring consistency. + +#### File locations and precedence + +Gemini CLI discovers commands from two locations, loaded in a specific order: + +1. **User Commands (Global):** Located in `~/.gemini/commands/`. These commands are available in any project you are working on. +2. **Project Commands (Local):** Located in `/.gemini/commands/`. These commands are specific to the current project and can be checked into version control to be shared with your team. + +If a command in the project directory has the same name as a command in the user directory, the **project command will always be used.** This allows projects to override global commands with project-specific versions. + +#### Naming and namespacing + +The name of a command is determined by its file path relative to its `commands` directory. Subdirectories are used to create namespaced commands, with the path separator (`/` or `\`) being converted to a colon (`:`). + +- A file at `~/.gemini/commands/test.toml` becomes the command `/test`. +- A file at `/.gemini/commands/git/commit.toml` becomes the namespaced command `/git:commit`. + +#### TOML File Format (v1) + +Your command definition files must be written in the TOML format and use the `.toml` file extension. + +##### Required fields + +- `prompt` (String): The prompt that will be sent to the Gemini model when the command is executed. This can be a single-line or multi-line string. + +##### Optional fields + +- `description` (String): A brief, one-line description of what the command does. This text will be displayed next to your command in the `/help` menu. **If you omit this field, a generic description will be generated from the filename.** + +#### Handling arguments + +Custom commands support two powerful methods for handling arguments. The CLI automatically chooses the correct method based on the content of your command\'s `prompt`. + +##### 1. Context-aware injection with `{{args}}` + +If your `prompt` contains the special placeholder `{{args}}`, the CLI will replace that placeholder with the text the user typed after the command name. + +The behavior of this injection depends on where it is used: + +**A. Raw injection (outside Shell commands)** + +When used in the main body of the prompt, the arguments are injected exactly as the user typed them. + +**Example (`git/fix.toml`):** + +```toml +# Invoked via: /git:fix "Button is misaligned" + +description = "Generates a fix for a given issue." +prompt = "Please provide a code fix for the issue described here: {{args}}." +``` + +The model receives: `Please provide a code fix for the issue described here: "Button is misaligned".` + +**B. Using arguments in Shell commands (inside `!{...}` blocks)** + +When you use `{{args}}` inside a shell injection block (`!{...}`), the arguments are automatically **shell-escaped** before replacement. This allows you to safely pass arguments to shell commands, ensuring the resulting command is syntactically correct and secure while preventing command injection vulnerabilities. + +**Example (`/grep-code.toml`):** + +```toml +prompt = """ +Please summarize the findings for the pattern `{{args}}`. + +Search Results: +!{grep -r {{args}} .} +""" +``` + +When you run `/grep-code It\'s complicated`: + +1. The CLI sees `{{args}}` used both outside and inside `!{...}`. +2. Outside: The first `{{args}}` is replaced raw with `It\'s complicated`. +3. Inside: The second `{{args}}` is replaced with the escaped version (e.g., on Linux: `"It\'s complicated"`). +4. The command executed is `grep -r "It\'s complicated" .`. +5. The CLI prompts you to confirm this exact, secure command before execution. +6. The final prompt is sent. + +##### 2. Default argument handling + +If your `prompt` does **not** contain the special placeholder `{{args}}`, the CLI uses a default behavior for handling arguments. + +If you provide arguments to the command (e.g., `/mycommand arg1`), the CLI will append the full command you typed to the end of the prompt, separated by two newlines. This allows the model to see both the original instructions and the specific arguments you just provided. + +If you do **not** provide any arguments (e.g., `/mycommand`), the prompt is sent to the model exactly as it is, with nothing appended. + +**Example (`changelog.toml`):** + +This example shows how to create a robust command by defining a role for the model, explaining where to find the user's input, and specifying the expected format and behavior. + +```toml +# In: /.gemini/commands/changelog.toml +# Invoked via: /changelog 1.2.0 added "Support for default argument parsing." + +description = "Adds a new entry to the project\'s CHANGELOG.md file." +prompt = """ +# Task: Update Changelog + +You are an expert maintainer of this software project. A user has invoked a command to add a new entry to the changelog. + +**The user\'s raw command is appended below your instructions.** + +Your task is to parse the ``, ``, and `` from their input and use the `write_file` tool to correctly update the `CHANGELOG.md` file. + +## Expected Format +The command follows this format: `/changelog ` +- `` must be one of: "added", "changed", "fixed", "removed". + +## Behavior +1. Read the `CHANGELOG.md` file. +2. Find the section for the specified ``. +3. Add the `` under the correct `` heading. +4. If the version or type section doesn\'t exist, create it. +5. Adhere strictly to the "Keep a Changelog" format. +""" +``` + +When you run `/changelog 1.2.0 added "New feature"`, the final text sent to the model will be the original prompt followed by two newlines and the command you typed. + +##### 3. Executing Shell commands with `!{...}` + +You can make your commands dynamic by executing shell commands directly within your `prompt` and injecting their output. This is ideal for gathering context from your local environment, like reading file content or checking the status of Git. + +When a custom command attempts to execute a shell command, Gemini CLI will now prompt you for confirmation before proceeding. This is a security measure to ensure that only intended commands can be run. + +**How it works:** + +1. **Inject commands:** Use the `!{...}` syntax. +2. **Argument substitution:** If `{{args}}` is present inside the block, it is automatically shell-escaped (see [Context-Aware Injection](#1-context-aware-injection-with-args) above). +3. **Robust parsing:** The parser correctly handles complex shell commands that include nested braces, such as JSON payloads. **Note:** The content inside `!{...}` must have balanced braces (`{` and `}`). If you need to execute a command containing unbalanced braces, consider wrapping it in an external script file and calling the script within the `!{...}` block. +4. **Security check and confirmation:** The CLI performs a security check on the final, resolved command (after arguments are escaped and substituted). A dialog will appear showing the exact command(s) to be executed. +5. **Execution and error reporting:** The command is executed. If the command fails, the output injected into the prompt will include the error messages (stderr) followed by a status line, e.g., `[Shell command exited with code 1]`. This helps the model understand the context of the failure. + +**Example (`git/commit.toml`):** + +This command gets the staged git diff and uses it to ask the model to write a commit message. + +````toml +# In: /.gemini/commands/git/commit.toml +# Invoked via: /git:commit + +description = "Generates a Git commit message based on staged changes." + +# The prompt uses !{...} to execute the command and inject its output. +prompt = """ +Please generate a Conventional Commit message based on the following git diff: + +```diff +!{git diff --staged} +``` + +""" + +```` + +When you run `/git:commit`, the CLI first executes `git diff --staged`, then replaces `!{git diff --staged}` with the output of that command before sending the final, complete prompt to the model. + +##### 4. Injecting file content with `@{...}` + +You can directly embed the content of a file or a directory listing into your prompt using the `@{...}` syntax. This is useful for creating commands that operate on specific files. + +**How it works:** + +- **File injection**: `@{path/to/file.txt}` is replaced by the content of `file.txt`. +- **Multimodal support**: If the path points to a supported image (e.g., PNG, JPEG), PDF, audio, or video file, it will be correctly encoded and injected as multimodal input. Other binary files are handled gracefully and skipped. +- **Directory listing**: `@{path/to/dir}` is traversed and each file present within the directory and all subdirectories is inserted into the prompt. This respects `.gitignore` and `.geminiignore` if enabled. +- **Workspace-aware**: The command searches for the path in the current directory and any other workspace directories. Absolute paths are allowed if they are within the workspace. +- **Processing order**: File content injection with `@{...}` is processed _before_ shell commands (`!{...}`) and argument substitution (`{{args}}`). +- **Parsing**: The parser requires the content inside `@{...}` (the path) to have balanced braces (`{` and `}`). + +**Example (`review.toml`):** + +This command injects the content of a _fixed_ best practices file (`docs/best-practices.md`) and uses the user\'s arguments to provide context for the review. + +```toml +# In: /.gemini/commands/review.toml +# Invoked via: /review FileCommandLoader.ts + +description = "Reviews the provided context using a best practice guide." +prompt = """ +You are an expert code reviewer. + +Your task is to review {{args}}. + +Use the following best practices when providing your review: + +@{docs/best-practices.md} +""" +``` + +When you run `/review FileCommandLoader.ts`, the `@{docs/best-practices.md}` placeholder is replaced by the content of that file, and `{{args}}` is replaced by the text you provided, before the final prompt is sent to the model. + +--- + +#### Example: A "Pure Function" refactoring command + +Let's create a global command that asks the model to refactor a piece of code. + +**1. Create the file and directories:** + +First, ensure the user commands directory exists, then create a `refactor` subdirectory for organization and the final TOML file. + +```bash +mkdir -p ~/.gemini/commands/refactor +touch ~/.gemini/commands/refactor/pure.toml +``` + +**2. Add the content to the file:** + +Open `~/.gemini/commands/refactor/pure.toml` in your editor and add the following content. We are including the optional `description` for best practice. + +```toml +# In: ~/.gemini/commands/refactor/pure.toml +# This command will be invoked via: /refactor:pure + +description = "Asks the model to refactor the current context into a pure function." + +prompt = """ +Please analyze the code I\'ve provided in the current context. +Refactor it into a pure function. + +Your response should include: +1. The refactored, pure function code block. +2. A brief explanation of the key changes you made and why they contribute to purity. +""" +``` + +**3. Run the Command:** + +That's it! You can now run your command in the CLI. First, you might add a file to the context, and then invoke your command: + +``` +> @my-messy-function.js +> /refactor:pure +``` + +Gemini CLI will then execute the multi-line prompt defined in your TOML file. diff --git a/docs/cli/enterprise.md b/docs/cli/enterprise.md index 9333bf1c4b..2322d3f440 100644 --- a/docs/cli/enterprise.md +++ b/docs/cli/enterprise.md @@ -6,7 +6,7 @@ This document outlines configuration patterns and best practices for deploying a ## Centralized Configuration: The System Settings File -The most powerful tools for enterprise administration are the system-wide settings files. These files allow you to define a baseline configuration (`system-defaults.json`) and a set of overrides (`settings.json`) that apply to all users on a machine. For a complete overview of configuration options, see the [Configuration documentation](./configuration.md). +The most powerful tools for enterprise administration are the system-wide settings files. These files allow you to define a baseline configuration (`system-defaults.json`) and a set of overrides (`settings.json`) that apply to all users on a machine. For a complete overview of configuration options, see the [Configuration documentation](../get-started/configuration.md). Settings are merged from four files. The precedence order for single-value settings (like `theme`) is: @@ -276,7 +276,7 @@ To mitigate the risk of potentially harmful operations, you can enforce the use } ``` -You can also specify a custom, hardened Docker image for the sandbox using the `--sandbox-image` command-line argument or by building a custom `sandbox.Dockerfile` as described in the [Sandboxing documentation](./configuration.md#sandboxing). +You can also specify a custom, hardened Docker image for the sandbox using the `--sandbox-image` command-line argument or by building a custom `sandbox.Dockerfile` as described in the [Sandboxing documentation](./sandbox.md). ## Controlling Network Access via Proxy @@ -301,7 +301,7 @@ In corporate environments with strict network policies, you can configure Gemini ## Telemetry and Auditing -For auditing and monitoring purposes, you can configure Gemini CLI to send telemetry data to a central location. This allows you to track tool usage and other events. For more information, see the [telemetry documentation](../telemetry.md). +For auditing and monitoring purposes, you can configure Gemini CLI to send telemetry data to a central location. This allows you to track tool usage and other events. For more information, see the [telemetry documentation](./telemetry.md). **Example:** Enable telemetry and send it to a local OTLP collector. If `otlpEndpoint` is not specified, it defaults to `http://localhost:4317`. diff --git a/docs/gemini-ignore.md b/docs/cli/gemini-ignore.md similarity index 94% rename from docs/gemini-ignore.md rename to docs/cli/gemini-ignore.md index 8e8fdf2070..58b81cbaad 100644 --- a/docs/gemini-ignore.md +++ b/docs/cli/gemini-ignore.md @@ -6,7 +6,7 @@ The Gemini CLI includes the ability to automatically ignore files, similar to `. ## How it works -When you add a path to your `.geminiignore` file, tools that respect this file will exclude matching files and directories from their operations. For example, when you use the [`read_many_files`](./tools/multi-file.md) command, any paths in your `.geminiignore` file will be automatically excluded. +When you add a path to your `.geminiignore` file, tools that respect this file will exclude matching files and directories from their operations. For example, when you use the [`read_many_files`](../tools/multi-file.md) command, any paths in your `.geminiignore` file will be automatically excluded. For the most part, `.geminiignore` follows the conventions of `.gitignore` files: diff --git a/docs/cli/gemini-md.md b/docs/cli/gemini-md.md new file mode 100644 index 0000000000..1f1fb270bc --- /dev/null +++ b/docs/cli/gemini-md.md @@ -0,0 +1,85 @@ +# Provide Context with GEMINI.md Files + +Context files, which use the default name `GEMINI.md`, are a powerful feature for providing instructional context to the Gemini model. You can use these files to give project-specific instructions, define a persona, or provide coding style guides to make the AI's responses more accurate and tailored to your needs. + +Instead of repeating instructions in every prompt, you can define them once in a context file. + +## Understand the context hierarchy + +The CLI uses a hierarchical system to source context. It loads various context files from several locations, concatenates the contents of all found files, and sends them to the model with every prompt. The CLI loads files in the following order: + +1. **Global context file:** + - **Location:** `~/.gemini/GEMINI.md` (in your user home directory). + - **Scope:** Provides default instructions for all your projects. + +2. **Project root and ancestor context files:** + - **Location:** The CLI searches for a `GEMINI.md` file in your current working directory and then in each parent directory up to the project root (identified by a `.git` folder). + - **Scope:** Provides context relevant to the entire project. + +3. **Sub-directory context files:** + - **Location:** The CLI also scans for `GEMINI.md` files in subdirectories below your current working directory. It respects rules in `.gitignore` and `.geminiignore`. + - **Scope:** Lets you write highly specific instructions for a particular component or module. + +The CLI footer displays the number of loaded context files, which gives you a quick visual cue of the active instructional context. + +### Example `GEMINI.md` file + +Here is an example of what you can include in a `GEMINI.md` file at the root of a TypeScript project: + +```markdown +# Project: My TypeScript Library + +## General Instructions + +- When you generate new TypeScript code, follow the existing coding style. +- Ensure all new functions and classes have JSDoc comments. +- Prefer functional programming paradigms where appropriate. + +## Coding Style + +- Use 2 spaces for indentation. +- Prefix interface names with `I` (for example, `IUserService`). +- Always use strict equality (`===` and `!==`). +``` + +## Manage context with the `/memory` command + +You can interact with the loaded context files by using the `/memory` command. + +- **`/memory show`**: Displays the full, concatenated content of the current hierarchical memory. This lets you inspect the exact instructional context being provided to the model. +- **`/memory refresh`**: Forces a re-scan and reload of all `GEMINI.md` files from all configured locations. +- **`/memory add `**: Appends your text to your global `~/.gemini/GEMINI.md` file. This lets you add persistent memories on the fly. + +## Modularize context with imports + +You can break down large `GEMINI.md` files into smaller, more manageable components by importing content from other files using the `@file.md` syntax. This feature supports both relative and absolute paths. + +**Example `GEMINI.md` with imports:** + +```markdown +# Main GEMINI.md file + +This is the main content. + +@./components/instructions.md + +More content here. + +@../shared/style-guide.md +``` + +For more details, see the [Memory Import Processor](../core/memport.md) documentation. + +## Customize the context file name + +While `GEMINI.md` is the default filename, you can configure this in your `settings.json` file. To specify a different name or a list of names, use the `context.fileName` property. + +**Example `settings.json`:** + +```json +{ + "context": { + "fileName": ["AGENTS.md", "CONTEXT.md", "GEMINI.md"] + } +} +``` diff --git a/docs/headless.md b/docs/cli/headless.md similarity index 96% rename from docs/headless.md rename to docs/cli/headless.md index a4fcc425cd..45e53a2d13 100644 --- a/docs/headless.md +++ b/docs/cli/headless.md @@ -244,7 +244,7 @@ Key command-line options for headless usage: | `--yolo`, `-y` | Auto-approve all actions | `gemini -p "query" --yolo` | | `--approval-mode` | Set approval mode | `gemini -p "query" --approval-mode auto_edit` | -For complete details on all available configuration options, settings files, and environment variables, see the [Configuration Guide](./cli/configuration.md). +For complete details on all available configuration options, settings files, and environment variables, see the [Configuration Guide](../get-started/configuration.md). ## Examples @@ -317,7 +317,7 @@ tail -5 usage.log ## Resources -- [CLI Configuration](./cli/configuration.md) - Complete configuration guide -- [Authentication](./cli/authentication.md) - Setup authentication -- [Commands](./cli/commands.md) - Interactive commands reference -- [Tutorials](./cli/tutorials.md) - Step-by-step automation guides +- [CLI Configuration](../get-started/configuration.md) - Complete configuration guide +- [Authentication](../get-started/authentication.md) - Setup authentication +- [Commands](./commands.md) - Interactive commands reference +- [Tutorials](./tutorials.md) - Step-by-step automation guides diff --git a/docs/cli/index.md b/docs/cli/index.md index 13cf37470c..3ece7321cf 100644 --- a/docs/cli/index.md +++ b/docs/cli/index.md @@ -2,16 +2,25 @@ Within Gemini CLI, `packages/cli` is the frontend for users to send and receive prompts with the Gemini AI model and its associated tools. For a general overview of Gemini CLI, see the [main documentation page](../index.md). -## Navigating this section +## Basic features -- **[Authentication](./authentication.md):** A guide to setting up authentication with Google's AI services. -- **[Commands](./commands.md):** A reference for Gemini CLI commands (e.g., `/help`, `/tools`, `/theme`). -- **[Configuration](./configuration.md):** A guide to tailoring Gemini CLI behavior using configuration files. -- **[Enterprise](./enterprise.md):** A guide to enterprise configuration. -- **[Headless Mode](../headless.md):** A comprehensive guide to using Gemini CLI programmatically for scripting and automation. -- **[Token Caching](./token-caching.md):** Optimize API costs through token caching. -- **[Themes](./themes.md)**: A guide to customizing the CLI's appearance with different themes. -- **[Tutorials](tutorials.md)**: A tutorial showing how to use Gemini CLI to automate a development task. +- **[Commands](./commands.md):** A reference for all built-in slash commands (e.g., `/help`, `/chat`, `/tools`). +- **[Custom Commands](./custom-commands.md):** Create your own commands and shortcuts for frequently used prompts. +- **[Headless Mode](./headless.md):** Use Gemini CLI programmatically for scripting and automation. +- **[Themes](./themes.md):** Customizing the CLI's appearance with different themes. +- **[Keyboard Shortcuts](./keyboard-shortcuts.md):** A reference for all keyboard shortcuts to improve your workflow. +- **[Tutorials](./tutorials.md):** Step-by-step guides for common tasks. + +## Advanced features + +- **[Checkpointing](./checkpointing.md):** Automatically save and restore snapshots of your session and files. +- **[Enterprise Configuration](./enterprise.md):** Deploying and manage Gemini CLI in an enterprise environment. +- **[Sandboxing](./sandbox.md):** Isolate tool execution in a secure, containerized environment. +- **[Telemetry](./telemetry.md):** Configure observability to monitor usage and performance. +- **[Token Caching](./token-caching.md):** Optimize API costs by caching tokens. +- **[Trusted Folders](./trusted-folders.md):** A security feature to control which projects can use the full capabilities of the CLI. +- **[Ignoring Files (.geminiignore)](./gemini-ignore.md):** Exclude specific files and directories from being accessed by tools. +- **[Context Files (GEMINI.md)](./gemini-md.md):** Provide persistent, hierarchical context to the model. ## Non-interactive mode @@ -29,4 +38,4 @@ You can also use the `--prompt` or `-p` flag: gemini -p "What is fine tuning?" ``` -For comprehensive documentation on headless usage, scripting, automation, and advanced examples, see the **[Headless Mode](../headless.md)** guide. +For comprehensive documentation on headless usage, scripting, automation, and advanced examples, see the **[Headless Mode](./headless.md)** guide. diff --git a/docs/keyboard-shortcuts.md b/docs/cli/keyboard-shortcuts.md similarity index 100% rename from docs/keyboard-shortcuts.md rename to docs/cli/keyboard-shortcuts.md diff --git a/docs/sandbox.md b/docs/cli/sandbox.md similarity index 95% rename from docs/sandbox.md rename to docs/cli/sandbox.md index 0f336094c8..eb1d1bf149 100644 --- a/docs/sandbox.md +++ b/docs/cli/sandbox.md @@ -152,6 +152,6 @@ gemini -s -p "run shell command: mount | grep workspace" ## Related documentation -- [Configuration](./cli/configuration.md): Full configuration options. -- [Commands](./cli/commands.md): Available commands. -- [Troubleshooting](./troubleshooting.md): General troubleshooting. +- [Configuration](../get-started/configuration.md): Full configuration options. +- [Commands](./commands.md): Available commands. +- [Troubleshooting](../troubleshooting.md): General troubleshooting. diff --git a/docs/telemetry.md b/docs/cli/telemetry.md similarity index 99% rename from docs/telemetry.md rename to docs/cli/telemetry.md index 672f5c5011..ae0947a5f8 100644 --- a/docs/telemetry.md +++ b/docs/cli/telemetry.md @@ -68,7 +68,7 @@ These settings can be overridden by environment variables or CLI flags. `true` or `1` will enable the feature. Any other value will disable it. For detailed information about all configuration options, see the -[Configuration Guide](./cli/configuration.md). +[Configuration Guide](../get-started/configuration.md). ## Google Cloud Telemetry diff --git a/docs/cli/themes.md b/docs/cli/themes.md index 6881832ca0..6954946082 100644 --- a/docs/cli/themes.md +++ b/docs/cli/themes.md @@ -32,7 +32,7 @@ Gemini CLI comes with a selection of pre-defined themes, which you can list usin ### Theme Persistence -Selected themes are saved in Gemini CLI's [configuration](./configuration.md) so your preference is remembered across sessions. +Selected themes are saved in Gemini CLI's [configuration](../get-started/configuration.md) so your preference is remembered across sessions. --- @@ -146,7 +146,7 @@ The theme file must be a valid JSON file that follows the same structure as a cu - Select your custom theme using the `/theme` command in Gemini CLI. Your custom theme will appear in the theme selection dialog. - Or, set it as the default by adding `"theme": "MyCustomTheme"` to the `ui` object in your `settings.json`. -- Custom themes can be set at the user, project, or system level, and follow the same [configuration precedence](./configuration.md) as other settings. +- Custom themes can be set at the user, project, or system level, and follow the same [configuration precedence](../get-started/configuration.md) as other settings. --- diff --git a/docs/trusted-folders.md b/docs/cli/trusted-folders.md similarity index 96% rename from docs/trusted-folders.md rename to docs/cli/trusted-folders.md index 3c1d4098a4..399d0d8d95 100644 --- a/docs/trusted-folders.md +++ b/docs/cli/trusted-folders.md @@ -56,6 +56,6 @@ If you need to change a decision or see all your settings, you have a couple of For advanced users, it's helpful to know the exact order of operations for how trust is determined: -1. **IDE Trust Signal**: If you are using the [IDE Integration](./ide-integration.md), the CLI first asks the IDE if the workspace is trusted. The IDE's response takes highest priority. +1. **IDE Trust Signal**: If you are using the [IDE Integration](../ide-integration/index.md), the CLI first asks the IDE if the workspace is trusted. The IDE's response takes highest priority. 2. **Local Trust File**: If the IDE is not connected, the CLI checks the central `~/.gemini/trustedFolders.json` file. diff --git a/docs/cli/tutorials.md b/docs/cli/tutorials.md index 1f77791dc9..e156809592 100644 --- a/docs/cli/tutorials.md +++ b/docs/cli/tutorials.md @@ -24,7 +24,7 @@ Before you begin, ensure you have the following installed and configured: #### Configure the MCP server in `settings.json` -In your project's root directory, create or open the [`.gemini/settings.json` file](./configuration.md). Within the file, add the `mcpServers` configuration block, which provides instructions for how to launch the GitHub MCP server. +In your project's root directory, create or open the [`.gemini/settings.json` file](../get-started/configuration.md). Within the file, add the `mcpServers` configuration block, which provides instructions for how to launch the GitHub MCP server. ```json { diff --git a/docs/Uninstall.md b/docs/cli/uninstall.md similarity index 100% rename from docs/Uninstall.md rename to docs/cli/uninstall.md diff --git a/docs/core/memport.md b/docs/core/memport.md index 68dd34cc41..e90d195f3c 100644 --- a/docs/core/memport.md +++ b/docs/core/memport.md @@ -43,7 +43,7 @@ More content here. Welcome to my project! -@./getting-started.md +@./get-started.md ## Features diff --git a/docs/extension-releasing.md b/docs/extensions/extension-releasing.md similarity index 98% rename from docs/extension-releasing.md rename to docs/extensions/extension-releasing.md index 86e212c653..dbfef3694d 100644 --- a/docs/extension-releasing.md +++ b/docs/extensions/extension-releasing.md @@ -9,7 +9,7 @@ Git repository releases tend to be the simplest and most flexible approach, whil ## Releasing through a git repository -This is the most flexible and simple option. All you need to do us create a publicly accessible git repo (such as a public github repository) and then users can install your extension using `gemini extensions install `, or for a GitHub repository they can use the simplified `gemini extensions install /` format. They can optionally depend on a specific ref (branch/tag/commit) using the `--ref=` argument, this defaults to the default branch. +This is the most flexible and simple option. All you need to do is create a publicly accessible git repo (such as a public github repository) and then users can install your extension using `gemini extensions install `, or for a GitHub repository they can use the simplified `gemini extensions install /` format. They can optionally depend on a specific ref (branch/tag/commit) using the `--ref=` argument, this defaults to the default branch. Whenever commits are pushed to the ref that a user depends on, they will be prompted to update the extension. Note that this also allows for easy rollbacks, the HEAD commit is always treated as the latest version regardless of the actual version in the `gemini-extension.json` file. @@ -74,7 +74,7 @@ To ensure Gemini CLI can automatically find the correct release asset for each p Archives must be fully contained extensions and have all the standard requirements - specifically the `gemini-extension.json` file must be at the root of the archive. -The rest of the layout should look exactly the same as a typical extension, see [extensions.md](extension.md). +The rest of the layout should look exactly the same as a typical extension, see [extensions.md](./index.md). #### Example GitHub Actions workflow diff --git a/docs/extension.md b/docs/extensions/index.md similarity index 93% rename from docs/extension.md rename to docs/extensions/index.md index a82472bfb9..5c8fe6aabc 100644 --- a/docs/extension.md +++ b/docs/extensions/index.md @@ -106,7 +106,7 @@ The `gemini-extension.json` file contains the configuration for the extension. T - `name`: The name of the extension. This is used to uniquely identify the extension and for conflict resolution when extension commands have the same name as user or project commands. The name should be lowercase or numbers and use dashes instead of underscores or spaces. This is how users will refer to your extension in the CLI. Note that we expect this name to match the extension directory name. - `version`: The version of the extension. -- `mcpServers`: A map of MCP servers to configure. The key is the name of the server, and the value is the server configuration. These servers will be loaded on startup just like MCP servers configured in a [`settings.json` file](./cli/configuration.md). If both an extension and a `settings.json` file configure an MCP server with the same name, the server defined in the `settings.json` file takes precedence. +- `mcpServers`: A map of MCP servers to configure. The key is the name of the server, and the value is the server configuration. These servers will be loaded on startup just like MCP servers configured in a [`settings.json` file](../get-started/configuration.md). If both an extension and a `settings.json` file configure an MCP server with the same name, the server defined in the `settings.json` file takes precedence. - Note that all MCP server configuration options are supported except for `trust`. - `contextFileName`: The name of the file that contains the context for the extension. This will be used to load the context from the extension directory. If this property is not used but a `GEMINI.md` file is present in your extension directory, then that file will be loaded. - `excludeTools`: An array of tool names to exclude from the model. You can also specify command-specific restrictions for tools that support it, like the `run_shell_command` tool. For example, `"excludeTools": ["run_shell_command(rm -rf)"]` will block the `rm -rf` command. Note that this differs from the MCP server `excludeTools` functionality, which can be listed in the MCP server config. @@ -115,7 +115,7 @@ When Gemini CLI starts, it loads all the extensions and merges their configurati ### Custom commands -Extensions can provide [custom commands](./cli/commands.md#custom-commands) by placing TOML files in a `commands/` subdirectory within the extension directory. These commands follow the same format as user and project custom commands and use standard naming conventions. +Extensions can provide [custom commands](../cli/custom-commands.md) by placing TOML files in a `commands/` subdirectory within the extension directory. These commands follow the same format as user and project custom commands and use standard naming conventions. **Example** diff --git a/docs/faq.md b/docs/faq.md new file mode 100644 index 0000000000..675d66815c --- /dev/null +++ b/docs/faq.md @@ -0,0 +1,105 @@ +# Frequently Asked Questions (FAQ) + +This page provides answers to common questions and solutions to frequent problems encountered while using Gemini CLI. + +## General issues + +### Why am I getting an `API error: 429 - Resource exhausted`? + +This error indicates that you have exceeded your API request limit. The Gemini API has rate limits to prevent abuse and ensure fair usage. + +To resolve this, you can: + +- **Check your usage:** Review your API usage in the Google AI Studio or your Google Cloud project dashboard. +- **Optimize your prompts:** If you are making many requests in a short period, try to batch your prompts or introduce delays between requests. +- **Request a quota increase:** If you consistently need a higher limit, you can request a quota increase from Google. + +### Why am I getting an `ERR_REQUIRE_ESM` error when running `npm run start`? + +This error typically occurs in Node.js projects when there is a mismatch between CommonJS and ES Modules. + +This is often due to a misconfiguration in your `package.json` or `tsconfig.json`. Ensure that: + +1. Your `package.json` has `"type": "module"`. +2. Your `tsconfig.json` has `"module": "NodeNext"` or a compatible setting in the `compilerOptions`. + +If the problem persists, try deleting your `node_modules` directory and `package-lock.json` file, and then run `npm install` again. + +### Why don't I see cached token counts in my stats output? + +Cached token information is only displayed when cached tokens are being used. This feature is available for API key users (Gemini API key or Google Cloud Vertex AI) but not for OAuth users (such as Google Personal/Enterprise accounts like Google Gmail or Google Workspace, respectively). This is because the Gemini Code Assist API does not support cached content creation. You can still view your total token usage using the `/stats` command in Gemini CLI. + +## Installation and updates + +### How do I update Gemini CLI to the latest version? + +If you installed it globally via `npm`, update it using the command `npm install -g @google/gemini-cli@latest`. If you compiled it from source, pull the latest changes from the repository, and then rebuild using the command `npm run build`. + +## Platform-specific issues + +### Why does the CLI crash on Windows when I run a command like `chmod +x`? + +Commands like `chmod` are specific to Unix-like operating systems (Linux, macOS). They are not available on Windows by default. + +To resolve this, you can: + +- **Use Windows-equivalent commands:** Instead of `chmod`, you can use `icacls` to modify file permissions on Windows. +- **Use a compatibility layer:** Tools like Git Bash or Windows Subsystem for Linux (WSL) provide a Unix-like environment on Windows where these commands will work. + +## Configuration + +### How do I configure my `GOOGLE_CLOUD_PROJECT`? + +You can configure your Google Cloud Project ID using an environment variable. + +Set the `GOOGLE_CLOUD_PROJECT` environment variable in your shell: + +```bash +export GOOGLE_CLOUD_PROJECT="your-project-id" +``` + +To make this setting permanent, add this line to your shell's startup file (e.g., `~/.bashrc`, `~/.zshrc`). + +### What is the best way to store my API keys securely? + +Exposing API keys in scripts or checking them into source control is a security risk. + +To store your API keys securely, you can: + +- **Use a `.env` file:** Create a `.env` file in your project's `.gemini` directory (`.gemini/.env`) and store your keys there. Gemini CLI will automatically load these variables. +- **Use your system's keyring:** For the most secure storage, use your operating system's secret management tool (like macOS Keychain, Windows Credential Manager, or a secret manager on Linux). You can then have your scripts or environment load the key from the secure storage at runtime. + +### Where are the Gemini CLI configuration and settings files stored? + +The Gemini CLI configuration is stored in two `settings.json` files: + +1. In your home directory: `~/.gemini/settings.json`. +2. In your project's root directory: `./.gemini/settings.json`. + +Refer to [Gemini CLI Configuration](./get-started/configuration.md) for more details. + +## Google AI Pro/Ultra and subscription FAQs + +### Where can I learn more about my Google AI Pro or Google AI Ultra subscription? + +To learn more about your Google AI Pro or Google AI Ultra subscription, visit **Manage subscription** in your [subscription settings](https://one.google.com). + +### How do I know if I have higher limits for Google AI Pro or Ultra? + +If you're subscribed to Google AI Pro or Ultra, you automatically have higher limits to Gemini Code Assist and Gemini CLI. These are shared across Gemini CLI and agent mode in the IDE. You can confirm you have higher limits by checking if you are still subscribed to Google AI Pro or Ultra in your [subscription settings](https://one.google.com). + +### What is the privacy policy for using Gemini Code Assist or Gemini CLI if I've subscribed to Google AI Pro or Ultra? + +To learn more about your privacy policy and terms of service governed by your subscription, visit [Gemini Code Assist: Terms of Service and Privacy Policies](https://developers.google.com/gemini-code-assist/resources/privacy-notices). + +### I've upgraded to Google AI Pro or Ultra but it still says I am hitting quota limits. Is this a bug? + +The higher limits in your Google AI Pro or Ultra subscription are for Gemini 2.5 across both Gemini 2.5 Pro and Flash. They are shared quota across Gemini CLI and agent mode in Gemini Code Assist IDE extensions. You can learn more about quota limits for Gemini CLI, Gemini Code Assist and agent mode in Gemini Code Assist at [Quotas and limits](https://developers.google.com/gemini-code-assist/resources/quotas). + +### If I upgrade to higher limits for Gemini CLI and Gemini Code Assist by purchasing a Google AI Pro or Ultra subscription, will Gemini start using my data to improve its machine learning models? + +Google does not use your data to improve Google's machine learning models if you purchase a paid plan. Note: If you decide to remain on the free version of Gemini Code Assist, Gemini Code Assist for individuals, you can also opt out of using your data to improve Google's machine learning models. See the [Gemini Code Assist for individuals privacy notice](https://developers.google.com/gemini-code-assist/resources/privacy-notice-gemini-code-assist-individuals) for more information. + +## Not seeing your question? + +Search the Gemini CLI [Issue tracker on GitHub](https://github.com/google-gemini/gemini-cli/issues). If you can't find an issue similar to yours, consider creating a new GitHub Issue with a detailed description. Pull requests are also welcome! diff --git a/docs/get-started/authentication.md b/docs/get-started/authentication.md new file mode 100644 index 0000000000..7e18ef9f8f --- /dev/null +++ b/docs/get-started/authentication.md @@ -0,0 +1,209 @@ +# Gemini CLI Authentication Setup + +Gemini CLI requires authentication using Google's services. Before using Gemini CLI, configure **one** of the following authentication methods: + +- Interactive mode: + - Recommended: Login with Google + - Use Gemini API key + - Use Vertex AI +- Headless (non-interactive) mode +- Google Cloud Shell + +## Quick Check: Running in Google Cloud Shell? + +If you are running the Gemini CLI within a Google Cloud Shell environment, authentication is typically automatic using your Cloud Shell credentials. + +## Authenticate in Interactive mode + +When you run Gemini CLI through the command-line, Gemini CLI will provide the following options: + +```bash +> 1. Login with Google +> 2. Use Gemini API key +> 3. Vertex AI +``` + +The following sections provide instructions for each of these authentication options. + +### Recommended: Login with Google + +If you are running Gemini CLI on your local machine, the simplest method is logging in with your Google account. + +> **Important:** Use this method if you are a **Google AI Pro** or **Google AI Ultra** subscriber. + +1. Select **Login with Google**. Gemini CLI will open a login prompt using your web browser. + + If you are a **Google AI Pro** or **Google AI Ultra** subscriber, login with the Google account associated with your subscription. + +2. Follow the on-screen instructions. Your credentials will be cached locally for future sessions. + + > **Note:** This method requires a web browser on a machine that can communicate with the terminal running the CLI (e.g., your local machine). The browser will be redirected to a `localhost` URL that the CLI listens on during setup. + +#### (Optional) Set your GOOGLE_CLOUD_PROJECT + +When you log in using a Google account, you may be prompted to select a `GOOGLE_CLOUD_PROJECT`. + +This can be necessary if you are: + +- Using a Google Workspace account. +- Using a Gemini Code Assist license from the Google Developer Program. +- Using a license from a Gemini Code Assist subscription. +- Using the product outside the [supported regions](https://developers.google.com/gemini-code-assist/resources/available-locations) for free individual usage. +- A Google account holder under the age of 18. + +If you fall into one of these categories, you must: + +1. Have a Google Cloud Project ID. +2. [Enable the Gemini for Cloud API](https://cloud.google.com/gemini/docs/discover/set-up-gemini#enable-api). +3. [Configure necessary IAM access permissions](https://cloud.google.com/gemini/docs/discover/set-up-gemini#grant-iam). + +To set the project ID, export the `GOOGLE_CLOUD_PROJECT` environment variable: + +```bash +# Replace YOUR_PROJECT_ID with your actual Google Cloud Project ID +export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID" +``` + +To make this setting persistent, see [Persisting Environment Variables](#persisting-environment-variables). + +### Use Gemini API Key + +If you don't want to authenticate using your Google account, you can use an API key from Google AI Studio. + +1. Obtain your API key from [Google AI Studio](https://aistudio.google.com/app/apikey). +2. Set the `GEMINI_API_KEY` environment variable: + + ```bash + # Replace YOUR_GEMINI_API_KEY with the key from AI Studio + export GEMINI_API_KEY="YOUR_GEMINI_API_KEY" + ``` + +To make this setting persistent, see [Persisting Environment Variables](#persisting-environment-variables). + +> **Warning:** Treat API keys, especially for services like Gemini, as sensitive credentials. Protect them to prevent unauthorized access and potential misuse of the service under your account. + +### Use Vertex AI + +If you intend to use Google Cloud's Vertex AI platform, you have several authentication options: + +- Application Default Credentials (ADC) and `gcloud`. +- A Service Account JSON key. +- A Google Cloud API key. + +#### First: Set required environment variables + +Regardless of your method of authentication, you'll typically need to set the following variables: `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION`. + +To set these variables: + +```bash +# Replace with your project ID and desired location (e.g., us-central1) +export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID" +export GOOGLE_CLOUD_LOCATION="YOUR_PROJECT_LOCATION" +``` + +#### A. Vertex AI - Application Default Credentials (ADC) using `gcloud` + +Consider this method of authentication if you have Google Cloud CLI installed. + +> **Note:** If you have previously set `GOOGLE_API_KEY` or `GEMINI_API_KEY`, you must unset them to use ADC: + +```bash +unset GOOGLE_API_KEY GEMINI_API_KEY +``` + +1. Ensure you have a Google Cloud project and Vertex AI API is enabled. +2. Log in to Google Cloud: + + ```bash + gcloud auth application-default login + ``` + + See [Set up Application Default Credentials](https://cloud.google.com/docs/authentication/provide-credentials-adc) for details. + +3. Ensure `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` are set. + +#### B. Vertex AI - Service Account JSON key + +Consider this method of authentication in non-interactive environments, CI/CD, or if your organization restricts user-based ADC or API key creation. + +> **Note:** If you have previously set `GOOGLE_API_KEY` or `GEMINI_API_KEY`, you must unset them: + +```bash +unset GOOGLE_API_KEY GEMINI_API_KEY +``` + +1. [Create a service account and key](https://cloud.google.com/iam/docs/keys-create-delete) and download the provided JSON file. Assign the "Vertex AI User" role to the service account. +2. Set the `GOOGLE_APPLICATION_CREDENTIALS` environment variable to the JSON file's absolute path: + + ```bash + # Replace /path/to/your/keyfile.json with the actual path + export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/keyfile.json" + ``` + +3. Ensure `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` are set. + +> **Warning:** Protect your service account key file as it provides access to your resources. + +#### C. Vertex AI - Google Cloud API key + +1. Obtain a Google Cloud API key: [Get an API Key](https://cloud.google.com/vertex-ai/generative-ai/docs/start/api-keys?usertype=newuser). +2. Set the `GOOGLE_API_KEY` environment variable: + + ```bash + # Replace YOUR_GOOGLE_API_KEY with your Vertex AI API key + export GOOGLE_API_KEY="YOUR_GOOGLE_API_KEY" + ``` + + > **Note:** If you see errors like `"API keys are not supported by this API..."`, your organization might restrict API key usage for this service. Try the [Service Account JSON Key](#b-vertex-ai-service-account-json-key) or [ADC](#a-vertex-ai-application-default-credentials-adc-using-gcloud) methods instead. + +To make any of these Vertex AI environment variable settings persistent, see [Persisting Environment Variables](#persisting-environment-variables). + +## Persisting Environment Variables + +To avoid setting environment variables in every terminal session, you can: + +1. **Add your environment variables to your shell configuration file:** Append the `export ...` commands to your shell's startup file (e.g., `~/.bashrc`, `~/.zshrc`, or `~/.profile`) and reload your shell (e.g., `source ~/.bashrc`). + + ```bash + # Example for .bashrc + echo 'export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"' >> ~/.bashrc + source ~/.bashrc + ``` + + > **Warning:** Be advised that when you export API keys or service account paths in your shell configuration file, any process executed from the shell can potentially read them. + +2. **Use a `.env` file:** Create a `.gemini/.env` file in your project directory or home directory. Gemini CLI automatically loads variables from the first `.env` file it finds, searching up from the current directory, then in `~/.gemini/.env` or `~/.env`. `.gemini/.env` is recommended. + + Example for user-wide settings: + + ```bash + mkdir -p ~/.gemini + cat >> ~/.gemini/.env <<'EOF' + GOOGLE_CLOUD_PROJECT="your-project-id" + # Add other variables like GEMINI_API_KEY as needed + EOF + ``` + + Variables are loaded from the first file found, not merged. + +## Non-interactive mode / headless environments + +Non-interative mode / headless environments will use your existing authentication method, if an existing authentication credential is cached. + +If you have not already logged in with an authentication credential (such as a Google account), you **must** configure authentication using environment variables: + +1. **Gemini API Key:** Set `GEMINI_API_KEY`. +2. **Vertex AI:** + - Set `GOOGLE_GENAI_USE_VERTEXAI=true`. + - **With Google Cloud API Key:** Set `GOOGLE_API_KEY`. + - **With ADC:** Ensure ADC is configured (e.g., via a service account with `GOOGLE_APPLICATION_CREDENTIALS`) and set `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION`. + +The CLI will exit with an error in non-interactive mode if no suitable environment variables are found. + +## What's next? + +Your authentication method affects your quotas, pricing, Terms of Service, and privacy notices. Review the following pages to learn more: + +- [Gemini CLI: Quotas and Pricing](../quota-and-pricing.md). +- [Gemini CLI: Terms of Service and Privacy Notice](../tos-privacy.md). diff --git a/docs/cli/configuration-v1.md b/docs/get-started/configuration-v1.md similarity index 99% rename from docs/cli/configuration-v1.md rename to docs/get-started/configuration-v1.md index c3be399619..02fabbdb5e 100644 --- a/docs/cli/configuration-v1.md +++ b/docs/get-started/configuration-v1.md @@ -42,7 +42,7 @@ Gemini CLI uses JSON settings files for persistent configuration. There are four **Note on environment variables in settings:** String values within your `settings.json` files can reference environment variables using either `$VAR_NAME` or `${VAR_NAME}` syntax. These variables will be automatically resolved when the settings are loaded. For example, if you have an environment variable `MY_API_TOKEN`, you could use it in `settings.json` like this: `"apiKey": "$MY_API_TOKEN"`. -> **Note for Enterprise Users:** For guidance on deploying and managing Gemini CLI in a corporate environment, please see the [Enterprise Configuration](./enterprise.md) documentation. +> **Note for Enterprise Users:** For guidance on deploying and managing Gemini CLI in a corporate environment, please see the [Enterprise Configuration](../cli/enterprise.md) documentation. ### The `.gemini` directory in your project @@ -583,7 +583,7 @@ This example demonstrates how you can provide general project context, specific - **Commands for Memory Management:** - Use `/memory refresh` to force a re-scan and reload of all context files from all configured locations. This updates the AI's instructional context. - Use `/memory show` to display the combined instructional context currently loaded, allowing you to verify the hierarchy and content being used by the AI. - - See the [Commands documentation](./commands.md#memory) for full details on the `/memory` command and its sub-commands (`show` and `refresh`). + - See the [Commands documentation](../cli/commands.md#memory) for full details on the `/memory` command and its sub-commands (`show` and `refresh`). By understanding and utilizing these configuration layers and the hierarchical nature of context files, you can effectively manage the AI's memory and tailor the Gemini CLI's responses to your specific needs and projects. diff --git a/docs/cli/configuration.md b/docs/get-started/configuration.md similarity index 97% rename from docs/cli/configuration.md rename to docs/get-started/configuration.md index f83bdf9d49..bb8dcd534d 100644 --- a/docs/cli/configuration.md +++ b/docs/get-started/configuration.md @@ -1,13 +1,11 @@ # Gemini CLI Configuration -**Note on New Configuration Format** - -The format of the `settings.json` file has been updated to a new, more organized structure. - -- The new format will be supported in the stable release starting **[09/10/25]**. -- Automatic migration from the old format to the new format will begin on **[09/17/25]**. - -For details on the previous format, please see the [v1 Configuration documentation](./configuration-v1.md). +> **Note on Configuration Format, 9/17/25:** The format of the `settings.json` file has been updated to a new, more organized structure. +> +> - The new format will be supported in the stable release starting **[09/10/25]**. +> - Automatic migration from the old format to the new format will begin on **[09/17/25]**. +> +> For details on the previous format, please see the [v1 Configuration documentation](./configuration-v1.md). Gemini CLI offers several ways to configure its behavior, including environment variables, command-line arguments, and settings files. This document outlines the different configuration methods and available settings. @@ -42,7 +40,7 @@ Gemini CLI uses JSON settings files for persistent configuration. There are four **Note on environment variables in settings:** String values within your `settings.json` files can reference environment variables using either `$VAR_NAME` or `${VAR_NAME}` syntax. These variables will be automatically resolved when the settings are loaded. For example, if you have an environment variable `MY_API_TOKEN`, you could use it in `settings.json` like this: `"apiKey": "$MY_API_TOKEN"`. -> **Note for Enterprise Users:** For guidance on deploying and managing Gemini CLI in a corporate environment, please see the [Enterprise Configuration](./enterprise.md) documentation. +> **Note for Enterprise Users:** For guidance on deploying and managing Gemini CLI in a corporate environment, please see the [Enterprise Configuration](../cli/enterprise.md) documentation. ### The `.gemini` directory in your project @@ -86,7 +84,7 @@ Settings are organized into categories. All settings should be placed within the #### `ui` - **`ui.theme`** (string): - - **Description:** The color theme for the UI. See [Themes](./themes.md) for available options. + - **Description:** The color theme for the UI. See [Themes](../cli/themes.md) for available options. - **Default:** `undefined` - **`ui.customThemes`** (object): @@ -212,7 +210,7 @@ Settings are organized into categories. All settings should be placed within the Use `node-pty` for an interactive shell experience. Fallback to `child_process` still applies. Defaults to `false`. - **`tools.core`** (array of strings): - - **Description:** This can be used to restrict the set of built-in tools [with an allowlist](./enterprise.md#restricting-tool-access). See [Built-in Tools](../core/tools-api.md#built-in-tools) for a list of core tools. The match semantics are the same as `tools.allowed`. + - **Description:** This can be used to restrict the set of built-in tools [with an allowlist](../cli/enterprise.md#restricting-tool-access). See [Built-in Tools](../core/tools-api.md#built-in-tools) for a list of core tools. The match semantics are the same as `tools.allowed`. - **Default:** `undefined` - **`tools.exclude`** (array of strings): @@ -229,7 +227,7 @@ Settings are organized into categories. All settings should be placed within the - **`tools.callCommand`** (string): - **Description:** Defines a custom shell command for calling a specific tool that was discovered using `tools.discoveryCommand`. The shell command must meet the following criteria: - - It must take function `name` (exactly as in [function declaration](https://ai.google.dev/gemini-api/docs/function-calling#function-declarations)) as first command line argument. + - It must take function `name` (exactly as in [function declaration](https://ai.google.dev/gemini-api/docs/function-calling#function-declarations)) as the first command line argument. - It must read function arguments as JSON on `stdin`, analogous to [`functionCall.args`](https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/inference#functioncall). - It must return function output as JSON on `stdout`, analogous to [`functionResponse.response.content`](https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/inference#functionresponse). - **Default:** `undefined` @@ -449,7 +447,7 @@ The CLI automatically loads environment variables from an `.env` file. The loadi - Overrides the `telemetry.useCollector` setting. - **`GOOGLE_CLOUD_LOCATION`**: - Your Google Cloud Project Location (e.g., us-central1). - - Required for using Vertex AI in non express mode. + - Required for using Vertex AI in non-express mode. - Example: `export GOOGLE_CLOUD_LOCATION="YOUR_PROJECT_LOCATION"`. - **`GEMINI_SANDBOX`**: - Alternative to the `sandbox` setting in `settings.json`. @@ -602,7 +600,7 @@ This example demonstrates how you can provide general project context, specific - **Commands for Memory Management:** - Use `/memory refresh` to force a re-scan and reload of all context files from all configured locations. This updates the AI's instructional context. - Use `/memory show` to display the combined instructional context currently loaded, allowing you to verify the hierarchy and content being used by the AI. - - See the [Commands documentation](./commands.md#memory) for full details on the `/memory` command and its sub-commands (`show` and `refresh`). + - See the [Commands documentation](../cli/commands.md#memory) for full details on the `/memory` command and its sub-commands (`show` and `refresh`). By understanding and utilizing these configuration layers and the hierarchical nature of context files, you can effectively manage the AI's memory and tailor the Gemini CLI's responses to your specific needs and projects. diff --git a/docs/deployment.md b/docs/get-started/deployment.md similarity index 89% rename from docs/deployment.md rename to docs/get-started/deployment.md index 3287839c22..e535bdf4b8 100644 --- a/docs/deployment.md +++ b/docs/get-started/deployment.md @@ -1,14 +1,16 @@ # Gemini CLI Execution and Deployment -This document describes how to run Gemini CLI and explains the deployment architecture that Gemini CLI uses. +This document describes how to run Gemini CLI and its deployment architecture. ## Running Gemini CLI There are several ways to run Gemini CLI. The option you choose depends on how you intend to use Gemini CLI. ---- +- As a standard installation. This is the most straightforward method of using Gemini CLI. +- In a sandbox. This method offers increased security and isolation. +- From the source. This is recommended for contributors to the project. -### 1. Standard installation (Recommended for typical users) +### 1. Standard installation (recommended for standard users) This is the recommended way for end-users to install Gemini CLI. It involves downloading the Gemini CLI package from the NPM registry. @@ -31,9 +33,7 @@ This is the recommended way for end-users to install Gemini CLI. It involves dow npx @google/gemini-cli ``` ---- - -### 2. Running in a sandbox (Docker/Podman) +### 2. Run in a sandbox (Docker/Podman) 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. @@ -49,9 +49,7 @@ For security and isolation, Gemini CLI can be run inside a container. This is th gemini --sandbox -y -p "your prompt here" ``` ---- - -### 3. Running from source (Recommended for Gemini CLI contributors) +### 3. Run from source (recommended for Gemini CLI contributors) Contributors to the project will want to run the CLI directly from the source code. diff --git a/docs/get-started/examples.md b/docs/get-started/examples.md new file mode 100644 index 0000000000..3383cc25a9 --- /dev/null +++ b/docs/get-started/examples.md @@ -0,0 +1,200 @@ +# Gemini CLI Examples + +Not sure where to get started with Gemini CLI? This document covers examples on how to use Gemini CLI for a variety of tasks. + +**Note:** Results are examples intended to showcase potential use cases. Your results may vary. + +## Rename your photographs based on content + +Scenario: You have a folder containing the following files: + +```bash +photos/photo1.png +photos/photo2.png +photos/photo3.png +``` + +Give Gemini the following prompt: + +```cli +Rename the photos in my "photos" directory based on their contents. +``` + +Result: Gemini will ask for permission to rename your files. + +Select **Yes, allow once.** and your files will be renamed: + +```bash +photos/yellow_flowers.png +photos/antique_dresser.png +photos/green_android_robot.png +``` + +## Explain a repository by reading its code + +Scenario: You want to understand how a popular open-source utility works by inspecting its code, not just its README. + +Give Gemini CLI the following prompt: + +```cli +Clone the 'chalk' repository from https://github.com/chalk/chalk, read its key source files, and explain how it works. +``` + +Result: Gemini will perform a sequence of actions to answer your request. + +1. First, it will ask for permission to run `git clone` to download the repository. +2. Next, it will find the important source files and ask for permission to read them. +3. Finally, after analyzing the code, it will provide a summary. + +Gemini CLI will return an explanation based on the actual source code: + +```markdown +The `chalk` library is a popular npm package for styling terminal output with colors. After analyzing the source code, here's how it works: + +- **Core Functionality:** The main file sets up a chainable API. Each color or modifier (like `bold` or `italic`) is a getter that appends the corresponding ANSI escape code to an internal stack. + +- **Chainable API:** When you call `chalk.red.bold('Hello')`, you are accessing getters. The `red` getter adds the red color code, and the `bold` getter adds the bold code. + +- **Output Generation:** When the chain is treated as a string (e.g., in `console.log`), a final `toString()` method is called. This method joins all the stored ANSI codes, wraps them around the input string ('Hello'), and adds a reset code at the end. This produces the final, styled string that the terminal can render. +``` + +## Combine two spreadsheets into one spreadsheet + +Scenario: You have two .csv files: `Revenue - 2023.csv` and `Revenue - 2024.csv`. Each file contains monthly revenue figures, like so: + +```csv +January,0 +February,0 +March,0 +April,900 +May,1000 +June,1000 +July,1200 +August,1800 +September,2000 +October,2400 +November,3400 +December,2100 +``` + +You want to combine these two .csv files into a single .csv file. + +Give Gemini CLI the following prompt: + +```cli +Combine the two .csv files into a single .csv file, with each year a different column. +``` + +Result: Gemini CLI will read each file and then ask for permission to write a new file. Provide your permission and Gemini CLI will provide the following .csv: + +```csv +Month,2023,2024 +January,0,1000 +February,0,1200 +March,0,2400 +April,900,500 +May,1000,800 +June,1000,900 +July,1200,1000 +August,1800,400 +September,2000,2000 +October,2400,3400 +November,3400,1800 +December,2100,9000 +``` + +## Run unit tests + +Scenario: You've written a simple login page. You wish to write unit tests to ensure that your login page has code coverage. + +Give Gemini CLI the following prompt: + +```cli +Write unit tests for Login.js. +``` + +Result: Gemini CLI will ask for permission to write a new file and create a test for your login page + +```javascript +import React from 'react'; +import { render, fireEvent, waitFor } from '@testing-library/react'; +import Login from './Login'; + +// Mock the API call for login +jest.mock('./api', () => ({ + login: jest.fn(), +})); + +describe('Login component', () => { + it('renders the login form correctly', () => { + const { getByLabelText, getByText } = render(); + + expect(getByLabelText('Username')).toBeInTheDocument(); + expect(getByLabelText('Password')).toBeInTheDocument(); + expect(getByText('Login')).toBeInTheDocument(); + }); + + it('shows an error message with invalid credentials', async () => { + const { getByLabelText, getByText, findByText } = render(); + const usernameInput = getByLabelText('Username'); + const passwordInput = getByLabelText('Password'); + const loginButton = getByText('Login'); + + // Mock the API to return an error + require('./api').login.mockRejectedValue(new Error('Invalid credentials')); + + fireEvent.change(usernameInput, { target: { value: 'testuser' } }); + fireEvent.change(passwordInput, { target: { value: 'wrongpassword' } }); + fireEvent.click(loginButton); + + const errorMessage = await findByText('Invalid credentials'); + expect(errorMessage).toBeInTheDocument(); + }); + + it('logs in successfully with valid credentials', async () => { + const onLoginSuccess = jest.fn(); + const { getByLabelText, getByText } = render( + , + ); + const usernameInput = getByLabelText('Username'); + const passwordInput = getByLabelText('Password'); + const loginButton = getByText('Login'); + + // Mock the API to return a success message + require('./api').login.mockResolvedValue({ success: true }); + + fireEvent.change(usernameInput, { target: { value: 'testuser' } }); + fireEvent.change(passwordInput, { target: { value: 'correctpassword' } }); + fireEvent.click(loginButton); + + await waitFor(() => { + expect(onLoginSuccess).toHaveBeenCalled(); + }); + }); + + it('disables the submit button while submitting', async () => { + const { getByLabelText, getByText } = render(); + const usernameInput = getByLabelText('Username'); + const passwordInput = getByLabelText('Password'); + const loginButton = getByText('Login'); + + // Mock the API to have a delay + require('./api').login.mockImplementation( + () => + new Promise((resolve) => + setTimeout(() => resolve({ success: true }), 1000), + ), + ); + + fireEvent.change(usernameInput, { target: { value: 'testuser' } }); + fireEvent.change(passwordInput, { target: { value: 'correctpassword' } }); + fireEvent.click(loginButton); + + expect(loginButton).toBeDisabled(); + + await waitFor(() => { + expect(loginButton).not.toBeDisabled(); + }); + }); +}); +``` diff --git a/docs/get-started/index.md b/docs/get-started/index.md new file mode 100644 index 0000000000..f10d8f5101 --- /dev/null +++ b/docs/get-started/index.md @@ -0,0 +1,54 @@ +# Get Started with Gemini CLI + +Welcome to Gemini CLI! This guide will help you install, configure, and start using the Gemini CLI to enhance your workflow right from your terminal. + +## Quickstart: Install, authenticate, configure, and use Gemini CLI + +Gemini CLI brings the power of advanced language models directly to your command line interface. As an AI-powered assistant, Gemini CLI can help you with a variety of tasks, from understanding and generating code to reviewing and editing documents. + +## Install + +The standard method to install and run Gemini CLI uses `npm`: + +```bash +npm install -g @google/gemini-cli +``` + +Once Gemini CLI is installed, run Gemini CLI from your command line: + +```bash +gemini +``` + +For more deployment options, see [Gemini CLI Execution and Deployment](./deployment.md). + +## Authenticate + +To begin using Gemini CLI, you must authenticate with a Google service. The most straightforward authentication method uses your existing Google account: + +1. Run Gemini CLI after installation: + ```bash + gemini + ``` +2. When asked "How would you like to authenticate for this project?" select **1. Login with Google**. +3. Select your Google account. +4. Click on **Sign in**. + +For other authentication options and information, see [GeminI CLI Authentication Setup](./authentication.md). + +## Configure + +Gemini CLI offers several ways to configure its behavior, including environment variables, command-line arguments, and settings files. + +To explore your configuration options, see [Gemini CLI Configuration](./configuration.md). + +## Use + +Once installed and authenticated, you can start using Gemini CLI by issuing commands and prompts in your terminal. Ask it to generate code, explain files, and more. + +To explore the power of Gemini CLI, see [Gemini CLI examples](./examples.md). + +## What's next? + +- Find out more about [Gemini CLI's tools](../tools/index.md). +- Review [Gemini CLI's commands](../cli/commands.md). diff --git a/docs/ide-companion-spec.md b/docs/ide-integration/ide-companion-spec.md similarity index 100% rename from docs/ide-companion-spec.md rename to docs/ide-integration/ide-companion-spec.md diff --git a/docs/ide-integration.md b/docs/ide-integration/index.md similarity index 100% rename from docs/ide-integration.md rename to docs/ide-integration/index.md diff --git a/docs/index.md b/docs/index.md index 0de9f8480a..025a0f5e23 100644 --- a/docs/index.md +++ b/docs/index.md @@ -10,33 +10,61 @@ Gemini CLI brings the capabilities of Gemini models to your terminal in an inter This documentation is organized into the following sections: -- **[Execution and Deployment](./deployment.md):** Information for running Gemini CLI. +### Get started + +- **[Gemini CLI Quickstart](./get-started/index.md):** Let's get started with Gemini CLI. +- **[Deployment](./get-started/deployment.md):** Install and run Gemini CLI. +- **[Authentication](./get-started/authentication.md):** Authenticate Gemini CLI. +- **[Configuration](./get-started/configuration.md):** Information on configuring the CLI. +- **[Examples](./get-started/examples.md):** Example usage of Gemini CLI. + +### CLI + +- **[CLI overview](./cli/index.md):** Overview of the command-line interface. +- **[Commands](./cli/commands.md):** Description of available CLI commands. +- **[Enterprise](./cli/enterprise.md):** Gemini CLI for enterprise. +- **[Themes](./cli/themes.md):** Themes for Gemini CLI. +- **[Token Caching](./cli/token-caching.md):** Token caching and optimization. +- **[Tutorials](./cli/tutorials.md):** Tutorials for Gemini CLI. +- **[Checkpointing](./cli/checkpointing.md):** Documentation for the checkpointing feature. +- **[Telemetry](./cli/telemetry.md):** Overview of telemetry in the CLI. +- **[Trusted Folders](./cli/trusted-folders.md):** An overview of the Trusted Folders security feature. + +### Core + +- **[Gemini CLI core overview](./core/index.md):** Information about Gemini CLI core. +- **[Memport](./core/memport.md):** Using the Memory Import Processor. +- **[Tools API](./core/tools-api.md):** Information on how the core manages and exposes tools. + +### Tools + +- **[Gemini CLI tools overview](./tools/index.md):** Information about Gemini CLI's tools. +- **[File System Tools](./tools/file-system.md):** Documentation for the `read_file` and `write_file` tools. +- **[MCP servers](./tools/mcp-server.md):** Using MCP servers with Gemini CLI. +- **[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. +- **[Memory Tool](./tools/memory.md):** Documentation for the `save_memory` tool. + +### Extensions + +- **[Extensions](./extensions/index.md):** How to extend the CLI with new functionality. +- **[Extension Releasing](./extensions/extension-releasing.md):** How to release Gemini CLI extensions. + +### IDE integration + +- **[IDE Integration](./ide-integration/index.md):** Connect the CLI to your editor. +- **[IDE Companion Extension Spec](./ide-integration/ide-companion-spec.md):** Spec for building IDE companion extensions. + +### About the Gemini CLI project + - **[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. - - **[Checkpointing](./checkpointing.md):** Documentation for the checkpointing feature. - - **[Extensions](./extension.md):** How to extend the CLI with new functionality. - - **[IDE Integration](./ide-integration.md):** Connect the CLI to your editor. - - **[IDE Companion Extension Spec](./ide-companion-spec.md):** Spec for building IDE companion extensions. - - **[Telemetry](./telemetry.md):** Overview of telemetry in the CLI. - - **[Trusted Folders](./trusted-folders.md):** An overview of the Trusted Folders security feature. -- **Core Details:** Documentation for `packages/core`. - - **[Core Introduction](./core/index.md):** Overview of the core component. - - **[Tools API](./core/tools-api.md):** Information on how the core manages and exposes tools. -- **Tools:** - - **[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. - - **[Memory Tool](./tools/memory.md):** Documentation for the `save_memory` tool. - **[Contributing & Development Guide](../CONTRIBUTING.md):** Information for contributors and developers, including setup, building, testing, and coding conventions. -- **[NPM](./npm.md):** Details on how the project's packages are structured -- **[Troubleshooting Guide](./troubleshooting.md):** Find solutions to common problems and FAQs. +- **[NPM](./npm.md):** Details on how the project's packages are structured. +- **[Troubleshooting Guide](./troubleshooting.md):** Find solutions to common problems. +- **[FAQ](./faq.md):** Frequently asked questions. - **[Terms of Service and Privacy Notice](./tos-privacy.md):** Information on the terms of service and privacy notices applicable to your use of Gemini CLI. - **[Releases](./releases.md):** Information on the project's releases and deployment cadence. -We hope this documentation helps you make the most of the Gemini CLI! +We hope this documentation helps you make the most of Gemini CLI! diff --git a/docs/releases.md b/docs/releases.md index cfce8d31f8..03ff181245 100644 --- a/docs/releases.md +++ b/docs/releases.md @@ -6,9 +6,9 @@ We will follow https://semver.org/ as closely as possible but will call out when Each Tuesday ~2000 UTC new Stable and Preview releases will be cut. The promotion flow is: -- Code is commited to main and pushed each night to nightly +- Code is committed to main and pushed each night to nightly - After no more than 1 week on main, code is promoted to the `preview` channel -- After 1 week the most recent `preview` channel is promoted to `stable` cannel +- After 1 week the most recent `preview` channel is promoted to `stable` channel - Patch fixes will be produced against both `preview` and `stable` as needed, with the final 'patch' version number incrementing each time. ### Preview diff --git a/docs/sidebar.json b/docs/sidebar.json index 75b85208c9..e539cddf4f 100644 --- a/docs/sidebar.json +++ b/docs/sidebar.json @@ -2,68 +2,218 @@ { "label": "Overview", "items": [ - { "label": "Welcome", "slug": "docs" }, - { "label": "Execution and Deployment", "slug": "docs/deployment" }, - { "label": "Architecture Overview", "slug": "docs/architecture" } + { + "label": "Architecture Overview", + "slug": "docs/architecture" + } + ] + }, + { + "label": "Get Started", + "items": [ + { + "label": "Gemini CLI Quickstart", + "slug": "docs/get-started" + }, + { + "label": "Authentication", + "slug": "docs/get-started/authentication" + }, + { + "label": "Configuration", + "slug": "docs/get-started/configuration" + }, + { + "label": "Deployment", + "slug": "docs/get-started/deployment" + }, + { + "label": "Examples", + "slug": "docs/get-started/examples" + } ] }, { "label": "CLI", "items": [ - { "label": "Introduction", "slug": "docs/cli" }, - { "label": "Authentication", "slug": "docs/cli/authentication" }, - { "label": "Commands", "slug": "docs/cli/commands" }, - { "label": "Configuration", "slug": "docs/cli/configuration" }, - { "label": "Checkpointing", "slug": "docs/checkpointing" }, - { "label": "Enterprise", "slug": "docs/cli/enterprise" }, - { "label": "Extensions", "slug": "docs/extension" }, - { "label": "Headless Mode", "slug": "docs/headless" }, - { "label": "IDE Integration", "slug": "docs/ide-integration" }, { - "label": "IDE Companion Spec", - "slug": "docs/ide-companion-spec" + "label": "Introduction", + "slug": "docs/cli" }, - { "label": "Telemetry", "slug": "docs/telemetry" }, - { "label": "Themes", "slug": "docs/cli/themes" }, - { "label": "Token Caching", "slug": "docs/cli/token-caching" }, - { "label": "Trusted Folders", "slug": "docs/trusted-folders" }, - { "label": "Tutorials", "slug": "docs/cli/tutorials" } + { + "label": "Commands", + "slug": "docs/cli/commands" + }, + { + "label": "Checkpointing", + "slug": "docs/cli/checkpointing" + }, + { + "label": "Custom Commands", + "slug": "docs/cli/custom-commands" + }, + { + "label": "Enterprise", + "slug": "docs/cli/enterprise" + }, + { + "label": "Headless Mode", + "slug": "docs/cli/headless" + }, + { + "label": "Keyboard Shortcuts", + "slug": "docs/cli/keyboard-shortcuts" + }, + { + "label": "Sandbox", + "slug": "docs/cli/sandbox" + }, + { + "label": "Telemetry", + "slug": "docs/cli/telemetry" + }, + { + "label": "Themes", + "slug": "docs/cli/themes" + }, + { + "label": "Token Caching", + "slug": "docs/cli/token-caching" + }, + { + "label": "Trusted Folders", + "slug": "docs/cli/trusted-folders" + }, + { + "label": "Tutorials", + "slug": "docs/cli/tutorials" + }, + { + "label": "Uninstall", + "slug": "docs/cli/uninstall" + } ] }, { "label": "Core", "items": [ - { "label": "Introduction", "slug": "docs/core" }, - { "label": "Tools API", "slug": "docs/core/tools-api" }, - { "label": "Memory Import Processor", "slug": "docs/core/memport" } + { + "label": "Introduction", + "slug": "docs/core" + }, + { + "label": "Tools API", + "slug": "docs/core/tools-api" + }, + { + "label": "Memory Import Processor", + "slug": "docs/core/memport" + } ] }, { "label": "Tools", "items": [ - { "label": "Overview", "slug": "docs/tools" }, - { "label": "File System", "slug": "docs/tools/file-system" }, - { "label": "Multi-File Read", "slug": "docs/tools/multi-file" }, - { "label": "Shell", "slug": "docs/tools/shell" }, - { "label": "Web Fetch", "slug": "docs/tools/web-fetch" }, - { "label": "Web Search", "slug": "docs/tools/web-search" }, - { "label": "Memory", "slug": "docs/tools/memory" }, - { "label": "MCP Servers", "slug": "docs/tools/mcp-server" }, - { "label": "Sandboxing", "slug": "docs/sandbox" } + { + "label": "Overview", + "slug": "docs/tools" + }, + { + "label": "File System", + "slug": "docs/tools/file-system" + }, + { + "label": "Multi-File Read", + "slug": "docs/tools/multi-file" + }, + { + "label": "Shell", + "slug": "docs/tools/shell" + }, + { + "label": "Web Fetch", + "slug": "docs/tools/web-fetch" + }, + { + "label": "Web Search", + "slug": "docs/tools/web-search" + }, + { + "label": "Memory", + "slug": "docs/tools/memory" + }, + { + "label": "MCP Servers", + "slug": "docs/tools/mcp-server" + } + ] + }, + { + "label": "Extensions", + "items": [ + { + "label": "Introduction", + "slug": "docs/extensions" + }, + { + "label": "Extension Releasing", + "slug": "docs/extensions/extension-releasing" + } + ] + }, + { + "label": "IDE Integration", + "items": [ + { + "label": "Introduction", + "slug": "docs/ide-integration" + }, + { + "label": "IDE Companion Spec", + "slug": "docs/ide-integration/ide-companion-spec" + } ] }, { "label": "Development", "items": [ - { "label": "NPM", "slug": "docs/npm" }, - { "label": "Releases", "slug": "docs/releases" } + { + "label": "NPM", + "slug": "docs/npm" + }, + { + "label": "Releases", + "slug": "docs/releases" + }, + { + "label": "Integration Tests", + "slug": "docs/integration-tests" + }, + { + "label": "Issue and PR Automation", + "slug": "docs/issue-and-pr-automation" + } ] }, { "label": "Support", "items": [ - { "label": "Troubleshooting", "slug": "docs/troubleshooting" }, - { "label": "Terms of Service", "slug": "docs/tos-privacy" } + { + "label": "FAQ", + "slug": "docs/faq" + }, + { + "label": "Troubleshooting", + "slug": "docs/troubleshooting" + }, + { + "label": "Quota and Pricing", + "slug": "docs/quota-and-pricing" + }, + { + "label": "Terms of Service", + "slug": "docs/tos-privacy" + } ] } ] diff --git a/docs/tools/index.md b/docs/tools/index.md index 4fa98c03b8..a56020f4de 100644 --- a/docs/tools/index.md +++ b/docs/tools/index.md @@ -35,7 +35,7 @@ You will typically see messages in the CLI indicating when a tool is being calle Many tools, especially those that can modify your file system or execute commands (`write_file`, `edit`, `run_shell_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:** All tools are subject to restrictions enforced by sandboxing (see [Sandboxing in the Gemini CLI](../sandbox.md)). This means that when operating in a sandbox, any tools (including MCP servers) you wish to use must be available _inside_ the sandbox environment. For example, to run an MCP server through `npx`, the `npx` executable must be installed within the sandbox's Docker image or be available in the `sandbox-exec` environment. +- **Utilize sandboxing:** All tools are subject to restrictions enforced by sandboxing (see [Sandboxing in the Gemini CLI](../cli/sandbox.md)). This means that when operating in a sandbox, any tools (including MCP servers) you wish to use must be available _inside_ the sandbox environment. For example, to run an MCP server through `npx`, the `npx` executable must be installed within the sandbox's Docker image or be available in the `sandbox-exec` environment. It's important to always review confirmation prompts carefully before allowing a tool to proceed. @@ -46,11 +46,11 @@ Gemini CLI's 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) (`run_shell_command`):** For executing shell commands. - **[Web Fetch Tool](./web-fetch.md) (`web_fetch`):** For retrieving content from URLs. -- **[Web Search Tool](./web-search.md) (`web_search`):** For searching the web. -- **[Multi-File Read Tool](./multi-file.md) (`read_many_files`):** A specialized tool for reading content from multiple files or directories, often used by the `@` command. +- **[Web Search Tool](./web-search.md) (`google_web_search`):** For searching the web. +- **[Multi-File Read Tool](./multi-file.md) (`read_many_files`):** A specialized tool for reading content from multiple files or directories. - **[Memory Tool](./memory.md) (`save_memory`):** For saving and recalling information across sessions. Additionally, these tools incorporate: - **[MCP servers](./mcp-server.md)**: MCP servers act as a bridge between the Gemini model and your local environment or other services like APIs. -- **[Sandboxing](../sandbox.md)**: Sandboxing isolates the model and its changes from your environment to reduce potential risk. +- **[Sandboxing](../cli/sandbox.md)**: Sandboxing isolates the model and its changes from your environment to reduce potential risk. diff --git a/docs/tos-privacy.md b/docs/tos-privacy.md index ea06e31e73..29c8dfe626 100644 --- a/docs/tos-privacy.md +++ b/docs/tos-privacy.md @@ -55,7 +55,7 @@ If you are using a Gemini API key for authentication with a [Vertex AI GenAI API ### Usage Statistics Opt-Out -You may opt-out from sending Usage Statistics to Google by following the instructions available here: [Usage Statistics Configuration](./cli/configuration.md#usage-statistics). +You may opt-out from sending Usage Statistics to Google by following the instructions available here: [Usage Statistics Configuration](./get-started/configuration.md#usage-statistics). ## Frequently Asked Questions (FAQ) for the Gemini CLI @@ -90,4 +90,4 @@ The data it collects depends on your account and authentication type: Please refer to the Privacy Notice that applies to your authentication method for more information about what data is collected and how this data is used. -You can disable Usage Statistics for any account type by following the instructions in the [Usage Statistics Configuration](./cli/configuration.md#usage-statistics) documentation. +You can disable Usage Statistics for any account type by following the instructions in the [Usage Statistics Configuration](./get-started/configuration-v1.md#usage-statistics) documentation. diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index a17af9676f..e1fea31c7c 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -24,21 +24,6 @@ This guide provides solutions to common issues and debugging tips, including top - **Solution:** Set the `NODE_EXTRA_CA_CERTS` environment variable to the absolute path of your corporate root CA certificate file. - Example: `export NODE_EXTRA_CA_CERTS=/path/to/your/corporate-ca.crt` -## Frequently asked questions (FAQs) - -- **Q: How do I update Gemini CLI to the latest version?** - - A: If you installed it globally via `npm`, update it using the command `npm install -g @google/gemini-cli@latest`. If you compiled it from source, pull the latest changes from the repository, and then rebuild using the command `npm run build`. - -- **Q: Where are the Gemini CLI configuration or settings files stored?** - - A: The Gemini CLI configuration is stored in two `settings.json` files: - 1. In your home directory: `~/.gemini/settings.json`. - 2. In your project's root directory: `./.gemini/settings.json`. - - Refer to [Gemini CLI Configuration](./cli/configuration.md) for more details. - -- **Q: Why don't I see cached token counts in my stats output?** - - A: Cached token information is only displayed when cached tokens are being used. This feature is available for API key users (Gemini API key or Google Cloud Vertex AI) but not for OAuth users (such as Google Personal/Enterprise accounts like Google Gmail or Google Workspace, respectively). This is because the Gemini Code Assist API does not support cached content creation. You can still view your total token usage using the `/stats` command in Gemini CLI. - ## Common error messages and solutions - **Error: `EADDRINUSE` (Address already in use) when starting an MCP server.** @@ -62,7 +47,7 @@ This guide provides solutions to common issues and debugging tips, including top - **Error: "Operation not permitted", "Permission denied", or similar.** - **Cause:** When sandboxing is enabled, Gemini CLI may attempt operations that are restricted by your sandbox configuration, such as writing outside the project directory or system temp directory. - - **Solution:** Refer to the [Configuration: Sandboxing](./cli/configuration.md#sandboxing) documentation for more information, including how to customize your sandbox configuration. + - **Solution:** Refer to the [Configuration: Sandboxing](./cli/sandbox.md) documentation for more information, including how to customize your sandbox configuration. - **Gemini CLI is not running in interactive mode in "CI" environments** - **Issue:** The Gemini CLI does not enter interactive mode (no prompt appears) if an environment variable starting with `CI_` (e.g., `CI_TOKEN`) is set. This is because the `is-in-ci` package, used by the underlying UI framework, detects these variables and assumes a non-interactive CI environment. diff --git a/packages/cli/src/ui/components/Help.tsx b/packages/cli/src/ui/components/Help.tsx index 90a6b26a9c..a3e124d759 100644 --- a/packages/cli/src/ui/components/Help.tsx +++ b/packages/cli/src/ui/components/Help.tsx @@ -176,7 +176,7 @@ export const Help: React.FC = ({ commands }) => ( For a full list of shortcuts, see{' '} - docs/keyboard-shortcuts.md + docs/cli/keyboard-shortcuts.md