Skip to content

CLI 命令

¥CLI Commands

Gemini CLI 支持多个内置命令，可帮助您管理会话、自定义界面并控制其行为。这些命令以斜杠 (/）、at 符号（@) 或感叹号 (!）。

¥Gemini CLI supports several built-in commands to help you manage your session, customize the interface, and control its behavior. These commands are prefixed with a forward slash (/), an at symbol (@), or an exclamation mark (!).

斜线命令 (/)

¥Slash commands (/)

斜线命令为 CLI 本身提供元级别控制。

¥Slash commands provide meta-level control over the CLI itself.

内置命令

¥Built-in Commands

  • /bug

    ¥/bug

  • 描述：提交关于 Gemini CLI 的问题。默认情况下，问题会在 Gemini CLI 的 GitHub 仓库中提交。您在/bug将成为所提交错误的标题。默认/bug可以使用bugCommand在您的设置中.gemini/settings.json文件。

    ¥Description: File an issue about Gemini CLI. By default, the issue is filed within the GitHub repository for Gemini CLI. The string you enter after /bug will become the headline for the bug being filed. The default /bug behavior can be modified using the bugCommand setting in your .gemini/settings.json files.

  • /chat

    ¥/chat

  • 描述：保存并恢复对话历史记录，以便以交互方式分支对话状态，或从稍后的会话恢复先前的状态。

    ¥Description: Save and resume conversation history for branching conversation state interactively, or resuming a previous state from a later session.

  • 子命令：

    ¥Sub-commands:

    • save

      ¥save

    • 描述：保存当前对话历史记录。您必须添加<tag>用于识别对话状态。

      ¥Description: Saves the current conversation history. You must add a <tag> for identifying the conversation state.

    • 用法： /chat save <tag>

      ¥Usage:/chat save <tag>

    • 检查站位置详情：保存聊天检查点的默认位置是：

      ¥Details on Checkpoint Location: The default locations for saved chat checkpoints are:

      • Linux/macOS：~/.gemini/tmp/<project_hash>/

        ¥Linux/macOS: ~/.gemini/tmp/<project_hash>/

      • 视窗：C:\Users\<YourUsername>\.gemini\tmp\<project_hash>\

        ¥Windows: C:\Users\<YourUsername>\.gemini\tmp\<project_hash>\

      • 当你跑步时/chat list，CLI 仅扫描这些特定目录以查找可用的检查点。

        ¥When you run /chat list, the CLI only scans these specific directories to find available checkpoints.

      • 笔记：这些检查点用于手动保存和恢复对话状态。有关在文件修改之前创建的自动检查点，请参阅检查点文档。

        ¥Note: These checkpoints are for manually saving and resuming conversation states. For automatic checkpoints created before file modifications, see the Checkpointing documentation.

    • resume

      ¥resume

    • 描述：从先前保存的内容恢复对话。

      ¥Description: Resumes a conversation from a previous save.

    • 用法： /chat resume <tag>

      ¥Usage:/chat resume <tag>

    • list

      ¥list

    • 描述：列出可用于恢复聊天状态的标签。

      ¥Description: Lists available tags for chat state resumption.

    • delete

      ¥delete

    • 描述：删除已保存的对话检查点。

      ¥Description: Deletes a saved conversation checkpoint.

    • 用法： /chat delete <tag>

      ¥Usage:/chat delete <tag>

  • /clear

    ¥/clear

  • 描述：清除终端屏幕，包括 CLI 中可见的会话历史记录和回滚内容。底层会话数据（用于历史记录调用）可能会根据具体实现方式保留，但视觉显示会被清除。

    ¥Description: Clear the terminal screen, including the visible session history and scrollback within the CLI. The underlying session data (for history recall) might be preserved depending on the exact implementation, but the visual display is cleared.

  • 键盘快捷键：按Ctrl+L随时执行明确的行动。

    ¥Keyboard shortcut: Press Ctrl+L at any time to perform a clear action.

  • /compress

    ¥/compress

  • 描述：用摘要替换整个聊天上下文。这可以节省用于未来任务的令牌，同时保留已发生事件的概要。

    ¥Description: Replace the entire chat context with a summary. This saves on tokens used for future tasks while retaining a high level summary of what has happened.

  • /copy

    ¥/copy

  • 描述：将 Gemini CLI 生成的最后输出复制到剪贴板，以便于共享或重复使用。

    ¥Description: Copies the last output produced by Gemini CLI to your clipboard, for easy sharing or reuse.

  • 笔记：此命令需要安装特定于平台的剪贴板工具。

    ¥Note: This command requires platform-specific clipboard tools to be installed.

    • 在 Linux 上，它需要xclip或者xsel。您通常可以使用系统的包管理器来安装它们。

      ¥On Linux, it requires xclip or xsel. You can typically install them using your system's package manager.

    • 在 macOS 上，它需要pbcopy，而在 Windows 上，它需要clip. 这些工具通常预先安装在各自的系统上。

      ¥On macOS, it requires pbcopy, and on Windows, it requires clip. These tools are typically pre-installed on their respective systems.

  • /directory（或者/dir)

    ¥/directory (or /dir)

  • 描述：管理工作区目录以实现多目录支持。

    ¥Description: Manage workspace directories for multi-directory support.

  • 子命令：

    ¥Sub-commands:

    • add：

      ¥add:

    • 描述：向工作区添加目录。路径可以是绝对路径，也可以是相对于当前工作目录的相对路径。此外，还支持从主目录引用。

      ¥Description: Add a directory to the workspace. The path can be absolute or relative to the current working directory. Moreover, the reference from home directory is supported as well.

    • 用法： /directory add <path1>,<path2>

      ¥Usage:/directory add <path1>,<path2>

    • 笔记：在限制性沙盒配置文件中已禁用。如果您正在使用沙盒配置文件，请使用--include-directories在启动会话时。

      ¥Note: Disabled in restrictive sandbox profiles. If you're using that, use --include-directories when starting the session instead.

    • show：

      ¥show:

    • 描述：显示由...添加的所有目录/directory add和--include-directories。

      ¥Description: Display all directories added by /directory add and --include-directories.

    • 用法： /directory show

      ¥Usage:/directory show

  • /editor

    ¥/editor

  • 描述：打开一个对话框来选择支持的编辑器。

    ¥Description: Open a dialog for selecting supported editors.

  • /extensions

    ¥/extensions

  • 描述：列出当前 Gemini CLI 会话中所有活动的扩展。参见Gemini CLI 扩展。

    ¥Description: Lists all active extensions in the current Gemini CLI session. See Gemini CLI Extensions.

  • /help（或者/?)

    ¥/help (or /?)

  • 描述：显示有关 Gemini CLI 的帮助信息，包括可用的命令及其用法。

    ¥Description: Display help information about Gemini CLI, including available commands and their usage.

  • /mcp

    ¥/mcp

  • 描述：列出已配置的模型上下文协议 (MCP) 服务器、它们的连接状态、服务器详细信息和可用工具。

    ¥Description: List configured Model Context Protocol (MCP) servers, their connection status, server details, and available tools.

  • 子命令：

    ¥Sub-commands:

    • desc或者descriptions：

      ¥desc or descriptions:

    • 描述：显示 MCP 服务器和工具的详细描述。

      ¥Description: Show detailed descriptions for MCP servers and tools.

    • nodesc或者nodescriptions：

      ¥nodesc or nodescriptions:

    • 描述：隐藏工具描述，仅显示工具名称。

      ¥Description: Hide tool descriptions, showing only the tool names.

    • schema：

      ¥schema:

    • 描述：显示该工具配置参数的完整 JSON 模式。

      ¥Description: Show the full JSON schema for the tool's configured parameters.

  • 键盘快捷键：按Ctrl+T随时在显示和隐藏工具描述之间切换。

    ¥Keyboard Shortcut: Press Ctrl+T at any time to toggle between showing and hiding tool descriptions.

  • /memory

    ¥/memory

  • 描述：管理人工智能的教学上下文（从GEMINI.md文件）。

    ¥Description: Manage the AI's instructional context (hierarchical memory loaded from GEMINI.md files).

  • 子命令：

    ¥Sub-commands:

    • add：

      ¥add:

    • 描述：将以下文本添加到AI的内存中。用法：/memory add <text to remember>

      ¥Description: Adds the following text to the AI's memory. Usage: /memory add <text to remember>

    • show：

      ¥show:

    • 描述：显示已从所有加载的当前分层内存的完整、串联内容GEMINI.md文件。这可让您检查提供给 Gemini 模型的教学内容。

      ¥Description: Display the full, concatenated content of the current hierarchical memory that has been loaded from all GEMINI.md files. This lets you inspect the instructional context being provided to the Gemini model.

    • refresh：

      ¥refresh:

    • 描述：从所有GEMINI.md在配置的位置（全局、项目/祖先和子目录）中找到的文件。此命令使用最新的GEMINI.md内容。

      ¥Description: Reload the hierarchical instructional memory from all GEMINI.md files found in the configured locations (global, project/ancestors, and sub-directories). This command updates the model with the latest GEMINI.md content.

    • 笔记：有关如何GEMINI.md文件有助于分层内存，请参阅CLI 配置文档。

      ¥Note: For more details on how GEMINI.md files contribute to hierarchical memory, see the CLI Configuration documentation.

  • /restore

    ¥/restore

  • 描述：将项目文件恢复到工具执行之前的状态。这对于撤消工具所做的文件编辑尤其有用。如果运行时没有指定工具调用 ID，它将列出可供恢复的检查点。

    ¥Description: Restores the project files to the state they were in just before a tool was executed. This is particularly useful for undoing file edits made by a tool. If run without a tool call ID, it will list available checkpoints to restore from.

  • 用法： /restore [tool_call_id]

    ¥Usage:/restore [tool_call_id]

  • 笔记：仅当使用以下方式调用 CLI 时才可用--checkpointing选项或通过配置设置。 看检查点文档了解更多详情。

    ¥Note: Only available if the CLI is invoked with the --checkpointing option or configured via settings. See Checkpointing documentation for more details.

  • /settings

    ¥/settings

  • 描述：打开设置编辑器以查看和修改 Gemini CLI 设置。

    ¥Description: Open the settings editor to view and modify Gemini CLI settings.

  • 细节：此命令提供了一个用户友好的界面，用于更改控制 Gemini CLI 行为和外观的设置。它相当于手动编辑.gemini/settings.json文件，但要有验证和指导以防止错误。

    ¥Details: This command provides a user-friendly interface for changing settings that control the behavior and appearance of Gemini CLI. It is equivalent to manually editing the .gemini/settings.json file, but with validation and guidance to prevent errors.

  • 用法：只需运行/settings编辑器将打开。您可以浏览或搜索特定设置，查看其当前值，并根据需要进行修改。某些设置的更改会立即生效，而其他设置则需要重启。

    ¥Usage: Simply run /settings and the editor will open. You can then browse or search for specific settings, view their current values, and modify them as desired. Changes to some settings are applied immediately, while others require a restart.

  • /stats

    ¥/stats

  • 描述：显示当前 Gemini CLI 会话的详细统计信息，包括令牌使用情况、缓存令牌节省量（如有）以及会话时长。注意：缓存令牌信息仅在使用缓存令牌时显示，这种情况在 API 密钥身份验证中发生，但目前在 OAuth 身份验证中不显示。

    ¥Description: Display detailed statistics for the current Gemini CLI session, including token usage, cached token savings (when available), and session duration. Note: Cached token information is only displayed when cached tokens are being used, which occurs with API key authentication but not with OAuth authentication at this time.

  • /theme

    ¥/theme

  • 描述：打开一个对话框，让您更改 Gemini CLI 的视觉主题。

    ¥Description: Open a dialog that lets you change the visual theme of Gemini CLI.

  • /auth

    ¥/auth

  • 描述：打开一个对话框，让您更改身份验证方法。

    ¥Description: Open a dialog that lets you change the authentication method.

  • /about

    ¥/about

  • 描述：显示版本信息。请在提交问题时分享此信息。

    ¥Description: Show version info. Please share this information when filing issues.

  • /tools

    ¥/tools

  • 描述：显示 Gemini CLI 中当前可用的工具列表。

    ¥Description: Display a list of tools that are currently available within Gemini CLI.

  • 用法： /tools [desc]

    ¥Usage:/tools [desc]

  • 子命令：

    ¥Sub-commands:

    • desc或者descriptions：

      ¥desc or descriptions:

    • 描述：显示每个工具的详细描述，包括每个工具的名称及其提供给模型的完整描述。

      ¥Description: Show detailed descriptions of each tool, including each tool's name with its full description as provided to the model.

    • nodesc或者nodescriptions：

      ¥nodesc or nodescriptions:

    • 描述：隐藏工具描述，仅显示工具名称。

      ¥Description: Hide tool descriptions, showing only the tool names.

  • /privacy

    ¥/privacy

  • 描述：显示隐私声明并允许用户选择是否同意为改进服务而收集其数据。

    ¥Description: Display the Privacy Notice and allow users to select whether they consent to the collection of their data for service improvement purposes.

  • /quit（或者/exit)

    ¥/quit (or /exit)

  • 描述：退出 Gemini CLI。

    ¥Description: Exit Gemini CLI.

  • /vim

    ¥/vim

  • 描述：切换 Vim 模式的开启或关闭。启用 Vim 模式后，输入区域在“常规”和“插入”模式下均支持 Vim 风格的导航和编辑命令。

    ¥Description: Toggle vim mode on or off. When vim mode is enabled, the input area supports vim-style navigation and editing commands in both NORMAL and INSERT modes.

  • 特征：

    ¥Features:

    • 正常模式：导航h，j，k，l; 按单词跳转w，b，e; 转到行首/行末0，$，^; 使用G（或者gg（第一行）

      ¥NORMAL mode: Navigate with h, j, k, l; jump by words with w, b, e; go to line start/end with 0, $, ^; go to specific lines with G (or gg for first line)

    • 插入模式：标准文本输入，带退出键以返回正常模式

      ¥INSERT mode: Standard text input with escape to return to NORMAL mode

    • 编辑命令：删除x，更改为c，插入i，a，o，O；复杂的操作，例如dd，cc，dw，cw

      ¥Editing commands: Delete with x, change with c, insert with i, a, o, O; complex operations like dd, cc, dw, cw

    • 计数支持：使用数字作为命令前缀（例如，3h，5w，10G)

      ¥Count support: Prefix commands with numbers (e.g., 3h, 5w, 10G)

    • 重复上一个命令：使用.重复上一次编辑操作

      ¥Repeat last command: Use . to repeat the last editing operation

    • 持久设置：Vim 模式偏好设置已保存至~/.gemini/settings.json并在会话之间恢复

      ¥Persistent setting: Vim mode preference is saved to ~/.gemini/settings.json and restored between sessions

  • 状态指示灯：启用后，显示[NORMAL]或者[INSERT]在页脚中

    ¥Status indicator: When enabled, shows [NORMAL] or [INSERT] in the footer

  • /init

    ¥/init

  • 描述：为了帮助用户轻松创建GEMINI.md文件，此命令会分析当前目录并生成定制的上下文文件，使它们能够更轻松地向 Gemini 代理提供特定于项目的指令。

    ¥Description: To help users easily create a GEMINI.md file, this command analyzes the current directory and generates a tailored context file, making it simpler for them to provide project-specific instructions to the Gemini agent.

