Headless mode

Headless mode 是 Gemini CLI 的程序化入口。它不会打开交互式终端 UI，而是执行一次任务并把结果输出到标准输出。

触发方式

两种常见触发方式：

gemini -p "Explain this error"
gemini --prompt "Write a commit message"

或在非 TTY 环境中运行，例如管道、重定向、CI。

如果没有 -p 且没有 pipe / redirect，Gemini CLI 会进入交互 UI。自动化脚本应显式使用 -p 或 --prompt，避免 CI 因为等待交互输入卡住。

官方还支持 --prompt-interactive 这类混合入口，但生产脚本不要依赖交互追问。能一次性给出输入、上下文、输出格式和失败策略，脚本才可复现。

输出格式

默认输出普通文本。需要给脚本消费时，使用结构化输出：

gemini --output-format json -p "Summarize @package.json"

JSON 模式通常包含：

• response：最终回答。
• stats：token 与延迟统计。
• error：失败时的错误信息。

Streaming JSON 输出适合长期任务或实时消费事件，事件可能包括初始化、消息片段、工具调用、工具结果、错误和最终结果。

脚本消费 JSON 时，要用真正的 JSON parser，不要用 grep 或字符串切分。模型输出和错误字段都可能包含换行、引号和代码块。

退出码

0   成功
1   通用错误或 API 失败
42  输入错误
53  turn limit exceeded

脚本里不要只读 stdout。必须同时处理退出码和 stderr；response 为空但退出码为 0、或者模型返回了不可解析结构，都要算失败分支。

什么时候用

• CI 里自动总结 diff。
• 批量处理日志。
• 为内部工具包一层 AI wrapper。
• 生成结构化 JSON 后交给 jq 或后续脚本。

生产脚本注意

• prompt 要固定，不要依赖交互追问。
• 输入先限流和过滤，避免把大文件、密钥、二进制文件塞进上下文。
• 需要 JSON 时使用 --output-format json，再用 jq 或语言内 JSON parser 校验。
• 对 429、网络错误、turn limit exceeded 做重试或失败记录。
• 批量任务写入文件时先写临时文件，校验后再替换正式文件。

验收方式

用成功样例、无效输入、超长输入、API 失败四种情况跑脚本。确认退出码、JSON 解析、空输出处理和日志记录都符合预期，再接入 CI。

脚本里建议把失败分成三类记录：输入不合法、模型或网络失败、输出不符合 schema。三类失败的重试策略不同，不要统一写成“再跑一次”。

CI 中还要设置超时。

失败日志要可追溯。 方便复查。

还要记录输入摘要和模型信息。否则同一个 headless 脚本在配额、fallback 或模型选择变化后，失败很难复现。

上线前检查

上线前至少跑三种输入：正常输入、空输入、超长输入。再模拟一次非零退出和一次 JSON 解析失败。脚本能稳定处理这五类情况，才适合放进 CI 或定时任务。

失败分支要写入日志，且保留输入摘要、任务编号和退出码。

接下来去哪

官方来源

• Gemini CLI headless mode
• Gemini CLI automation tutorial