Gemini CLI 入门

Gemini CLI 入门

基础概念

Gemini CLI 是 Google 官方推出的开源终端 Agent，仓库 google-gemini/gemini-cli，Apache-2.0 协议，截至 2026-04 的最新版本是 v0.38.2（4 月 17 日发布）。它把 Gemini 系列模型直接接进你的命令行，让你在 shell 里像和人对话一样指挥它读代码、改文件、跑命令、查文档。

它和 Claude Code、Codex CLI 属于同一类——都是模型厂商自己出的"亲儿子"终端 Agent，但 Gemini CLI 有两张特别打的牌：

• 超大上下文窗口：默认 1M tokens（约等于 30000 行代码或 1500 页文本），单次会话就能把一个中等规模仓库整个塞进去，不用分块也不用 RAG 检索。这是 Claude Code（约 200K）和 Codex CLI（128K-200K）目前都达不到的量级。
• 慷慨的免费额度：用 Google 个人账号 OAuth 登录，每天 1000 次模型请求、每分钟约 60 次，对个人开发者和小项目几乎等同于"白嫖"。

它要解决的痛点很现实：以前想让 AI 帮你看一个 50 万行的 monorepo，要么得切分成几十段喂给模型，要么得搭一套向量检索做 RAG。Gemini CLI 把这件事简化成了"全部塞进上下文，让模型自己读"。

核心要素

架构与一次调用流程

这张图画的是 Gemini CLI 一次完整调用：用户输入 → CLI 加 GEMINI.md → 模型判断要不要调工具 → 工具结果回传给模型 → 循环直到模型给出最终答案。整个流程和 Claude Code 几乎一模一样，差别在于模型和认证后端是 Google 的。

基础用法

安装

# 方式 1：npm 全局安装（最常见）
npm install -g @google/gemini-cli

# 验证
gemini --version
# 预期输出：0.38.2（截至 2026-04）

# 方式 2：用 npx 临时跑（不想全局装时）
npx @google/gemini-cli

要求 Node.js 18+。装完后命令名就是 gemini。

配置认证

第一次跑 gemini 会弹出认证选项，选一个即可：

gemini
# 终端会提示：
#   1. Login with Google (推荐，免费 1000 次/天)
#   2. Use Gemini API Key
#   3. Use Vertex AI

# 选 1 会打开浏览器走 OAuth；选 2 需要先在 AI Studio 拿 key
export GEMINI_API_KEY="your-key-here"

API Key 可以在 Google AI Studio 一键生成，零成本。如果你公司用 GCP，更推荐走 Vertex AI 路线，权限和审计都接到企业 IAM。

最小示例

# 一次性调用，问完即退
gemini "把 README.md 翻译成中文，保留代码块"

# 交互式 REPL
gemini
> 帮我看看 src/api/users.ts 这个文件有什么潜在 bug
> 加个单元测试覆盖刚才说的边界情况
> /exit

# 指定模型
gemini -m gemini-2.5-flash "总结一下当前目录的项目结构"

# 非交互脚本模式（CI 友好，输出 JSON）
gemini --output-format json "列出 package.json 里所有依赖" > deps.json

预期行为：

你：帮我看看 src/api/users.ts 有什么潜在 bug
Gemini：[调用工具：read_file src/api/users.ts]
Gemini：发现三个潜在问题：
  1. 第 42 行 user.id 可能为 undefined，没做空值判断……
  2. ……

项目级配置：GEMINI.md

在项目根放一个 GEMINI.md，Gemini CLI 每次启动都会自动读进上下文，相当于给 Agent 写"项目说明书"：

# 这个项目是什么
- 一个 Next.js 14 + TypeScript 的内容站
- 数据流：.publish → scripts/build-content.ts → public/data → 页面

# 编码约定
- 不要在页面组件里直接读 .publish 源文件
- 新增 API 必须配 Vitest 测试

这和 Claude Code 的 CLAUDE.md、Codex CLI 的 AGENTS.md 是一类东西——都是给终端 Agent 的项目记忆。

同类工具对比

核心区别一句话：Gemini CLI 的杀手锏是 大上下文 + 免费额度，最适合"整库丢给它分析"这种场景；Claude Code 强在多文件推理一致性；Codex CLI 强在沙箱自主执行。这三个不是替代关系，而是按任务挑工具——预算紧 / 需要读大型 monorepo / 想白嫖 → Gemini CLI 几乎是首选。

常见误区

优劣势分析

思考题

参考资料

1. Gemini CLI 官方仓库：https://github.com/google-gemini/gemini-cli (查询日期: 2026-04-22)
2. Gemini CLI 配额与定价文档：https://github.com/google-gemini/gemini-cli/blob/main/docs/resources/quota-and-pricing.md (查询日期: 2026-04-22)
3. Gemini API 速率限制：https://ai.google.dev/gemini-api/docs/rate-limits (查询日期: 2026-04-22)
4. Google AI Studio（API Key 申请入口）：https://aistudio.google.com/ (查询日期: 2026-04-22)
5. 官方文档站：https://google-gemini.github.io/gemini-cli/ (查询日期: 2026-04-22)
6. 2026 年终端 Agent 横评（DataCamp）：https://www.datacamp.com/blog/gemini-cli-vs-claude-code (查询日期: 2026-04-22)
7. 三大终端 Agent 实测对比（IntuitionLabs）：https://intuitionlabs.ai/articles/claude-code-vs-codex-vs-gemini-cli-comparison (查询日期: 2026-04-22)