#cursor#cli#ci#output-format#automation

Cursor CLI の出力形式と CI 連携

5 min read

前回 10-headless-scripts では -p --force でスクリプトからファイルを変更した。今回は 出力形式：同じ Agent 実行で「最終テキストのみ」「構造化 JSON 全体」「実行中にストリーミング JSON」のいずれかを選べる — CI ではこの 3 形式で結果をパースしたり時間を計ったり進捗を出したりする。

3 つの出力形式

形式 フラグ 向いている用途
text デフォルト、または --output-format text 人間が読む、最終回答のみ、ファイルへ書き出し
json --output-format json スクリプトでパース、CI の pass/fail、フィールド抽出
stream-json --output-format stream-json ライブ進捗、ツール呼び出し追跡、長時間実行の監視

text: 最終回答だけ

cursor agent -p "What is the entry point of this repo?"

--output-format を付けないと text：出力は 最終返答のみ で、ツール呼び出しや中間ステップは出ない — ドキュメントに貼るや短い説明向け。

CI で Agent の結論をファイルに書く例：

cursor agent -p "Generate release notes for this version from CHANGELOG" > release_notes.txt

json: スクリプト・CI 向け

cursor agent -p --output-format json "Analyze src/ dependencies and return JSON: { \"entry\": \"...\", \"deps\": [...] }"

出力は構造化 JSON。result、duration_ms やプロンプトで指定したフィールドが含まれることがある。
CI では：

  • jq でフィールド取得・空チェック・キーワード検索
  • 終了コードと内容で job の pass/fail を判定

概念例：

cursor agent -p --output-format json "Do a short code review; return {\"ok\": true/false, \"summary\": \"...\"}" | jq -r '.result'
# Then use .ok or .summary for next steps or to fail the build

正確なフィールドは Cursor のドキュメント次第；ここでは「json はプログラムでパースする用」と押さえておけばよい。

stream-json: ライブ進捗とツール追跡

cursor agent -p --output-format stream-json --stream-partial-output "Analyze project and write analysis.txt"
  • 1 行が 1 つの JSON イベント（system、assistant、tool_call、result など）
  • --stream-partial-output で assistant のテキストが 増分デルタ で送られ、「文字数ライブ」や「進捗 %」表示が可能
  • tool_call の開始/完了をパースすると、Agent がどのファイルを読んでいる/書いているかや所要時間が分かる

長時間実行・CI ログや UI で「ファイル N を処理中」表示・ツール呼び出し回数や時間の集計向け。

CI 連携のヒント

ニーズ 提案
「終わったか・結論は何か」だけ知りたい text + ファイルや変数へリダイレクト；終了コードを確認
内容で pass/fail を決めたい json + jq でパース
ライブログや進捗 stream-json + 行ごとに type/subtype でパース
Agent にファイルを編集させたい --force を付ける（10-headless-scripts 参照）
CI で実行 CURSOR_API_KEY を設定；必要なら --model でモデル固定

失敗時の扱い

  • Agent 実行が失敗すると、CLI は通常 0 以外の終了コード を返す
  • スクリプトでは if [ $? -ne 0 ]; then exit 1; fi や set -e で CI を正しく失敗させる
  • json の場合は error フィールドや独自の ok: false もチェックすると安心

まとめ

  • text: デフォルト、人間が読む用、最小限の出力；ファイル書き出しや説明向け
  • json: jq やスクリプト用の構造化；CI の判定や抽出向け
  • stream-json + --stream-partial-output: ライブイベントストリーム；進捗・ツール追跡向け
  • CI では: CURSOR_API_KEY を設定し、終了コードを尊重し、必要に応じて JSON をパースして pass/fail

次: 12-sessions-cloud — --resume でセッション再開、-c でクラウド実行。