gemini-api-cli

gemini-api CLI 将每个 Gemini API 资源都作为 shell 子命令公开。与 curl 相比：媒体和转录命令会将输出解码到磁盘，并且只打印文件路径；-i 可附加本地文件或 files/<id> URI；--jq 可在进程内提取字段（默认输出原始字符串，无需外部 jq）；--dry-run 可离线预览已脱敏的 HTTP 请求；列表端点会通过 --all 自动分页（使用 --max-pages N 限制页数；--page-size 设置服务器端的页面大小）。

CLI 与 SDK

CLI 用于 shell 操作，SDK 用于应用代码。 在终端、脚本和 CI 任务中使用 gemini-api 来生成媒体文件、分析本地 PDF 或录音、运行 Deep Research，以及管理 Agent 沙盒（gemini-api 是无状态的 Gemini API 客户端，与交互式的 @google/gemini-cli 编码 Agent 不同）。当调用位于应用源代码中，或需要双向 Live API WebSocket 时，请使用 Google GenAI SDK（gemini-api-dev、gemini-live-api-dev）。

安装和身份验证

# macOS / Linux (set GEMINI_VERSION=<tag> to pin a release)
curl -fsSL https://raw.githubusercontent.com/google-gemini/gemini-api-cli/main/scripts/install.sh | bash

凭据按以下顺序解析（匹配到第一个即停止）：--api-key / --access-token 标志、GEMINI_API_KEY / GEMINI_ACCESS_TOKEN 环境变量、操作系统密钥链，然后是 ~/.config/gemini-api/config.yaml。

• 环境变量（Agent 和 CI）：export GEMINI_API_KEY="..."
• 工作站密钥：gemini-api configure --api-key "..." 会将密钥保存到操作系统密钥链。在无头 Linux 上，传入 --no-keyring 或设置 GEMINI_NO_KEYRING=1 以使用 config.yaml；gemini-api auth logout 会清除已存储的密钥。
• 当前身份验证状态：gemini-api whoami（添加 -o json 可输出 JSON）会打印已屏蔽的凭据和生效的凭据来源。

**身份验证的头号陷阱：**已导出的 GEMINI_API_KEY 会覆盖密钥链或 config.yaml 中存储的凭据，并会向该环境变量所属的项目计费。运行 gemini-api whoami 查看哪个来源生效，或运行 env -u GEMINI_API_KEY gemini-api ... 忽略该环境变量。

命令结构

gemini-api <intent> [prompt] [flags]          # task commands with model and modality presets
gemini-api <resource> <action> [flags]        # REST resource groups

运行 gemini-api --help 可列出命令，或运行 <subcommand> --help 查看标志和示例（--usage 会输出 45 KB 的 KDL 规范，因此请使用 --help 以节省上下文）。

命令	关键标志 / 操作	默认模型与行为
generate [prompt]	-m、-i、--stdin、--system、--previous-interaction-id、--stream=false、--body	gemini-3.8-flash；将文本增量流式输出到 stdout
image [prompt]	-m、-i、--aspect-ratio、--image-size（512..4K）、--previous-interaction-id、--out	gemini-nano-banana-2.1；写入图像并打印路径
tts [text]	-f、--stdin、--voice（默认 Kore）、--multi-speaker、--language、--out	gemini-3.8-flash-tts；写入 24 kHz WAV 并打印路径（不存储）
music [prompt]	-m、-f、--stdin、--out、--body	lyria-3.5；写入音轨并打印路径
video [prompt]	-m、-i、--aspect-ratio、--resolution（360p..4k）、--async、--resume、--out	gemini-omni-1.1-flash；轮询直至完成，写入 MP4 并打印路径
analyze [question]	-i（必需，可重复）、--stdin、--system、-m	gemini-3.8-flash；针对 PDF、媒体、CSV/文本和 YouTube URL 作答（不存储）
transcribe	-i（必需，可重复）、--format（md、text、json、srt）、--no-speakers、--no-timestamps、--out	gemini-3.8-flash；写入 --out（或 ./transcript-*），并打印路径（不存储）
agent	run、status、cancel、delete-interaction；create、list、get、delete	运行模型或托管 Agent；管理自定义 Agent 定义
files	upload [--wait]、list、get、generated-files-list、register、delete	上传可重复使用的 files/<id> URI（有效期 48h；最多 2 GB，PDF 最大 50 MB）
models	（不带参数）、list [--all]、get <id>	不带参数的 models 会打印离线目录；list 和 get 会查询实时 API
environments	create、list、get、delete、files、connect、poll、serve	远程沙盒和工作区快照（Agent 基础设施的 credentials、webhooks、triggers）

**模型选择：**使用 gemini-3.8-flash（默认）、gemini-4-argon（复杂推理和编码），或 gemini-3.5-flash-lite（高吞吐量）；图像任务可使用 gemini-nano-banana-2.1、gemini-3.1-flash-lite-image 或 gemini-3-pro-image。避免使用已弃用的 gemini-2.5-*、gemini-2.0-* 和 gemini-1.5-* 模型。

全局标志

标志	用途
-o、--output-format	pretty（默认）、json、toon、yaml、table
-q、--jq	使用内置 jq 表达式筛选 JSON 输出（默认启用 --raw-output）
--agent-mode	在 stdout 输出紧凑的 TOON，并在 stderr 输出结构化 JSON 错误
--no-interactive	禁用提示、TUI 表单和 explore
--dry-run	离线验证输入并预览已脱敏的 HTTP 请求（-o json 会输出 JSON）
-d、--debug	将 HTTP 请求和响应详细信息记录到 stderr

