Gemini CLI 命令行参考：命令、选项与子命令的完整实战手册

本文以 Gemini CLI 官方文档中的命令行速查表为骨架，系统梳理 gemini 的启动命令、交互式斜杠命令、全部 CLI 选项、模型别名以及扩展（extensions）、MCP 服务器、技能（skills）三大子命令管理体系。并结合仓库源码（yargs 参数解析、模型解析函数、会话恢复逻辑等）说明每个选项在底层如何生效，帮助你在日常开发、CI 脚本和自动化任务中精确、可复现地使用 Gemini CLI 的每一个命令行能力。

基础启动命令

Command	说明	示例
gemini	启动交互式 REPL	gemini
gemini -p "query"	以非交互（headless）方式执行查询	gemini -p "summarize README.md"
gemini "query"	以位置参数提供提示词并继续交互	gemini "explain this project"
cat file | gemini	处理管道输入的内容	cat logs.txt | gemini（PowerShell：Get-Content logs.txt | gemini）
gemini -i "query"	执行提示词后继续交互	gemini -i "What is the purpose of this project?"
gemini -r "latest"	继续最近一次会话	gemini -r "latest"
gemini -r "latest" "query"	继续会话并带新提示词	gemini -r "latest" "Check for type errors"
gemini -r "<session-id>" "query"	按会话 ID 恢复	gemini -r "abc123" "Finish this PR"
gemini update	更新到最新版本	gemini update
gemini extensions	管理扩展	见下文扩展管理
gemini mcp	配置 MCP 服务器	见下文MCP 服务器管理

位置参数 query

参数	类型	说明
query	string（可变长）	位置提示词。在 TTY 终端中默认进入交互模式；若希望非交互执行请使用 -p/--prompt。

从源码结构看，位置参数与提示词标志位的关系在 参数解析逻辑 中处理：多个位置参数会被以空格拼接；在终端（非 headless）环境下提供位置参数时，CLI 会给出提示"Positional arguments now default to interactive mode"，并把该参数当作 --prompt-interactive 处理。若同时使用位置参数和 --prompt (-p)，校验逻辑会直接报错：Cannot use both a positional prompt and the --prompt (-p) flag together。

管道输入的处理逻辑可以在主流程 入口文件 中确认：当 stdin 不是 TTY 时，CLI 会读取全部管道内容，并将其与 --prompt 提供的提示词拼接（管道内容在前）。这也解释了为什么 cat file | gemini 可以直接工作。

交互式命令（斜杠命令）

以下命令在交互式 REPL 内可用：

命令	说明
/skills reload	从磁盘重新加载已发现的技能
/agents reload	重新加载 agent 注册表
/commands list	列出所有可用的自定义斜杠命令
/commands reload	重新加载自定义斜杠命令
/memory reload	重新加载上下文文件（例如 GEMINI.md）
/mcp reload	重启并重新加载 MCP 服务器
/extensions reload	重新加载所有已启用的扩展
/help	显示所有命令的帮助
/quit	退出交互会话

从源码结构看，内置斜杠命令由 BuiltinCommandLoader 统一注册，除了上表列出的命令外，还包含 /about、/bug、/clear、/compress、/chat、/copy、/docs、/export、/editor、/hooks、/ide、/init、/model、/permissions、/plan、/policies、/privacy、/profile、/resume、/restore、/shortcuts、/stats、/theme、/tools、/vim 等数十个内置命令；本文只聚焦与"重载/管理"相关的常用命令，完整清单可直接运行 /help 查看。

CLI 选项

选项	别名	类型	默认值	说明
--debug	-d	boolean	false	以调试模式运行，输出详细日志（可打开调试控制台）
--version	-v	-	-	显示 CLI 版本号并退出
--help	-h	-	-	显示帮助信息
--model	-m	string	auto	指定使用的模型，可用值见模型选择
--prompt	-p	string	-	提示词文本；若同时存在 stdin 输入则追加其后。强制非交互模式
--prompt-interactive	-i	string	-	执行提示词后继续进入交互模式
--worktree	-w	string	-	在新的 git worktree 中启动。未提供名称时自动生成。需要 settings 中启用 experimental.worktrees: true
--sandbox	-s	boolean	false	在沙箱环境中运行以获得更安全的执行
--skip-trust	-	boolean	false	本次会话信任当前工作区，跳过文件夹信任检查
--approval-mode	-	string	default	工具执行的审批模式，可选：default、auto_edit、yolo、plan
--yolo	-y	boolean	false	已弃用。 自动批准所有操作，请改用 --approval-mode=yolo
--experimental-acp	-	boolean	-	以 ACP（Agent Client Protocol）模式启动。实验特性
--experimental-zed-integration	-	boolean	-	以 Zed 编辑器集成模式运行。实验特性
--allowed-mcp-server-names	-	array	-	允许的 MCP 服务器名称（逗号分隔或重复使用该标志）
--allowed-tools	-	array	-	已弃用。 建议改用 Policy Engine。无需确认即可运行的工具（逗号分隔或重复使用）
--extensions	-e	array	-	指定使用的扩展列表；不提供则启用全部扩展（逗号分隔或重复使用）
--list-extensions	-l	boolean	-	列出所有可用扩展后退出
--resume	-r	string	-	恢复历史会话；"latest" 表示最近一次，也可用序号（例如 --resume 5）
--list-sessions	-	boolean	-	列出当前项目的可用会话后退出
--delete-session	-	string	-	按序号删除会话（先用 --list-sessions 查看可用会话）
--include-directories	-	array	-	纳入工作区的附加目录（逗号分隔或重复使用）
--screen-reader	-	boolean	-	启用屏幕阅读器无障碍模式
--output-format	-o	string	text	CLI 输出格式，可选：text、json、stream-json

