CLI 命令

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

斜杠命令（`/`）

斜杠命令提供对 CLI 本身的元级别控制。

内置命令

/bug
- 描述： 提交关于 Gemini CLI 的问题报告。默认情况下，问题会在 Gemini CLI 的 GitHub 仓库中提交。您在 /bug 后输入的字符串将成为提交问题的标题。默认的 /bug 行为可以通过 .gemini/settings.json 文件中的 advanced.bugCommand 设置进行修改。
/chat
- 描述： 保存和恢复对话历史，用于交互式分支对话状态，或从后续会话中恢复之前的状态。
- 子命令：
  - save
    - 描述： 保存当前对话历史。您必须添加一个 <tag> 来标识对话状态。
    - 用法： /chat save <tag>
    - 检查点位置详情： 保存的聊天检查点的默认位置是：
      - Linux/macOS：~/.gemini/tmp/<project_hash>/
      - Windows：C:\Users\<YourUsername>\.gemini\tmp\<project_hash>\
      - 当您运行 /chat list 时，CLI 只扫描这些特定目录来查找可用的检查点。
      - 注意： 这些检查点用于手动保存和恢复对话状态。对于文件修改前自动创建的检查点，请参阅 Checkpointing 文档。
  - resume
    - 描述： 从之前的保存中恢复对话。
    - 用法： /chat resume <tag>
  - list
    - 描述： 列出可用于聊天状态恢复的标签。
  - delete
    - 描述： 删除已保存的对话检查点。
    - 用法： /chat delete <tag>
/clear
- 描述： 清除终端屏幕，包括可见的会话历史和 CLI 内的回滚。底层会话数据（用于历史回调）可能会根据具体实现被保留，但视觉显示会被清除。
- 键盘快捷键： 随时按 Ctrl+L 执行清除操作。
/compress
- 描述： 用摘要替换整个聊天上下文。这节省了未来任务使用的令牌，同时保留了发生事情的高级摘要。
/copy
- 描述： 将 Gemini CLI 产生的最后输出复制到剪贴板，便于分享或重用。
- 注意： 此命令需要安装特定平台的剪贴板工具。
  - 在 Linux 上，需要 xclip 或 xsel。您通常可以使用系统的包管理器安装它们。
  - 在 macOS 上，需要 pbcopy，在 Windows 上，需要 clip。这些工具通常在各自的系统上预装。
/directory（或 /dir）
- 描述： 管理工作区目录以支持多目录。
- 子命令：
  - add：
    - 描述： 向工作区添加目录。路径可以是绝对路径或相对于当前工作目录的相对路径。此外，还支持从主目录的引用。
    - 用法： /directory add <path1>,<path2>
    - 注意： 在限制性沙盒配置文件中禁用。如果您使用该配置，请在启动会话时使用 --include-directories。
  - show：
    - 描述： 显示通过 /directory add 和 --include-directories 添加的所有目录。
    - 用法： /directory show
/editor
- 描述： 打开选择支持编辑器的对话框。
/extensions
- 描述： 列出当前 Gemini CLI 会话中的所有活动扩展。参见 Gemini CLI 扩展。
/help（或 /?）
- 描述： 显示关于 Gemini CLI 的帮助信息，包括可用命令及其用法。
/mcp
- 描述： 列出配置的模型上下文协议（MCP）服务器、它们的连接状态、服务器详情和可用工具。
- 子命令：
  - desc 或 descriptions：
    - 描述： 显示 MCP 服务器和工具的详细描述。
  - nodesc 或 nodescriptions：
    - 描述： 隐藏工具描述，只显示工具名称。
  - schema：
    - 描述： 显示工具配置参数的完整 JSON 架构。
- 键盘快捷键： 随时按 Ctrl+T 在显示和隐藏工具描述之间切换。
/memory
- 描述： 管理 AI 的指令上下文（从 GEMINI.md 文件加载的分层内存）。
- 子命令：
  - add：
    - 描述： 将以下文本添加到 AI 的内存中。用法：/memory add <要记住的文本>
  - show：
    - 描述： 显示从所有 GEMINI.md 文件加载的当前分层内存的完整、连接内容。这让您检查提供给 Gemini 模型的指令上下文。
  - refresh：
    - 描述： 从配置位置（全局、项目/祖先和子目录）找到的所有 GEMINI.md 文件重新加载分层指令内存。此命令使用最新的 GEMINI.md 内容更新模型。
  - 注意： 有关 GEMINI.md 文件如何贡献分层内存的更多详情，请参阅 CLI 配置文档。
