自定义命令

自定义命令让你把最喜欢或最常用的提示词保存为 Gemini CLI 里的个人快捷方式。可以创建只针对单个项目的命令，也可以创建在你所有项目里都可用的全局命令。

文件位置与优先级

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

1. 用户命令（全局）：位于 ~/.gemini/commands/，在你工作的任何项目里都可用
2. 项目命令（本地）：位于 <项目根>/.gemini/commands/，只针对当前项目，可以提交进版本控制与团队共享

如果项目目录里的命令与用户目录里的命令同名，始终使用项目命令，这让项目可以用项目特定的版本覆盖全局命令。

命名与命名空间

命令名由它相对于 commands 目录的文件路径决定；子目录用来创建命名空间命令，路径分隔符（/ 或 \）被转换为冒号（:）：

• ~/.gemini/commands/test.toml 成为命令 /test
• <项目>/.gemini/commands/git/commit.toml 成为命名空间命令 /git:commit

创建或修改 .toml 命令文件后，运行 /commands reload 不重启 CLI 就能加载改动；/commands list 查看所有可用的命令文件。

TOML 文件格式（v1）

命令定义文件必须用 TOML 格式，扩展名是 .toml。必填字段 prompt（字符串）：执行命令时发给 Gemini 模型的提示词，可以是单行或多行字符串。可选字段 description（字符串）：对命令作用的简短一行描述，显示在 /help 菜单里命令的旁边；省略时会根据文件名生成通用描述。

处理参数

自定义命令支持两种处理参数的方法，CLI 根据命令 prompt 的内容自动选择：

1. 用 {{args}} 做上下文感知的注入：如果 prompt 包含特殊占位符 {{args}}，CLI 会把它替换为用户在命令名之后输入的文本。注入行为取决于使用位置：

• 原样注入（shell 命令之外）：用在提示正文里时，参数完全按用户输入的样子注入。例如 git/fix.toml（调用 /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}}."

• 在 shell 命令里使用参数（!{...} 块内）：在 shell 注入块 !{...} 里使用 {{args}} 时，参数在替换前自动做shell 转义，使你能安全地把参数传给 shell 命令，保证结果命令语法正确且安全，防止命令注入。例如 /grep-code.toml：

  prompt = """
  Please summarize the findings for the pattern `{{args}}`.
  
  Search Results:
  !{grep -r {{args}} .}
  """

  运行 /grep-code It's complicated 时，CLI 看到 {{args}} 在 !{...} 之外和之内都有使用：外面的第一个被原样替换为 It's complicated，里面的第二个被替换为转义后的版本，最终执行的命令是 grep -r "It's complicated" .；CLI 会在执行前提示你确认这条精确的、安全的命令，然后发送最终提示。

2. 默认参数处理：如果 prompt 不含 {{args}}，CLI 使用默认行为：你给命令提供了参数（如 /mycommand arg1），CLI 会把你输入的完整命令追加到提示末尾，中间隔两个换行，让模型同时看到原始指令和你刚提供的具体参数；没提供参数（如 /mycommand）时，提示原样发给模型，不追加任何东西。

3. 用 !{...} 执行 shell 命令：可以在 prompt 里直接执行 shell 命令并注入其输出，非常适合从本地环境收集上下文，如读取文件内容或检查 git 状态。官方文档还介绍了用 @{...} 嵌入文件或目录内容的做法，详见官方原文。