Cursor CLI --print 與 --force：腳本裡真的改檔案的做法

04-non-interactive 講了 --no-interactive 讓 Agent 跑完不等人。但如果你想要的是腳本裡叫 AI 直接改你的檔案、改完腳本繼續跑——那要再多加兩個 flag：-p（--print）和 --force。

不開 Cursor 視窗、不按鍵確認，一行指令，AI 改完，腳本繼續——這就是無頭模式（Headless）在做的事。

-p / --print：輸出到終端，預設不改檔

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

-p 的意思是：跑完就結束、結果印到終端，不加 --force 就不會寫入任何檔案。只有讀取、分析、輸出。

適合問答、產報告到 stdout、或給 pipe 和後續腳本解析。

--force：加了才會真的動檔案

在 -p 底下加 --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
find src/ -name "*.js" | while read -r file; do
  echo "Processing $file..."
  cursor agent -p --force "為 $file 加上完整的 JSDoc 註解，直接修改該檔"
done

每一個 .js 都會被 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 的用法。

CI 環境記得設好 API Key

無頭模式通常在沒有 Cursor 視窗的環境跑——CI 機器、遠端伺服器——這些地方要設好授權：

export CURSOR_API_KEY=你的金鑰

或先在那台機器跑過 cursor auth login（若支援）。沒設好直接跑，Agent 上不了工，腳本就在那邊卡著。

三種模式的差異

模式	典型用法	會不會改檔
`--no-interactive`	終端機裡跑、可以看輸出，但不用按鍵	依設定，可能會問
`-p` / `--print`	腳本、CI、完全非互動，輸出到 stdout	預設不改檔
`-p --force`	同上，但允許 Agent 直接改檔	會改，不問

要腳本「真的改檔案」用 -p --force；只要分析或輸出報告到終端，-p 就夠了。

--print 是容器，--force 才是鑰匙。記住這個分工，腳本裡的 AI 自動化就沒什麼黑魔法。

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