gemini-api 的安装脚本默认往 /usr/local/bin 放一个单文件 Go 二进制，不依赖 Node 或 Python 运行时。它是 Google 10 月 27 日放出的 beta 版 API 命令行，跟很多人 PATH 里早就有的 Gemini CLI（gemini）是两回事，定位几乎没有交集。
gemini-api 是干嘛的
官方发布说明 10 月 27 日那条的描述是：无状态、零依赖的命令行客户端，给 AI 编码助手、脚本和 CI 流水线用，底层走 Interactions API，能生成文本和媒体、分析文件、启动托管 Agent。
官方文档页里专门加了一条提示：gemini-api 是无状态的 API 客户端，不是 @google/gemini-cli 那种陪你写代码的交互式助手，任何编码 Agent 里都能调用它。
说白了，这东西是给 Codex、Claude Code 这类已经在干活的 Agent 多配一把工具，自己并不陪人聊天改代码。要张占位图、一段配音、读份 PDF，或者把 Deep Research 任务丢到后台，在 shell 里敲条命令就行。媒体文件直接写到磁盘，stdout 只吐路径，不会把 base64 塞满上下文。
「无状态」指本地不存会话。要接着上一轮聊，得显式传 --previous-interaction-id，或者复用上传后拿到的 files/ URI、后台任务的 interaction ID。
Gemini CLI 现在的处境
另一边，gemini-cli 仓库 README 开头那段说明可以看一眼。按 10 月的版本，Gemini CLI 现在主要服务买了 Code Assist Standard / Enterprise 授权（含 GitHub 版）的组织。免费个人用户和 Google AI Pro / Ultra 订阅者已在 6 月 18 日迁到 Antigravity CLI（agy）。README 还写明它没针对 Gemini 4 系列调优。
所以站里那篇 Gemini CLI 卡在 Waiting for auth 讲的是交互式工具的登录问题，跟这里的 gemini-api 不是一个东西，排查思路不通用。
自己整理的对照：
Gemini CLI（gemini） |
gemini-api |
|
|---|---|---|
| 形态 | 交互式终端编码 Agent | 一次一条命令的 API 客户端 |
| 本地状态 | 有会话 | 不存，靠 ID 串联 |
| 安装 | npm 包 @google/gemini-cli |
单个 Go 二进制 |
| 认证 | Code Assist 授权，兼容旧的付费 API / Vertex 密钥 | API Key（GEMINI_API_KEY） |
| 典型用户 | 坐在终端前的人 | 其他 Agent、脚本、CI |
| 阶段 | 面向企业持续维护 | beta |
如果只是坐在终端前让 AI 帮忙改代码，gemini-api 派不上用场。反过来，想让流水线每次构建时顺手生成一段发布说明配音，或者批量转写会议录像，交互式 CLI 又显得太重。两者放在同一台机器上并不冲突。
装和配
官方文档列的安装方式就这几种：
# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/google-gemini/gemini-api-cli/main/scripts/install.sh | bash
# 用 Go 装
go install github.com/google-gemini/gemini-api-cli/cmd/gemini-api@latest
Windows 用 PowerShell 跑仓库里的 install.ps1，也可以去 GitHub Releases 下预编译包。别想当然去 npm 上搜 gemini-api：那上面的同名包不是 Google 发的。官方列的渠道里同样没有 pip。
认证就是 API Key：
export GEMINI_API_KEY="YOUR_API_KEY"
gemini-api whoami
gemini-api generate "Confirm CLI setup in one sentence." --dry-run
自己电脑上可以用 gemini-api configure --api-key "YOUR_API_KEY" 存进系统钥匙串，加 --no-keyring 则落到 ~/.config/gemini-api/config.yaml。在 CI 里，文档建议从 secret 存储注入，别提交进仓库。
放进脚本和 CI 要留意的
--dry-run会校验参数、打印将要发出的 HTTP 请求，凭据打码，不联网。第一次用某个命令前先跑一遍挺省事。- 想拿结构化结果用
--output-format json（简写-o），也能配--jq直接取字段。generate和agent run默认流式输出，要单个 JSON 得加--stream=false。 --usage会把整棵命令树、参数和默认值按 KDL 格式打出来，gemini-api <command> --schema给出--body能接受的 JSON Schema，Agent 不必翻外部文档就能查到用法。再加上--agent-mode，报错会变成结构化 JSON 写进 stderr。- 退出码分得很清楚：0 成功，1 运行时或 API 错误，2 参数校验错，3 认证失败。脚本里按退出码分支比解析报错文字靠谱。
- 文档明说 beta 阶段哪怕小版本升级也可能带破坏性变更，CI 里最好锁死 release。安装脚本认
GEMINI_VERSION环境变量，Docker 镜像里则建议直接用 Releases 的归档包。 - 它只走普通 HTTP、SSE 和轮询，不支持双向 WebSocket，实时语音视频还是得用 SDK 接 Live API。
锁版本的写法，<release-tag> 换成 Releases 页上的具体 tag：
curl -fsSL https://raw.githubusercontent.com/google-gemini/gemini-api-cli/main/scripts/install.sh | GEMINI_VERSION=<release-tag> bash
你们会把 gemini-api 写进 AGENTS.md 让 Agent 自己挑命令，还是只在 CI 里跑几条固定的？