自定义命令

¥Custom Commands

要快速入门，请参阅例子以下。

¥For a quick start, see the example below.

自定义命令允许您在 Gemini CLI 中将您最喜欢或最常用的提示保存为个人快捷方式并重复使用。您可以创建特定于单个项目的命令，也可以创建适用于所有项目的全局命令，从而简化工作流程并确保一致性。

¥Custom commands allow you to save and reuse your favorite or most frequently used prompts as personal shortcuts within Gemini CLI. You can create commands that are specific to a single project or commands that are available globally across all your projects, streamlining your workflow and ensuring consistency.

文件位置和优先级

¥File Locations & Precedence

Gemini CLI 从两个位置发现命令，并按特定顺序加载：

¥Gemini CLI discovers commands from two locations, loaded in a specific order:

  1. 用户命令（全局）：位于~/.gemini/commands/。这些命令在您正在处理的任何项目中都可用。

    ¥User Commands (Global): Located in ~/.gemini/commands/. These commands are available in any project you are working on.

  2. 项目命令（本地）：位于<your-project-root>/.gemini/commands/。这些命令特定于当前项目，可以签入版本控制以与您的团队共享。

    ¥Project Commands (Local): Located in <your-project-root>/.gemini/commands/. These commands are specific to the current project and can be checked into version control to be shared with your team.

