Gemini CLI 使用指南

Gemini CLI 是 Google 官方开源的终端 AI agent，强调长上下文、内置搜索、脚本化调用和 MCP 扩展。它适合终端党，也适合需要把 AI 用进自动化脚本的人。

适合谁

• 想用 Google 官方工具链
• 需要长上下文分析大型仓库
• 需要非交互模式、脚本化输出或 MCP 扩展

官方系统要求

根据官方 GitHub README，安装前建议满足：

• macOS / Linux / Windows
• Node.js 20+

安装

macOS

方案 A：直接运行，不安装

npx https://github.com/google-gemini/gemini-cli

方案 B：npm 全局安装

npm install -g @google/gemini-cli

方案 C：Homebrew

brew install gemini-cli

Linux

npm install -g @google/gemini-cli

或：

brew install gemini-cli

Windows

npm install -g @google/gemini-cli

如果你只是想先试用，也可以直接用 npx 启动，不必先全局安装。

安装后检查

gemini --version
gemini --help

接入 Flash API

Gemini CLI 可以通过 ~/.gemini/.env 和 settings.json 改用 Flash API。

你需要准备

• 已安装 Gemini CLI
• 一个可用的 Flash API Key
• 如果后台区分令牌组，优先创建 Gemini 对应的 Key

Flash API 地址

https://ai.flashapi.top

配置目录

macOS / Linux

mkdir -p ~/.gemini

Windows

mkdir %USERPROFILE%\.gemini

创建 .env

GOOGLE_GEMINI_BASE_URL=https://ai.flashapi.top
GEMINI_API_KEY=你的Flash API Key
GEMINI_MODEL=gemini-2.5-pro

创建 settings.json

{
  "ide": {
    "enabled": true
  },
  "security": {
    "auth": {
      "selectedType": "gemini-api-key"
    }
  }
}

启动

gemini

如果 .env 和 settings.json 都写对了，Gemini CLI 会优先走你配置的 Key 和地址。

基本使用

交互模式

gemini

单次提问

gemini -p "Explain the architecture of this repository"

结构化输出

gemini -p "Summarize this repo" --output-format json

指定模型

gemini -m gemini-2.5-flash

同时包含多个目录

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

可选：用 CC-Switch 管理 Gemini 配置

如果你已经安装了 CC-Switch，也可以直接在 Gemini 标签页里填写：

• Base URL：https://ai.flashapi.top
• API Key：你的 Flash API Key
• Model：如 gemini-2.5-pro

这样会比手改 ~/.gemini 更方便。

macOS / Windows / Linux 的差异建议

macOS

• 用 Homebrew 或 npm 都很方便。
• 如果你主要在本机做开发，体验通常比较直接。

Windows

• 官方支持原生 Windows。
• 但如果你的日常开发本来就在 WSL 中，建议直接在 WSL 里统一运行，避免路径和权限来回切换。

Linux

• 适合服务器、CI 和自动化场景。
• 如果你主要是非交互脚本调用，Linux 环境通常最省心。

常用场景

读仓库

请先总结这个仓库的目录结构、依赖关系和构建流程，不要修改文件。

让它生成可机读结果

如果你打算把输出接进脚本或 CI，优先使用：

gemini -p "List all packages in this repo" --output-format json

使用项目级上下文文件

Gemini CLI 支持 GEMINI.md，适合把项目约定、测试命令、代码规范写进去，减少重复解释。

常见问题

配置完仍然弹 Google 登录

先检查：

• ~/.gemini/.env 是否真的存在
• GEMINI_API_KEY 是否写对
• GOOGLE_GEMINI_BASE_URL 是否指向 https://ai.flashapi.top
• settings.json 里认证类型是否为 gemini-api-key

官方链接

• 官方仓库：https://github.com/google-gemini/gemini-cli