出力形式

Cursor Agent CLIでは、--printと組み合わせて--output-formatオプションを使用することで、複数の出力形式を指定できます。プログラムから利用できる構造化形式 (json、stream-json) と、人間が読みやすい簡易テキスト形式 (text) が用意されています。

デフォルトの--output-formatはtextです。このオプションは、出力時 (--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_ms`	API リクエスト時間 (ミリ秒、現在は `duration_ms` と同じ)
`result`	Assistant の完全なレスポンステキスト (すべてのテキスト差分を連結したもの)
`session_id`	一意のセッション識別子
`request_id`	省略可能なリクエスト識別子 (省略される場合があります)

Stream JSON 形式

stream-json 出力形式では、改行区切り JSON (NDJSON) が出力されます。各行には、実行中のイベントを表す JSON オブジェクトが1つ含まれます。この形式ではテキスト差分を集約し、アシスタントメッセージごとに1行 (ツール呼び出しの間の完全なメッセージ) を出力します。

成功時、ストリームは終端の result イベントで終了します。失敗時はプロセスが非ゼロコードで終了し、終端イベントなしでストリームが早期に終了する場合があります。エラーメッセージは stderr に書き込まれます。

部分出力のストリーミング: リアルタイムの文字単位ストリーミングには、--output-format stream-json とともに --stream-partial-output を使用します。これにより、テキストは生成に合わせて小さなチャンクで出力され、メッセージごとに複数の assistant イベントが出力されます。

--stream-partial-output を使用すると、CLI は3種類の assistant イベントを出力します。新しいテキストを含むのは最初の種類だけです。

`timestamp_ms`	`model_call_id`	内容	操作
あり	なし	新しいテキストを含むストリーミング差分	使用 — `message.content[].text` を追加
あり	あり	ツール呼び出し前のバッファ済みフラッシュ (重複)	スキップ
なし	なし	ターン終了時の最終フラッシュ (重複)	スキップ

リアルタイムストリーミングが不要で、完成した回答だけが必要な場合は、すべての assistant イベントをスキップし、終端の result イベントの result フィールドを読み取ります。

イベントタイプ

システムの初期化

各セッションの開始時に一度出力されます：

{  "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>"}

Assistant メッセージ

完全な assistant メッセージごとに1回 (ツール呼び出しの間に) 送出されます。各イベントには、そのメッセージセグメントの全文が含まれます。

{  "type": "assistant",  "message": {    "role": "assistant",    "content": [{ "type": "text", "text": "<complete message text>" }]  },  "session_id": "<uuid>"}

--stream-partial-output を有効にすると、assistant events に次の2つのフィールドが追加されることがあります。

フィールド	説明
`timestamp_ms`	ストリーミング中の delta とツール呼び出し前の flush に含まれます。ターン終了時の final flush には含まれません。
`model_call_id`	ツール呼び出し前に出力されるバッファ済みの flush にのみ含まれます。これを使用して重複するテキストを識別し、スキップします。

これらのイベントのフィルタリング方法については、上記の部分出力のストリーミングに関する注記を参照してください。

ツール呼び出しイベント

ツール呼び出しは、開始イベントと完了イベントで追跡されます。

ツール呼び出しの開始:

{  "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 } が含まれます

その他のツール:

{ "name": "tool_name", "arguments": "..." } を含む tool_call.function 構造を使用する場合があります

ターミナル結果

正常終了時に発行される最終イベント:

{  "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":"Read README.md and create a summary"}]},"session_id":"c6b62c6f-7ead-4fd6-9922-e952131177ff"}{"type":"assistant","message":{"role":"assistant","content":[{"type":"text","text":"I'll read the README.md file"}]},"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":"Based on the README, I'll create a summary"}]},"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":"assistant","message":{"role":"assistant","content":[{"type":"text","text":"Done! I've created the summary in summary.txt"}]},"session_id":"c6b62c6f-7ead-4fd6-9922-e952131177ff"}{"type":"result","subtype":"success","duration_ms":5234,"duration_api_ms":5234,"is_error":false,"result":"I'll read the README.md fileBased on the README, I'll create a summaryDone! I've created the summary in summary.txt","session_id":"c6b62c6f-7ead-4fd6-9922-e952131177ff","request_id":"10e11780-df2f-45dc-a1ff-4540af32e9c0"}

テキスト形式

text 出力形式では、中間の進捗更新やツール呼び出しの要約を含めず、最終アシスタントメッセージのみが出力されます。エージェントの最終レスポンスだけが必要なスクリプトに最も適した、シンプルな出力形式です。

進捗表示やツール実行の詳細を含めず、エージェントからの回答または最終メッセージだけが必要な場合に適しています。

出力例

The command to move this branch onto main is `git rebase --onto main HEAD~3`.

最後のツール呼び出し後の最終アシスタントメッセージのみが出力され、ツール呼び出しの要約や中間テキストは出力されません。

注記

各イベントは、\n で終端される1行として出力されます
thinking イベントは出力モードでは抑制され、どの出力形式にも含まれません
フィールドは後方互換性を保ったまま追加される場合があります (コンシューマーは不明なフィールドを無視してください)
json 形式では、完了後に結果を出力します
stream-json 形式では、完全なエージェントメッセージを出力します
--stream-partial-output フラグは、文字単位のストリーミング用にリアルタイムのテキスト差分を提供します (stream-json 形式でのみ機能します)
ツール呼び出しIDを使用して、開始・完了イベントを関連付けられます
セッションIDは、1回のエージェント実行中は一貫しています

出力形式

JSON 形式

json 出力形式では、実行が正常に完了すると、単一の 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_ms`	API リクエスト時間 (ミリ秒、現在は `duration_ms` と同じ)
`result`	Assistant の完全なレスポンステキスト (すべてのテキスト差分を連結したもの)
`session_id`	一意のセッション識別子
`request_id`	省略可能なリクエスト識別子 (省略される場合があります)

Stream JSON 形式

--stream-partial-output を使用すると、CLI は3種類の assistant イベントを出力します。新しいテキストを含むのは最初の種類だけです。

`timestamp_ms`	`model_call_id`	内容	操作
あり	なし	新しいテキストを含むストリーミング差分	使用 — `message.content[].text` を追加
あり	あり	ツール呼び出し前のバッファ済みフラッシュ (重複)	スキップ
なし	なし	ターン終了時の最終フラッシュ (重複)	スキップ

イベントタイプ

システムの初期化

各セッションの開始時に一度出力されます：

{  "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>"}

Assistant メッセージ

完全な assistant メッセージごとに1回 (ツール呼び出しの間に) 送出されます。各イベントには、そのメッセージセグメントの全文が含まれます。

{  "type": "assistant",  "message": {    "role": "assistant",    "content": [{ "type": "text", "text": "<complete message text>" }]  },  "session_id": "<uuid>"}

--stream-partial-output を有効にすると、assistant events に次の2つのフィールドが追加されることがあります。

フィールド	説明
`timestamp_ms`	ストリーミング中の delta とツール呼び出し前の flush に含まれます。ターン終了時の final flush には含まれません。
`model_call_id`	ツール呼び出し前に出力されるバッファ済みの flush にのみ含まれます。これを使用して重複するテキストを識別し、スキップします。

これらのイベントのフィルタリング方法については、上記の部分出力のストリーミングに関する注記を参照してください。

ツール呼び出しイベント

ツール呼び出しは、開始イベントと完了イベントで追跡されます。

ツール呼び出しの開始:

{  "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 } が含まれます

その他のツール:

{ "name": "tool_name", "arguments": "..." } を含む tool_call.function 構造を使用する場合があります

ターミナル結果

正常終了時に発行される最終イベント:

{  "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":"Read README.md and create a summary"}]},"session_id":"c6b62c6f-7ead-4fd6-9922-e952131177ff"}{"type":"assistant","message":{"role":"assistant","content":[{"type":"text","text":"I'll read the README.md file"}]},"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":"Based on the README, I'll create a summary"}]},"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":"assistant","message":{"role":"assistant","content":[{"type":"text","text":"Done! I've created the summary in summary.txt"}]},"session_id":"c6b62c6f-7ead-4fd6-9922-e952131177ff"}{"type":"result","subtype":"success","duration_ms":5234,"duration_api_ms":5234,"is_error":false,"result":"I'll read the README.md fileBased on the README, I'll create a summaryDone! I've created the summary in summary.txt","session_id":"c6b62c6f-7ead-4fd6-9922-e952131177ff","request_id":"10e11780-df2f-45dc-a1ff-4540af32e9c0"}