如果项目目录中的命令与用户目录中的命令同名，则项目命令将始终被使用。这允许项目使用特定于项目的版本覆盖全局命令。

¥If a command in the project directory has the same name as a command in the user directory, the project command will always be used. This allows projects to override global commands with project-specific versions.

命名和命名空间

¥Naming and Namespacing

命令的名称由其相对于其的文件路径决定commands目录。子目录用于创建命名空间命令，路径分隔符为 (/或者\) 被转换为冒号 (:）。

¥The name of a command is determined by its file path relative to its commands directory. Subdirectories are used to create namespaced commands, with the path separator (/ or \) being converted to a colon (:).

  • 文件位于~/.gemini/commands/test.toml成为命令/test。

    ¥A file at ~/.gemini/commands/test.toml becomes the command /test.

  • 文件位于<project>/.gemini/commands/git/commit.toml成为命名空间命令/git:commit。

    ¥A file at <project>/.gemini/commands/git/commit.toml becomes the namespaced command /git:commit.

TOML 文件格式 (v1)

¥TOML File Format (v1)

您的命令定义文件必须以 TOML 格式编写并使用.toml文件扩展名。

¥Your command definition files must be written in the TOML format and use the .toml file extension.

必填字段

¥Required Fields

  • prompt（字符串）：执行命令时将发送给 Gemini 模型的提示。可以是单行或多行字符串。

    ¥prompt (String): The prompt that will be sent to the Gemini model when the command is executed. This can be a single-line or multi-line string.

可选字段

¥Optional Fields

  • description（字符串）：一行简短的描述，用于说明该命令的作用。此文本将显示在命令旁边/help菜单。如果省略此字段，则会从文件名生成通用描述。

    ¥description (String): A brief, one-line description of what the command does. This text will be displayed next to your command in the /help menu. If you omit this field, a generic description will be generated from the filename.

处理参数

¥Handling Arguments

自定义命令支持两种强大的参数处理方法。CLI 会根据命令的内容自动选择正确的方法prompt。

¥Custom commands support two powerful methods for handling arguments. The CLI automatically chooses the correct method based on the content of your command's prompt.

1. 上下文感知注入{{args}}

¥1. Context-Aware Injection with {{args}}

如果你的prompt包含特殊占位符{{args}}，CLI 将用用户在命令名称后键入的文本替换该占位符。

¥If your prompt contains the special placeholder {{args}}, the CLI will replace that placeholder with the text the user typed after the command name.

此注入的行为取决于其使用位置：

¥The behavior of this injection depends on where it is used:

A. 原始注入（外部 Shell 命令）

¥A. Raw Injection (Outside Shell Commands)

当在提示的主体中使用时，参数将按照用户输入的方式注入。

¥When used in the main body of the prompt, the arguments are injected exactly as the user typed them.

例子 （git/fix.toml):

