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>"
}
欄位說明
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 Summary\n\nThis project contains...","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 Summary\n\nThis project contains...","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 可用於關聯開始/完成事件
  • 會話 ID 在單次 agent 執行過程中保持一致