CLI 命令

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

斜杠命令（`/`）

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

内置命令

/bug
- 描述： 提交关于 Gemini CLI 的问题报告。默认情况下，问题会提交到 Gemini CLI 的 GitHub 仓库。您在 /bug 后输入的字符串将成为所提交 bug 的标题。可以通过在 .gemini/settings.json 文件中的 bugCommand 设置修改默认的 /bug 行为。
/chat
- 描述： 保存和恢复对话历史，用于交互式分支对话状态，或从后续会话中恢复之前的状态。
- 子命令：
  - save
    - 描述： 保存当前的对话历史。您必须添加一个 <tag> 来标识对话状态。
    - 用法： /chat save <tag>
    - 检查点位置详细信息： 保存的聊天检查点的默认位置为：
      - Linux/macOS: ~/.config/google-generative-ai/checkpoints/
      - Windows: C:\Users\<YourUsername>\AppData\Roaming\google-generative-ai\checkpoints\
      - 当您运行 /chat list 时，CLI 只扫描这些特定目录以查找可用的检查点。
      - 注意： 这些检查点用于手动保存和恢复对话状态。有关在文件修改前创建的自动检查点，请参阅检查点文档。
  - resume
    - 描述： 从之前保存的状态恢复对话。
    - 用法： /chat resume <tag>
  - list
    - 描述： 列出可用于恢复聊天状态的标签。
  - delete
    - 描述： 删除已保存的对话检查点。
    - 用法： /chat delete <tag>
/clear
- 描述： 清除终端屏幕，包括 CLI 中的可见会话历史和回滚缓冲区。根据具体实现，底层会话数据（用于历史记录回调）可能会被保留，但视觉显示会被清除。
- 键盘快捷键： 随时按 Ctrl+L 执行清除操作。
/compress
- 描述： 将整个聊天上下文替换为摘要。这可以节省未来任务中使用的令牌，同时保留已发生事件的高级摘要。
/copy
- 描述： 将 Gemini CLI 产生的最后一次输出复制到剪贴板，以便轻松分享或重复使用。
/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 或通过设置配置时可用。有关更多详细信息，请参阅检查点文档。
/settings
- 描述： 打开设置编辑器来查看和修改 Gemini CLI 设置。
- 详细信息： 此命令提供用户友好的界面来更改控制 Gemini CLI 行为和外观的设置。它等同于手动编辑 .gemini/settings.json 文件，但具有验证和指导功能以防止错误。
- 用法： 只需运行 /settings，编辑器就会打开。然后您可以浏览或搜索特定设置，查看其当前值，并根据需要进行修改。某些设置的更改会立即应用，而其他设置则需要重启。
/stats
- 描述： 显示当前 Gemini CLI 会话的详细统计信息，包括令牌使用情况、缓存令牌节省（如果可用）和会话持续时间。注意：缓存令牌信息仅在使用缓存令牌时显示，这在 API 密钥身份验证时会发生，但在此时不适用于 OAuth 身份验证。
/theme
- 描述： 打开一个对话框，让您更改 Gemini CLI 的视觉主题。
/auth
- 描述： 打开一个对话框，让您更改身份验证方法。
/about
- 描述： 显示版本信息。提交问题时请分享此信息。
/tools
- 描述： 显示 Gemini CLI 中当前可用的工具列表。
- 子命令：
  - 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 "按钮未对齐"

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

模型接收：请为此处描述的问题提供代码修复："按钮未对齐"。

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 "对默认参数解析的支持。"

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 "新功能" 时，发送给模型的最终文本将是原始提示，后跟两个换行符和您输入的命令。

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 生成一个传统提交消息：

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

"""

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

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

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

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 文件中定义的多行提示。

@ 命令（`@`）

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

@<文件或目录路径>
- 描述： 将指定文件或文件的内容注入到您当前的提示中。这对于询问有关特定代码、文本或文件集合的问题很有用。
- 示例：
  - @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/）会被排除。可以通过 fileFiltering 设置更改此行为。
  - 文件类型： 该命令适用于基于文本的文件。虽然它可能会尝试读取任何文件，但二进制文件或非常大的文件可能会被底层的 read_many_files 工具跳过或截断，以确保性能和相关性。工具会指示是否跳过了文件。
- 输出： CLI 将显示一条工具调用消息，指示使用了 read_many_files，以及详细说明状态和处理的路径的消息。
@（单独的 @ 符号）
- 描述： 如果您输入一个没有路径的单独 @ 符号，查询会原样传递给 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 命令 ​

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

@ 命令（@） ​

@ 命令的错误处理 ​

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

CLI 命令

斜杠命令（`/`）

内置命令

自定义命令

文件位置和优先级

命名和命名空间

TOML 文件格式（v1）

必需字段

可选字段

处理参数

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

2. 默认参数处理

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

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

@ 命令（`@`）

`@` 命令的错误处理

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