Gemini CLI Docs

简体中文

English

简体中文

English

主题

CLI 命令 ​

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

斜杠命令（/） ​

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

内置命令 ​

  • /bug

    • 描述： 提交关于 Gemini CLI 的问题。默认情况下，问题会在 Gemini CLI 的 GitHub 仓库中提交。您在 /bug 后输入的字符串将成为所提交错误的标题。可以通过 .gemini/settings.json 文件中的 bugCommand 设置修改默认的 /bug 行为。

  • /chat

    • 描述： 保存和恢复对话历史，用于交互式分支对话状态，或从后续会话中恢复之前的状态。
    • 子命令：
      • save
        • 描述： 保存当前对话历史。您必须添加一个用于标识对话状态的 <tag>。
        • 用法： /chat save <tag>
        • 检查点位置详情： 保存的聊天检查点的默认位置是：
          • Linux/macOS：~/.config/google-generative-ai/checkpoints/
          • Windows：C:\Users\<您的用户名>\AppData\Roaming\google-generative-ai\checkpoints\
          • 当您运行 /chat list 时，CLI 只扫描这些特定目录来查找可用的检查点。
          • 注意： 这些检查点用于手动保存和恢复对话状态。对于在文件修改前创建的自动检查点，请参阅检查点文档。
      • resume
        • 描述： 从之前的保存中恢复对话。
        • 用法： /chat resume <tag>
      • list
        • 描述： 列出可用于聊天状态恢复的标签。

  • /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 或通过设置配置时才可用。更多详情请参阅检查点文档。

  • /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 从两个位置发现命令，按特定顺序加载：

  1. 用户命令（全局）： 位于 ~/.gemini/commands/。这些命令在您工作的任何项目中都可用。
  2. 项目命令（本地）： 位于 <您的项目根目录>/.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 将用用户在命令名称后键入的所有文本替换该确切占位符。这非常适合简单、确定性的命令，您需要将用户输入注入到更大提示模板中的特定位置。

示例（git/fix.toml）：

toml
# 位于：~/.gemini/commands/git/fix.toml
# 通过以下方式调用：/git:fix "按钮在移动端未对齐"

description = "为给定的 GitHub 问题生成修复方案。"
prompt = "请分析暂存的 git 更改并为此处描述的问题提供代码修复：{{args}}。"

模型将收到最终提示：请分析暂存的 git 更改并为此处描述的问题提供代码修复："按钮在移动端未对齐"。

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 现在会在继续之前提示您确认。这是一项安全措施，确保只能运行预期的命令。

工作原理：

  1. 注入命令： 在您的 prompt 中使用 !{...} 语法指定命令应在何处运行及其输出注入位置。
  2. 确认执行： 当您运行命令时，将出现一个对话框，列出提示要执行的 shell 命令。
  3. 授予权限： 您可以选择：
    • 允许一次： 命令将运行这一次。
    • 本次会话始终允许： 命令将添加到当前 CLI 会话的临时允许列表中，不再需要确认。
    • 否： 取消 shell 命令的执行。

CLI 仍然遵循全局 excludeTools 和 coreTools 设置。如果命令在您的配置中被明确禁止，将在没有确认提示的情况下被阻止。

示例（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}。

示例：纯函数重构命令 ​

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

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/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，以及详细说明状态和处理的路径的消息。

  • @（单独的 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 内部运行。

基于 MIT 许可证发布

版权所有 © 2025-至今