无头模式与自动化

无头模式提供 Gemini CLI 的编程接口，返回结构化文本或 JSON 输出，没有交互式终端界面。它在 CLI 于非 TTY 环境里运行，或用 -p（--prompt）标志提供查询时触发。例如 gemini -p "总结这个仓库的目录结构"，也可以把内容管道给 gemini。无头模式使用你已有的认证方式；还没认证过时，要用环境变量配置 Gemini API Key 或 Vertex AI（见「认证」页）。

输出格式

用 --output-format（-o）标志指定输出格式：text（默认）、json、stream-json。

JSON 输出：返回一个包含回复和用量统计的 JSON 对象：response（字符串，模型的最终回答）、stats（对象，token 用量和 API 延迟指标）、error（对象，可选，请求失败时的错误详情）。

流式 JSON 输出：返回换行分隔的 JSON（JSONL）事件流，事件类型：init（会话元数据，如会话 ID、模型）、message（用户和助手的消息块）、tool_use（带参数的工具调用请求）、tool_result（已执行工具的输出）、error（非致命的警告和系统错误）、result（带聚合统计和按模型 token 用量明细的最终结果）。

退出码

CLI 返回标准退出码指示无头执行的结果：0 成功；1 一般错误或 API 失败；42 输入错误（无效的提示词或参数）；53 超出回合限制。

在 CI 里的注意事项

官方排障页指出：如果设置了名字以 CI_ 开头的环境变量（如 CI_TOKEN），Gemini CLI 不会进入交互模式（底层 UI 框架使用的 is-in-ci 包会检测 CI、CONTINUOUS_INTEGRATION 或任何 CI_ 前缀的环境变量，并假定是非交互的 CI 环境）；如果这个变量对 CLI 运行不需要，可以对该命令临时取消设置，例如 env -u CI_TOKEN gemini。官方还有「自动化任务」教程，给出实用的脚本示例。