Gemini CLI 深度指南
Gemini CLI 是 Google 推出的开源终端 AI 工具，核心特点是“直接在命令行里使用 Gemini”。它支持交互式会话、非交互调用、会话恢复、扩展管理和 MCP 相关能力，适合把 AI 助手嵌入日常开发流程。
如果你已经习惯在终端里做大部分开发工作，Gemini CLI 上手会很自然。
官方地址
| 类型 | 地址 |
|---|---|
| 官方站点 | https://geminicli.com/ |
| 官方 GitHub | https://github.com/google-gemini/gemini-cli |
| CLI 文档 | https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/cli-reference.md |
适用场景
Gemini CLI 适合这些常见用途：
- 读取代码库并快速总结结构
- 在终端中直接问问题、生成内容或解释代码
- 批量处理文本、日志、文档
- 通过脚本方式调用模型完成自动化任务
- 结合扩展或 MCP 服务器做更复杂的集成
它的设计非常偏“终端优先”，所以特别适合已经把 shell 当主工作台的人。
安装准备
官方文档给出的基础准备包括：
- Node.js 环境
- 可用的 Google 账号或对应的认证方式
- 网络连接
- 需要时再补充 Google Cloud 项目配置
从安装难度来说，Gemini CLI 相对简单，初学者最容易踩的坑通常不是命令本身，而是认证和账号配置。
安装方式
方式一：npm 全局安装
这是官方 README 和入门文档最常见的安装方式：
npm install -g @google/gemini-cli
gemini方式二：npx 直接运行
如果你只是想先体验一下，不想立刻全局安装，可以直接运行：
npx @google/gemini-cli方式三：Homebrew、MacPorts 或 Conda
官方 README 还列出了 Homebrew、MacPorts、Conda 等方式，适合不同平台和环境约束。对于初学者，优先建议 npm 方式，路径和行为更清晰。
首次登录 / 认证
Gemini CLI 的认证通常从首次启动开始。
启动后，选择：
gemini然后按提示选择 Sign in with Google。官方文档说明：
- 一般用户可以直接用 Google 账号登录
- 某些账号类型可能需要配置 Google Cloud 项目
- 企业或受控环境下，认证方式可能和个人账号不完全一样
对于第一次使用的人，建议先把默认 Google 登录流程跑通，再考虑改模型、改配置或接扩展。
常用命令大全
| 命令 | 作用 | 示例 | 注意事项 |
|---|---|---|---|
gemini | 启动交互式 REPL | gemini | 默认从当前目录开始 |
gemini "query" | 带初始提示进入交互模式 | gemini "explain this project" | 适合先问一个大问题 |
gemini -p "query" | 非交互模式 | gemini -p "summarize README.md" | 适合脚本和一次性任务 |
cat file | gemini | 处理管道输入 | cat 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 | 更新 CLI | gemini update | 建议定期升级 |
gemini extensions | 管理扩展 | gemini extensions | 用于安装和维护扩展 |
gemini mcp | 管理 MCP 服务器 | gemini mcp | 做工具集成时会用到 |
gemini -m <model> | 指定模型 | gemini -m gemini-2.5-flash | 模型名以官方支持为准 |
gemini --include-directories | 额外包含目录 | gemini --include-directories ../lib,../docs | 适合跨目录分析 |
gemini --output-format json | 输出 JSON | gemini -p "..." --output-format json | 适合程序化处理 |
gemini --output-format stream-json | 流式 JSON 输出 | gemini -p "..." --output-format stream-json | 适合长任务监控 |
常用工作流
1. 先交互，后批处理
初学者最容易理解的流程是：先运行 gemini 进入交互模式，确认它能看懂你的项目，再把稳定的步骤改写成 -p 命令。
2. 用模型选择控制速度和质量
官方 README 把 flash、flash-lite、pro、auto 这些选择都整理出来了。一般来说，简单任务先用更快的模型，复杂推理再切换到更强的模型。
3. 用输出格式对接脚本
如果你要把 Gemini CLI 接进脚本或自动化流程，优先考虑 --output-format json 或 stream-json。这样更容易稳定解析结果。
4. 用扩展和 MCP 拓展能力
Gemini CLI 不只是一个问答壳，它还支持扩展和 MCP 服务器。对于需要接入外部工具链的场景，这一层会很有价值。
权限与安全建议
Gemini CLI 既能读文件，也能执行动作，所以要注意控制边界。
- 不要把敏感信息直接写进提示词
- 处理本地仓库时，确认当前目录是否正确
- 在脚本模式下，优先输出结构化结果，减少误判
- 企业账号和个人账号的认证与权限可能不同，首次配置时要先确认
- 对扩展和 MCP 服务器来源保持审慎
如果你在团队环境中使用，建议先约定哪些操作可以自动跑，哪些必须人工确认。
排错
1. gemini 启动后无法登录
检查 Google 账号状态，确认是否需要 Google Cloud 项目配置。企业账号或特殊账号类型通常更容易遇到这个问题。
2. 命令执行后没有输出
先确认你使用的是交互模式还是 -p 非交互模式。很多时候只是模式选错了。
3. 结果不好解析
改用 --output-format json，不要直接依赖自然语言输出做自动处理。
4. 扩展或 MCP 不生效
先确认相关命令是否已安装、配置文件是否正确，然后再看当前版本文档里的约束。
总结
Gemini CLI 的优点很明确：安装方式多、命令风格简单、模型选择清晰，而且很适合终端党。对新手来说，最值得先掌握的是 gemini、gemini -p、会话恢复和认证这几个核心动作。
先跑通基础流程，再去碰扩展、MCP 和结构化输出，会比较稳。