0 前言

折腾 Gemini 的命令行工具 (CLI) 时，会发现官方工具的路径和想当然的有出入。不少人以为是 Node.js 应用，结果踩了坑。这篇文档记录一下正确的安装配置流程，避免走弯路。

1 环境准备

官方的 Gemini CLI 是用 Go 语言写的，并依赖 Google Cloud SDK 进行认证和配置。所以，准备工作是安装这两个核心依赖。

1.1 安装 Go (1.21+)

需要 Go 的编译器和工具链来安装 CLI。

• Linux (Debian/Ubuntu):
  bash sudo apt update sudo apt install golang-go
• macOS (Homebrew):
  bash brew install go
• 其他系统: 参考 Go 官网下载页面。

安装后，通过 go version 确认版本不低于 1.21。

1.2 安装与初始化 gcloud

Google Cloud SDK (gcloud) 是与 Google Cloud 交互的基础，负责身份认证和项目配置。

• 安装: 访问 Google Cloud SDK 官方文档，按照指引安装。通常是一个安装脚本。
• 初始化: 安装后，运行 gcloud init，根据提示登录你的 Google 账号并选择一个默认项目。

2 安装与配置

环境就绪后，通过以下四步完成 CLI 的安装和配置。这是一个连续的过程。

2.1 安装 CLI

官方推荐使用 go install 命令。它会自动下载源码、编译并把可执行文件放到 Go 的二进制路径下 ($GOPATH/bin)。

go install github.com/google-gemini/gemini-cli/cmd/gemini@latest

安装后，确保你的 $GOPATH/bin 路径（通常是 $HOME/go/bin）已经添加到了系统的 PATH 环境变量中。

2.2 本地认证

Gemini CLI 使用 gcloud 的应用默认凭据 (Application Default Credentials, ADC) 进行认证。运行以下命令，浏览器会自动打开登录页面，完成授权即可。

gcloud auth application-default login

2.3 关联云端项目

你需要告诉 gcloud 当前工作的项目是哪一个。Gemini CLI 会自动使用这个配置。

gcloud config set project YOUR_PROJECT_ID

将 YOUR_PROJECT_ID 替换为你的项目 ID。

2.4 启用 API

这是最容易出错的一步。如果直接运行 gemini 命令，很可能会遇到 API has not been used... or it is disabled 的错误。这是因为 cloudaicompanion.googleapis.com 服务没有启用。

• 解决方法: 访问以下链接（将 YOUR_PROJECT_ID 替换为你的项目 ID），在打开的页面中点击 “启用” (Enable) 按钮，并等待几分钟让配置生效。
  https://console.developers.google.com/apis/api/cloudaicompanion.googleapis.com/overview?project=YOUR_PROJECT_ID

3 使用与进阶

完成以上所有步骤后，就可以正常使用 Gemini CLI 了。

3.1 基本用法

• 文本提问:
  bash gemini "写一个 Golang 的 Hello World 程序"
• 多模态提问 (带图片):
  bash gemini "这张图里有什么？" -m path/to/your/image.jpg

3.2 多项目管理

gcloud 的配置是按用户隔离的，可以轻松切换。当你需要为另一个项目工作时，只需再次运行 gcloud config set project ANOTHER_PROJECT_ID 即可切换上下文。这比管理环境变量或 settings.json 文件更标准、更方便。

4 总结与排错

• 总结:
  1. 官方 Gemini CLI 是 Go 应用，不要用 npm 安装。
  2. 核心依赖是 Go 语言环境和 Google Cloud SDK。
  3. 认证和项目配置通过 gcloud 命令完成。
  4. 使用前，务必在对应的 Google Cloud 项目中启用 cloudaicompanion.googleapis.com API。
• 排错:
  如果在配置完成后遇到任何连接或权限问题，首先运行诊断命令：
  bash gemini check
  它会告诉你问题出在哪里。