diff --git a/docs/architecture.md b/docs/architecture.md deleted file mode 100644 index cf6ac8359d..0000000000 --- a/docs/architecture.md +++ /dev/null @@ -1,80 +0,0 @@ -# Gemini CLI Architecture Overview - -This document provides a high-level overview of the Gemini CLI's architecture. - -## Core components - -The Gemini CLI is primarily composed of two main packages, along with a suite of -tools that can be used by the system in the course of handling command-line -input: - -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](/docs/cli/commands) - - History management - - Display rendering - - [Theme and UI customization](/docs/cli/themes) - - [CLI configuration settings](/docs/get-started/configuration) - -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. - - **Key functions contained in the package:** - - API client for communicating with the Google Gemini API - - Prompt construction and management - - Tool registration and execution logic - - State management for conversations or sessions - - Server-side configuration - -3. **Tools (`packages/core/src/tools/`):** - - **Purpose:** These are individual modules that extend the capabilities of - the Gemini model, allowing it to interact with the local environment - (e.g., file system, shell commands, web fetching). - - **Interaction:** `packages/core` invokes these tools based on requests - from the Gemini model. - -## Interaction flow - -A typical interaction with the Gemini CLI follows this flow: - -1. **User input:** The user types a prompt or command into the terminal, which - is managed by `packages/cli`. -2. **Request to core:** `packages/cli` sends the user's input to - `packages/core`. -3. **Request processed:** The core package: - - Constructs an appropriate prompt for the Gemini API, possibly including - conversation history and available tool definitions. - - Sends the prompt to the Gemini API. -4. **Gemini API response:** The Gemini API processes the prompt and returns a - response. This response might be a direct answer or a request to use one of - the available tools. -5. **Tool execution (if applicable):** - - When the Gemini API requests a tool, the core package prepares to execute - it. - - If the requested tool can modify the file system or execute shell - commands, the user is first given details of the tool and its arguments, - and the user must approve the execution. - - Read-only operations, such as reading files, might not require explicit - user confirmation to proceed. - - Once confirmed, or if confirmation is not required, the core package - executes the relevant action within the relevant tool, and the result is - sent back to the Gemini API by the core package. - - The Gemini API processes the tool result and generates a final response. -6. **Response to CLI:** The core package sends the final response back to the - CLI package. -7. **Display to user:** The CLI package formats and displays the response to - the user in the terminal. - -## Key design principles - -- **Modularity:** Separating the CLI (frontend) from the Core (backend) allows - for independent development and potential future extensions (e.g., different - frontends for the same backend). -- **Extensibility:** The tool system is designed to be extensible, allowing new - capabilities to be added. -- **User experience:** The CLI focuses on providing a rich and interactive - terminal experience. diff --git a/docs/cli/index.md b/docs/cli/index.md deleted file mode 100644 index a9594169fa..0000000000 --- a/docs/cli/index.md +++ /dev/null @@ -1,123 +0,0 @@ -# Using Gemini CLI - -Gemini CLI is a terminal-first interface that brings the power of Gemini AI -models directly into your development workflow. It lets you interact with AI -using your local files, shell environment, and project context, creating a -bridge between generative AI and your system tools. - -## User guides - -These guides provide step-by-step instructions and practical examples for using -Gemini CLI in your daily development workflow. - -- **[Quickstart](../get-started/index.md):** Get up and running with Gemini CLI - in minutes. -- **[Examples](../get-started/examples.md):** See practical examples of Gemini - CLI in action. -- **[Get started with skills](./tutorials/skills-getting-started.md):** Learn - how to use and manage specialized expertise. -- **[File management](./tutorials/file-management.md):** How to include, search, - and modify local files. -- **[Set up an MCP server](./tutorials/mcp-setup.md):** Configure Model Context - Protocol servers for custom tools. -- **[Manage context and memory](./tutorials/memory-management.md):** Manage - persistent instructions and individual facts. -- **[Manage sessions and history](./tutorials/session-management.md):** Resume, - manage, and rewind your conversations. -- **[Execute shell commands](./tutorials/shell-commands.md):** Execute system - commands safely directly from your prompt. -- **[Plan tasks with todos](./tutorials/task-planning.md):** Using todos for - complex, multi-step agent requests. -- **[Web search and fetch](./tutorials/web-tools.md):** Searching and fetching - content from the web. - -## Features - -Technical reference documentation for each capability of Gemini CLI. - -- **[/about](../cli/commands.md#about):** Show version info. -- **[/auth](../cli/commands.md#auth):** Change authentication method. -- **[/bug](../cli/commands.md#bug):** File an issue about Gemini CLI. -- **[/chat](../cli/commands.md#chat):** Save and resume conversation history. -- **[/clear](../cli/commands.md#clear):** Clear the terminal screen. -- **[/compress](../cli/commands.md#compress):** Replace context with a summary. -- **[/copy](../cli/commands.md#copy):** Copy output to clipboard. -- **[/directory](../cli/commands.md#directory-or-dir):** Manage workspace - directories. -- **[/docs](../cli/commands.md#docs):** Open documentation in browser. -- **[/editor](../cli/commands.md#editor):** Select preferred editor. -- **[/extensions](../cli/commands.md#extensions):** List active extensions. -- **[/help](../cli/commands.md#help-or):** Display help information. -- **[/hooks](../hooks/index.md):** Manage hooks for lifecycle events. -- **[/ide](../ide-integration/index.md):** Manage IDE integration. -- **[/init](../cli/commands.md#init):** Create a GEMINI.md context file. -- **[/mcp](../tools/mcp-server.md):** Manage Model Context Protocol servers. -- **[/memory](../cli/commands.md#memory):** Manage instructional context. -- **[/model](./model.md):** Choose Gemini model. -- **[/policies](../cli/commands.md#policies):** Manage security policies. -- **[/privacy](../cli/commands.md#privacy):** Display privacy notice. -- **[/quit](../cli/commands.md#quit-or-exit):** Exit Gemini CLI. -- **[/restore](../cli/commands.md#restore):** Restore file state. -- **[/resume](../cli/commands.md#resume):** Browse and resume sessions. -- **[/rewind](./rewind.md):** Navigate backward through history. -- **[/settings](./settings.md):** Open settings editor. -- **[/setup-github](../cli/commands.md#setup-github):** Set up GitHub Actions. -- **[/shells](../cli/commands.md#shells-or-bashes):** Toggle background shells - view. -- **[/skills](./skills.md):** Manage Agent Skills. -- **[/stats](../cli/commands.md#stats):** Display session statistics. -- **[/terminal-setup](../cli/commands.md#terminal-setup):** Configure - keybindings. -- **[/theme](./themes.md):** Change visual theme. -- **[/tools](../cli/commands.md#tools):** Display list of available tools. -- **[/vim](../cli/commands.md#vim):** Toggle vim mode. -- **[Activate skill (tool)](../tools/activate-skill.md):** Internal mechanism - for loading expert procedures. -- **[Ask user (tool)](../tools/ask-user.md):** Internal dialog system for - clarification. -- **[Checkpointing](./checkpointing.md):** Automatic session snapshots. -- **[File system (tool)](../tools/file-system.md):** Technical details for local - file operations. -- **[Headless mode](./headless.md):** Programmatic and scripting interface. -- **[Internal documentation (tool)](../tools/internal-docs.md):** Technical - lookup for CLI features. -- **[Memory (tool)](../tools/memory.md):** Storage details for persistent facts. -- **[Model routing](./model-routing.md):** Automatic fallback resilience. -- **[Plan mode (experimental)](./plan-mode.md):** Use a safe, read-only mode for - planning complex changes. -- **[Sandboxing](./sandbox.md):** Isolate tool execution. -- **[Shell (tool)](../tools/shell.md):** Detailed system execution parameters. -- **[Telemetry](./telemetry.md):** Usage and performance metric details. -- **[Todo (tool)](../tools/todos.md):** Progress tracking specification. -- **[Token caching](./token-caching.md):** Performance optimization. -- **[Web fetch (tool)](../tools/web-fetch.md):** URL retrieval and extraction - details. -- **[Web search (tool)](../tools/web-search.md):** Google Search integration - technicals. - -## Configuration - -Settings and customization options for Gemini CLI. - -- **[Custom commands](./custom-commands.md):** Personalized shortcuts. -- **[Enterprise configuration](./enterprise.md):** Professional environment - controls. -- **[Ignore files (.geminiignore)](./gemini-ignore.md):** Exclusion pattern - reference. -- **[Model configuration](./generation-settings.md):** Fine-tune generation - parameters like temperature and thinking budget. -- **[Project context (GEMINI.md)](./gemini-md.md):** Technical hierarchy of - context files. -- **[Settings](./settings.md):** Full `settings.json` schema. -- **[System prompt override](./system-prompt.md):** Instruction replacement - logic. -- **[Themes](./themes.md):** UI personalization technical guide. -- **[Trusted folders](./trusted-folders.md):** Security permission logic. - -## Next steps - -- Explore the [Command reference](./commands.md) to learn about all available - slash commands. -- Read about [Project context](./gemini-md.md) to understand how to provide - persistent instructions to the model. -- See the [CLI reference](./cli-reference.md) for a quick cheatsheet of flags. diff --git a/docs/core/concepts.md b/docs/core/concepts.md deleted file mode 100644 index 7a6e52c1b7..0000000000 --- a/docs/core/concepts.md +++ /dev/null @@ -1,137 +0,0 @@ -# Core concepts - -This guide explains the fundamental concepts and terminology used throughout the -Gemini CLI ecosystem. Understanding these terms will help you make the most of -the tool's capabilities. - -## Approval mode - -**Approval mode** determines the level of autonomy you grant to the agent when -executing tools. - -- **Default:** The agent asks for confirmation before performing any potentially - impactful action (like writing files or running shell commands). -- **Auto-edit:** File modifications are applied automatically, but shell - commands still require confirmation. -- **YOLO (You Only Look Once):** The agent runs all tools without asking for - permission. High risk, high speed. - -## Checkpointing - -**Checkpointing** is a safety feature that automatically snapshots your -project's file state before the agent performs any destructive action (like -writing a file). - -- **Snapshots:** Stored in a hidden Git repository (separate from your project's - Git history). -- **Restore:** Allows you to instantly revert changes if the agent makes a - mistake, using the `/restore` command. - -## Context - -**Context** refers to the information the agent has about your current task and -environment. Gemini CLI provides context through several mechanisms: - -- **Conversation history:** The chat log of the current session. -- **Project context (`GEMINI.md`):** Persistent instructions and rules defined - in your project's root or subdirectories. -- **File content:** Files you explicitly reference (e.g., `@src/app.ts`) or that - the agent reads using tools. -- **Environment:** Information about your operating system, shell, and working - directory. - -Effective context management is key to getting accurate and relevant responses. - -## Extension - -An **Extension** is a pluggable package that adds new capabilities to Gemini -CLI. Extensions can bundle: - -- **Skills:** Specialized procedural knowledge. -- **MCP Servers:** Connections to external tools and data. -- **Commands:** Custom slash commands. - -## Headless mode - -**Headless mode** refers to running Gemini CLI without the interactive terminal -UI (TUI). This is used for scripting, automation, and piping data into or out of -the agent. - -- **Interactive:** `gemini` (starts the REPL). -- **Headless:** `gemini "Fix this file"` (runs once and exits). - -## Hook - -A **Hook** is a script or function that intercepts specific lifecycle events in -the CLI. - -- **Use cases:** Logging tool usage, validating user input, or modifying the - agent's system prompt dynamically. -- **Lifecycle:** Hooks can run before or after the agent starts, before tools - are executed, or after the session ends. - -## Model Context Protocol (MCP) - -The **Model Context Protocol (MCP)** is an open standard that allows Gemini CLI -to connect to external data sources and tools. - -- **MCP Server:** A lightweight application that exposes resources (data) and - tools (functions) to the CLI. -- **Use case:** Connecting Gemini to a PostgreSQL database, a GitHub repository, - or a Slack workspace without building custom integration logic into the CLI - core. - -## Policy engine - -The **Policy Engine** is the security subsystem that enforces rules on tool -execution. It evaluates every tool call against your configuration (e.g., -[Trusted folders](#trusted-folders), allowed commands) to decide whether to: - -- Allow the action immediately. -- Require user confirmation. -- Block the action entirely. - -## Sandboxing - -**Sandboxing** is an optional security mode that isolates the agent's execution -environment. When enabled, the agent runs inside a secure container (e.g., -Docker), preventing it from accessing sensitive files or system resources -outside of the designated workspace. - -## Session - -A **Session** is a single continuous interaction thread with the agent. - -- **State:** Sessions maintain conversation history and short-term memory. -- **Persistence:** Sessions are automatically saved, allowing you to pause, - resume, or rewind them later. - -## Skill - -A **Skill** (or **Agent Skill**) is a package of specialized expertise that the -agent can load on demand. Unlike general context, a skill provides specific -procedural knowledge for a distinct task. - -- **Example:** A "Code Reviewer" skill might contain a checklist of security - vulnerabilities to look for and a specific format for reporting findings. -- **Activation:** Skills are typically activated dynamically when the agent - recognizes a matching request. - -## Tool - -A **Tool** is a specific function or capability that the agent can execute. -Tools allow the AI to interact with the outside world. - -- **Built-in tools:** Core capabilities like `read_file`, `run_shell_command`, - and `google_web_search`. -- **MCP tools:** External tools provided by - [MCP servers](#model-context-protocol-mcp). - -When the agent uses a tool, it pauses generation, executes the code, and feeds -the output back into its context window. - -## Trusted folders - -**Trusted folders** are specific directories you have explicitly authorized the -agent to access without repeated confirmation prompts. This is a key component -of the [Policy engine](#policy-engine) to balance security and usability. diff --git a/docs/core/subagents.md b/docs/core/subagents.md index 1725d4a0f5..7e17da94ae 100644 --- a/docs/core/subagents.md +++ b/docs/core/subagents.md @@ -1,13 +1,13 @@ -# Sub-agents (experimental) +# Subagents (experimental) -Sub-agents are specialized agents that operate within your main Gemini CLI +Subagents are specialized agents that operate within your main Gemini CLI session. They are designed to handle specific, complex tasks—like deep codebase analysis, documentation lookup, or domain-specific reasoning—without cluttering the main agent's context or toolset. -> **Note: Sub-agents are currently an experimental feature.** +> **Note: Subagents are currently an experimental feature.** > -> To use custom sub-agents, you must explicitly enable them in your +> To use custom subagents, you must explicitly enable them in your > `settings.json`: > > ```json @@ -16,31 +16,31 @@ the main agent's context or toolset. > } > ``` > -> **Warning:** Sub-agents currently operate in +> **Warning:** Subagents currently operate in > ["YOLO mode"](../get-started/configuration.md#command-line-arguments), meaning > they may execute tools without individual user confirmation for each step. > Proceed with caution when defining agents with powerful tools like > `run_shell_command` or `write_file`. -## What are sub-agents? +## What are subagents? -Sub-agents are "specialists" that the main Gemini agent can hire for a specific +Subagents are "specialists" that the main Gemini agent can hire for a specific job. -- **Focused context:** Each sub-agent has its own system prompt and persona. -- **Specialized tools:** Sub-agents can have a restricted or specialized set of +- **Focused context:** Each subagent has its own system prompt and persona. +- **Specialized tools:** Subagents can have a restricted or specialized set of tools. -- **Independent context window:** Interactions with a sub-agent happen in a +- **Independent context window:** Interactions with a subagent happen in a separate context loop, which saves tokens in your main conversation history. -Sub-agents are exposed to the main agent as a tool of the same name. When the -main agent calls the tool, it delegates the task to the sub-agent. Once the -sub-agent completes its task, it reports back to the main agent with its +Subagents are exposed to the main agent as a tool of the same name. When the +main agent calls the tool, it delegates the task to the subagent. Once the +subagent completes its task, it reports back to the main agent with its findings. -## Built-in sub-agents +## Built-in subagents -Gemini CLI comes with the following built-in sub-agents: +Gemini CLI comes with the following built-in subagents: ### Codebase Investigator @@ -75,15 +75,15 @@ Gemini CLI comes with the following built-in sub-agents: ### Generalist Agent - **Name:** `generalist_agent` -- **Purpose:** Route tasks to the appropriate specialized sub-agent. +- **Purpose:** Route tasks to the appropriate specialized subagent. - **When to use:** Implicitly used by the main agent for routing. Not directly invoked by the user. - **Configuration:** Enabled by default. No specific configuration options. -## Creating custom sub-agents +## Creating custom subagents -You can create your own sub-agents to automate specific workflows or enforce -specific personas. To use custom sub-agents, you must enable them in your +You can create your own subagents to automate specific workflows or enforce +specific personas. To use custom subagents, you must enable them in your `settings.json`: ```json @@ -138,20 +138,20 @@ it yourself; just report it. ### Configuration schema -| Field | Type | Required | Description | -| :------------- | :----- | :------- | :------------------------------------------------------------------------------------------------------------------------- | -| `name` | string | Yes | Unique identifier (slug) used as the tool name for the agent. Only lowercase letters, numbers, hyphens, and underscores. | -| `description` | string | Yes | Short description of what the agent does. This is visible to the main agent to help it decide when to call this sub-agent. | -| `kind` | string | No | `local` (default) or `remote`. | -| `tools` | array | No | List of tool names this agent can use. If omitted, it may have access to a default set. | -| `model` | string | No | Specific model to use (e.g., `gemini-2.5-pro`). Defaults to `inherit` (uses the main session model). | -| `temperature` | number | No | Model temperature (0.0 - 2.0). | -| `max_turns` | number | No | Maximum number of conversation turns allowed for this agent before it must return. Defaults to `15`. | -| `timeout_mins` | number | No | Maximum execution time in minutes. Defaults to `5`. | +| Field | Type | Required | Description | +| :------------- | :----- | :------- | :------------------------------------------------------------------------------------------------------------------------ | +| `name` | string | Yes | Unique identifier (slug) used as the tool name for the agent. Only lowercase letters, numbers, hyphens, and underscores. | +| `description` | string | Yes | Short description of what the agent does. This is visible to the main agent to help it decide when to call this subagent. | +| `kind` | string | No | `local` (default) or `remote`. | +| `tools` | array | No | List of tool names this agent can use. If omitted, it may have access to a default set. | +| `model` | string | No | Specific model to use (e.g., `gemini-2.5-pro`). Defaults to `inherit` (uses the main session model). | +| `temperature` | number | No | Model temperature (0.0 - 2.0). | +| `max_turns` | number | No | Maximum number of conversation turns allowed for this agent before it must return. Defaults to `15`. | +| `timeout_mins` | number | No | Maximum execution time in minutes. Defaults to `5`. | -### Optimizing your sub-agent +### Optimizing your subagent -The main agent's system prompt encourages it to use an expert sub-agent when one +The main agent's system prompt encourages it to use an expert subagent when one is available. It decides whether an agent is a relevant expert based on the agent's description. You can improve the reliability with which an agent is used by updating the description to more clearly indicate: @@ -160,7 +160,7 @@ by updating the description to more clearly indicate: - When it should be used. - Some example scenarios. -For example, the following sub-agent description should be called fairly +For example, the following subagent description should be called fairly consistently for Git operations. > Git expert agent which should be used for all local and remote git operations. @@ -170,13 +170,13 @@ consistently for Git operations. > - Searching for regressions with bisect > - Interacting with source control and issues providers such as GitHub. -If you need to further tune your sub-agent, you can do so by selecting the model +If you need to further tune your subagent, you can do so by selecting the model to optimize for with `/model` and then asking the model why it does not think -that your sub-agent was called with a specific prompt and the given description. +that your subagent was called with a specific prompt and the given description. ## Remote subagents (Agent2Agent) (experimental) -Gemini CLI can also delegate tasks to remote sub-agents using the Agent-to-Agent +Gemini CLI can also delegate tasks to remote subagents using the Agent-to-Agent (A2A) protocol. > **Note: Remote subagents are currently an experimental feature.** @@ -184,8 +184,8 @@ Gemini CLI can also delegate tasks to remote sub-agents using the Agent-to-Agent See the [Remote Subagents documentation](/docs/core/remote-agents) for detailed configuration and usage instructions. -## Extension sub-agents +## Extension subagents -Extensions can bundle and distribute sub-agents. See the -[Extensions documentation](../extensions/index.md#sub-agents) for details on how +Extensions can bundle and distribute subagents. See the +[Extensions documentation](../extensions/index.md#subagents) for details on how to package agents within an extension. diff --git a/docs/get-started/configuration-v1.md b/docs/get-started/configuration-v1.md deleted file mode 100644 index cd1325b977..0000000000 --- a/docs/get-started/configuration-v1.md +++ /dev/null @@ -1,882 +0,0 @@ -# Gemini CLI configuration - -**Note on deprecated configuration format** - -This document describes the legacy v1 format for the `settings.json` file. This -format is now deprecated. - -- 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 new, recommended format, please see the -[current Configuration documentation](./configuration.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. - -## Configuration layers - -Configuration is applied in the following order of precedence (lower numbers are -overridden by higher numbers): - -1. **Default values:** Hardcoded defaults within the application. -2. **System defaults file:** System-wide default settings that can be - overridden by other settings files. -3. **User settings file:** Global settings for the current user. -4. **Project settings file:** Project-specific settings. -5. **System settings file:** System-wide settings that override all other - settings files. -6. **Environment variables:** System-wide or session-specific variables, - potentially loaded from `.env` files. -7. **Command-line arguments:** Values passed when launching the CLI. - -## Settings files - -Gemini CLI uses JSON settings files for persistent configuration. There are four -locations for these files: - -- **System defaults file:** - - **Location:** `/etc/gemini-cli/system-defaults.json` (Linux), - `C:\ProgramData\gemini-cli\system-defaults.json` (Windows) or - `/Library/Application Support/GeminiCli/system-defaults.json` (macOS). The - path can be overridden using the `GEMINI_CLI_SYSTEM_DEFAULTS_PATH` - environment variable. - - **Scope:** Provides a base layer of system-wide default settings. These - settings have the lowest precedence and are intended to be overridden by - user, project, or system override settings. -- **User settings file:** - - **Location:** `~/.gemini/settings.json` (where `~` is your home directory). - - **Scope:** Applies to all Gemini CLI sessions for the current user. User - settings override system defaults. -- **Project settings file:** - - **Location:** `.gemini/settings.json` within your project's root directory. - - **Scope:** Applies only when running Gemini CLI from that specific project. - Project settings override user settings and system defaults. -- **System settings file:** - - **Location:** `/etc/gemini-cli/settings.json` (Linux), - `C:\ProgramData\gemini-cli\settings.json` (Windows) or - `/Library/Application Support/GeminiCli/settings.json` (macOS). The path can - be overridden using the `GEMINI_CLI_SYSTEM_SETTINGS_PATH` environment - variable. - - **Scope:** Applies to all Gemini CLI sessions on the system, for all users. - System settings act as overrides, taking precedence over all other settings - files. May be useful for system administrators at enterprises to have - controls over users' Gemini CLI setups. - -**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](../cli/enterprise.md) documentation. - -### The `.gemini` directory in your project - -In addition to a project settings file, a project's `.gemini` directory can -contain other project-specific files related to Gemini CLI's operation, such as: - -- [Custom sandbox profiles](#sandboxing) (e.g., - `.gemini/sandbox-macos-custom.sb`, `.gemini/sandbox.Dockerfile`). - -### Available settings in `settings.json`: - -- **`contextFileName`** (string or array of strings): - - **Description:** Specifies the filename for context files (e.g., - `GEMINI.md`, `AGENTS.md`). Can be a single filename or a list of accepted - filenames. - - **Default:** `GEMINI.md` - - **Example:** `"contextFileName": "AGENTS.md"` - -- **`bugCommand`** (object): - - **Description:** Overrides the default URL for the `/bug` command. - - **Default:** - `"urlTemplate": "https://github.com/google-gemini/gemini-cli/issues/new?template=bug_report.yml&title={title}&info={info}"` - - **Properties:** - - **`urlTemplate`** (string): A URL that can contain `{title}` and `{info}` - placeholders. - - **Example:** - ```json - "bugCommand": { - "urlTemplate": "https://bug.example.com/new?title={title}&info={info}" - } - ``` - -- **`fileFiltering`** (object): - - **Description:** Controls git-aware file filtering behavior for @ commands - and file discovery tools. - - **Default:** `"respectGitIgnore": true, "enableRecursiveFileSearch": true` - - **Properties:** - - **`respectGitIgnore`** (boolean): Whether to respect .gitignore patterns - when discovering files. When set to `true`, git-ignored files (like - `node_modules/`, `dist/`, `.env`) are automatically excluded from @ - commands and file listing operations. - - **`enableRecursiveFileSearch`** (boolean): Whether to enable searching - recursively for filenames under the current tree when completing @ - prefixes in the prompt. - - **`disableFuzzySearch`** (boolean): When `true`, disables the fuzzy search - capabilities when searching for files, which can improve performance on - projects with a large number of files. - - **Example:** - ```json - "fileFiltering": { - "respectGitIgnore": true, - "enableRecursiveFileSearch": false, - "disableFuzzySearch": true - } - ``` - -### Troubleshooting file search performance - -If you are experiencing performance issues with file searching (e.g., with `@` -completions), especially in projects with a very large number of files, here are -a few things you can try in order of recommendation: - -1. **Use `.geminiignore`:** Create a `.geminiignore` file in your project root - to exclude directories that contain a large number of files that you don't - need to reference (e.g., build artifacts, logs, `node_modules`). Reducing - the total number of files crawled is the most effective way to improve - performance. - -2. **Disable fuzzy search:** If ignoring files is not enough, you can disable - fuzzy search by setting `disableFuzzySearch` to `true` in your - `settings.json` file. This will use a simpler, non-fuzzy matching algorithm, - which can be faster. - -3. **Disable recursive file search:** As a last resort, you can disable - recursive file search entirely by setting `enableRecursiveFileSearch` to - `false`. This will be the fastest option as it avoids a recursive crawl of - your project. However, it means you will need to type the full path to files - when using `@` completions. - -- **`coreTools`** (array of strings): - - **Description:** Allows you to specify a list of core tool names that should - be made available to the model. This can be used to restrict the set of - built-in tools. See [Built-in Tools](../core/tools-api.md#built-in-tools) - for a list of core tools. You can also specify command-specific restrictions - for tools that support it, like the `ShellTool`. For example, - `"coreTools": ["ShellTool(ls -l)"]` will only allow the `ls -l` command to - be executed. - - **Default:** All tools available for use by the Gemini model. - - **Example:** `"coreTools": ["ReadFileTool", "GlobTool", "ShellTool(ls)"]`. - -- **`allowedTools`** (array of strings) [DEPRECATED]: - - **Default:** `undefined` - - **Description:** A list of tool names that will bypass the confirmation - dialog. This is useful for tools that you trust and use frequently. The - match semantics are the same as `coreTools`. **Deprecated**: Use the - [Policy Engine](../core/policy-engine.md) instead. - - **Example:** `"allowedTools": ["ShellTool(git status)"]`. - -- **`excludeTools`** (array of strings) [DEPRECATED]: - - **Description:** Allows you to specify a list of core tool names that should - be excluded from the model. A tool listed in both `excludeTools` and - `coreTools` is excluded. You can also specify command-specific restrictions - for tools that support it, like the `ShellTool`. For example, - `"excludeTools": ["ShellTool(rm -rf)"]` will block the `rm -rf` command. - **Deprecated**: Use the [Policy Engine](../core/policy-engine.md) instead. - - **Default**: No tools excluded. - - **Example:** `"excludeTools": ["run_shell_command", "findFiles"]`. - - **Security Note:** Command-specific restrictions in `excludeTools` for - `run_shell_command` are based on simple string matching and can be easily - bypassed. This feature is **not a security mechanism** and should not be - relied upon to safely execute untrusted code. It is recommended to use - `coreTools` to explicitly select commands that can be executed. - -- **`allowMCPServers`** (array of strings): - - **Description:** Allows you to specify a list of MCP server names that - should be made available to the model. This can be used to restrict the set - of MCP servers to connect to. Note that this will be ignored if - `--allowed-mcp-server-names` is set. - - **Default:** All MCP servers are available for use by the Gemini model. - - **Example:** `"allowMCPServers": ["myPythonServer"]`. - - **Security note:** This uses simple string matching on MCP server names, - which can be modified. If you're a system administrator looking to prevent - users from bypassing this, consider configuring the `mcpServers` at the - system settings level such that the user will not be able to configure any - MCP servers of their own. This should not be used as an airtight security - mechanism. - -- **`excludeMCPServers`** (array of strings): - - **Description:** Allows you to specify a list of MCP server names that - should be excluded from the model. A server listed in both - `excludeMCPServers` and `allowMCPServers` is excluded. Note that this will - be ignored if `--allowed-mcp-server-names` is set. - - **Default**: No MCP servers excluded. - - **Example:** `"excludeMCPServers": ["myNodeServer"]`. - - **Security note:** This uses simple string matching on MCP server names, - which can be modified. If you're a system administrator looking to prevent - users from bypassing this, consider configuring the `mcpServers` at the - system settings level such that the user will not be able to configure any - MCP servers of their own. This should not be used as an airtight security - mechanism. - -- **`theme`** (string): - - **Description:** Sets the visual [theme](../cli/themes.md) for Gemini CLI. - - **Default:** `"Default"` - - **Example:** `"theme": "GitHub"` - -- **`vimMode`** (boolean): - - **Description:** Enables or disables vim mode for input editing. When - enabled, the input area supports vim-style navigation and editing commands - with NORMAL and INSERT modes. The vim mode status is displayed in the footer - and persists between sessions. - - **Default:** `false` - - **Example:** `"vimMode": true` - -- **`sandbox`** (boolean or string): - - **Description:** Controls whether and how to use sandboxing for tool - execution. If set to `true`, Gemini CLI uses a pre-built - `gemini-cli-sandbox` Docker image. For more information, see - [Sandboxing](#sandboxing). - - **Default:** `false` - - **Example:** `"sandbox": "docker"` - -- **`toolDiscoveryCommand`** (string): - - **Description:** Defines a custom shell command for discovering tools from - your project. The shell command must return on `stdout` a JSON array of - [function declarations](https://ai.google.dev/gemini-api/docs/function-calling#function-declarations). - Tool wrappers are optional. - - **Default:** Empty - - **Example:** `"toolDiscoveryCommand": "bin/get_tools"` - -- **`toolCallCommand`** (string): - - **Description:** Defines a custom shell command for calling a specific tool - that was discovered using `toolDiscoveryCommand`. 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 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:** Empty - - **Example:** `"toolCallCommand": "bin/call_tool"` - -- **`mcpServers`** (object): - - **Description:** Configures connections to one or more Model-Context - Protocol (MCP) servers for discovering and using custom tools. Gemini CLI - attempts to connect to each configured MCP server to discover available - tools. If multiple MCP servers expose a tool with the same name, the tool - names will be prefixed with the server alias you defined in the - configuration (e.g., `serverAlias__actualToolName`) to avoid conflicts. Note - that the system might strip certain schema properties from MCP tool - definitions for compatibility. At least one of `command`, `url`, or - `httpUrl` must be provided. If multiple are specified, the order of - precedence is `httpUrl`, then `url`, then `command`. - - **Default:** Empty - - **Properties:** - - **``** (object): The server parameters for the named server. - - `command` (string, optional): The command to execute to start the MCP - server via standard I/O. - - `args` (array of strings, optional): Arguments to pass to the command. - - `env` (object, optional): Environment variables to set for the server - process. - - `cwd` (string, optional): The working directory in which to start the - server. - - `url` (string, optional): The URL of an MCP server that uses Server-Sent - Events (SSE) for communication. - - `httpUrl` (string, optional): The URL of an MCP server that uses - streamable HTTP for communication. - - `headers` (object, optional): A map of HTTP headers to send with - requests to `url` or `httpUrl`. - - `timeout` (number, optional): Timeout in milliseconds for requests to - this MCP server. - - `trust` (boolean, optional): Trust this server and bypass all tool call - confirmations. - - `description` (string, optional): A brief description of the server, - which may be used for display purposes. - - `includeTools` (array of strings, optional): List of tool names to - include from this MCP server. When specified, only the tools listed here - will be available from this server (allowlist behavior). If not - specified, all tools from the server are enabled by default. - - `excludeTools` (array of strings, optional): List of tool names to - exclude from this MCP server. Tools listed here will not be available to - the model, even if they are exposed by the server. **Note:** - `excludeTools` takes precedence over `includeTools` - if a tool is in - both lists, it will be excluded. - - **Example:** - ```json - "mcpServers": { - "myPythonServer": { - "command": "python", - "args": ["mcp_server.py", "--port", "8080"], - "cwd": "./mcp_tools/python", - "timeout": 5000, - "includeTools": ["safe_tool", "file_reader"], - }, - "myNodeServer": { - "command": "node", - "args": ["mcp_server.js"], - "cwd": "./mcp_tools/node", - "excludeTools": ["dangerous_tool", "file_deleter"] - }, - "myDockerServer": { - "command": "docker", - "args": ["run", "-i", "--rm", "-e", "API_KEY", "ghcr.io/foo/bar"], - "env": { - "API_KEY": "$MY_API_TOKEN" - } - }, - "mySseServer": { - "url": "http://localhost:8081/events", - "headers": { - "Authorization": "Bearer $MY_SSE_TOKEN" - }, - "description": "An example SSE-based MCP server." - }, - "myStreamableHttpServer": { - "httpUrl": "http://localhost:8082/stream", - "headers": { - "X-API-Key": "$MY_HTTP_API_KEY" - }, - "description": "An example Streamable HTTP-based MCP server." - } - } - ``` - -- **`checkpointing`** (object): - - **Description:** Configures the checkpointing feature, which allows you to - save and restore conversation and file states. See the - [Checkpointing documentation](../cli/checkpointing.md) for more details. - - **Default:** `{"enabled": false}` - - **Properties:** - - **`enabled`** (boolean): When `true`, the `/restore` command is available. - -- **`preferredEditor`** (string): - - **Description:** Specifies the preferred editor to use for viewing diffs. - - **Default:** `vscode` - - **Example:** `"preferredEditor": "vscode"` - -- **`telemetry`** (object) - - **Description:** Configures logging and metrics collection for Gemini CLI. - For more information, see [Telemetry](../cli/telemetry.md). - - **Default:** - `{"enabled": false, "target": "local", "otlpEndpoint": "http://localhost:4317", "logPrompts": true}` - - **Properties:** - - **`enabled`** (boolean): Whether or not telemetry is enabled. - - **`target`** (string): The destination for collected telemetry. Supported - values are `local` and `gcp`. - - **`otlpEndpoint`** (string): The endpoint for the OTLP Exporter. - - **`logPrompts`** (boolean): Whether or not to include the content of user - prompts in the logs. - - **Example:** - ```json - "telemetry": { - "enabled": true, - "target": "local", - "otlpEndpoint": "http://localhost:16686", - "logPrompts": false - } - ``` -- **`usageStatisticsEnabled`** (boolean): - - **Description:** Enables or disables the collection of usage statistics. See - [Usage Statistics](#usage-statistics) for more information. - - **Default:** `true` - - **Example:** - ```json - "usageStatisticsEnabled": false - ``` - -- **`hideTips`** (boolean): - - **Description:** Enables or disables helpful tips in the CLI interface. - - **Default:** `false` - - **Example:** - - ```json - "hideTips": true - ``` - -- **`hideBanner`** (boolean): - - **Description:** Enables or disables the startup banner (ASCII art logo) in - the CLI interface. - - **Default:** `false` - - **Example:** - - ```json - "hideBanner": true - ``` - -- **`maxSessionTurns`** (number): - - **Description:** Sets the maximum number of turns for a session. If the - session exceeds this limit, the CLI will stop processing and start a new - chat. - - **Default:** `-1` (unlimited) - - **Example:** - ```json - "maxSessionTurns": 10 - ``` - -- **`summarizeToolOutput`** (object): - - **Description:** Enables or disables the summarization of tool output. You - can specify the token budget for the summarization using the `tokenBudget` - setting. - - Note: Currently only the `run_shell_command` tool is supported. - - **Default:** `{}` (Disabled by default) - - **Example:** - ```json - "summarizeToolOutput": { - "run_shell_command": { - "tokenBudget": 2000 - } - } - ``` - -- **`excludedProjectEnvVars`** (array of strings): - - **Description:** Specifies environment variables that should be excluded - from being loaded from project `.env` files. This prevents project-specific - environment variables (like `DEBUG=true`) from interfering with gemini-cli - behavior. Variables from `.gemini/.env` files are never excluded. - - **Default:** `["DEBUG", "DEBUG_MODE"]` - - **Example:** - ```json - "excludedProjectEnvVars": ["DEBUG", "DEBUG_MODE", "NODE_ENV"] - ``` - -- **`includeDirectories`** (array of strings): - - **Description:** Specifies an array of additional absolute or relative paths - to include in the workspace context. Missing directories will be skipped - with a warning by default. Paths can use `~` to refer to the user's home - directory. This setting can be combined with the `--include-directories` - command-line flag. - - **Default:** `[]` - - **Example:** - ```json - "includeDirectories": [ - "/path/to/another/project", - "../shared-library", - "~/common-utils" - ] - ``` - -- **`loadMemoryFromIncludeDirectories`** (boolean): - - **Description:** Controls the behavior of the `/memory refresh` command. If - set to `true`, `GEMINI.md` files should be loaded from all directories that - are added. If set to `false`, `GEMINI.md` should only be loaded from the - current directory. - - **Default:** `false` - - **Example:** - ```json - "loadMemoryFromIncludeDirectories": true - ``` - -- **`showLineNumbers`** (boolean): - - **Description:** Controls whether line numbers are displayed in code blocks - in the CLI output. - - **Default:** `true` - - **Example:** - ```json - "showLineNumbers": false - ``` - -- **`accessibility`** (object): - - **Description:** Configures accessibility features for the CLI. - - **Properties:** - - **`screenReader`** (boolean): Enables screen reader mode, which adjusts - the TUI for better compatibility with screen readers. This can also be - enabled with the `--screen-reader` command-line flag, which will take - precedence over the setting. - - **`disableLoadingPhrases`** (boolean): Disables the display of loading - phrases during operations. - - **Default:** `{"screenReader": false, "disableLoadingPhrases": false}` - - **Example:** - ```json - "accessibility": { - "screenReader": true, - "disableLoadingPhrases": true - } - ``` - -### Example `settings.json`: - -```json -{ - "theme": "GitHub", - "sandbox": "docker", - "toolDiscoveryCommand": "bin/get_tools", - "toolCallCommand": "bin/call_tool", - "mcpServers": { - "mainServer": { - "command": "bin/mcp_server.py" - }, - "anotherServer": { - "command": "node", - "args": ["mcp_server.js", "--verbose"] - } - }, - "telemetry": { - "enabled": true, - "target": "local", - "otlpEndpoint": "http://localhost:4317", - "logPrompts": true - }, - "usageStatisticsEnabled": true, - "hideTips": false, - "hideBanner": false, - "maxSessionTurns": 10, - "summarizeToolOutput": { - "run_shell_command": { - "tokenBudget": 100 - } - }, - "excludedProjectEnvVars": ["DEBUG", "DEBUG_MODE", "NODE_ENV"], - "includeDirectories": ["path/to/dir1", "~/path/to/dir2", "../path/to/dir3"], - "loadMemoryFromIncludeDirectories": true -} -``` - -## Shell history - -The CLI keeps a history of shell commands you run. To avoid conflicts between -different projects, this history is stored in a project-specific directory -within your user's home folder. - -- **Location:** `~/.gemini/tmp//shell_history` - - `` is a unique identifier generated from your project's root - path. - - The history is stored in a file named `shell_history`. - -## Environment variables and `.env` files - -Environment variables are a common way to configure applications, especially for -sensitive information like API keys or for settings that might change between -environments. For authentication setup, see the -[Authentication documentation](./authentication.md) which covers all available -authentication methods. - -The CLI automatically loads environment variables from an `.env` file. The -loading order is: - -1. `.env` file in the current working directory. -2. If not found, it searches upwards in parent directories until it finds an - `.env` file or reaches the project root (identified by a `.git` folder) or - the home directory. -3. If still not found, it looks for `~/.env` (in the user's home directory). - -**Environment variable exclusion:** Some environment variables (like `DEBUG` and -`DEBUG_MODE`) are automatically excluded from being loaded from project `.env` -files to prevent interference with gemini-cli behavior. Variables from -`.gemini/.env` files are never excluded. You can customize this behavior using -the `excludedProjectEnvVars` setting in your `settings.json` file. - -- **`GEMINI_API_KEY`**: - - Your API key for the Gemini API. - - One of several available [authentication methods](./authentication.md). - - Set this in your shell profile (e.g., `~/.bashrc`, `~/.zshrc`) or an `.env` - file. -- **`GEMINI_MODEL`**: - - Specifies the default Gemini model to use. - - Overrides the hardcoded default - - Example: `export GEMINI_MODEL="gemini-2.5-flash"` -- **`GOOGLE_API_KEY`**: - - Your Google Cloud API key. - - Required for using Vertex AI in express mode. - - Ensure you have the necessary permissions. - - Example: `export GOOGLE_API_KEY="YOUR_GOOGLE_API_KEY"`. -- **`GOOGLE_CLOUD_PROJECT`**: - - Your Google Cloud Project ID. - - Required for using Code Assist or Vertex AI. - - If using Vertex AI, ensure you have the necessary permissions in this - project. - - **Cloud Shell note:** When running in a Cloud Shell environment, this - variable defaults to a special project allocated for Cloud Shell users. If - you have `GOOGLE_CLOUD_PROJECT` set in your global environment in Cloud - Shell, it will be overridden by this default. To use a different project in - Cloud Shell, you must define `GOOGLE_CLOUD_PROJECT` in a `.env` file. - - Example: `export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"`. -- **`GOOGLE_APPLICATION_CREDENTIALS`** (string): - - **Description:** The path to your Google Application Credentials JSON file. - - **Example:** - `export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/credentials.json"` -- **`OTLP_GOOGLE_CLOUD_PROJECT`**: - - Your Google Cloud Project ID for Telemetry in Google Cloud - - Example: `export OTLP_GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"`. -- **`GOOGLE_CLOUD_LOCATION`**: - - Your Google Cloud Project Location (e.g., us-central1). - - 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`. - - Accepts `true`, `false`, `docker`, `podman`, or a custom command string. -- **`HTTP_PROXY` / `HTTPS_PROXY`**: - - Specifies the proxy server to use for outgoing HTTP/HTTPS requests. - - Example: `export HTTPS_PROXY="http://proxy.example.com:8080"` -- **`SEATBELT_PROFILE`** (macOS specific): - - Switches the Seatbelt (`sandbox-exec`) profile on macOS. - - `permissive-open`: (Default) Restricts writes to the project folder (and a - few other folders, see - `packages/cli/src/utils/sandbox-macos-permissive-open.sb`) but allows other - operations. - - `strict`: Uses a strict profile that declines operations by default. - - ``: Uses a custom profile. To define a custom profile, create - a file named `sandbox-macos-.sb` in your project's `.gemini/` - directory (e.g., `my-project/.gemini/sandbox-macos-custom.sb`). -- **`DEBUG` or `DEBUG_MODE`** (often used by underlying libraries or the CLI - itself): - - Set to `true` or `1` to enable verbose debug logging, which can be helpful - for troubleshooting. - - **Note:** These variables are automatically excluded from project `.env` - files by default to prevent interference with gemini-cli behavior. Use - `.gemini/.env` files if you need to set these for gemini-cli specifically. -- **`NO_COLOR`**: - - Set to any value to disable all color output in the CLI. -- **`CLI_TITLE`**: - - Set to a string to customize the title of the CLI. -- **`CODE_ASSIST_ENDPOINT`**: - - Specifies the endpoint for the code assist server. - - This is useful for development and testing. - -## Command-line arguments - -Arguments passed directly when running the CLI can override other configurations -for that specific session. - -- **`--model `** (**`-m `**): - - Specifies the Gemini model to use for this session. - - Example: `npm start -- --model gemini-1.5-pro-latest` -- **`--prompt `** (**`-p `**): - - Used to pass a prompt directly to the command. This invokes Gemini CLI in a - non-interactive mode. -- **`--prompt-interactive `** (**`-i `**): - - Starts an interactive session with the provided prompt as the initial input. - - The prompt is processed within the interactive session, not before it. - - Cannot be used when piping input from stdin. - - Example: `gemini -i "explain this code"` -- **`--sandbox`** (**`-s`**): - - Enables sandbox mode for this session. -- **`--sandbox-image`**: - - Sets the sandbox image URI. -- **`--debug`** (**`-d`**): - - Enables debug mode for this session, providing more verbose output. - -- **`--help`** (or **`-h`**): - - Displays help information about command-line arguments. -- **`--show-memory-usage`**: - - Displays the current memory usage. -- **`--yolo`**: - - Enables YOLO mode, which automatically approves all tool calls. -- **`--approval-mode `**: - - Sets the approval mode for tool calls. Available modes: - - `default`: Prompt for approval on each tool call (default behavior) - - `auto_edit`: Automatically approve edit tools (replace, write_file) while - prompting for others - - `yolo`: Automatically approve all tool calls (equivalent to `--yolo`) - - Cannot be used together with `--yolo`. Use `--approval-mode=yolo` instead of - `--yolo` for the new unified approach. - - Example: `gemini --approval-mode auto_edit` -- **`--allowed-tools `**: - - A comma-separated list of tool names that will bypass the confirmation - dialog. - - Example: `gemini --allowed-tools "ShellTool(git status)"` -- **`--telemetry`**: - - Enables [telemetry](../cli/telemetry.md). -- **`--telemetry-target`**: - - Sets the telemetry target. See [telemetry](../cli/telemetry.md) for more - information. -- **`--telemetry-otlp-endpoint`**: - - Sets the OTLP endpoint for telemetry. See [telemetry](../cli/telemetry.md) - for more information. -- **`--telemetry-otlp-protocol`**: - - Sets the OTLP protocol for telemetry (`grpc` or `http`). Defaults to `grpc`. - See [telemetry](../cli/telemetry.md) for more information. -- **`--telemetry-log-prompts`**: - - Enables logging of prompts for telemetry. See - [telemetry](../cli/telemetry.md) for more information. -- **`--extensions `** (**`-e `**): - - Specifies a list of extensions to use for the session. If not provided, all - available extensions are used. - - Use the special term `gemini -e none` to disable all extensions. - - Example: `gemini -e my-extension -e my-other-extension` -- **`--list-extensions`** (**`-l`**): - - Lists all available extensions and exits. -- **`--include-directories `**: - - Includes additional directories in the workspace for multi-directory - support. - - Can be specified multiple times or as comma-separated values. - - 5 directories can be added at maximum. - - Example: `--include-directories /path/to/project1,/path/to/project2` or - `--include-directories /path/to/project1 --include-directories /path/to/project2` -- **`--screen-reader`**: - - Enables screen reader mode for accessibility. -- **`--version`**: - - Displays the version of the CLI. - -## Context files (hierarchical instructional context) - -While not strictly configuration for the CLI's _behavior_, context files -(defaulting to `GEMINI.md` but configurable via the `contextFileName` setting) -are crucial for configuring the _instructional context_ (also referred to as -"memory") provided to the Gemini model. This powerful feature allows you to give -project-specific instructions, coding style guides, or any relevant background -information to the AI, making its responses more tailored and accurate to your -needs. The CLI includes UI elements, such as an indicator in the footer showing -the number of loaded context files, to keep you informed about the active -context. - -- **Purpose:** These Markdown files contain instructions, guidelines, or context - that you want the Gemini model to be aware of during your interactions. The - system is designed to manage this instructional context hierarchically. - -### Example context file content (e.g., `GEMINI.md`) - -Here's a conceptual example of what a context file at the root of a TypeScript -project might contain: - -```markdown -# Project: My Awesome TypeScript Library - -## General Instructions: - -- When generating new TypeScript code, please follow the existing coding style. -- Ensure all new functions and classes have JSDoc comments. -- Prefer functional programming paradigms where appropriate. -- All code should be compatible with TypeScript 5.0 and Node.js 20+. - -## Coding Style: - -- Use 2 spaces for indentation. -- Interface names should be prefixed with `I` (e.g., `IUserService`). -- Private class members should be prefixed with an underscore (`_`). -- Always use strict equality (`===` and `!==`). - -## Specific Component: `src/api/client.ts` - -- This file handles all outbound API requests. -- When adding new API call functions, ensure they include robust error handling - and logging. -- Use the existing `fetchWithRetry` utility for all GET requests. - -## Regarding Dependencies: - -- Avoid introducing new external dependencies unless absolutely necessary. -- If a new dependency is required, please state the reason. -``` - -This example demonstrates how you can provide general project context, specific -coding conventions, and even notes about particular files or components. The -more relevant and precise your context files are, the better the AI can assist -you. Project-specific context files are highly encouraged to establish -conventions and context. - -- **Hierarchical loading and precedence:** The CLI implements a sophisticated - hierarchical memory system by loading context files (e.g., `GEMINI.md`) from - several locations. Content from files lower in this list (more specific) - typically overrides or supplements content from files higher up (more - general). The exact concatenation order and final context can be inspected - using the `/memory show` command. The typical loading order is: - 1. **Global context file:** - - Location: `~/.gemini/` (e.g., `~/.gemini/GEMINI.md` in - your user home directory). - - Scope: Provides default instructions for all your projects. - 2. **Project root and ancestors context files:** - - Location: The CLI searches for the configured context file in the - current working directory and then in each parent directory up to either - the project root (identified by a `.git` folder) or your home directory. - - Scope: Provides context relevant to the entire project or a significant - portion of it. - 3. **Sub-directory context files (contextual/local):** - - Location: The CLI also scans for the configured context file in - subdirectories _below_ the current working directory (respecting common - ignore patterns like `node_modules`, `.git`, etc.). The breadth of this - search is limited to 200 directories by default, but can be configured - with a `memoryDiscoveryMaxDirs` field in your `settings.json` file. - - Scope: Allows for highly specific instructions relevant to a particular - component, module, or subsection of your project. -- **Concatenation and UI indication:** The contents of all found context files - are concatenated (with separators indicating their origin and path) and - provided as part of the system prompt to the Gemini model. The CLI footer - displays the count of loaded context files, giving you a quick visual cue - about the active instructional context. -- **Importing content:** You can modularize your context files by importing - other Markdown files using the `@path/to/file.md` syntax. For more details, - see the [Memory Import Processor documentation](../core/memport.md). -- **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](../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. - -## Sandboxing - -The Gemini CLI can execute potentially unsafe operations (like shell commands -and file modifications) within a sandboxed environment to protect your system. - -Sandboxing is disabled by default, but you can enable it in a few ways: - -- Using `--sandbox` or `-s` flag. -- Setting `GEMINI_SANDBOX` environment variable. -- Sandbox is enabled when using `--yolo` or `--approval-mode=yolo` by default. - -By default, it uses a pre-built `gemini-cli-sandbox` Docker image. - -For project-specific sandboxing needs, you can create a custom Dockerfile at -`.gemini/sandbox.Dockerfile` in your project's root directory. This Dockerfile -can be based on the base sandbox image: - -```dockerfile -FROM gemini-cli-sandbox - -# Add your custom dependencies or configurations here -# For example: -# RUN apt-get update && apt-get install -y some-package -# COPY ./my-config /app/my-config -``` - -When `.gemini/sandbox.Dockerfile` exists, you can use `BUILD_SANDBOX` -environment variable when running Gemini CLI to automatically build the custom -sandbox image: - -```bash -BUILD_SANDBOX=1 gemini -s -``` - -## Usage statistics - -To help us improve the Gemini CLI, we collect anonymized usage statistics. This -data helps us understand how the CLI is used, identify common issues, and -prioritize new features. - -**What we collect:** - -- **Tool calls:** We log the names of the tools that are called, whether they - succeed or fail, and how long they take to execute. We do not collect the - arguments passed to the tools or any data returned by them. -- **API requests:** We log the Gemini model used for each request, the duration - of the request, and whether it was successful. We do not collect the content - of the prompts or responses. -- **Session information:** We collect information about the configuration of the - CLI, such as the enabled tools and the approval mode. - -**What we DON'T collect:** - -- **Personally identifiable information (PII):** We do not collect any personal - information, such as your name, email address, or API keys. -- **Prompt and response content:** We do not log the content of your prompts or - the responses from the Gemini model. -- **File content:** We do not log the content of any files that are read or - written by the CLI. - -**How to opt out:** - -You can opt out of usage statistics collection at any time by setting the -`usageStatisticsEnabled` property to `false` in your `settings.json` file: - -```json -{ - "usageStatisticsEnabled": false -} -``` diff --git a/docs/get-started/configuration.md b/docs/get-started/configuration.md index 8d324c8795..77065ab3c8 100644 --- a/docs/get-started/configuration.md +++ b/docs/get-started/configuration.md @@ -1,16 +1,5 @@ # Gemini CLI configuration -> **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. diff --git a/docs/get-started/examples.md b/docs/get-started/examples.md index b1359efc73..5d31ddedb8 100644 --- a/docs/get-started/examples.md +++ b/docs/get-started/examples.md @@ -132,8 +132,8 @@ for your login page. ## Next steps -- Explore the [User guides](../cli/index.md#user-guides) for detailed - walkthroughs of common tasks. +- Follow the [File management](../cli/tutorials/file-management.md) guide to + start working with your codebase. - Follow the [Quickstart](./index.md) to start your first session. - See the [Cheatsheet](../cli/cli-reference.md) for a quick reference of available commands. diff --git a/docs/get-started/index.md b/docs/get-started/index.md index 0dfb8ee18f..d5cf891381 100644 --- a/docs/get-started/index.md +++ b/docs/get-started/index.md @@ -70,4 +70,3 @@ To explore the power of Gemini CLI, see [Gemini CLI examples](./examples.md). start working with your codebase. - See [Shell commands](../cli/tutorials/shell-commands.md) to learn about terminal integration. -- Explore the full range of [User guides](../cli/index.md#user-guides). diff --git a/docs/index.md b/docs/index.md index 9711d39e18..813cd4047e 100644 --- a/docs/index.md +++ b/docs/index.md @@ -30,6 +30,8 @@ User-focused guides and tutorials for daily development workflows. - **[File management](./cli/tutorials/file-management.md):** How to work with local files and directories. +- **[Get started with Agent skills](./cli/tutorials/skills-getting-started.md):** + Getting started with specialized expertise. - **[Manage context and memory](./cli/tutorials/memory-management.md):** Managing persistent instructions and facts. - **[Execute shell commands](./cli/tutorials/shell-commands.md):** Executing @@ -40,8 +42,9 @@ User-focused guides and tutorials for daily development workflows. complex workflows. - **[Web search and fetch](./cli/tutorials/web-tools.md):** Searching and fetching content from the web. -- **[Get started with skills](./cli/tutorials/skills-getting-started.md):** - Getting started with specialized expertise. +- **[Set up an MCP server](./cli/tutorials/mcp-setup.md):** Set up an MCP + server. +- **[Automate tasks](./cli/tutorials/automation.md):** Automate tasks. ## Features @@ -92,10 +95,14 @@ Technical reference documentation for each capability of Gemini CLI. lookup for CLI features. - **[Memory (tool)](./tools/memory.md):** Storage details for persistent facts. - **[Model routing](./cli/model-routing.md):** Automatic fallback resilience. -- **[Plan mode (experimental)](./cli/plan-mode.md):** Use a safe, read-only mode - for planning complex changes. +- **[Plan mode 🧪](./cli/plan-mode.md):** Use a safe, read-only mode for + planning complex changes. +- **[Remote subagents 🧪](./core/remote-agents.md):** Connecting to and using + remote agents. - **[Sandboxing](./cli/sandbox.md):** Isolate tool execution. - **[Shell (tool)](./tools/shell.md):** Detailed system execution parameters. +- **[Subagents 🧪](./core/subagents.md):** Using specialized agents for specific + tasks. - **[Telemetry](./cli/telemetry.md):** Usage and performance metric details. - **[Todo (tool)](./tools/todos.md):** Progress tracking specification. - **[Token caching](./cli/token-caching.md):** Performance optimization. @@ -127,14 +134,14 @@ Settings and customization options for Gemini CLI. Deep technical documentation and API specifications. -- **[Architecture overview](./architecture.md):** System design and components. - **[Command reference](./cli/commands.md):** Detailed slash command guide. - **[Configuration reference](./get-started/configuration.md):** Settings and environment variables. -- **[Core concepts](./core/concepts.md):** Fundamental terminology and - definitions. - **[Keyboard shortcuts](./cli/keyboard-shortcuts.md):** Productivity tips. +- **[Memory import processor](./core/memport.md):** How Gemini CLI processes + memory from various sources. - **[Policy engine](./core/policy-engine.md):** Fine-grained execution control. +- **[Tools API](./core/tools-api.md):** The API for defining and using tools. ## Resources @@ -144,3 +151,19 @@ Support, release history, and legal information. - **[Changelogs](./changelogs/index.md):** Highlights and notable changes. - **[Quota and pricing](./quota-and-pricing.md):** Limits and billing details. - **[Terms and privacy](./tos-privacy.md):** Official notices and terms. + +## Development + +- **[Contribution guide](/docs/contributing):** How to contribute to Gemini CLI. +- **[Integration testing](./integration-tests.md):** Running integration tests. +- **[Issue and PR automation](./issue-and-pr-automation.md):** Automation for + issues and pull requests. +- **[Local development](./local-development.md):** Setting up a local + development environment. +- **[NPM package structure](./npm.md):** The structure of the NPM packages. + +## Releases + +- **[Release notes](./changelogs/index.md):** Release notes for all versions. +- **[Stable release](./changelogs/latest.md):** The latest stable release. +- **[Preview release](./changelogs/preview.md):** The latest preview release. diff --git a/docs/sidebar.json b/docs/sidebar.json index 617c31756e..4e95111a13 100644 --- a/docs/sidebar.json +++ b/docs/sidebar.json @@ -18,6 +18,10 @@ "label": "File management", "slug": "docs/cli/tutorials/file-management" }, + { + "label": "Get started with Agent skills", + "slug": "docs/cli/tutorials/skills-getting-started" + }, { "label": "Manage context and memory", "slug": "docs/cli/tutorials/memory-management" @@ -38,10 +42,6 @@ "label": "Web search and fetch", "slug": "docs/cli/tutorials/web-tools" }, - { - "label": "Get started with skills", - "slug": "docs/cli/tutorials/skills-getting-started" - }, { "label": "Set up an MCP server", "slug": "docs/cli/tutorials/mcp-setup" @@ -73,7 +73,13 @@ }, { "label": "Model routing", "slug": "docs/cli/model-routing" }, { "label": "Model selection", "slug": "docs/cli/model" }, - { "label": "Plan mode (experimental)", "slug": "docs/cli/plan-mode" }, + { "label": "Plan mode", "badge": "🧪", "slug": "docs/cli/plan-mode" }, + { "label": "Subagents", "badge": "🧪", "slug": "docs/core/subagents" }, + { + "label": "Remote subagents", + "badge": "🧪", + "slug": "docs/core/remote-agents" + }, { "label": "Rewind", "slug": "docs/cli/rewind" }, { "label": "Sandboxing", "slug": "docs/cli/sandbox" }, { "label": "Settings", "slug": "docs/cli/settings" }, @@ -142,13 +148,11 @@ { "label": "Reference", "items": [ - { "label": "Architecture", "slug": "docs/architecture" }, { "label": "Command reference", "slug": "docs/cli/commands" }, { "label": "Configuration reference", "slug": "docs/get-started/configuration" }, - { "label": "Core concepts", "slug": "docs/core/concepts" }, { "label": "Keyboard shortcuts", "slug": "docs/cli/keyboard-shortcuts" }, { "label": "Memory import processor", "slug": "docs/core/memport" }, { "label": "Policy engine", "slug": "docs/core/policy-engine" },