¥Example (git/fix.toml):

# Invoked via: /git:fix "Button is misaligned"

description = "Generates a fix for a given issue."
prompt = "Please provide a code fix for the issue described here: {{args}}."

该模型接收：Please provide a code fix for the issue described here: "Button is misaligned".

¥The model receives: Please provide a code fix for the issue described here: "Button is misaligned".

B. 在 Shell 命令中使用参数（在!{...}块）

¥B. Using Arguments in Shell Commands (Inside !{...} Blocks)

当你使用{{args}}在壳注入块内（!{...}），参数自动shell 逃逸替换之前。这允许您安全地将参数传递给 shell 命令，确保生成的命令语法正确且安全，同时防止命令注入漏洞。

¥When you use {{args}} inside a shell injection block (!{...}), the arguments are automatically shell-escaped before replacement. This allows you to safely pass arguments to shell commands, ensuring the resulting command is syntactically correct and secure while preventing command injection vulnerabilities.

例子 （/grep-code.toml):

¥Example (/grep-code.toml):

prompt = """
Please summarize the findings for the pattern `{{args}}`.

Search Results:
!{grep -r {{args}} .}
"""

当你跑步时/grep-code It's complicated：

¥When you run /grep-code It's complicated:

  1. CLI 看到{{args}}内外均可使用!{...}。

    ¥The CLI sees {{args}} used both outside and inside !{...}.

  2. 外部：第一个{{args}}被替换为It's complicated。

    ¥Outside: The first {{args}} is replaced raw with It's complicated.

  3. 内部：第二个{{args}}被替换为转义版本（例如，在 Linux 上："It's complicated"）。

    ¥Inside: The second {{args}} is replaced with the escaped version (e.g., on Linux: "It's complicated").

  4. 执行的命令是grep -r "It's complicated" .。

    ¥The command executed is grep -r "It's complicated" ..

  5. CLI 会在执行之前提示您确认此准确、安全的命令。

    ¥The CLI prompts you to confirm this exact, secure command before execution.

  6. 最后的提示已发送。

    ¥The final prompt is sent.

