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 即刻运行

# 使用 npx（无需安装）
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 安装

# 创建并激活新环境
conda create -y -n gemini_env -c conda-forge nodejs
conda activate gemini_env

# 在该环境中通过 npm 全局安装 Gemini CLI
npm install -g @google/gemini-cli

发布渠道

更多详情请参阅 发布记录。

预览版

每周二 UTC 时间 23:59 将发布新的预览版本。这些版本尚未经过全面测试，可能包含回归或其他未解决的问题。欢迎您帮助我们测试，并使用 preview 标签进行安装。

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

稳定版

• 每周二 UTC 时间 20:00 将发布新的稳定版本，这将是上周预览版的完整升级版本，同时包含所有修复和验证内容。请使用 latest 标签。

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

夜间版

• 每天 UTC 时间 00:00 将发布新的夜间版本。此版本包含了主分支在发布时刻的所有更改，但可能存在尚未完成的验证和问题。请使用 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 问题进行标记和优先级排序
• 按需协助：在问题和拉取请求中提及 @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 项目。

# 设置您的 Google Cloud 项目
export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
gemini

选项 2：Gemini API 密钥

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

优势：

• 免费层级：每天 1,000 次请求，使用 Gemini 3 模型（混合 flash 和 pro 版本）
• 模型选择：可以选择特定的 Gemini 模型
• 按用量计费：当需要更高限额时可进行升级

# 从 https://aistudio.google.com/apikey 获取您的密钥
export GEMINI_API_KEY="YOUR_API_KEY"
gemini

选项 3：Vertex AI

✨ 适用人群：企业团队和生产工作负载

优势：

• 企业级特性：高级安全性和合规性
• 可扩展性：通过计费账户可获得更高的速率限制
• 集成性：可与现有的 Google Cloud 基础设施无缝对接

# 从 Google Cloud 控制台获取您的密钥
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 "解释这个代码库的架构"

对于更高级的脚本编写，包括如何解析 JSON 和处理错误，请使用 --output-format json 标志来获取结构化输出：

gemini -p "解释这个代码库的架构" --output-format json

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

gemini -p "运行测试并部署" --output-format stream-json

快速示例

开始一个新项目

cd new-project/
gemini
> 写一个 Discord 机器人，使用我提供的 FAQ.md 文件回答问题

分析现有代码

git clone https://github.com/google-gemini/gemini-cli
cd gemini-cli
gemini
> 给我总结一下昨天的所有更改

📚 文档

入门

• 快速入门指南 - 快速上手。
• 认证设置 - 详细的认证配置。
• 配置指南 - 设置与自定义。
• 快捷键 - 提高效率的小技巧。

核心功能

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

工具与扩展

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

进阶主题

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

故障排除与支持

• 故障排除指南 - 常见问题及解决方案。
• 常见问题解答 - 常见问题。
• 使用 /bug 命令可以直接从 CLI 报告问题。

使用 MCP 服务器

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

> @github 列出我的未合并拉取请求
> @slack 将今天的提交摘要发送到 #dev 频道
> @database 执行查询以查找不活跃用户

请参阅 MCP 服务器集成指南 以获取设置说明。

🤝 贡献

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

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

请参阅我们的 贡献指南 了解开发设置、编码规范以及如何提交拉取请求。

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

📖 资源

• 官方路线图 - 查看接下来的计划。
• 变更日志 - 查看最近的重要更新。
• NPM 包 - 包注册表。
• GitHub 问题 - 报告 bug 或请求功能。
• 安全公告 - 安全更新。

卸载

请参阅 卸载指南 以获取移除说明。

📄 法律声明

• 许可证: Apache 许可证 2.0
• 服务条款: 条款与隐私
• 安全: 安全政策

---

由 Google 和开源社区用心打造

Gemini CLI 快速上手指南

Gemini CLI 是一款开源的 AI 命令行工具，让您直接在终端中调用强大的 Gemini 模型，进行代码理解、生成、调试及自动化任务。

环境准备

在开始之前，请确保您的系统满足以下基本要求：

• 操作系统：支持 macOS、Linux 或 Windows（需配置相应终端环境）。
• 前置依赖：
  • Node.js：推荐安装最新 LTS 版本（用于 npm/npx 安装方式）。
  • 包管理器（可选）：
    • macOS/Linux: npm 或 Homebrew
    • macOS: MacPorts
    • 受限环境：Anaconda (需包含 nodejs)
• 网络环境：由于服务由 Google 提供，中国大陆用户可能需要配置网络代理才能正常连接 API 或使用 OAuth 登录。

安装步骤

您可以根据习惯选择以下任意一种方式进行安装：

方式一：免安装运行（推荐尝试）

无需全局安装，直接使用 npx 运行：

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 环境（适用于受限环境）

# 创建并激活新环境
conda create -y -n gemini_env -c conda-forge nodejs
conda activate gemini_env

# 在环境中全局安装
npm install -g @google/gemini-cli

提示：如需体验最新预览版或每日构建版，可在上述 npm 命令后添加 @preview 或 @nightly 标签。

基本使用

1. 认证登录

启动工具后，首选通过 Google 账号登录（免费额度：60 次/分钟，1000 次/天）：

gemini

启动后选择 Sign in with Google，按提示在浏览器完成授权即可。

替代方案：使用 API Key 如果您更倾向于使用 API Key，请先设置环境变量：

export GEMINI_API_KEY="YOUR_API_KEY"
gemini

2. 交互式对话

进入当前目录并启动交互模式，可直接询问代码库或请求生成代码：

cd your-project-folder
gemini

示例对话：

> Write me a Discord bot that answers questions using a FAQ.md file I will provide
> Give me a summary of all of the changes that went in yesterday

3. 指定目录与模型

您可以包含多个目录或使用特定模型版本：

# 包含多个目录
gemini --include-directories ../lib,../docs

# 指定模型
gemini -m gemini-2.5-flash

4. 脚本化与非交互模式

在 Shell 脚本中直接获取结果，支持纯文本或 JSON 格式输出：

# 获取纯文本回答
gemini -p "Explain the architecture of this codebase"

# 获取结构化 JSON 输出（便于程序解析）
gemini -p "Explain the architecture of this codebase" --output-format json

# 实时事件流输出（适合监控长任务）
gemini -p "Run tests and deploy" --output-format stream-json