跳转到主要内容
将 --output-format 与 --print 搭配使用时，Cursor Agent CLI 提供多种输出格式。这些格式包括用于编程场景的结构化格式（json、stream-json），以及用于人类可读进度跟踪的简化文本格式。
--output-format 的默认值是 stream-json。该选项仅在打印（--print）时有效，或在推断为打印模式（非 TTY 的 stdout 或通过管道的 stdin）时有效。

​
JSON 格式

当运行成功完成时，json 输出格式会输出单个 JSON 对象（后跟换行符）。不会输出增量数据或工具事件；文本会汇总到最终结果中。 发生失败时，进程会以非零退出码结束，并将错误消息写到 stderr。失败情况下不会输出任何格式正确的 JSON 对象。

​
成功响应

成功时，CLI 会输出一个具有以下结构的 JSON 对象： 
{
  "type": "result",
  "subtype": "success",
  "is_error": false,
  "duration_ms": 1234,
  "duration_api_ms": 1234,
  "result": "<完整助手文本>",
  "session_id": "<uuid>",
  "request_id": "<可选请求ID>"
}
字段描述
type终端结果的取值始终为 "result"
subtype成功完成时的取值始终为 "success"
is_error成功响应时始终为 false
duration_ms总执行时长（毫秒）
duration_api_msAPI 请求时长（毫秒）（当前等同于 duration_ms）
result助手完整响应文本（将所有文本增量拼接而成）
session_id唯一会话 ID
request_id可选的请求 ID（可能省略）

​
流式 JSON 格式

stream-json 输出格式会产生以换行分隔的 JSON（NDJSON）。每一行都是一个 JSON 对象，表示执行过程中的实时事件。 成功时，流以终止的 result 事件结束。失败时，进程以非零退出码退出，流可能在未产生终止事件的情况下提前结束；错误信息会写入 stderr。

​
事件类型

​
系统初始化

在每个会话开始时发出一次： 
{
  "type": "system",
  "subtype": "init",
  "apiKeySource": "环境变量|标志位|登录",
  "cwd": "/绝对路径",
  "session_id": "<uuid>",
  "model": "<模型展示名称>",
  "permissionMode": "默认",
}
未来可能会为此事件新增 tools 和 mcp_servers 等字段。

​
用户消息

包含用户的输入提示词： 
{
  "type": "user",
  "message": {
    "role": "user",
    "content": [{ "type": "text", "text": "<prompt>" }]
  },
  "session_id": "<uuid>"
}

​
助手文本增量

在助手生成回复的过程中会多次触发。这些事件包含逐步生成的文本片段： 
{
  "type": "assistant",
  "message": {
    "role": "assistant",
    "content": [{ "type": "text", "text": "<delta chunk>" }]
  },
  "session_id": "<uuid>"
}
按顺序串联所有 message.content[].text 的值，以重建完整的助手回复。

​
工具调用事件

工具调用通过开始和完成事件进行追踪： 工具调用开始： 
{
  "type": "tool_call",
  "subtype": "started",
  "call_id": "<字符串ID>",
  "tool_call": {
    "readToolCall": {
      "args": { "path": "file.txt" }
    }
  },
  "session_id": "<uuid>"
}
工具调用完成： 
{
  "type": "tool_call",
  "subtype": "completed",
  "call_id": "<string id>",
  "tool_call": {
    "readToolCall": {
      "args": { "path": "file.txt" },
      "result": {
        "success": {
          "content": "文件内容…",
          "isEmpty": false,
          "exceededLimit": false,
          "totalLines": 54,
          "totalChars": 1254
        }
      }
    }
  },
  "session_id": "<uuid>"
}

​
工具调用类型

读取文件工具：
  • 开始：tool_call.readToolCall.args 包含 { "path": "file.txt" }
  • 完成：tool_call.readToolCall.result.success 包含文件元数据和内容
写入文件工具：
  • 开始：tool_call.writeToolCall.args 包含 { "path": "file.txt", "fileText": "content...", "toolCallId": "id" }
  • 完成：tool_call.writeToolCall.result.success 包含 { "path": "/absolute/path", "linesCreated": 19, "fileSize": 942 }
其他工具：
  • 可能使用 tool_call.function 结构，形如 { "name": "tool_name", "arguments": "..." }

​
终端结果

