Gemini CLI 终端编程指南

Gemini CLI 终端编程指南

Gemini CLI 是 Google 官方开源的终端 AI Agent（Apache-2.0 协议）。它把 Gemini 2.5 系列模型的能力直接接入终端：可以读写文件、执行 Shell 命令、用 Google 搜索接地获取实时信息、抓取网页，并通过 MCP 协议扩展自定义工具。

Gemini CLI 本身就是「终端工具」，用 gemini 命令启动；本教程聚焦于如何安装它，并接入合适的 Google AI 模型后端（个人 Google 账号 OAuth、Gemini API Key、或 Vertex AI）。

前置准备

1. 获取 Google 凭据

Gemini CLI 支持三种认证方式，按账号类型选择：

2. 系统要求

支持的系统： macOS（Apple Silicon / Intel）、Linux、Windows（推荐 WSL2）。

分步安装指南

方式一：npx 即跑（无需安装）

1# 直接运行，不污染全局
2npx @google/gemini-cli

方式二：npm 全局安装（推荐）

1# 全局安装
2npm install -g @google/gemini-cli
3
4# 升级到最新稳定版（每周二 UTC 20:00 发布）
5npm install -g @google/gemini-cli@latest
6
7# 验证安装
8gemini --version

中国大陆用户（使用 npm 镜像加速）：

1npm config set registry https://registry.npmmirror.com
2npm install -g @google/gemini-cli

方式三：Homebrew（macOS / Linux）

1brew install gemini-cli

方式四：MacPorts（macOS）

1sudo port install gemini-cli

方式五：Anaconda（受限环境）

1# 创建带 Node.js 的隔离环境
2conda create -y -n gemini_env -c conda-forge nodejs
3conda activate gemini_env
4
5# 在环境内全局安装
6npm install -g @google/gemini-cli

发布通道说明

1# 安装 preview 版体验新特性
2npm install -g @google/gemini-cli@preview

配置认证与 API Key

方法一：Sign in with Google（推荐）

1# 启动 CLI
2gemini

首次启动会弹出选择认证方式的菜单，选择 Sign in with Google，浏览器自动打开完成 OAuth 授权。凭据缓存到本地，后续会话无需重复登录。

何时需要关联 Google Cloud 项目：

• 企业、学校、Google Workspace 账号
• 使用 Gemini Code Assist 订阅授权

个人 Google 账号（免费层 + Google AI Pro/Ultra 订阅）通常无需配置项目。

方法二：Gemini API Key

从 Google AI Studio 获取 API Key 后，设置环境变量：

1# 临时设置
2export GEMINI_API_KEY="your-gemini-api-key"
3
4# 持久化（zsh）
5echo 'export GEMINI_API_KEY="your-gemini-api-key"' >> ~/.zshrc
6source ~/.zshrc

1# Windows PowerShell 临时设置
2$env:GEMINI_API_KEY = "your-gemini-api-key"
3
4# 永久设置（用户级环境变量）
5[System.Environment]::SetEnvironmentVariable("GEMINI_API_KEY", "your-gemini-api-key", "User")

设置后启动 CLI，会自动识别并使用 API Key 认证。

方法三：Vertex AI（企业）

适合已使用 Google Cloud 的组织。配置环境变量：

1export GOOGLE_CLOUD_PROJECT="your-project-id"
2export GOOGLE_CLOUD_LOCATION="us-central1"
3export GOOGLE_GENAI_USE_VERTEXAI=true
4export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account-key.json"

并在 ~/.gemini/settings.json 中将 selectedType 设为 vertex-ai。

配置文件：settings.json

Gemini CLI 的配置文件分层加载：

settings.json 示例：

1{
2  "selectedType": "oauth-personal",
3  "model": "gemini-2.5-pro"
4}

快速开始

1. 进入项目目录

1cd /path/to/your/project

2. 启动 TUI 交互界面

1gemini

3. 非交互模式（适合脚本）