テキスト形式

進捗表示やツール実行の詳細を含めず、エージェントからの回答または最終メッセージだけが必要な場合に適しています。

出力例

The command to move this branch onto main is `git rebase --onto main HEAD~3`.

最後のツール呼び出し後の最終アシスタントメッセージのみが出力され、ツール呼び出しの要約や中間テキストは出力されません。

注記

各イベントは、\n で終端される1行として出力されます
thinking イベントは出力モードでは抑制され、どの出力形式にも含まれません
フィールドは後方互換性を保ったまま追加される場合があります (コンシューマーは不明なフィールドを無視してください)
json 形式では、完了後に結果を出力します
stream-json 形式では、完全なエージェントメッセージを出力します
--stream-partial-output フラグは、文字単位のストリーミング用にリアルタイムのテキスト差分を提供します (stream-json 形式でのみ機能します)
ツール呼び出しIDを使用して、開始・完了イベントを関連付けられます
セッションIDは、1回のエージェント実行中は一貫しています

Command Palette

はじめに

Agent

Grok Bot

カスタマイズ

Cloud Agents

オリジン

連携機能

SDK

CLI

チームとEnterprise

出力形式

Command Palette

はじめに

Agent

Grok Bot

カスタマイズ

Cloud Agents

オリジン

連携機能

SDK

CLI

チームとEnterprise

出力形式