2. 默认参数处理

¥2. Default Argument Handling

如果你的prompt做不是包含特殊占位符{{args}}，CLI 使用默认行为来处理参数。

¥If your prompt does not contain the special placeholder {{args}}, the CLI uses a default behavior for handling arguments.

如果您为命令提供参数（例如，/mycommand arg1)，CLI 会将你输入的完整命令附加到提示符的末尾，并以两个换行符分隔。这使得模型能够同时看到原始指令和你刚刚提供的具体参数。

¥If you provide arguments to the command (e.g., /mycommand arg1), the CLI will append the full command you typed to the end of the prompt, separated by two newlines. This allows the model to see both the original instructions and the specific arguments you just provided.

如果你这样做不是提供任何论据（例如，/mycommand)，提示将按原样发送到模型，不附加任何内容。

¥If you do not provide any arguments (e.g., /mycommand), the prompt is sent to the model exactly as it is, with nothing appended.

例子 （changelog.toml):

¥Example (changelog.toml):

此示例展示了如何通过为模型定义角色、解释在何处找到用户的输入以及指定预期的格式和行为来创建强大的命令。

¥This example shows how to create a robust command by defining a role for the model, explaining where to find the user's input, and specifying the expected format and behavior.

# In: <project>/.gemini/commands/changelog.toml
# Invoked via: /changelog 1.2.0 added "Support for default argument parsing."