/restore
- 描述： 将项目文件恢复到工具执行前的状态。这对于撤销工具进行的文件编辑特别有用。如果不带工具调用 ID 运行，它将列出可恢复的可用检查点。
- 用法： /restore [tool_call_id]
- 注意： 仅在使用 --checkpointing 选项调用 CLI 或通过设置配置时可用。有关更多详情，请参阅 Checkpointing 文档。
/settings
- 描述： 打开设置编辑器以查看和修改 Gemini CLI 设置。
- 详情： 此命令提供用户友好的界面来更改控制 Gemini CLI 行为和外观的设置。它等同于手动编辑 .gemini/settings.json 文件，但具有验证和指导功能以防止错误。
- 用法： 只需运行 /settings，编辑器将打开。然后您可以浏览或搜索特定设置、查看其当前值并根据需要修改它们。某些设置的更改会立即应用，而其他设置需要重启。
/stats
- 描述： 显示当前 Gemini CLI 会话的详细统计信息，包括令牌使用量、缓存令牌节省（如果可用）和会话持续时间。注意：缓存令牌信息仅在使用缓存令牌时显示，这在 API 密钥身份验证时发生，但目前在 OAuth 身份验证时不发生。
/theme
- 描述： 打开让您更改 Gemini CLI 视觉主题的对话框。
/auth
- 描述： 打开让您更改身份验证方法的对话框。
/about
- 描述： 显示版本信息。提交问题时请分享此信息。
/tools
- 描述： 显示 Gemini CLI 中当前可用的工具列表。
- 用法： /tools [desc]
- 子命令：
  - desc 或 descriptions：
    - 描述： 显示每个工具的详细描述，包括每个工具的名称及其提供给模型的完整描述。
  - nodesc 或 nodescriptions：
    - 描述： 隐藏工具描述，只显示工具名称。
/privacy
- 描述： 显示隐私声明并允许用户选择是否同意收集其数据用于服务改进目的。
/quit（或 /exit）
- 描述： 退出 Gemini CLI。
/vim
- 描述： 开启或关闭 vim 模式。启用 vim 模式时，输入区域在 NORMAL 和 INSERT 模式下都支持 vim 风格的导航和编辑命令。
- 功能：
  - NORMAL 模式： 使用 h、j、k、l 导航；使用 w、b、e 按单词跳转；使用 0、$、^ 转到行首/行尾；使用 G（或 gg 转到第一行）转到特定行
  - INSERT 模式： 标准文本输入，按 escape 返回 NORMAL 模式
  - 编辑命令： 使用 x 删除，使用 c 更改，使用 i、a、o、O 插入；复杂操作如 dd、cc、dw、cw
  - 计数支持： 在命令前加数字（例如 3h、5w、10G）
  - 重复上一个命令： 使用 . 重复上一个编辑操作
  - 持久设置： Vim 模式偏好保存到 ~/.gemini/settings.json 并在会话间恢复
- 状态指示器： 启用时，在页脚显示 [NORMAL] 或 [INSERT]
/init
- 描述： 为了帮助用户轻松创建 GEMINI.md 文件，此命令分析当前目录并生成定制的上下文文件，使他们更容易向 Gemini 代理提供项目特定的指令。

自定义命令

快速入门，请参阅下面的示例。

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

文件位置和优先级

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

用户命令（全局）： 位于 ~/.gemini/commands/。这些命令在您工作的任何项目中都可用。
项目命令（本地）： 位于 <your-project-root>/.gemini/commands/。这些命令特定于当前项目，可以检入版本控制以与您的团队共享。

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

命名和命名空间

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

~/.gemini/commands/test.toml 处的文件变成命令 /test。
<project>/.gemini/commands/git/commit.toml 处的文件变成命名空间命令 /git:commit。

TOML 文件格式（v1）

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

必需字段

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

可选字段

description（字符串）：命令功能的简要单行描述。此文本将在 /help 菜单中显示在您的命令旁边。如果您省略此字段，将从文件名生成通用描述。

处理参数

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

1. 使用的上下文感知注入

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

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

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

在提示的主体中使用时，参数完全按照用户键入的方式注入。

示例（git/fix.toml）：

toml

# 通过以下方式调用：/git:fix "Button is misaligned"

description = "为给定问题生成修复。"
prompt = "请为此处描述的问题提供代码修复：{{args}}。"

模型接收：请为此处描述的问题提供代码修复："Button is misaligned"。

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

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

示例（/grep-code.toml）：

toml

prompt = """
请总结模式 `{{args}}` 的发现。

搜索结果：
!{grep -r {{args}} .}
"""

当您运行 /grep-code It's complicated 时：

CLI 看到在 !{...} 内外都被使用。
外部：第一个被原始替换为 It's complicated。
内部：第二个被替换为转义版本（例如，在 Linux 上："It's complicated"）。
执行的命令是 grep -r "It's complicated" .。
CLI 在执行前提示您确认这个确切的、安全的命令。
发送最终提示。

