google-gemini--gemini-cli/README.md

Note

本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

Gemini CLI

Gemini CLI 是一个开源 AI 代理，将 Gemini 的强大能力直接带到您的终端。它提供轻量级访问 Gemini 的途径，为您提供从提示到模型的最直接路径。

在文档.)中了解 Gemini CLI 的全部内容。

🚀 为什么选择 Gemini CLI？

• 🎯 免费使用额度：使用个人 Google 账号即可享受每分钟 60 次请求和每日 1,000 次请求。
• 🧠 强大的 Gemini 3 模型：访问改进的推理能力和 100 万 token 上下文窗口。
• 🔧 内置工具：Google 搜索验证、文件操作、Shell 命令、网页抓取。
• 🔌 可扩展：支持 MCP（模型上下文协议）以实现自定义集成。
• 💻 终端优先：为命令行开发者量身打造。
• 🛡️ 开源：基于 Apache 2.0 许可证。

📦 安装

请参阅 Gemini CLI 安装、运行与版本发布) 了解推荐系统规格和详细的安装指南。

快速安装

使用 npx 立即运行

# Using npx (no installation required)
npx @google/gemini-cli

使用 npm 全局安装

npm install -g @google/gemini-cli

使用 Homebrew 全局安装（macOS/Linux）

brew install gemini-cli

使用 MacPorts 全局安装（macOS）

sudo port install gemini-cli

使用 Anaconda 安装（受限环境）

# Create and activate a new environment
conda create -y -n gemini_env -c conda-forge nodejs
conda activate gemini_env

# Install Gemini CLI globally via npm (inside the environment)
npm install -g @google/gemini-cli

发布渠道

详见版本发布)。

预览版

每周二 UTC 23:59 发布新的预览版。这些版本未经全面验证，可能包含退化或其他未解决的问题。请帮助我们测试，并使用 preview 标签安装。

npm install -g @google/gemini-cli@preview

稳定版

• 每周二 UTC 20:00 发布新的稳定版，即上周 preview 版本的完整升级，包含所有 Bug 修复和验证。使用 latest 标签。

npm install -g @google/gemini-cli@latest

每夜版

• 每天 UTC 00:00 发布新版本，包含截至发布时 main 分支上的所有变更。应假定存在待处理的验证和问题。使用 nightly 标签。

npm install -g @google/gemini-cli@nightly

📋 主要功能

代码理解与生成

• 查询和编辑大型代码库
• 利用多模态能力从 PDF、图片或草稿生成新应用
• 调试问题并使用自然语言排查故障

自动化与集成

• 自动化运维任务，如查询拉取请求或处理复杂的变基操作
• 使用 MCP 服务器连接新能力，包括 使用 Imagen、Veo 或 Lyria 生成媒体)
• 以非交互模式在脚本中运行，实现工作流自动化

高级能力

• 使用内置的 Google 搜索)为查询提供实时信息验证
• 对话检查点功能，可保存和恢复复杂会话
• 自定义上下文文件（GEMINI.md），为项目定制行为

GitHub 集成

通过 Gemini CLI GitHub Action:) 将 Gemini CLI 直接集成到您的 GitHub 工作流中

• 拉取请求审查：基于上下文的自动化代码审查，提供反馈和建议
• 问题分类：基于内容分析自动对 GitHub Issue 进行标注和优先级排序
• 按需协助：在 Issue 和拉取请求中提及 @gemini-cli，获取调试、解释或任务委派方面的帮助
• 自定义工作流：构建自动化、定时和按需工作流，满足团队需求

🔐 身份验证选项

选择最适合您的身份验证方式：

选项 1：使用 Google 账号登录（OAuth 登录）

✨ 适合： 个人开发者以及拥有 Gemini Code Assist 许可证的用户（详见 配额限制与服务条款)）

优势：

• 免费使用额度：每分钟 60 次请求和每日 1,000 次请求
• Gemini 3 模型，附带 100 万 token 上下文窗口
• 无需管理 API 密钥——只需使用 Google 账号登录即可
• 自动更新至最新模型

启动 Gemini CLI，然后选择"使用 Google 账号登录"并按提示完成浏览器身份验证流程

gemini

如果您使用的是所在组织的付费 Code Assist 许可证，请记得设置 Google Cloud 项目

# Set your Google Cloud Project
export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
gemini

选项 2：Gemini API 密钥

✨ 适合： 需要特定模型控制或付费层级访问权限的开发者

优势：