以下选项在 参数定义源码 中同样可见，但常被脚本使用，值得单独说明：

选项	类型	说明
--acp	boolean	以 ACP 模式启动（--experimental-acp 的正式替代，源码中标注后者为 deprecated）
--policy	array	加载额外的策略文件或目录（逗号分隔或重复使用）
--admin-policy	array	加载额外的管理员策略文件或目录
--session-id	string	以手动指定的 UUID 开启新会话，仅允许字母、数字、连字符、下划线
--session-file	string	从 JSON 文件导入会话（历史消息会被过滤为用户/模型对话）
--raw-output / --accept-raw-output-risk	boolean	禁用模型输出净化（允许 ANSI 序列），存在安全风险，默认输出会给出警告

参数校验规则（源码依据）

所有选项通过 parseArguments 中的 yargs .check() 校验 统一检查，包含以下互斥与约束规则：

• --resume、--session-id、--session-file 三者互斥，最多提供一个；
• 位置提示词与 --prompt (-p) 不能同时使用；
• --prompt (-p) 与 --prompt-interactive (-i) 不能同时使用；
• --yolo 与 --approval-mode 不能同时使用（应写为 --approval-mode=yolo）；
• --output-format 只接受 text、json、stream-json 三种取值；
• --worktree 仅当 settings 中启用 experimental.worktrees 时可用，否则报错：The --worktree flag is only available when experimental.worktrees is enabled in your settings.（该行为在 参数测试 中有专门用例覆盖）；
• --prompt-interactive 不能用于管道 stdin 场景，主流程会提前报错退出（见 gemini.tsx）。

会话管理的底层实现

--resume、--list-sessions、--delete-session 的执行逻辑集中在 resolveSessionId 与主流程：

• --resume latest 在没有历史会话时仅给出警告并创建新会话（RESUME_LATEST 特判）；
• --session-id 指定已存在的 ID 时会直接报错退出，避免覆盖；
• --session-file 导入时会过滤旧的系统/信息消息，只保留 user 与 gemini 类型的对话记录，并写入新的会话文件；
• --list-sessions 会尝试完成认证以生成会话摘要（认证失败时降级为无摘要列表）；
• 会话解析完成后，--list-sessions 和 --delete-session 属于"执行完即退出"类选项，会立即 process.exit。

弃用选项的迁移提示

当使用 --allowed-tools 或 settings 中的 tools.allowed / tools.exclude 时，启动阶段会打印弃用警告，提示迁移至 Policy Engine（见 入口文件中的警告逻辑）。策略文件的完整配置方式参见 策略引擎参考。

模型选择

--model（或 -m）可用于指定 Gemini 模型。既可使用模型别名（用户友好名称），也可使用具体模型名。

模型别名

别名	解析结果	说明
auto	gemini-2.5-pro 或 gemini-3-pro-preview	默认值。 若启用了预览功能则解析为预览模型，否则解析为标准 pro 模型
pro	gemini-2.5-pro 或 gemini-3-pro-preview	面向复杂推理任务。启用预览时解析为预览模型
flash	gemini-2.5-flash	面向大多数任务的快速均衡模型
flash-lite	gemini-2.5-flash-lite	面向简单任务的最快模型

源码中的解析机制

别名的实际解析由 resolveModel 函数 完成，可确认的关键行为：

• 别名常量定义在 models.ts：auto、pro、flash、flash-lite（GEMINI_MODEL_ALIAS_*）；
• 解析结果取决于 hasAccessToPreview（用户是否具备预览模型访问权限）：无预览权限时 auto/pro 会降级为稳定版 gemini-2.5-pro，解析出的预览模型也会自动"降级到稳定模型"；
• 解析函数还处理了动态模型配置实验路径（experimental.dynamicModelConfiguration）：启用时通过 ModelConfigService.resolveModelId 解析，并对无预览权限的用户做兜底降级；
• 具体模型名（非别名）会原样透传，例如 gemini-2.5-pro、gemini-3.1-flash-lite 等；
• 当前源码中 flash 别名的解析还受 useGemini3_5Flash 开关影响（在特定后端可解析为 GA 的 flash 模型），flash-lite 别名当前解析到 DEFAULT_GEMINI_FLASH_LITE_MODEL 常量。以上属于实验性演进逻辑，日常使用以别名语义为准即可。

