Cursor CLI 與 Headless 自動化

Cursor CLI 的價值不是"換個地方聊天"，而是把 Agent 放進 terminal、git、scripts、CI、PR review 和自動化流水線。Headless（無介面 / 非互動）模式更進一步，讓任務可以非互動執行。邊界也更嚴格：非互動越多，許可權、輸出和回退越要明確。

1. 安裝與第一次啟動

官方安裝命令：

# macOS / Linux / WSL
curl https://cursor.com/install -fsS | bash

# Windows PowerShell
irm 'https://cursor.com/install?win32=true' | iex

# 安装完成后直接启动交互
agent

agent 是 Cursor CLI 的可執行命令。第一次啟動會要求登入，認證完畢後即可在終端直接對話。

2. CLI 適合什麼

編輯器適合邊看程式碼邊協作；CLI 適合貼近工程命令和自動化系統。

CLI 適合：

• 終端裡快速問專案結構。
• 對當前 git diff 做只讀 review。
• 批次生成報告。
• 在 CI 中輸出檢查結果。
• 透過 script 固定 prompt 和 output format。
• 把任務 handoff 到 Cloud Agent。

不適合：

• 需要大量視覺互動的 UI 調整。
• 需要人工逐步審查的複雜改動卻沒有 review gate。
• 生產部署、刪除、資料庫遷移這類高風險自動寫入。

3. 三種模式仍然重要

Cursor CLI 支援 Agent、Plan、Ask。和編輯器一樣，模式決定風險。

agent --mode=ask "explain how billing is initialized"
agent --plan "plan a safe migration from REST to GraphQL"
agent "fix the failing checkout parser test and show the diff"

判斷：

• 只讀理解：--mode=ask。
• 複雜任務先方案：--plan 或 --mode=plan。
• 明確小任務：預設 Agent。

很多 CLI 事故來自把 Ask 任務用 Agent 執行，或者把 Plan 任務直接寫入。

把任務推到 Cloud Agent（mid-conversation handoff）

在互動會話中，把訊息開頭加 & 可以把任務推到 Cloud Agent 繼續跑——本地終端關掉它也不會停。適合長任務邊喝咖啡邊跑：

& 把整个 auth module 重构为 JWT，并补完整测试

跑起來之後可以在 cursor.com/agents 網頁端或移動端繼續跟進。

恢復歷史會話（Sessions）

agent ls                  # 列所有历史对话
agent resume              # 恢复最近一个
agent --continue          # 继续上一个会话
agent --resume="chat-id"  # 指定 chat id 恢复

會話恢復保留了完整上下文，適合長任務跨天繼續，或者本地切到不同終端視窗接著幹。

4. Headless 是自動化入口，不是無監管入口

Headless 的核心是 print mode（列印模式，非互動輸出到 stdout 而非進入 REPL）：agent -p 或 agent --print。它適合 scripts、CI、批處理和自動報告。

只讀示例：

agent -p --output-format text \
  "Review the current git diff for correctness and security risks. Do not edit files."

可寫示例需要顯式邊界：

agent -p --force --output-format text \
  "Only edit src/public-api.ts. Add missing JSDoc for exported functions. Do not edit any other file."

關鍵點：

• agent -p 適合輸出建議或報告。
• 寫入指令碼必須顯式使用 --force 或 --yolo（you-only-live-once，跳過所有確認的極簡寫入開關，比 --force 更激進），並限制檔案範圍。
• 只讀指令碼要明確寫 Do not edit files。
• 寫入指令碼前檢查 git 工作區。

5. 輸出格式決定能否自動化

官方 Headless 文件支援 text、json、stream-json：

機器消費不要靠字串擷取。要麼要求 JSON schema，要麼用 jq 或正式 parser 處理。

agent -p --output-format json \
  "Return exactly JSON with keys: findings, riskLevel, recommendedCommands."

6. 只讀審查指令碼

第一階段建議只做 review，不寫檔案。

#!/usr/bin/env bash
set -euo pipefail

agent -p --output-format text \
  "Review the current git diff for:
  - correctness risks
  - security risks
  - missing tests

  Do not edit files.
  Return concise findings with file paths when possible."

這個指令碼適合放在本地 pre-review、人工觸發的 CI job 或 PR 輔助評論。它的價值是穩定產出風險清單，而不是替代測試。

7. 小範圍寫入指令碼

寫入必須更嚴格。

#!/usr/bin/env bash
set -euo pipefail

test -z "$(git status --short)"

agent -p --force --output-format text \
  "Only edit src/public-api.ts.
  Add JSDoc comments to exported functions.
  Do not change runtime behavior.
  After editing, summarize exact changes."

git diff -- src/public-api.ts

上線標準：

• 工作區乾淨。
• 檔案範圍固定。
• 禁止觸碰 secrets、lockfile、配置和無關模組。
• 執行後展示 diff。
• 跑 focused test、lint 或 build。
• 失敗時能丟棄分支或 revert commit。

8. GitHub Actions：先 restricted autonomy

官方 GitHub Actions 文件有 full autonomy 和 restricted autonomy 兩種思路。

生產 CI 預設用 restricted autonomy：

• Agent 負責分析和有限檔案修改。
• deterministic workflow step（確定性工作流步驟，命令列為可預測、不依賴 AI 推理的固定 step）負責 branch、commit、push、PR comment。
• CURSOR_API_KEY 只走 GitHub Secrets。
• permissions 明確 allow / deny。
• 預設 deny Shell(git)、Shell(gh) 和 .env* 寫入。

不要一開始就讓 Agent 在 CI 裡同時負責理解問題、修改檔案、提交、推送和評論 PR。職責拆開，日誌和回退才清楚。

9. 商業級上線清單

把 CLI / headless 放進團隊流程前，確認：

• 安裝來源、PATH、版本驗證可復現。
• 本地、CI、團隊成員的認證邊界分開。
• Ask、Plan、Agent 使用場景寫清楚。
• agent -p 預設只讀。
• 寫入指令碼要求乾淨 Git 工作區。
• 輸出格式固定，機器消費用 JSON。
• CI secrets 不進日誌和 prompt。
• Git / gh / deploy 由 deterministic step 執行。
• 每個自動化都有日誌、退出碼和人工 gate。

官方來源

• Cursor CLI Overview：官方 CLI 總覽、interactive / print mode、Cloud Agent handoff、sessions、sandbox 和 sudo prompt。
• Using Headless CLI：官方 print mode、--force / --yolo、輸出格式、API key 和指令碼示例。
• Cursor GitHub Actions：官方 CI 安裝、CURSOR_API_KEY、full autonomy、restricted autonomy 和 permissions。
• Cursor CLI Output Format：官方 text、json、stream-json 輸出格式。

接下來去哪