Cursor CLI ヘッドレスモード: --print, --force とファイルを編集するスクリプト

04-non-interactive では --no-interactive で Agent が入力待ちせず最後まで実行することを扱った。今回はさらに ヘッドレスモード の -p / --print（「ターミナルへの出力のみ」の実行）と --force（または --yolo）で、Agent が プロジェクトのファイルを実際に変更 できるようにする — CI・バッチ JSDoc・自動 lint 修正・レポート生成向け。

要するに：Cursor ウィンドウもキー確認も不要；スクリプトが CLI を呼んでコードを変更し、スクリプトが続行する。

--print: 非対話、出力はターミナルへ

cursor agent -p "What does this project do?"
# or
cursor agent --print "List all API endpoints under src/"

--force なし: Agent はファイルの読み取り・コードベース検索・分析結果の返却はできるが、ファイルには書かない — 提案や内容の表示のみ
向いているのは: Q&A、分析、レポートを stdout に書く、パイプやスクリプトでのパース

つまり -p 単体は「最後まで実行し、出力はターミナル」；ファイルを変えるかどうかは --force を付けるか次第。

--force: ファイルの直接編集を許可

--print と --force（または --yolo）を組み合わせると、Agent は Y/N を聞かずに 作成・編集・削除 できる：

cursor agent -p --force "Refactor src/utils.js to ES6+ syntax"

用途	例
単一ファイルのリファクタ	`agent -p --force "Refactor src/foo.ts to use async/await"`
設定に沿った lint 修正	`agent -p --force "Fix all auto-fixable errors per .eslintrc"`
バッチ JSDoc	下記スクリプト例参照
プロジェクト内にファイル生成	`agent -p --force "Generate CONTRIBUTING.md from README"`

⚠️ スクリプトで --force を使う前に、単一ファイルや狭い範囲で挙動を確認してから全体に広げること。

スクリプト例: バッチ JSDoc

#!/bin/bash
# For each .js under src/, ask Agent to add JSDoc and write directly
find src/ -name "*.js" | while read -r file; do
  echo "Processing $file..."
  cursor agent -p --force "Add full JSDoc comments to $file, editing the file in place"
done

各ファイルを Agent が読み書きするので、プロジェクトのコピーやブランチで実行するか、まず 1〜2 ファイルで試すとよい。

スクリプト例: 自動コードレビューとレポート書き出し

#!/bin/bash
cursor agent -p --force --output-format text \
  "Do a code review of recent changes: readability, potential bugs, security, best practices. Write conclusions and concrete suggestions to review.txt"

--output-format text で出力をプレーンテキストにし、ファイルへの書き出しや grep/スクリプトへのパイプがしやすくなる。次回は json と stream-json を扱う。

環境: API キー

ヘッドレスモードは Cursor ウィンドウのない環境（CI・リモートマシンなど）で動かすことが多いため、認証が必要：

環境変数: export CURSOR_API_KEY=your_key
またはその環境で先に cursor auth login を実行（サポートされていれば）

ないとエラーになり、Agent は動かない。

--no-interactive との違い（簡潔に）

モード	主な用途	ファイルを編集する？
`--no-interactive`	ターミナルで実行、出力をステップごとに見る、キー不要	編集できるが、設定次第で確認する場合あり
`-p` / `--print`	スクリプト・CI、完全非対話、出力は stdout	デフォルトではしない
`-p --force`	同上だが、Agent のファイル編集を許可	する、確認なし

つまり 「本当にファイルを変える」スクリプト には -p --force；分析やレポートをターミナルに出すだけなら -p で十分。

まとめ

-p / --print: 非対話、終了時にターミナルへ出力；デフォルトではファイル編集なし
--force / --yolo: print モードで Agent のファイル編集を許可；スクリプト・CI 向け
スクリプト/CI では CURSOR_API_KEY を設定するかログインを完了させる
全体で回す前に狭い範囲で試す

次: 11-output-ci — 出力形式 text / json / stream-json と CI 連携例。