Cursor CLI 總覽
基於 Cursor 官方 CLI 文件解釋互動模式、非互動模式、Cloud Agent handoff、session 恢復、sandbox 和上線驗收邊界。
Cursor CLI 是把 Cursor Agent 放進終端的入口。它適合兩類場景：人在終端裡互動式改程式碼，以及指令碼、CI、自動化流程裡用 print mode 輸出結果。
閱讀目標：讀完本章，你應該能判斷什麼時候用 agent，什麼時候繼續留在編輯器裡，並能為 CLI 自動化設計最小可控邊界。
1. Cursor CLI 解決什麼問題
編輯器裡的 Agent 適合邊看檔案邊修改；CLI 適合貼近 shell、儲存庫和自動化系統。
| 場景 | 更適合的入口 | 原因 |
|---|---|---|
| 臨時理解一段程式碼 | CLI Ask mode | 不需要開啟完整編輯器，也不應該寫檔案 |
| 修改本地專案 | CLI Agent mode 或編輯器 Agent | 兩者都能讀寫檔案，取決於你是否更常在終端工作 |
| 先設計方案 | CLI Plan mode | 先問清楚、產出計劃，再決定是否寫程式碼 |
| CI 裡做審查 | CLI print mode | 可以固定 prompt、輸出格式和失敗處理 |
| 長任務離線繼續 | Cloud Agent handoff | 把當前任務推到雲端繼續執行 |
最重要的不是“CLI 更方便”，而是它讓 Agent 能進入現有工程鏈路：terminal、git、scripts、CI、issue、PR 和日誌系統。
2. 基本入口
官方給出的最小路徑是：安裝後執行 agent。
# macOS / Linux / WSL
curl https://cursor.com/install -fsS | bash
# 进入交互式会话
agent
# 带初始任务进入会话
agent "review the authentication module and explain the risks"Windows 原生 PowerShell 使用單獨安裝入口：
irm 'https://cursor.com/install?win32=true' | iex生產環境不要只記命令。還要記錄安裝來源、版本號、PATH 位置、認證方式、執行目錄和許可權模式。
3. 三種工作模式
Cursor CLI 支援與編輯器 Agent 一致的模式。
| Mode | 作用 | 進入方式 | 風險邊界 |
|---|---|---|---|
| Agent | 完整工具訪問，適合真實編碼任務 | 預設模式，不需要額外 flag | 可能寫檔案、跑命令，需要 review |
| Plan | 先設計方案和澄清問題 | --plan、--mode=plan、/plan、Shift+Tab | 不應急著寫程式碼 |
| Ask | 只讀理解專案 | --mode=ask、/ask | 適合調研，不適合交付修改 |
agent --mode=ask "explain how billing is initialized"
agent --plan "plan a safe migration from REST to GraphQL"如果你要把 CLI 教給團隊，先講這三種模式。很多失敗不是 Agent 能力問題，而是把“只讀理解”“方案設計”和“直接改程式碼”混在一起。
4. 互動式與非互動式
互動式適合探索、修改和審查：
agent
agent "fix the failing checkout test and show the diff before finalizing"非互動式適合指令碼、CI 和批處理：
agent -p "review the current git diff for security issues" --output-format text
agent --print "summarize the failing tests and suggest the next command"非互動式不是低風險模式。官方文件明確說明 non-interactive mode 裡 Cursor 具有寫入許可權，所以上線前要固定三件事：
- 輸入 prompt：包含範圍、限制、驗收方式。
- 輸出格式：人工閱讀用 text，機器消費用 json。
- 失敗處理：退出碼、日誌歸檔、PR 評論或人工 gate。
5. CLI 能接哪些能力
Cursor CLI 不是一個孤立 binary。它會複用 Cursor 的多項能力。
flowchart TD
CLI["agent CLI"] --> Modes["Agent / Plan / Ask"]
CLI --> Rules[".cursor/rules + AGENTS.md + CLAUDE.md"]
CLI --> MCP["mcp.json MCP servers"]
CLI --> ACP["agent acp over stdio"]
CLI --> Sessions["agent ls / resume / continue"]
CLI --> Worktree["--worktree isolated checkout"]
CLI --> Cloud["& Cloud Agent handoff"]這也是為什麼 CLI 自動化要先做邊界設計：它可能讀取專案規則、呼叫 MCP、執行 shell、寫程式碼、恢復歷史會話，也可能把任務交給 Cloud Agent。
6. Session 和 Cloud handoff
CLI 可以恢復歷史會話：
agent ls
agent resume
agent --continue
agent --resume="chat-id-here"中途把任務交給 Cloud Agent，可以在訊息前加 &：
& refactor the auth module and add regression tests這裡的商業級用法是：本地先把任務定義清楚，再交給雲端。不要把半截上下文、未說明許可權的任務直接推到 Cloud Agent，否則回來只會得到一組難審查的改動。
7. Sandbox、sudo 和許可權
CLI 可透過 /sandbox 或 --sandbox <mode> 控制命令執行環境。官方文件當前寫法是 enabled 或 disabled。
agent --sandbox enabled "run the test suite and diagnose failures"需要 sudo 的命令會觸發安全的密碼輸入提示。這裡要堅持一個邊界：能不用提權就不用提權；確實需要時，任務說明必須寫清楚為什麼需要、預期改哪裡、失敗後如何恢復。
8. 上線驗收清單
把 Cursor CLI 放進團隊流程前，至少驗收這些項：
- 安裝可復現：新機器能安裝、
agent --version有輸出。 - PATH 明確：shell、tmux、CI runner 都能找到
agent。 - 認證清楚：本地、CI、團隊成員使用不同憑據邊界。
- 模式清楚：Ask、Plan、Agent 的使用場景寫進團隊 SOP。
- 許可權可審計：sandbox、command approval、sudo、MCP 都有預設策略。
- 輸出可消費：指令碼使用固定
--output-format，日誌可追蹤。 - 變更可回退：所有寫入任務都經過 git diff、測試和 review。
深讀：為什麼不建議一開始就把 CLI 接進 CI 自動改程式碼
CI 環境通常缺少完整的人類判斷上下文。它知道測試失敗，但未必知道產品取捨、安全邊界和釋出節奏。
更穩的路線是先讓 CLI 在 CI 裡做只讀審查、總結失敗、生成候選修復建議；等輸出格式、日誌和 review gate 穩定後，再逐步開放更高許可權的自動修復流程。
本章自檢
完成本章後，用這 3 個問題檢查自己是否真正理解：
agent -p為什麼不等於只讀安全模式？- 什麼時候應該用
--mode=ask而不是預設 Agent mode？ - CLI 自動化上線前必須固定哪三類邊界？
透過標準：你能寫出一份團隊 CLI 使用規則，明確安裝、模式、許可權、輸出格式、日誌和人工審查入口。
官方來源
- Cursor CLI Overview —— 官方 CLI 總覽、互動模式、非互動模式、Cloud Agent handoff、sessions、sandbox、Max Mode 和 sudo prompt。
- Cursor CLI Installation —— 官方安裝、PATH、驗證和更新說明。
- Cursor CLI Using Agent —— 官方模式、prompting、MCP、ACP、rules、shortcuts、worktrees、history 和 non-interactive mode。