2. 默认参数处理

如果您的 prompt 不包含特殊占位符，CLI 使用默认行为处理参数。

如果您为命令提供参数（例如 /mycommand arg1），CLI 将把您键入的完整命令附加到提示的末尾，用两个换行符分隔。这允许模型看到原始指令和您刚刚提供的特定参数。

如果您不提供任何参数（例如 /mycommand），提示将完全按原样发送给模型，不附加任何内容。

示例（changelog.toml）：

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

toml

# 在：<project>/.gemini/commands/changelog.toml
# 通过以下方式调用：/changelog 1.2.0 added "Support for default argument parsing."

description = "向项目的 CHANGELOG.md 文件添加新条目。"
prompt = """
# 任务：更新更改日志

您是此软件项目的专家维护者。用户调用了一个命令来向更改日志添加新条目。

**用户的原始命令附加在您的指令下方。**

您的任务是从他们的输入中解析 `<version>`、`<change_type>` 和 `<message>`，并使用 `write_file` 工具正确更新 `CHANGELOG.md` 文件。

## 预期格式
命令遵循此格式：`/changelog <version> <type> <message>`
- `<type>` 必须是以下之一："added"、"changed"、"fixed"、"removed"。

## 行为
1. 读取 `CHANGELOG.md` 文件。
2. 找到指定 `<version>` 的部分。
3. 在正确的 `<type>` 标题下添加 `<message>`。
4. 如果版本或类型部分不存在，创建它。
5. 严格遵守"Keep a Changelog"格式。
"""

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

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

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

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

工作原理：

注入命令： 使用 !{...} 语法。
参数替换： 如果块内存在，它会自动进行 shell 转义（参见上面的上下文感知注入）。
健壮解析： 解析器正确处理包含嵌套大括号的复杂 shell 命令，如 JSON 负载。注意： !{...} 内的内容必须有平衡的大括号（{ 和 }）。如果您需要执行包含不平衡大括号的命令，考虑将其包装在外部脚本文件中并在 !{...} 块内调用脚本。
安全检查和确认： CLI 对最终的、解析的命令（在参数转义和替换后）执行安全检查。将出现一个对话框，显示要执行的确切命令。
执行和错误报告： 执行命令。如果命令失败，注入到提示中的输出将包括错误消息（stderr），后跟状态行，例如 [Shell command exited with code 1]。这帮助模型理解失败的上下文。

示例（git/commit.toml）：

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

toml

# 在：<project>/.gemini/commands/git/commit.toml
# 通过以下方式调用：/git:commit

description = "基于暂存更改生成 Git 提交消息。"

# 提示使用 !{...} 执行命令并注入其输出。
prompt = """
请基于以下 git diff 生成一个 Conventional Commit 消息：

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

"""

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

4. 使用 `@{...}` 注入文件内容

您可以使用 @{...} 语法将文件内容或目录列表直接嵌入到提示中。这对于创建操作特定文件的命令很有用。

工作原理：

文件注入：@{path/to/file.txt} 被 file.txt 的内容替换。
多模态支持：如果路径指向支持的图像（例如 PNG、JPEG）、PDF、音频或视频文件，它将被正确编码并作为多模态输入注入。其他二进制文件会被优雅处理并跳过。
目录列表：@{path/to/dir} 被遍历，目录和所有子目录中存在的每个文件都插入到提示中。如果启用，这会遵守 .gitignore 和 .geminiignore。
工作区感知：命令在当前目录和任何其他工作区目录中搜索路径。如果绝对路径在工作区内，则允许使用。
处理顺序：使用 @{...} 的文件内容注入在 shell 命令（!{...}）和参数替换（）_之前_处理。
解析：解析器要求 @{...} 内的内容（路径）有平衡的大括号（{ 和 }）。

示例（review.toml）：

此命令注入_固定_最佳实践文件（docs/best-practices.md）的内容，并使用用户的参数为审查提供上下文。

toml

# 在：<project>/.gemini/commands/review.toml
# 通过以下方式调用：/review FileCommandLoader.ts

description = "使用最佳实践指南审查提供的上下文。"
prompt = """
您是专家代码审查员。

您的任务是审查 {{args}}。

在提供审查时使用以下最佳实践：

@{docs/best-practices.md}
"""

当您运行 /review FileCommandLoader.ts 时，@{docs/best-practices.md} 占位符被该文件的内容替换，被您提供的文本替换，然后将最终提示发送给模型。

示例：一个"纯函数"重构命令

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

1. 创建文件和目录：

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

bash

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