description = "Adds a new entry to the project's CHANGELOG.md file."
prompt = """
# Task: Update Changelog

You are an expert maintainer of this software project. A user has invoked a command to add a new entry to the changelog.

**The user's raw command is appended below your instructions.**

Your task is to parse the `<version>`, `<change_type>`, and `<message>` from their input and use the `write_file` tool to correctly update the `CHANGELOG.md` file.

## Expected Format
The command follows this format: `/changelog <version> <type> <message>`
- `<type>` must be one of: "added", "changed", "fixed", "removed".

## Behavior
1. Read the `CHANGELOG.md` file.
2. Find the section for the specified `<version>`.
3. Add the `<message>` under the correct `<type>` heading.
4. If the version or type section doesn't exist, create it.
5. Adhere strictly to the "Keep a Changelog" format.
"""

当你跑步时/changelog 1.2.0 added "New feature"，发送给模型的最终文本将是原始提示符后跟两个换行符和您键入的命令。

¥When you run /changelog 1.2.0 added "New feature", the final text sent to the model will be the original prompt followed by two newlines and the command you typed.

3. 使用以下命令执行 Shell 命令!{...}

¥3. Executing Shell Commands with !{...}

您可以通过直接在命令行中执行 shell 命令来使命令动态化。prompt并注入它们的输出。这非常适合从本地环境收集上下文信息，例如读取文件内容或检查 Git 的状态。

¥You can make your commands dynamic by executing shell commands directly within your prompt and injecting their output. This is ideal for gathering context from your local environment, like reading file content or checking the status of Git.

当自定义命令尝试执行 shell 命令时，Gemini CLI 现在会在继续执行之前提示您确认。这是一项安全措施，旨在确保只有预期的命令才能运行。

¥When a custom command attempts to execute a shell command, Gemini CLI will now prompt you for confirmation before proceeding. This is a security measure to ensure that only intended commands can be run.

工作原理：

¥How It Works:

  1. 注入命令：使用!{...}句法。

    ¥Inject Commands: Use the !{...} syntax.

  2. 参数替换：如果{{args}}存在于块内部，它会自动进行 shell 转义（参见上下文感知注入多于）。

    ¥Argument Substitution: If {{args}} is present inside the block, it is automatically shell-escaped (see Context-Aware Injection above).

  3. 稳健解析：解析器可以正确处理包含嵌套括号的复杂 shell 命令，例如 JSON 有效负载。

    ¥Robust Parsing: The parser correctly handles complex shell commands that include nested braces, such as JSON payloads.

  4. 安全检查和确认：CLI 会对最终解析的命令（参数转义并替换后）执行安全检查。此时将出现一个对话框，显示要执行的具体命令。

    ¥Security Check and Confirmation: The CLI performs a security check on the final, resolved command (after arguments are escaped and substituted). A dialog will appear showing the exact command(s) to be executed.

  5. 执行和错误报告：命令执行成功。如果命令失败，则注入到提示符中的输出将包含错误消息（stderr）以及状态行，例如：[Shell command exited with code 1]。这有助于模型了解失败的背景。

    ¥Execution and Error Reporting: The command is executed. If the command fails, the output injected into the prompt will include the error messages (stderr) followed by a status line, e.g., [Shell command exited with code 1]. This helps the model understand the context of the failure.

