---
title: "Cursor CLI 總覽"
description: "基於 Cursor 官方 CLI 文件解釋互動模式、非互動模式、Cloud Agent handoff、session 恢復、sandbox 和上線驗收邊界。"
verifiedAt: "2026-05-09"
---

Cursor CLI 是把 Cursor Agent 放進終端的入口。它適合兩類場景：人在終端裡互動式改程式碼，以及指令碼、CI、自動化流程裡用 print mode 輸出結果。

> [!NOTE]
> **閱讀目標**：讀完本章，你應該能判斷什麼時候用 `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`。

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

# 进入交互式会话
agent

# 带初始任务进入会话
agent "review the authentication module and explain the risks"
```

Windows 原生 PowerShell 使用單獨安裝入口：

```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` | 適合調研，不適合交付修改 |

```bash
agent --mode=ask "explain how billing is initialized"
agent --plan "plan a safe migration from REST to GraphQL"
```

如果你要把 CLI 教給團隊，先講這三種模式。很多失敗不是 Agent 能力問題，而是把“只讀理解”“方案設計”和“直接改程式碼”混在一起。

## 4. 互動式與非互動式

互動式適合探索、修改和審查：

```bash
agent
agent "fix the failing checkout test and show the diff before finalizing"
```

非互動式適合指令碼、CI 和批處理：

```bash
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 具有寫入許可權，所以上線前要固定三件事：

1. 輸入 prompt：包含範圍、限制、驗收方式。
2. 輸出格式：人工閱讀用 text，機器消費用 json。
3. 失敗處理：退出碼、日誌歸檔、PR 評論或人工 gate。

## 5. CLI 能接哪些能力

Cursor CLI 不是一個孤立 binary。它會複用 Cursor 的多項能力。

```mermaid
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 可以恢復歷史會話：

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

中途把任務交給 Cloud Agent，可以在訊息前加 `&`：

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

這裡的商業級用法是：本地先把任務定義清楚，再交給雲端。不要把半截上下文、未說明許可權的任務直接推到 Cloud Agent，否則回來只會得到一組難審查的改動。

## 7. Sandbox、sudo 和許可權

CLI 可透過 `/sandbox` 或 `--sandbox <mode>` 控制命令執行環境。官方文件當前寫法是 `enabled` 或 `disabled`。

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

<details>
<summary>深讀：為什麼不建議一開始就把 CLI 接進 CI 自動改程式碼</summary>

CI 環境通常缺少完整的人類判斷上下文。它知道測試失敗，但未必知道產品取捨、安全邊界和釋出節奏。

更穩的路線是先讓 CLI 在 CI 裡做只讀審查、總結失敗、生成候選修復建議；等輸出格式、日誌和 review gate 穩定後，再逐步開放更高許可權的自動修復流程。
</details>

## 本章自檢

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

1. `agent -p` 為什麼不等於只讀安全模式？
2. 什麼時候應該用 `--mode=ask` 而不是預設 Agent mode？
3. CLI 自動化上線前必須固定哪三類邊界？

透過標準：你能寫出一份團隊 CLI 使用規則，明確安裝、模式、許可權、輸出格式、日誌和人工審查入口。

## 官方來源

- [Cursor CLI Overview](https://cursor.com/docs/cli/overview.md) —— 官方 CLI 總覽、互動模式、非互動模式、Cloud Agent handoff、sessions、sandbox、Max Mode 和 sudo prompt。
- [Cursor CLI Installation](https://cursor.com/docs/cli/installation.md) —— 官方安裝、PATH、驗證和更新說明。
- [Cursor CLI Using Agent](https://cursor.com/docs/cli/using.md) —— 官方模式、prompting、MCP、ACP、rules、shortcuts、worktrees、history 和 non-interactive mode。

## 接下來去哪

<Cards>
  <Card title="CLI 安裝" description="從安裝、PATH、版本驗證和更新策略開始落地。" href="/zh-Hant/docs/cursor/official/03-cli-automation/31-cli-installation" />
  <Card title="CLI 使用方式" description="繼續學習模式切換、上下文選擇、review、history 和 worktree。" href="/zh-Hant/docs/cursor/official/03-cli-automation/32-cli-using" />
</Cards>
