如何解析 Gemini CLI 无头模式 -p 的 JSON 输出与退出码

如何解析 Gemini CLI 无头模式 -p 的 JSON 输出与退出码

【免费下载链接】gemini-cliAn open-source AI agent that brings the power of Gemini directly into your terminal.项目地址: https://gitcode.com/GitHub_Trending/gemi/gemini-cli

把 Gemini CLI 的模型回答接入脚本、CI 任务或其他工具时，直接读取文本输出很难做可靠判断。无头模式（headless mode）解决的就是这个问题：用-p发起一次查询，通过--output-format json得到结构化的单个 JSON 对象，再用标准 shell 退出码判断本次执行是成功、失败还是参数有误。本文覆盖从触发无头模式、解析 JSON 字段到检查退出码的完整路径，前提是你已经安装并完成了 Gemini CLI 的认证（参见 无头模式教程的前置条件）。

触发无头模式并选择 JSON 输出

无头模式在两种情况下被触发：CLI 运行在非 TTY 环境，或者命令行中带-p（--prompt）标志。-p会绕过交互界面，把结果打印到 stdout 并立即退出：

gemini -p "Write a poem about TypeScript"

--output-format标志（别名-o）控制输出格式，默认值是text，可选值为text、json、stream-json。要拿到可直接被jq等工具处理的纯 JSON，需要显式指定json：

gemini --output-format json -p "Return a raw JSON object with keys 'version' and 'deps' from @package.json"

完整标志列表见 CLI 参考，JSON 结构细节见 Headless 模式参考。

JSON 输出包含哪些字段

--output-format json返回一个 JSON 对象，包含模型响应和用量统计，字段结构如下：

[stats]: 文档原文写作stats。

脚本中最常用的是response字段，它承载模型的回答正文。error只在请求失败时出现，可以在脚本里用它的存在与否作为失败信号之一。

用 jq 解析 response 字段（macOS/Linux）

自动化教程给出的标准做法是：--output-format json的输出管道给jq，用-r取出.response字段并写入文件。下面是文档中的完整示例脚本，保存为generate_json.sh：

#!/bin/bash # Ensure we are in a project root if [ ! -f "package.json" ]; then echo "Error: package.json not found." exit 1 fi # Extract data gemini --output-format json "Return a raw JSON object with keys 'version' and 'deps' from @package.json" | jq -r '.response' > data.json

注意这条命令的两个前置条件：一是它假定当前目录存在package.json（脚本开头会检查并exit 1），二是jq需要已安装。chmod +x generate_json.sh后运行./generate_json.sh，再打开data.json核对内容。文档给出的示例文件内容如下，仅作为"文档示例"展示字段形态，实际运行得到的值会因你的package.json不同而变化：

{ "version": "1.0.0", "deps": { "react": "^18.2.0" } }

Windows（PowerShell）替代路径

PowerShell 下可以不依赖jq，用ConvertFrom-Json解析同一个 JSON 对象：

$output = gemini --output-format json "Return a raw JSON object with keys 'version' and 'deps' from @package.json" | ConvertFrom-Json $output.response | Out-File -FilePath data.json -Encoding utf8

两种平台最终都是取出 JSON 对象的response字段，区别只在于解析工具。

检查退出码判断执行结果

无头执行结束时，CLI 返回固定的退出码来表示结果。脚本中可以用 shell 标准的退出码变量（如 Bash 的$?）捕获它，再按下表分支：

退出码和 JSON 里的error字段是两个互补的判断来源：error携带具体错误详情，退出码则让脚本能直接决定后续流程是否继续。例如退出码为42说明问题出在你传给 CLI 的 prompt 或参数上，而不是 API 侧；为1时则应同时查看 JSON 中的error对象定位原因。

可选分支：stream-json 流式事件

如果脚本需要实时观察执行过程（比如 CI 中边跑边输出进度），可以把--output-format设为stream-json。它输出换行分隔的 JSON（JSONL）事件流，每行一个事件，事件类型包括：

• init：会话元数据（session ID、模型）
• message：用户与助手消息块
• tool_use：带参数的工具调用请求
• tool_result：已执行工具的输出
• error：非致命警告与系统错误
• result：最终结果，含聚合统计和按模型划分的 Token 用量

与json的单个对象不同，stream-json下最后一行的result事件才携带最终结果与统计，需要逐行解析。对"跑完一次拿结果"的场景，json更简单，优先选它。

限制与下一步

• -p是强制无头执行的方式；不带该标志的位置参数在 TTY 下默认进入交互模式，除非输入或输出被管道/重定向。
• JSON 模式只对非交互模式生效，stats记录的是本次执行的 Token 用量与 API 延迟指标，不要把示例中的数值当成固定预期。
• 退出码53对应轮次上限被触发，说明任务在达到最大轮次前未完成，需要调整 prompt 或任务规模，这属于任务本身的问题而非解析问题。

进一步阅读：Headless 模式参考 与 自动化教程 中还包含管道输入、批量生成脚本和自定义命令别名（如gcommit包装git commit）的完整示例，都可以在本文的 JSON 解析与退出码判断基础上直接套用。

【免费下载链接】gemini-cliAn open-source AI agent that brings the power of Gemini directly into your terminal.项目地址: https://gitcode.com/GitHub_Trending/gemi/gemini-cli