Cursor Agent CLI 在搭配 --print 時，可透過 --output-format 指定多種輸出格式。這些格式包含供程式化使用的結構化格式（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": "<full assistant text>",
  "session_id": "<uuid>",
  "request_id": "<optional request id>"
}
FieldDescription
type對於終端結果一律為 "result"
subtype對於成功完成一律為 "success"
is_error對於成功回應一律為 false
duration_ms總執行時間（毫秒）
duration_api_msAPI 請求時間（毫秒）（目前等於 duration_ms）
result完整的助理回應文字（將所有文字增量串接後的結果）
session_id唯一的工作階段識別碼
request_id選用的請求識別碼（可能省略）

​
Stream JSON 格式

stream-json 輸出為以換行分隔的 JSON（NDJSON）。每一行包含一個 JSON 物件，代表執行期間的即時事件。 串流在成功時會以最後一個 result 事件結束。若失敗，程序會以非零代碼結束，且串流可能在沒有終結事件的情況下提前結束；錯誤訊息會寫入 stderr。

​
事件類型

​
系統初始化

在每次工作階段開始時發出一次： 
{
  "type": "system",
  "subtype": "init",
  "apiKeySource": "env|flag|login",
  "cwd": "/absolute/path",
  "session_id": "<uuid>",
  "model": "<model display name>",
  "permissionMode": "default"
}
此事件未來可能會新增 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": "<string 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": "file contents...",
          "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": "<full assistant text>",
  "session_id": "<uuid>",
  "request_id": "<optional request 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 事件，而是即時輸出代理正在執行動作的精簡文字描述。 這種格式適合在無需解析結構化資料的額外負擔下監控代理進度，非常適合用於記錄、除錯，或簡單的進度追蹤。

​
範例輸出

Read file
Edited file
Ran terminal command
Created new file
每個動作都會在代理執行時另起一行顯示，讓你即時掌握代理在任務中的進度。

​
實作注意事項

  • 每個事件以單行輸出，並以 \n 結尾
  • thinking 事件在列印模式下會被隱藏，且不會出現在任一輸出格式中
  • 欄位可能隨時間以向後相容的方式新增（消費端應忽略未知欄位）
  • 串流格式提供即時更新，而 JSON 格式會在完成後才輸出結果
  • 將所有 assistant 訊息增量串接以重建完整回應
  • 工具呼叫 ID 可用來對應開始/完成事件
  • Session ID 在單次代理執行期間保持一致