2. 向文件添加内容：

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

toml

# 在：~/.gemini/commands/refactor/pure.toml
# 此命令将通过以下方式调用：/refactor:pure

description = "要求模型将当前上下文重构为纯函数。"

prompt = """
请分析我在当前上下文中提供的代码。
将其重构为纯函数。

您的响应应包括：
1. 重构的纯函数代码块。
2. 您所做的关键更改的简要说明以及它们如何有助于纯度。
"""

3. 运行命令：

就是这样！您现在可以在 CLI 中运行您的命令。首先，您可能会向上下文添加一个文件，然后调用您的命令：

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

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

At 命令（`@`）

At 命令用于将文件或目录的内容作为您对 Gemini 的提示的一部分包含。这些命令包括 git 感知过滤。

@<path_to_file_or_directory>
- 描述： 将指定文件或文件的内容注入到您当前的提示中。这对于询问特定代码、文本或文件集合的问题很有用。
- 示例：
  - @path/to/your/file.txt 解释这个文本。
  - @src/my_project/ 总结这个目录中的代码。
  - 这个文件是关于什么的？ @README.md
- 详情：
  - 如果提供单个文件的路径，则读取该文件的内容。
  - 如果提供目录的路径，命令尝试读取该目录和任何子目录中文件的内容。
  - 路径中的空格应用反斜杠转义（例如 @My\ Documents/file.txt）。
  - 命令内部使用 read_many_files 工具。内容被获取后插入到您的查询中，然后发送给 Gemini 模型。
  - Git 感知过滤： 默认情况下，git 忽略的文件（如 node_modules/、dist/、.env、.git/）被排除。此行为可以通过 context.fileFiltering 设置更改。
  - 文件类型： 命令适用于基于文本的文件。虽然它可能尝试读取任何文件，但二进制文件或非常大的文件可能被底层 read_many_files 工具跳过或截断，以确保性能和相关性。工具指示文件是否被跳过。
- 输出： CLI 将显示一个工具调用消息，指示使用了 read_many_files，以及详细说明状态和处理的路径的消息。
@（单独的 at 符号）
- 描述： 如果您键入单独的 @ 符号而没有路径，查询将按原样传递给 Gemini 模型。如果您在提示中特别谈论 @ 符号本身，这可能很有用。

`@` 命令的错误处理

如果 @ 后指定的路径未找到或无效，将显示错误消息，查询可能不会发送给 Gemini 模型，或者将在没有文件内容的情况下发送。
如果 read_many_files 工具遇到错误（例如权限问题），这也会被报告。

Shell 模式和直通命令（`!`）

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

!<shell_command>
- 描述： 在 Linux/macOS 上使用 bash 或在 Windows 上使用 cmd.exe 执行给定的 <shell_command>。命令的任何输出或错误都会在终端中显示。
- 示例：
  - !ls -la（执行 ls -la 并返回到 Gemini CLI）
  - !git status（执行 git status 并返回到 Gemini CLI）
!（切换 shell 模式）
- 描述： 单独键入 ! 切换 shell 模式。
  - 进入 shell 模式：
    - 激活时，shell 模式使用不同的着色和"Shell 模式指示器"。
    - 在 shell 模式下，您键入的文本直接解释为 shell 命令。
  - 退出 shell 模式：
    - 退出时，UI 恢复到标准外观，正常的 Gemini CLI 行为恢复。
所有 ! 使用的注意事项： 您在 shell 模式下执行的命令具有与您直接在终端中运行它们相同的权限和影响。
环境变量： 当通过 ! 或在 shell 模式下执行命令时，在子进程的环境中设置 GEMINI_CLI=1 环境变量。这允许脚本或工具检测它们是否从 Gemini CLI 内运行。

CLI 命令 ​

斜杠命令（/） ​

内置命令 ​

自定义命令 ​

文件位置和优先级 ​

命名和命名空间 ​

TOML 文件格式（v1） ​

必需字段 ​

可选字段 ​

处理参数 ​

1. 使用 的上下文感知注入 ​

2. 默认参数处理 ​

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

4. 使用 @{...} 注入文件内容 ​

示例：一个"纯函数"重构命令 ​

At 命令（@） ​

@ 命令的错误处理 ​

Shell 模式和直通命令（!） ​

CLI 命令

斜杠命令（`/`）

内置命令

自定义命令

文件位置和优先级

命名和命名空间

TOML 文件格式（v1）

必需字段

可选字段

处理参数

1. 使用的上下文感知注入

2. 默认参数处理

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

4. 使用 `@{...}` 注入文件内容

示例：一个"纯函数"重构命令

At 命令（`@`）

`@` 命令的错误处理

Shell 模式和直通命令（`!`）