例子 （git/commit.toml):

¥Example (git/commit.toml):

此命令获取暂存的 git diff 并使用它来要求模型编写提交消息。

¥This command gets the staged git diff and uses it to ask the model to write a commit message.

# In: <project>/.gemini/commands/git/commit.toml
# Invoked via: /git:commit

description = "Generates a Git commit message based on staged changes."

# The prompt uses !{...} to execute the command and inject its output.
prompt = """
Please generate a Conventional Commit message based on the following git diff:

```diff
!{git diff --staged}
```

"""

当你跑步时/git:commit，CLI 首先执行git diff --staged，然后替换!{git diff --staged}在向模型发送最终的完整提示之前，使用该命令的输出。

¥When you run /git:commit, the CLI first executes git diff --staged, then replaces !{git diff --staged} with the output of that command before sending the final, complete prompt to the model.

示例：“纯函数”重构命令

¥Example: A "Pure Function" Refactoring Command

让我们创建一个全局命令，要求模型重构一段代码。

¥Let's create a global command that asks the model to refactor a piece of code.

1.创建文件和目录：

¥1. Create the file and directories:

首先，确保用户命令目录存在，然后创建一个refactor用于组织和最终 TOML 文件的子目录。

¥First, ensure the user commands directory exists, then create a refactor subdirectory for organization and the final TOML file.

mkdir -p ~/.gemini/commands/refactor
touch ~/.gemini/commands/refactor/pure.toml

2.向文件中添加内容：

¥2. Add the content to the file:

打开~/.gemini/commands/refactor/pure.toml在编辑器中添加以下内容。我们添加了可选的description最佳实践。

¥Open ~/.gemini/commands/refactor/pure.toml in your editor and add the following content. We are including the optional description for best practice.

# In: ~/.gemini/commands/refactor/pure.toml
# This command will be invoked via: /refactor:pure

description = "Asks the model to refactor the current context into a pure function."

prompt = """
Please analyze the code I've provided in the current context.
Refactor it into a pure function.

Your response should include:
1. The refactored, pure function code block.
2. A brief explanation of the key changes you made and why they contribute to purity.
"""

3.运行命令：

¥3. Run the Command:

就这样！现在您可以在 CLI 中运行命令了。首先，您可以将文件添加到上下文中，然后调用命令：

¥That's it! You can now run your command in the CLI. First, you might add a file to the context, and then invoke your command:

> @my-messy-function.js
> /refactor:pure

然后，Gemini CLI 将执行 TOML 文件中定义的多行提示。

¥Gemini CLI will then execute the multi-line prompt defined in your TOML file.

At 命令 (@)

¥At commands (@)

At 命令用于将文件或目录的内容作为提示符添加到 Gemini 中。这些命令包含 git 感知过滤功能。

¥At commands are used to include the content of files or directories as part of your prompt to Gemini. These commands include git-aware filtering.

  • @<path_to_file_or_directory>

    ¥@<path_to_file_or_directory>

  • 描述：将指定文件的内容注入当前提示符。这对于询问有关特定代码、文本或文件集合的问题非常有用。

    ¥Description: Inject the content of the specified file or files into your current prompt. This is useful for asking questions about specific code, text, or collections of files.

  • 例子：

    ¥Examples:

    • @path/to/your/file.txt Explain this text.

      ¥@path/to/your/file.txt Explain this text.

    • @src/my_project/ Summarize the code in this directory.

      ¥@src/my_project/ Summarize the code in this directory.

    • What is this file about? @README.md

      ¥What is this file about? @README.md

  • 细节：

    ¥Details:

    • 如果提供了单个文件的路径，则读取该文件的内容。

      ¥If a path to a single file is provided, the content of that file is read.

    • 如果提供了目录路径，该命令将尝试读取该目录及其任何子目录中的文件内容。

      ¥If a path to a directory is provided, the command attempts to read the content of files within that directory and any subdirectories.

    • 路径中的空格应该用反斜杠转义（例如，@My\ Documents/file.txt）。

      ¥Spaces in paths should be escaped with a backslash (e.g., @My\ Documents/file.txt).

    • 该命令使用read_many_files工具内部。内容被获取，然后插入到您的查询中，然后再发送到 Gemini 模型。

      ¥The command uses the read_many_files tool internally. The content is fetched and then inserted into your query before being sent to the Gemini model.

    • Git 感知过滤：默认情况下，git 忽略的文件（例如node_modules/，dist/，.env，.git/）被排除。此行为可以通过fileFiltering设置。

      ¥Git-aware filtering: By default, git-ignored files (like node_modules/, dist/, .env, .git/) are excluded. This behavior can be changed via the fileFiltering settings.

    • 文件类型：该命令适用于基于文本的文件。虽然它可能会尝试读取任何文件，但二进制文件或非常大的文件可能会被底层跳过或截断read_many_files工具来确保性能和相关性。该工具会指示是否跳过了某些文件。

      ¥File types: The command is intended for text-based files. While it might attempt to read any file, binary files or very large files might be skipped or truncated by the underlying read_many_files tool to ensure performance and relevance. The tool indicates if files were skipped.

  • 输出：CLI 将显示一个工具调用消息，表明read_many_files被使用，以及详细说明状态和已处理路径的消息。

    ¥Output: The CLI will show a tool call message indicating that read_many_files was used, along with a message detailing the status and the path(s) that were processed.

  • @（符号处孤独）

    ¥@ (Lone at symbol)

  • 描述：如果你输入一个@符号没有路径，查询将按原样传递给 Gemini 模型。如果你正在专门讨论关于这@提示中的符号。

    ¥Description: If you type a lone @ symbol without a path, the query is passed as-is to the Gemini model. This might be useful if you are specifically talking about the @ symbol in your prompt.

