CLI 使用方式
解釋 Cursor CLI 的模式切換、prompting、MCP、ACP、rules、快捷鍵、review、上下文選擇、Cloud handoff、worktree、history 和非互動模式。
Cursor CLI 的使用重點不是背引數，而是把“我要它讀什麼、能改什麼、怎麼驗收、失敗怎麼退”說清楚。
閱讀目標：讀完本章，你應該能用 CLI 完成一次只讀調研、一次計劃會話、一次帶 review 的修改，並知道什麼時候切換到 worktree 或 non-interactive mode。
1. 啟動一次會話
最常見入口是直接執行：
agent也可以帶初始任務：
agent "find why the checkout tests are failing and propose a fix"真實專案裡，初始 prompt 不要只寫“修一下”。至少包含四塊：
- 目標：要解決什麼問題。
- 範圍：允許看哪些目錄、改哪些模組。
- 限制：不要改什麼、不要跑什麼高風險命令。
- 驗收：需要跑哪些測試、輸出什麼證據。
示例：
Investigate why the checkout smoke test fails.
Stay within packages/checkout and tests/checkout.
Do not change billing code.
Before editing, summarize the root cause and the files you plan to touch.
After editing, run the focused test and show the git diff.2. 模式切換
CLI 支援 Agent、Plan、Ask 三種模式。
| 模式 | 使用方式 | 適合任務 |
|---|---|---|
| Agent | 預設模式，不需要額外 flag | 真實編碼、改檔案、跑命令 |
| Plan | /plan、--plan、--mode=plan、Shift+Tab | 先設計方案、澄清問題 |
| Ask | /ask、--mode=ask | 只讀理解專案 |
agent --mode=ask "explain how routing works in this app"
agent --plan "design a safe migration for the auth middleware"判斷很簡單：不知道該不該改，就先 Ask；知道要改但方案不清楚，就先 Plan；範圍和驗收都清楚，再 Agent。
3. Prompting 和工具邊界
官方文件提醒，清楚表達 intent 會得到更好結果。尤其是當你不希望 Agent 寫程式碼時，要明確寫出類似 do not write any code 的限制。
Cursor Agent 可使用檔案操作、搜尋、shell 命令和 web access。CLI 場景裡要額外補三條約束：
- shell 命令需要先說明目的。
- 寫檔案前需要說明預計修改點。
- 所有改動要回到 diff 和測試驗收。
可以直接這樣開場：
Do not write any code yet.
First inspect the project rules, then summarize the relevant files and propose a 3-step plan.
Ask before making edits.4. MCP、ACP 和 rules
Cursor CLI 會讀取與編輯器相同的擴充套件上下文。
| 能力 | CLI 行為 | 商業級注意點 |
|---|---|---|
| MCP | 自動檢測並尊重 mcp.json | 不要把高許可權 MCP 預設暴露給自動化 |
| ACP | agent acp 可作為 ACP server 透過 stdio 通訊 | 適合自定義 client，需處理 JSON-RPC 邊界 |
| Rules | 支援 .cursor/rules | 專案規則應寫清楚測試、風格和禁止動作 |
| Compatibility rules | 讀取根目錄 AGENTS.md 和 CLAUDE.md | 多 Agent 專案要避免規則互相沖突 |
這意味著 CLI 不是“乾淨無上下文”的命令。它會繼承專案規則和工具配置，所以排查異常時也要看這些檔案。
5. 輸入、快捷鍵和 review
官方列出的常用互動：
| 操作 | 快捷鍵或命令 |
|---|---|
| 歷史訊息 | ArrowUp |
| 模式輪換 | Shift+Tab |
| 多行輸入 | Shift+Enter、Ctrl+J 或 Alt+Enter |
| 退出 CLI | Ctrl+D |
| Review changes | Ctrl+R |
| Review 中追加說明 | i |
| Review 中切換檔案 | ArrowLeft / ArrowRight |
tmux 使用者要特別注意：Shift+Enter 可能不穩定，官方建議必要時使用 Ctrl+J，並參考 Terminal Setup。
Review 是 CLI 修改任務的關鍵環節。不要只看 Agent 的總結，要進入 review 看每個檔案的 diff，再決定是否繼續。
6. 選擇上下文和壓縮上下文
在 CLI 裡可以用 @ 選擇檔案和目錄放入上下文。上下文太滿時，用 /compress 釋放空間。
@src/auth @tests/auth
Explain how login tokens are validated. Do not edit files.上下文選擇的原則：
- 先給直接相關檔案。
- 再給規則、測試、日誌和錯誤輸出。
- 不要把整個儲存庫無差別塞進去。
- 長任務中途用
/compress，但壓縮前確認關鍵約束已經寫清楚。
7. Worktree 隔離
官方支援 --worktree，讓 Agent 在新的 Git worktree 裡工作，而不是直接改當前 checkout。
agent --worktree "upgrade the test runner and fix broken snapshots"
agent --workspace ~/src/my-app --worktree "fix the flaky auth test and open a PR"Cursor CLI worktrees 預設位於 ~/.cursor/worktrees。適合這些情況：
- 你當前工作區有未提交改動。
- 要讓 Agent 做較大改動，但不想汙染主 checkout。
- 同時跑多個候選方案。
- 需要把風險任務和日常開發隔離。
不適合這些情況：
- 任務必須直接基於當前未提交改動。
- 你還不熟悉 worktree 清理規則。
- 專案裡有不支援多 checkout 的本地服務或鎖檔案。
8. History 和恢復
CLI 可以列出和恢復會話：
agent ls
agent resume
agent --continue
agent --resume="chat-id-here"恢復會話適合繼續同一條問題鏈。不要把完全不同的任務塞進舊會話，否則歷史上下文會干擾判斷。
9. Command approval 和非互動模式
互動模式下，CLI 在執行終端命令前會詢問 approve 或 reject。
非互動模式用 -p 或 --print：
agent -p "review this diff for security issues. Do not edit files." --output-format text
agent --print "summarize test failures as JSON" --output-format json官方文件提醒：non-interactive mode 中 Cursor 具有完整寫入許可權。所以自動化裡必須把“不寫檔案”“只審查”“只輸出 JSON”等限制寫進 prompt，並用許可權、runner、git diff 和 review gate 雙重兜底。
10. Cloud Agent handoff
在會話裡用 & 可以把任務推給 Cloud Agent：
& refactor the auth module and add comprehensive tests建議只把這類任務交給 Cloud Agent：
- 範圍清楚。
- 驗收命令清楚。
- 允許修改的檔案邊界清楚。
- 不依賴本機私有登入態或不可複製環境。
否則它可能在雲端跑很久，最後產出一組無法復現的改動。
深讀：一次好的 CLI 任務應該長什麼樣
好的 CLI 任務不是命令很短，而是上下文足夠明確。它應該告訴 Agent 當前目標、禁止動作、允許修改範圍、驗證命令和最終輸出格式。
對於真實專案，建議先用 Ask mode 獲取現狀，再用 Plan mode 固定方案，最後再進入 Agent mode 修改。這個順序慢一點，但能顯著降低誤改和無效 diff。
本章自檢
完成本章後，用這 3 個問題檢查自己是否真正理解：
@、/compress和 rules 檔案分別解決什麼上下文問題？- 為什麼當前工作區有未提交改動時應該優先考慮
--worktree？ - 非互動模式接入 CI 前必須如何限制許可權和輸出？
透過標準：你能用 CLI 完成一次 Ask、一次 Plan、一次 Agent 修改，並透過 Ctrl+R、git diff 和測試命令驗收。
官方來源
- Using Agent in CLI —— 官方說明模式、prompting、MCP、ACP、rules、快捷鍵、review、上下文選擇、Cloud handoff、worktrees、history、command approval 和 non-interactive mode。
- Cursor CLI Overview —— 官方說明 CLI 總體入口、sessions、sandbox 和 handoff。
- Terminal Setup —— 官方終端快捷鍵配置和相容性說明。
- Cursor Worktrees —— 官方 worktree 位置、清理和相關限制說明。