1# 一次性提问
2gemini -p "解释这个仓库的入口文件是做什么的"
3
4# 管道传入
5cat README.md | gemini -p "总结这个文档的核心要点"

4. TUI 内常用斜杠命令

核心功能与使用模式

内置工具能力

多模态能力

• 从 PDF、图片、草图生成新应用
• 粘贴截图让模型理解 UI 并据此实现功能
• 支持长达 1M token 的上下文窗口

对话检查点

支持会话检查点（checkpointing），可保存复杂会话状态并在之后恢复，适合长周期工程任务。

配置文件与 GEMINI.md

项目级配置：GEMINI.md

在项目根目录创建 GEMINI.md，写入技术栈、编码规范、项目约定、关键文件说明等，Gemini CLI 会自动加载作为每次对话的上下文，让回答贴合项目实际。建议提交到 Git。

扩展能力：MCP 服务器

Gemini CLI 支持通过 MCP（Model Context Protocol）扩展工具能力，例如接入媒体生成（Imagen / Veo / Lyria）、Cloud Run、自定义数据源等。

GitHub Action 集成

通过 Gemini CLI GitHub Action，可在工作流中实现：

• PR 自动代码评审
• Issue 自动分类与打标
• 在 Issue / PR 中 @gemini-cli 召唤辅助

场景应用示例

场景一：代码库理解与导航

1你：How is authentication handled in @packages/auth/login.ts
2
3Gemini CLI 会：
41. 用 @ 模糊搜索定位文件
52. 读取并分析认证逻辑
63. 解释关键函数与数据流

场景二：用 Google 搜索接地回答实时问题

1你：最新的 React 19 suspense API 有哪些变化？给出官方文档链接
2
3Gemini CLI 会：
41. 触发 Google 搜索接地
52. 汇总实时搜索结果
63. 附上官方文档引用链接

场景三：自动化工程任务

1你：跑一下测试，把失败的用例修复
2
3Gemini CLI 会：
41. 执行测试命令
52. 分析失败原因
63. 编辑源码修复
74. 重跑验证

最佳实践

安全建议

1. OAuth 优先于 API Key：本地开发用 Google 账号登录，凭据由系统管理
2. .gemini/ 加入 .gitignore：避免本地配置与凭据泄露
3. CI/CD 用 API Key：通过环境变量注入，并设置最小权限
4. Vertex AI 用服务账号：通过 IAM 严格控制权限范围

性能优化

1. 合理选模型：日常问答用 Gemini 2.5 Flash，复杂推理用 Gemini 2.5 Pro
2. 善用检查点：长任务中途保存，避免上下文丢失后从头重来
3. 非交互模式批量处理：用 -p 标志把 CLI 嵌入自动化脚本

故障排查

1# 查看当前用量
2# 在 TUI 内执行：
3/stats

扩展与进阶

官方资源

• 🌐 官网：geminicli.com
• 📖 官方文档：GitHub Docs
• 💻 GitHub 仓库：github.com/google-gemini/gemini-cli
• 🔑 获取 API Key：Google AI Studio
• 📦 npm 包：@google/gemini-cli
• 🚀 GitHub Action：google-github-actions/run-gemini-cli

进阶玩法

• 多模态生成：通过 MCP 接入 Imagen / Veo / Lyria 实现文生图 / 文生视频 / 文生音乐
• 工作流自动化：用非交互模式处理 PR 评审、Issue 分类、复杂 rebase
• 自定义扩展：浏览 扩展库 安装社区扩展

总结

Gemini CLI 把 Google 最新的 Gemini 2.5 系列模型与 1M token 上下文窗口直接带进终端，并原生集成 Google 搜索接地、文件操作、Shell 执行与 MCP 扩展。个人账号还能享受每天 1000 次的免费额度。

无论是代码理解、实时信息查询，还是自动化工程任务，Gemini CLI 都能成为你终端里的得力 Google AI 编程 Agent。立即安装，把 Gemini 接入你的命令行工作流吧！