扩展管理（extensions）

命令	说明	示例
gemini extensions install <source>	从 Git URL 或本地路径安装扩展	gemini extensions install https://github.com/user/my-extension
gemini extensions install <source> --ref <ref>	从指定分支/标签/提交安装	gemini extensions install https://github.com/user/my-extension --ref develop
gemini extensions install <source> --auto-update	安装并启用自动更新	gemini extensions install https://github.com/user/my-extension --auto-update
gemini extensions uninstall <name>	卸载一个或多个扩展	gemini extensions uninstall my-extension
gemini extensions list	列出所有已安装的扩展	gemini extensions list
gemini extensions update <name>	更新指定扩展	gemini extensions update my-extension
gemini extensions update --all	更新全部扩展	gemini extensions update --all
gemini extensions enable <name>	启用扩展	gemini extensions enable my-extension
gemini extensions disable <name>	禁用扩展	gemini extensions disable my-extension
gemini extensions link <path>	链接本地扩展用于开发	gemini extensions link /path/to/extension
gemini extensions new <path>	从模板创建新扩展	gemini extensions new ./my-extension
gemini extensions validate <path>	校验扩展结构	gemini extensions validate ./my-extension

更多细节参见 扩展文档。

从源码结构看，extensions、mcp、skills、hooks、gemma 五组子命令均在 parseArguments 中通过 yargsInstance.command(...) 注册为独立的 yargs 子命令，对应的命令实现位于 packages/cli/src/commands/ 目录（extensions.tsx、mcp.ts、skills.tsx 等）。主流程在识别到这些子命令时会置内部标志 isCommand，从而跳过认证、沙箱等交互式启动逻辑，保证 gemini extensions list 这类纯管理命令可以快速执行并退出。

MCP 服务器管理

命令	说明	示例
gemini mcp add <name> <command>	添加 stdio 类型的 MCP 服务器	gemini mcp add github npx -y @modelcontextprotocol/server-github
gemini mcp add <name> <url> --transport http	添加 HTTP 类型的 MCP 服务器	gemini mcp add api-server http://localhost:3000 --transport http
gemini mcp add <name> <command> --env KEY=value	添加并配置环境变量	gemini mcp add slack node server.js --env SLACK_TOKEN=xoxb-xxx
gemini mcp add <name> <command> --scope user	以 user 作用域添加	gemini mcp add db node db-server.js --scope user
gemini mcp add <name> <command> --include-tools tool1,tool2	仅添加指定工具	gemini mcp add github npx -y @modelcontextprotocol/server-github --include-tools list_repos,get_pr
gemini mcp remove <name>	移除 MCP 服务器	gemini mcp remove github
gemini mcp list	列出所有已配置的 MCP 服务器	gemini mcp list

运行时可用 --allowed-mcp-server-names 选项在单次启动中限定可用的服务器；会话内也可用 /mcp reload 重启并重新加载 MCP 服务器。更多细节参见 MCP 服务器集成文档。

技能管理（skills）

命令	说明	示例
gemini skills list	列出所有已发现的 agent 技能	gemini skills list
gemini skills install <source>	从 Git、路径或文件安装技能	gemini skills install https://github.com/u/repo
gemini skills link <path>	通过符号链接链接本地技能	gemini skills link /path/to/my-skills
gemini skills uninstall <name>	卸载 agent 技能	gemini skills uninstall my-skill
gemini skills enable <name>	启用 agent 技能	gemini skills enable my-skill
gemini skills disable <name>	禁用 agent 技能	gemini skills disable my-skill
gemini skills enable --all	启用全部技能	gemini skills enable --all
gemini skills disable --all	禁用全部技能	gemini skills disable --all

更多细节参见 Agent Skills 文档。

小结与延伸阅读

• 交互式与 headless 的切换核心在于 -p/--prompt（强制非交互）与位置参数 / -i/--prompt-interactive（默认交互）的语义差异，二者互斥且各有校验保护；
• 会话相关选项（--resume、--list-sessions、--delete-session、--session-id、--session-file）覆盖了恢复、列表、删除与导入的完整生命周期，底层实现在 gemini.tsx 的会话解析；
• 弃用选项（--yolo、--allowed-tools）均应迁移到 --approval-mode 与 Policy Engine；
• 想进一步了解的仓库内文档：Policy Engine 参考、无头（headless）模式、扩展编写指南、Skills 最佳实践、设置参考。