成功完成时发出的最后一个事件： 
{
  "type": "result",
  "subtype": "success",
  "duration_ms": 1234,
  "duration_api_ms": 1234,
  "is_error": false,
  "result": "<完整助手文本>",
  "session_id": "<uuid>",
  "request_id": "<可选请求 ID>"
}

​
示例序列

下面展示了一个具有代表性的 NDJSON 序列，体现了事件的典型流转： 
{"type":"system","subtype":"init","apiKeySource":"login","cwd":"/Users/user/project","session_id":"c6b62c6f-7ead-4fd6-9922-e952131177ff","model":"Claude 4 Sonnet","permissionMode":"default"}
{"type":"user","message":{"role":"user","content":[{"type":"text","text":"阅读 README.md 并创建摘要"}]},"session_id":"c6b62c6f-7ead-4fd6-9922-e952131177ff"}
{"type":"assistant","message":{"role":"assistant","content":[{"type":"text","text":"我会"}]},"session_id":"c6b62c6f-7ead-4fd6-9922-e952131177ff"}
{"type":"assistant","message":{"role":"assistant","content":[{"type":"text","text":"阅读 README.md 文件"}]},"session_id":"c6b62c6f-7ead-4fd6-9922-e952131177ff"}
{"type":"tool_call","subtype":"started","call_id":"toolu_vrtx_01NnjaR886UcE8whekg2MGJd","tool_call":{"readToolCall":{"args":{"path":"README.md"}}},"session_id":"c6b62c6f-7ead-4fd6-9922-e952131177ff"}
{"type":"tool_call","subtype":"completed","call_id":"toolu_vrtx_01NnjaR886UcE8whekg2MGJd","tool_call":{"readToolCall":{"args":{"path":"README.md"},"result":{"success":{"content":"# Project\n\nThis is a sample project...","isEmpty":false,"exceededLimit":false,"totalLines":54,"totalChars":1254}}}},"session_id":"c6b62c6f-7ead-4fd6-9922-e952131177ff"}
{"type":"assistant","message":{"role":"assistant","content":[{"type":"text","text":"并创建摘要"}]},"session_id":"c6b62c6f-7ead-4fd6-9922-e952131177ff"}
{"type":"tool_call","subtype":"started","call_id":"toolu_vrtx_01Q3VHVnWFSKygaRPT7WDxrv","tool_call":{"writeToolCall":{"args":{"path":"summary.txt","fileText":"# README 概要\n\n该项目包含...","toolCallId":"toolu_vrtx_01Q3VHVnWFSKygaRPT7WDxrv"}}},"session_id":"c6b62c6f-7ead-4fd6-9922-e952131177ff"}
{"type":"tool_call","subtype":"completed","call_id":"toolu_vrtx_01Q3VHVnWFSKygaRPT7WDxrv","tool_call":{"writeToolCall":{"args":{"path":"summary.txt","fileText":"# README 概要\n\n该项目包含...","toolCallId":"toolu_vrtx_01Q3VHVnWFSKygaRPT7WDxrv"},"result":{"success":{"path":"/Users/user/project/summary.txt","linesCreated":19,"fileSize":942}}}},"session_id":"c6b62c6f-7ead-4fd6-9922-e952131177ff"}
{"type":"result","subtype":"success","duration_ms":5234,"duration_api_ms":5234,"is_error":false,"result":"我会阅读 README.md 文件并创建摘要","session_id":"c6b62c6f-7ead-4fd6-9922-e952131177ff","request_id":"10e11780-df2f-45dc-a1ff-4540af32e9c0"}

​
文本格式

text 输出格式以简洁、易读的方式呈现代理的动作流。它不会输出详尽的 JSON 事件，而是实时给出代理正在执行的操作的简明文字描述。 这种格式适合在不需解析结构化数据的前提下监控代理进度，非常适用于日志记录、调试或简单的进度跟踪。

​
示例输出

读取了文件
编辑了文件
运行了终端命令
创建了新文件
随着代理执行操作，每个动作都会以新行显示，并即时反馈其任务进度。

​
实现说明

  • 每个事件以单行形式发出，并以\n结尾
  • 打印模式下会抑制thinking事件，它不会出现在任一输出格式中
  • 字段可能会随时间以向后兼容的方式增加（使用方应忽略未知字段）
  • 流式格式提供实时更新，而 JSON 格式会在完成后再输出结果
  • 将所有 assistant 消息增量拼接以重建完整响应
  • 工具调用 ID 可用于关联开始/完成事件
  • 会话 ID 在单次代理执行期间保持一致