错误处理@命令

¥Error handling for @ commands

  • 如果路径指定后@未找到或无效，则会显示错误消息，并且查询可能不会发送到 Gemini 模型，或者发送时不包含文件内容。

    ¥If the path specified after @ is not found or is invalid, an error message will be displayed, and the query might not be sent to the Gemini model, or it will be sent without the file content.

  • 如果read_many_files工具遇到错误（例如权限问题），也会报告此错误。

    ¥If the read_many_files tool encounters an error (e.g., permission issues), this will also be reported.

Shell 模式和直通命令（!)

¥Shell mode & passthrough commands (!)

这!前缀让您直接从 Gemini CLI 内部与系统的 shell 进行交互。

¥The ! prefix lets you interact with your system's shell directly from within Gemini CLI.

  • !<shell_command>

    ¥!<shell_command>

  • 描述：执行给定的<shell_command>使用bash在 Linux/macOS 上或cmd.exe在 Windows 上。该命令的任何输出或错误都会显示在终端中。

    ¥Description: Execute the given <shell_command> using bash on Linux/macOS or cmd.exe on Windows. Any output or errors from the command are displayed in the terminal.

  • 例子：

    ¥Examples:

    • !ls -la（执行ls -la并返回 Gemini CLI)

      ¥!ls -la (executes ls -la and returns to Gemini CLI)

    • !git status（执行git status并返回 Gemini CLI)

      ¥!git status (executes git status and returns to Gemini CLI)

  • !（切换 shell 模式）

    ¥! (Toggle shell mode)

  • 描述：打字!自行切换 shell 模式。

    ¥Description: Typing ! on its own toggles shell mode.

    • 进入shell模式：

      ¥Entering shell mode:

    • 激活后，shell 模式会使用不同的颜色和“Shell 模式指示器”。

      ¥When active, shell mode uses a different coloring and a "Shell Mode Indicator".

    • 在 shell 模式下，您键入的文本将直接解释为 shell 命令。

      ¥While in shell mode, text you type is interpreted directly as a shell command.

    • 退出 shell 模式：

      ¥Exiting shell mode:

    • 退出时，UI 恢复其标准外观并恢复正常的 Gemini CLI 行为。

      ¥When exited, the UI reverts to its standard appearance and normal Gemini CLI behavior resumes.

  • 所有人的注意!用法：您在 shell 模式下执行的命令具有与直接在终端中运行的命令相同的权限和影响。

    ¥Caution for all ! usage: Commands you execute in shell mode have the same permissions and impact as if you ran them directly in your terminal.

  • 环境变量：当通过以下方式执行命令时!或者在 shell 模式下，GEMINI_CLI=1环境变量在子进程的环境中设置。这允许脚本或工具检测它们是否在 Gemini CLI 中运行。

    ¥Environment Variable: When a command is executed via ! or in shell mode, the GEMINI_CLI=1 environment variable is set in the subprocess's environment. This allows scripts or tools to detect if they are being run from within the Gemini CLI.