• 免费使用额度：Gemini 3（Flash 和 Pro 混合）每日 1,000 次请求
• 模型选择：选择特定的 Gemini 模型
• 按用量计费：需要更高额度时升级

# Get your key from https://aistudio.google.com/apikey
export GEMINI_API_KEY="YOUR_API_KEY"
gemini

选项 3：Vertex AI

✨ 适合： 企业团队和生产环境工作负载

优势：

• 企业级特性：高级安全性和合规性
• 可扩展：使用结算账户获得更高的速率限制
• 集成：与现有 Google Cloud 基础设施协同工作

# Get your key from Google Cloud Console
export GOOGLE_API_KEY="YOUR_API_KEY"
export GOOGLE_GENAI_USE_VERTEXAI=true
gemini

关于 Google Workspace 账号和其他身份验证方式，请参阅 身份验证指南.)。

🚀 快速上手

基本用法

在当前目录启动

gemini

包含多个目录

gemini --include-directories ../lib,../docs

使用指定模型

gemini -m gemini-2.5-flash

脚本模式（非交互）

获取纯文本响应：

gemini -p "Explain the architecture of this codebase"

如需更高级的脚本操作（包括解析 JSON 和处理错误），请使用 --output-format json 标志获取结构化输出：

gemini -p "Explain the architecture of this codebase" --output-format json

如需实时事件流（适用于监控长时间运行的操作）， 使用 --output-format stream-json 获取换行符分隔的 JSON 事件：

gemini -p "Run tests and deploy" --output-format stream-json

快速示例

启动新项目

cd new-project/
gemini
> Write me a Discord bot that answers questions using a FAQ.md file I will provide

分析现有代码

git clone https://github.com/google-gemini/gemini-cli
cd gemini-cli
gemini
> Give me a summary of all of the changes that went in yesterday

📚 文档

快速入门

• 快速开始指南) — 快速上手。
• 认证设置) — 详细的身份验证配置。
• 配置指南) — 设置与自定义。
• 键盘快捷键) — 提高效率的小技巧。

核心功能

• 命令参考) — 所有斜杠命令（/help、/chat 等）。
• 自定义命令) — 创建你自己的可复用命令。
• 上下文文件 (GEMINI.md)) — 为 Gemini CLI 提供持久化上下文。
• 检查点) — 保存和恢复对话。
• 令牌缓存) — 优化令牌用量。

工具与扩展

• 内置工具概览)
  • 文件系统操作)
  • Shell 命令)
  • 网络抓取与搜索)
• MCP 服务器集成) — 通过自定义工具进行扩展。
• 自定义扩展) — 构建和分享你自己的命令。

高级主题

• 无头模式（脚本化）) — 在自动化工作流中使用 Gemini CLI。
• IDE 集成) — VS Code 配套工具。
• 沙箱与安全) — 安全的执行环境。
• 受信任文件夹) — 按文件夹控制执行策略。
• 企业指南) — 在企业环境中部署和管理。
• 遥测与监控) — 使用追踪。
• 工具参考) — 内置工具概览。
• 本地开发) — 本地开发工具。

故障排查与支持

• 故障排查指南) — 常见问题与解决方案。
• 常见问题) — 常见问题解答。
• 使用 /bug 命令直接从 CLI 报告问题。

使用 MCP 服务器

在 ~/.gemini/settings.json 中配置 MCP 服务器，以通过自定义工具扩展 Gemini CLI：

> @github List my open pull requests
> @slack Send a summary of today's commits to #dev channel
> @database Run a query to find inactive users

有关设置说明，请参阅 MCP 服务器集成指南)。

🤝 贡献

欢迎贡献！Gemini CLI 是完全开源的（Apache 2.0），我们鼓励社区：

• 报告 Bug 和提出功能建议。
• 改进文档。
• 提交代码改进。
• 分享你的 MCP 服务器和扩展。

请参阅我们的贡献指南，了解开发环境搭建、编码标准以及如何提交 Pull Request。

查看我们的官方路线图)，了解计划中的功能和优先级。

📖 资源

• 免费课程)** — 学习基础知识。
• 官方路线图 — 查看下一步计划。
• 更新日志)** — 查看近期重要更新。
• NPM 包)** — 包注册表。
• GitHub Issues)** — 报告 Bug 或请求功能。
• 安全公告)** — 安全更新。

卸载

请参阅卸载指南)了解移除步骤。

📄 法律信息

• 许可证：Apache License 2.0
• 服务条款：条款与隐私)
• 安全：安全策略

---

由 Google 与开源社区 ❤️ 共同构建