退出码：0 表示成功，1 表示运行时或 API 错误（包括运行失败或未完成），2 表示用法或验证错误，3 表示身份验证错误。运行 gemini-api --help-global 查看 --server-url、分页和身份验证标志。

输出

媒体命令（image、tts、music、video）和 transcribe 会在本地写入文件，并仅在 stdout 打印文件路径。添加 -o json 仍会写入文件，并打印 {path, mime_type, size_bytes, response_id, status}。

流式输出与 JSON 结构：generate 和 agent run 默认会流式输出纯回复文本，因此单独使用 -o json 会输出 NDJSON 事件。传入 --stream=false -o json 可输出单个 JSON 对象 {id, status, steps, usage}（单独使用 --stream=false 会打印元数据 YAML；--jq 或 --background 会自动禁用流式输出）。回复文本位于 .steps[] 的 model_output 下（参见下文的 agent status），而非 .candidates[]。对于分页的 list 命令，--jq 会针对每个分页封套运行（.models[]?.name、.agents[]?.id）。

输入

• -i / --input 可在 generate、image、video、analyze、transcribe 和 agent run 中附加媒体和文档（可重复使用）。接受大小不超过约 14 MB 的本地路径（base64 上限为 20 MB）、files/<id> URI 或 YouTube URL。对于较大或需要重复使用的文件，请使用 gemini-api files upload <path> --wait 上传一次。
• -f / --file 可在 tts 和 music 中从文件读取提示词文本。管道传入的文本需要使用 --stdin： 将纯文本通过管道传入 generate、image、video 或 analyze 时，请传入 --stdin，否则管道输入会被解析为 JSON --body。
• --body 可直接传入原始 Gemini API JSON、从 @file.json 读取，或通过 @- 传入（与标志合并；遇到重复键时以状态码 2 退出）。可用于 response_format 架构、tools（google_search、code_execution、url_context、函数声明）、generation_config、environment 或 store。
• 不要直接输出 --schema： 它会打印约 91 KB 的压缩 JSON，并在 --jq 运行前退出。请将其传入 jq：

  gemini-api generate --schema | jq '."$defs".ModelInteraction.properties | keys'
  

媒体、分析和转录

HERO=$(gemini-api image "Isometric cloud database icon" --aspect-ratio 16:9 --image-size 2K --out ./hero.jpg)
gemini-api image "Add warm sunset lighting" -i "$HERO" --out ./hero-sunset.jpg

gemini-api tts "Alice: Ready to ship? Bob: Checks are green." \
  --multi-speaker "Alice=Kore,Bob=Puck" --out ./dialogue.wav

VID_ID=$(gemini-api video "Aerial coastal cliffs at sunrise" --aspect-ratio 16:9 --resolution 1080p --async)
gemini-api video --resume "$VID_ID" --out ./cliffs.mp4

FILE_URI=$(gemini-api files upload ./call.mp4 --wait)   # prints files/<id>
gemini-api analyze -i "$FILE_URI" "List action items with owners and timestamps."
gemini-api transcribe -i "$FILE_URI" --format srt --out ./call.srt

托管 Agent 和沙盒

• deep-research-preview-04-2026 和 deep-research-max-preview-04-2026：使用 --background 运行，并通过 agent status 轮询。
• antigravity-preview-09-2026（带有 Bash、Python、Node、文件操作和网页搜索功能的 Linux 沙盒）：在 --body 中传入 environment（"remote"）或 environment_id。

ID 范围： agent status、agent cancel 和 agent delete-interaction 接受运行 ID（v1_...）。agent create、agent get、agent list 和 agent delete 仅管理自定义 Agent（内置 Agent 显示在 gemini-api models 中；使用 --page-size 10 限制 agent list 和 environments list 的结果）。

RUN_ID=$(gemini-api agent run "Compare WebRTC SFU architectures with primary sources." \
  --agent deep-research-preview-04-2026 --background --jq '.id')
gemini-api agent status "$RUN_ID" --jq '.status'   # queued | in_progress | completed | failed
gemini-api agent status "$RUN_ID" \
  --jq '[.steps[]? | select(.type=="model_output") | .content[]? | select(.type=="text") | .text] | join("")'

ENV_ID=$(gemini-api agent run "Benchmark radix sort vs timsort in Python and write results.csv." \
  --agent antigravity-preview-09-2026 --body '{"environment": "remote"}' --jq '.environment_id')
gemini-api environments files list -e "$ENV_ID" -r
gemini-api environments files download "$ENV_ID" results.csv --out ./results.csv

gemini-api agent create --id code-reviewer --base-agent antigravity-preview-09-2026 \
  --system-instruction "Review diffs for race conditions and auth bugs."

多轮对话和结构化输出

调用默认在服务端存储状态（store 为 true），因此多轮调用链只需使用 --previous-interaction-id（system_instruction、tools 和 generation_config 按轮应用；将 store 设为 false 会禁用 previous_interaction_id 和 background）：

TURN1=$(gemini-api generate "Propose 2 indexing strategies for time-series logs." --jq '.id')
gemini-api generate "Compare them for write-heavy workloads." --previous-interaction-id "$TURN1"

将 --stdin 与 --body 结合使用，以生成符合架构约束的 JSON 输出：

cat build.log | gemini-api generate "Extract unique compiler errors." --stdin --stream=false --body '{
  "response_format": {
    "type": "text", "mime_type": "application/json",
    "schema": {"type": "object", "properties": {"errors": {"type": "array", "items": {"type": "string"}}}, "required": ["errors"]}
  },
  "store": false
}'

完整 CLI 参考：aistudio.google.com/docs/cli.md；文档索引：llms.txt。