Cursor CLI 無頭模式進階：--print、--force 與腳本改檔

04-non-interactive 講了 --no-interactive 讓 Agent 一鍵跑完不等人。這篇再進一步：無頭模式（Headless） 用 -p / --print 跑「只輸出到終端」的腳本，再加上 --force（或 --yolo），Agent 就能真的改你專案裡的檔案，適合 CI、批次加註解、自動修 lint、產報告。

一句話：不開 Cursor 視窗、不按鍵確認，腳本裡叫 CLI 改 code，改完腳本繼續跑。

--print：非互動、結果往終端丟

cursor agent -p "這個專案在做什麼？"
# 或
cursor agent --print "列出 src/ 下所有 API 端點"

不加 --force：Agent 可以讀檔、搜 codebase、回你分析，但不會寫入檔案，只會「建議」或把內容印在輸出裡
適合：問答、分析、產出報告到 stdout、給 pipe 或腳本解析

所以 -p 本身 = 「跑完就結束、輸出到終端」，有沒有改檔取決於你有沒有加 --force。

--force：允許直接改檔

在 --print 底下加上 --force（或 --yolo），Agent 就可以真的寫入、修改、刪除檔案，不會再問你 Y/N：

cursor agent -p --force "把 src/utils.js 重構成 ES6+ 語法"

情境	指令範例
單檔重構	`agent -p --force "重構 src/foo.ts 用 async/await"`
依規範修 lint	`agent -p --force "依 .eslintrc 修復所有可自動修復的錯誤"`
批次加 JSDoc	見下方腳本範例
產出檔案到專案	`agent -p --force "根據 README 產出 CONTRIBUTING.md"`

⚠️ 在腳本裡用 --force 前，建議先在單一檔案或小範圍試跑，確認行為再放大到整個 repo。

腳本範例：批次加 JSDoc

#!/bin/bash
# 對 src/ 下每個 .js 請 Agent 加 JSDoc，並直接寫入
find src/ -name "*.js" | while read -r file; do
  echo "Processing $file..."
  cursor agent -p --force "為 $file 加上完整的 JSDoc 註解，直接修改該檔"
done

這裡每一檔都會被 Agent 讀寫，所以適合在專案副本或 branch 上跑，或先對一兩個檔試跑。

腳本範例：自動 code review 並寫入報告

#!/bin/bash
cursor agent -p --force --output-format text \
  "針對最近變更做 code review，重點：可讀性、潛在 bug、安全性、最佳實踐。把結論與具體建議寫入 review.txt"

--output-format text 讓輸出是純文字，方便直接寫進檔案或後續用 grep/腳本處理。下一篇會講 json、stream-json 的用法。

環境準備：API Key

無頭模式通常在沒有 Cursor 視窗的環境跑（例如 CI、遠端機），需要授權：

設定環境變數：export CURSOR_API_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 或完成登入
先小範圍試跑再整批跑，避免一次改爆整個 repo

下一步：11-output-ci — 輸出格式 text / json / stream-json 與 CI 整合範例。