mirror of
https://github.com/google-gemini/gemini-cli.git
synced 2026-03-10 22:21:22 -07:00
Remove unused files and update index and sidebar. (#19479)
This commit is contained in:
Sam Roberts
@@ -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.
|
|
||||||
@@ -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.
|
|
||||||
@@ -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.
|
|
||||||
@@ -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
|
session. They are designed to handle specific, complex tasks—like deep codebase
|
||||||
analysis, documentation lookup, or domain-specific reasoning—without cluttering
|
analysis, documentation lookup, or domain-specific reasoning—without cluttering
|
||||||
the main agent's context or toolset.
|
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`:
|
> `settings.json`:
|
||||||
>
|
>
|
||||||
> ```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
|
> ["YOLO mode"](../get-started/configuration.md#command-line-arguments), meaning
|
||||||
> they may execute tools without individual user confirmation for each step.
|
> they may execute tools without individual user confirmation for each step.
|
||||||
> Proceed with caution when defining agents with powerful tools like
|
> Proceed with caution when defining agents with powerful tools like
|
||||||
> `run_shell_command` or `write_file`.
|
> `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.
|
job.
|
||||||
|
|
||||||
- **Focused context:** Each sub-agent has its own system prompt and persona.
|
- **Focused context:** Each subagent has its own system prompt and persona.
|
||||||
- **Specialized tools:** Sub-agents can have a restricted or specialized set of
|
- **Specialized tools:** Subagents can have a restricted or specialized set of
|
||||||
tools.
|
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.
|
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
|
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 sub-agent. Once the
|
main agent calls the tool, it delegates the task to the subagent. Once the
|
||||||
sub-agent completes its task, it reports back to the main agent with its
|
subagent completes its task, it reports back to the main agent with its
|
||||||
findings.
|
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
|
### Codebase Investigator
|
||||||
|
|
||||||
@@ -75,15 +75,15 @@ Gemini CLI comes with the following built-in sub-agents:
|
|||||||
### Generalist Agent
|
### Generalist Agent
|
||||||
|
|
||||||
- **Name:** `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
|
- **When to use:** Implicitly used by the main agent for routing. Not directly
|
||||||
invoked by the user.
|
invoked by the user.
|
||||||
- **Configuration:** Enabled by default. No specific configuration options.
|
- **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
|
You can create your own subagents to automate specific workflows or enforce
|
||||||
specific personas. To use custom sub-agents, you must enable them in your
|
specific personas. To use custom subagents, you must enable them in your
|
||||||
`settings.json`:
|
`settings.json`:
|
||||||
|
|
||||||
```json
|
```json
|
||||||
@@ -138,20 +138,20 @@ it yourself; just report it.
|
|||||||
|
|
||||||
### Configuration schema
|
### Configuration schema
|
||||||
|
|
||||||
| Field | Type | Required | Description |
|
| 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. |
|
| `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. |
|
| `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`. |
|
| `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. |
|
| `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). |
|
| `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). |
|
| `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`. |
|
| `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`. |
|
| `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
|
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
|
agent's description. You can improve the reliability with which an agent is used
|
||||||
by updating the description to more clearly indicate:
|
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.
|
- When it should be used.
|
||||||
- Some example scenarios.
|
- 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.
|
consistently for Git operations.
|
||||||
|
|
||||||
> Git expert agent which should be used for all local and remote 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
|
> - Searching for regressions with bisect
|
||||||
> - Interacting with source control and issues providers such as GitHub.
|
> - 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
|
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)
|
## 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.
|
(A2A) protocol.
|
||||||
|
|
||||||
> **Note: Remote subagents are currently an experimental feature.**
|
> **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
|
See the [Remote Subagents documentation](/docs/core/remote-agents) for detailed
|
||||||
configuration and usage instructions.
|
configuration and usage instructions.
|
||||||
|
|
||||||
## Extension sub-agents
|
## Extension subagents
|
||||||
|
|
||||||
Extensions can bundle and distribute sub-agents. See the
|
Extensions can bundle and distribute subagents. See the
|
||||||
[Extensions documentation](../extensions/index.md#sub-agents) for details on how
|
[Extensions documentation](../extensions/index.md#subagents) for details on how
|
||||||
to package agents within an extension.
|
to package agents within an extension.
|
||||||
|
|||||||
@@ -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:**
|
|
||||||
- **`<SERVER_NAME>`** (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/<project_hash>/shell_history`
|
|
||||||
- `<project_hash>` 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.
|
|
||||||
- `<profile_name>`: Uses a custom profile. To define a custom profile, create
|
|
||||||
a file named `sandbox-macos-<profile_name>.sb` in your project's `.gemini/`
|
|
||||||
directory (e.g., `my-project/.gemini/sandbox-macos-custom.sb`).
|
|
||||||
- **`DEBUG` or `DEBUG_MODE`** (often used by underlying libraries or the CLI
|
|
||||||
itself):
|
|
||||||
- Set to `true` or `1` to enable verbose debug logging, which can be helpful
|
|
||||||
for troubleshooting.
|
|
||||||
- **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 <model_name>`** (**`-m <model_name>`**):
|
|
||||||
- Specifies the Gemini model to use for this session.
|
|
||||||
- Example: `npm start -- --model gemini-1.5-pro-latest`
|
|
||||||
- **`--prompt <your_prompt>`** (**`-p <your_prompt>`**):
|
|
||||||
- Used to pass a prompt directly to the command. This invokes Gemini CLI in a
|
|
||||||
non-interactive mode.
|
|
||||||
- **`--prompt-interactive <your_prompt>`** (**`-i <your_prompt>`**):
|
|
||||||
- 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 <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 <tool1,tool2,...>`**:
|
|
||||||
- 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 <extension_name ...>`** (**`-e <extension_name ...>`**):
|
|
||||||
- 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 <dir1,dir2,...>`**:
|
|
||||||
- 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/<contextFileName>` (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
|
|
||||||
}
|
|
||||||
```
|
|
||||||
@@ -1,16 +1,5 @@
|
|||||||
# Gemini CLI configuration
|
# 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
|
Gemini CLI offers several ways to configure its behavior, including environment
|
||||||
variables, command-line arguments, and settings files. This document outlines
|
variables, command-line arguments, and settings files. This document outlines
|
||||||
the different configuration methods and available settings.
|
the different configuration methods and available settings.
|
||||||
|
|||||||
@@ -132,8 +132,8 @@ for your login page.
|
|||||||
|
|
||||||
## Next steps
|
## Next steps
|
||||||
|
|
||||||
- Explore the [User guides](../cli/index.md#user-guides) for detailed
|
- Follow the [File management](../cli/tutorials/file-management.md) guide to
|
||||||
walkthroughs of common tasks.
|
start working with your codebase.
|
||||||
- Follow the [Quickstart](./index.md) to start your first session.
|
- Follow the [Quickstart](./index.md) to start your first session.
|
||||||
- See the [Cheatsheet](../cli/cli-reference.md) for a quick reference of
|
- See the [Cheatsheet](../cli/cli-reference.md) for a quick reference of
|
||||||
available commands.
|
available commands.
|
||||||
|
|||||||
@@ -70,4 +70,3 @@ To explore the power of Gemini CLI, see [Gemini CLI examples](./examples.md).
|
|||||||
start working with your codebase.
|
start working with your codebase.
|
||||||
- See [Shell commands](../cli/tutorials/shell-commands.md) to learn about
|
- See [Shell commands](../cli/tutorials/shell-commands.md) to learn about
|
||||||
terminal integration.
|
terminal integration.
|
||||||
- Explore the full range of [User guides](../cli/index.md#user-guides).
|
|
||||||
|
|||||||
@@ -30,6 +30,8 @@ User-focused guides and tutorials for daily development workflows.
|
|||||||
|
|
||||||
- **[File management](./cli/tutorials/file-management.md):** How to work with
|
- **[File management](./cli/tutorials/file-management.md):** How to work with
|
||||||
local files and directories.
|
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):**
|
- **[Manage context and memory](./cli/tutorials/memory-management.md):**
|
||||||
Managing persistent instructions and facts.
|
Managing persistent instructions and facts.
|
||||||
- **[Execute shell commands](./cli/tutorials/shell-commands.md):** Executing
|
- **[Execute shell commands](./cli/tutorials/shell-commands.md):** Executing
|
||||||
@@ -40,8 +42,9 @@ User-focused guides and tutorials for daily development workflows.
|
|||||||
complex workflows.
|
complex workflows.
|
||||||
- **[Web search and fetch](./cli/tutorials/web-tools.md):** Searching and
|
- **[Web search and fetch](./cli/tutorials/web-tools.md):** Searching and
|
||||||
fetching content from the web.
|
fetching content from the web.
|
||||||
- **[Get started with skills](./cli/tutorials/skills-getting-started.md):**
|
- **[Set up an MCP server](./cli/tutorials/mcp-setup.md):** Set up an MCP
|
||||||
Getting started with specialized expertise.
|
server.
|
||||||
|
- **[Automate tasks](./cli/tutorials/automation.md):** Automate tasks.
|
||||||
|
|
||||||
## Features
|
## Features
|
||||||
|
|
||||||
@@ -92,10 +95,14 @@ Technical reference documentation for each capability of Gemini CLI.
|
|||||||
lookup for CLI features.
|
lookup for CLI features.
|
||||||
- **[Memory (tool)](./tools/memory.md):** Storage details for persistent facts.
|
- **[Memory (tool)](./tools/memory.md):** Storage details for persistent facts.
|
||||||
- **[Model routing](./cli/model-routing.md):** Automatic fallback resilience.
|
- **[Model routing](./cli/model-routing.md):** Automatic fallback resilience.
|
||||||
- **[Plan mode (experimental)](./cli/plan-mode.md):** Use a safe, read-only mode
|
- **[Plan mode 🧪](./cli/plan-mode.md):** Use a safe, read-only mode for
|
||||||
for planning complex changes.
|
planning complex changes.
|
||||||
|
- **[Remote subagents 🧪](./core/remote-agents.md):** Connecting to and using
|
||||||
|
remote agents.
|
||||||
- **[Sandboxing](./cli/sandbox.md):** Isolate tool execution.
|
- **[Sandboxing](./cli/sandbox.md):** Isolate tool execution.
|
||||||
- **[Shell (tool)](./tools/shell.md):** Detailed system execution parameters.
|
- **[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.
|
- **[Telemetry](./cli/telemetry.md):** Usage and performance metric details.
|
||||||
- **[Todo (tool)](./tools/todos.md):** Progress tracking specification.
|
- **[Todo (tool)](./tools/todos.md):** Progress tracking specification.
|
||||||
- **[Token caching](./cli/token-caching.md):** Performance optimization.
|
- **[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.
|
Deep technical documentation and API specifications.
|
||||||
|
|
||||||
- **[Architecture overview](./architecture.md):** System design and components.
|
|
||||||
- **[Command reference](./cli/commands.md):** Detailed slash command guide.
|
- **[Command reference](./cli/commands.md):** Detailed slash command guide.
|
||||||
- **[Configuration reference](./get-started/configuration.md):** Settings and
|
- **[Configuration reference](./get-started/configuration.md):** Settings and
|
||||||
environment variables.
|
environment variables.
|
||||||
- **[Core concepts](./core/concepts.md):** Fundamental terminology and
|
|
||||||
definitions.
|
|
||||||
- **[Keyboard shortcuts](./cli/keyboard-shortcuts.md):** Productivity tips.
|
- **[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.
|
- **[Policy engine](./core/policy-engine.md):** Fine-grained execution control.
|
||||||
|
- **[Tools API](./core/tools-api.md):** The API for defining and using tools.
|
||||||
|
|
||||||
## Resources
|
## Resources
|
||||||
|
|
||||||
@@ -144,3 +151,19 @@ Support, release history, and legal information.
|
|||||||
- **[Changelogs](./changelogs/index.md):** Highlights and notable changes.
|
- **[Changelogs](./changelogs/index.md):** Highlights and notable changes.
|
||||||
- **[Quota and pricing](./quota-and-pricing.md):** Limits and billing details.
|
- **[Quota and pricing](./quota-and-pricing.md):** Limits and billing details.
|
||||||
- **[Terms and privacy](./tos-privacy.md):** Official notices and terms.
|
- **[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.
|
||||||
|
|||||||
@@ -18,6 +18,10 @@
|
|||||||
"label": "File management",
|
"label": "File management",
|
||||||
"slug": "docs/cli/tutorials/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",
|
"label": "Manage context and memory",
|
||||||
"slug": "docs/cli/tutorials/memory-management"
|
"slug": "docs/cli/tutorials/memory-management"
|
||||||
@@ -38,10 +42,6 @@
|
|||||||
"label": "Web search and fetch",
|
"label": "Web search and fetch",
|
||||||
"slug": "docs/cli/tutorials/web-tools"
|
"slug": "docs/cli/tutorials/web-tools"
|
||||||
},
|
},
|
||||||
{
|
|
||||||
"label": "Get started with skills",
|
|
||||||
"slug": "docs/cli/tutorials/skills-getting-started"
|
|
||||||
},
|
|
||||||
{
|
{
|
||||||
"label": "Set up an MCP server",
|
"label": "Set up an MCP server",
|
||||||
"slug": "docs/cli/tutorials/mcp-setup"
|
"slug": "docs/cli/tutorials/mcp-setup"
|
||||||
@@ -73,7 +73,13 @@
|
|||||||
},
|
},
|
||||||
{ "label": "Model routing", "slug": "docs/cli/model-routing" },
|
{ "label": "Model routing", "slug": "docs/cli/model-routing" },
|
||||||
{ "label": "Model selection", "slug": "docs/cli/model" },
|
{ "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": "Rewind", "slug": "docs/cli/rewind" },
|
||||||
{ "label": "Sandboxing", "slug": "docs/cli/sandbox" },
|
{ "label": "Sandboxing", "slug": "docs/cli/sandbox" },
|
||||||
{ "label": "Settings", "slug": "docs/cli/settings" },
|
{ "label": "Settings", "slug": "docs/cli/settings" },
|
||||||
@@ -142,13 +148,11 @@
|
|||||||
{
|
{
|
||||||
"label": "Reference",
|
"label": "Reference",
|
||||||
"items": [
|
"items": [
|
||||||
{ "label": "Architecture", "slug": "docs/architecture" },
|
|
||||||
{ "label": "Command reference", "slug": "docs/cli/commands" },
|
{ "label": "Command reference", "slug": "docs/cli/commands" },
|
||||||
{
|
{
|
||||||
"label": "Configuration reference",
|
"label": "Configuration reference",
|
||||||
"slug": "docs/get-started/configuration"
|
"slug": "docs/get-started/configuration"
|
||||||
},
|
},
|
||||||
{ "label": "Core concepts", "slug": "docs/core/concepts" },
|
|
||||||
{ "label": "Keyboard shortcuts", "slug": "docs/cli/keyboard-shortcuts" },
|
{ "label": "Keyboard shortcuts", "slug": "docs/cli/keyboard-shortcuts" },
|
||||||
{ "label": "Memory import processor", "slug": "docs/core/memport" },
|
{ "label": "Memory import processor", "slug": "docs/core/memport" },
|
||||||
{ "label": "Policy engine", "slug": "docs/core/policy-engine" },
|
{ "label": "Policy engine", "slug": "docs/core/policy-engine" },
|
||||||
|
|||||||
Reference in New Issue
Block a user