---
title: "CLI 使用方式"
description: "解釋 Cursor CLI 的模式切換、prompting、MCP、ACP、rules、快捷鍵、review、上下文選擇、Cloud handoff、worktree、history 和非互動模式。"
verifiedAt: "2026-05-09"
---

Cursor CLI 的使用重點不是背引數，而是把“我要它讀什麼、能改什麼、怎麼驗收、失敗怎麼退”說清楚。

> [!NOTE]
> **閱讀目標**：讀完本章，你應該能用 CLI 完成一次只讀調研、一次計劃會話、一次帶 review 的修改，並知道什麼時候切換到 worktree 或 non-interactive mode。

## 1. 啟動一次會話

最常見入口是直接執行：

```bash
agent
```

也可以帶初始任務：

```bash
agent "find why the checkout tests are failing and propose a fix"
```

真實專案裡，初始 prompt 不要只寫“修一下”。至少包含四塊：

- 目標：要解決什麼問題。
- 範圍：允許看哪些目錄、改哪些模組。
- 限制：不要改什麼、不要跑什麼高風險命令。
- 驗收：需要跑哪些測試、輸出什麼證據。

示例：

```text
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` | 只讀理解專案 |

```bash
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 和測試驗收。

可以直接這樣開場：

```text
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` 釋放空間。

```text
@src/auth @tests/auth
Explain how login tokens are validated. Do not edit files.
```

上下文選擇的原則：

1. 先給直接相關檔案。
2. 再給規則、測試、日誌和錯誤輸出。
3. 不要把整個儲存庫無差別塞進去。
4. 長任務中途用 `/compress`，但壓縮前確認關鍵約束已經寫清楚。

## 7. Worktree 隔離

官方支援 `--worktree`，讓 Agent 在新的 Git worktree 裡工作，而不是直接改當前 checkout。

```bash
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 可以列出和恢復會話：

```bash
agent ls
agent resume
agent --continue
agent --resume="chat-id-here"
```

恢復會話適合繼續同一條問題鏈。不要把完全不同的任務塞進舊會話，否則歷史上下文會干擾判斷。

## 9. Command approval 和非互動模式

互動模式下，CLI 在執行終端命令前會詢問 approve 或 reject。

非互動模式用 `-p` 或 `--print`：

```bash
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：

```text
& refactor the auth module and add comprehensive tests
```

建議只把這類任務交給 Cloud Agent：

- 範圍清楚。
- 驗收命令清楚。
- 允許修改的檔案邊界清楚。
- 不依賴本機私有登入態或不可複製環境。

否則它可能在雲端跑很久，最後產出一組無法復現的改動。

<details>
<summary>深讀：一次好的 CLI 任務應該長什麼樣</summary>

好的 CLI 任務不是命令很短，而是上下文足夠明確。它應該告訴 Agent 當前目標、禁止動作、允許修改範圍、驗證命令和最終輸出格式。

對於真實專案，建議先用 Ask mode 獲取現狀，再用 Plan mode 固定方案，最後再進入 Agent mode 修改。這個順序慢一點，但能顯著降低誤改和無效 diff。
</details>

## 本章自檢

完成本章後，用這 3 個問題檢查自己是否真正理解：

1. `@`、`/compress` 和 rules 檔案分別解決什麼上下文問題？
2. 為什麼當前工作區有未提交改動時應該優先考慮 `--worktree`？
3. 非互動模式接入 CI 前必須如何限制許可權和輸出？

透過標準：你能用 CLI 完成一次 Ask、一次 Plan、一次 Agent 修改，並透過 Ctrl+R、git diff 和測試命令驗收。

## 官方來源

- [Using Agent in CLI](https://cursor.com/docs/cli/using.md) —— 官方說明模式、prompting、MCP、ACP、rules、快捷鍵、review、上下文選擇、Cloud handoff、worktrees、history、command approval 和 non-interactive mode。
- [Cursor CLI Overview](https://cursor.com/docs/cli/overview.md) —— 官方說明 CLI 總體入口、sessions、sandbox 和 handoff。
- [Terminal Setup](https://cursor.com/docs/cli/reference/terminal-setup.md) —— 官方終端快捷鍵配置和相容性說明。
- [Cursor Worktrees](https://cursor.com/docs/configuration/worktrees.md) —— 官方 worktree 位置、清理和相關限制說明。

## 接下來去哪

<Cards>
  <Card title="Shell Mode" description="繼續學習 CLI 中 shell 命令執行和命令審批邊界。" href="/zh-Hant/docs/cursor/official/03-cli-automation/33-shell-mode" />
  <Card title="Headless" description="繼續學習 non-interactive/headless 自動化。" href="/zh-Hant/docs/cursor/official/03-cli-automation/35-headless" />
</Cards>
