メインコンテンツへスキップ
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": "<アシスタントの完全なテキスト>"
  "session_id": "<uuid>",
  "request_id": "<任意のリクエスト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": "<モデルの表示名>"
  "permissionMode": "default"
}
将来的に、このイベントに tools や mcp_servers といったフィールドが追加される可能性がある。

​
ユーザーメッセージ

ユーザーの入力プロンプトを含む: 
{
  "type": "user",
  "message": {
    "role": "user",
    "content": [{ "type": "text", "text": "<prompt>" }]
  },
  "session_id": "<uuid>"
}

​
Assistant text delta

アシスタントがレスポンスを生成するあいだに複数回発行される。これらのイベントには、インクリメンタルなテキストチャンクが含まれる: 
{
  "type": "assistant",
  "message": {
    "role": "assistant",
    "content": [{ "type": "text", "text": "<delta チャンク>" }]
  },
  "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": "ファイルの内容...",
          "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 } が含まれる
その他のツール:
  • { "name": "tool_name", "arguments": "..." } を持つ tool_call.function 構造を使用する場合がある

​
ターミナル結果

正常終了時に発行される最終イベント: 
{
  "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":"# プロジェクト\n\nこれはサンプルプロジェクトです...","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 は単一のエージェント実行全体を通して一貫して維持される