---
title: "CLI 引數"
description: "基於 Cursor 官方 Parameters 參考解釋全域性引數、commands、MCP 子命令、prompt 引數和常用組合。"
verifiedAt: "2026-05-09"
---

CLI 引數是把 Cursor Agent 從“人手動聊天”變成“可重複命令”的關鍵。這裡重點不是背全表，而是知道哪些引數會改變許可權、輸出、認證和工作區。

> [!NOTE]
> **閱讀目標**：讀完本章，你應該能選擇 `--mode`、`--print`、`--output-format`、`--force`、`--sandbox`、`--workspace`、`--worktree` 等引數，並能組合出安全的指令碼入口。

## 1. 全域性引數分組

| 分組 | 引數 |
| --- | --- |
| 版本和幫助 | `-v, --version`、`-h, --help` |
| 認證 | `--api-key <key>`、環境變數 `CURSOR_API_KEY` |
| 請求定製 | `-H, --header <header>` |
| 非互動 | `-p, --print`、`--output-format <format>`、`--stream-partial-output` |
| 會話恢復 | `--resume [chatId]`、`--continue` |
| 模型和模式 | `--model <model>`、`--mode <mode>`、`--plan`、`--list-models` |
| 許可權 | `-f, --force`、`--yolo`、`--sandbox <mode>`、`--approve-mcps`、`--trust` |
| 工作區 | `--workspace <path>`、`--worktree` |

官方引數頁明確：`--mode <mode>` 當前設定 `plan` 或 `ask`；Agent 是預設模式，不需要寫 `--mode=agent`。

## 2. 非互動引數

```bash
agent -p "Review the current diff. Do not edit files."
agent -p --output-format json "Return risks as JSON"
agent -p --output-format stream-json --stream-partial-output "Analyze the project"
```

引數含義：

| 引數 | 用途 |
| --- | --- |
| `-p, --print` | 輸出到 console，適合 scripts / non-interactive |
| `--output-format text` | 預設格式，適合人讀 |
| `--output-format json` | 適合機器解析最終結果 |
| `--output-format stream-json` | 適合即時進度和工具呼叫流 |
| `--stream-partial-output` | 在 `stream-json` 下輸出增量文本 delta |

指令碼里不要用自然語言 text 做強解析。需要機器消費就用 JSON。

## 3. 許可權引數

| 引數 | 作用 | 風險 |
| --- | --- | --- |
| `-f, --force` | 除非明確 deny，否則強制允許命令 | 可能放大寫入和 shell 風險 |
| `--yolo` | `--force` alias | 語義上更適合實驗，不適合作預設生產入口 |
| `--sandbox enabled` | 啟用 sandbox | 更安全，可能限制部分命令 |
| `--sandbox disabled` | 關閉 sandbox | 高風險，需說明理由 |
| `--approve-mcps` | 自動批准 MCP servers | 可能暴露外部工具能力 |
| `--trust` | headless mode 中信任 workspace | 只用於受控儲存庫和 runner |

生產指令碼里先問一句：這條引數會不會讓 Agent 更容易寫檔案、跑命令、訪問網路或連線外部系統？如果會，就需要額外審計。

## 4. 工作區和 worktree

```bash
agent --workspace ~/src/my-app "Explain project structure"
agent --workspace ~/src/my-app --worktree "Fix the flaky auth test"
```

| 引數 | 用途 |
| --- | --- |
| `--workspace <path>` | 明確 workspace directory |
| `--worktree` | 在 `~/.cursor/worktrees` 下新建 Git worktree 執行 |

當前 shell 所在目錄不可靠時，用 `--workspace`。當前 checkout 有未提交改動、任務風險較大或要並行試方案時，用 `--worktree`。

## 5. 常用 commands

| Command | 用途 |
| --- | --- |
| `agent login` | 登入 Cursor |
| `agent logout` | 登出並清除認證 |
| `agent status` / `agent whoami` | 檢視認證狀態 |
| `agent about` | 檢視版本、系統和賬號資訊 |
| `agent models` | 列出可用模型 |
| `agent mcp` | 管理 MCP servers |
| `agent acp` | 啟動 ACP server，高階整合 |
| `agent update` | 更新 Cursor Agent |
| `agent ls` | 列出歷史會話 |
| `agent resume` | 恢復最近會話 |
| `agent create-chat` | 建立空會話並返回 ID |
| `agent generate-rule` / `agent rule` | 互動式生成 Cursor rule |
| `agent install-shell-integration` | 安裝 shell integration 到 `~/.zshrc` |
| `agent uninstall-shell-integration` | 移除 shell integration |
| `agent help [command]` | 檢視命令幫助 |

`agent acp` 是自定義 ACP client 和高階整合入口，預設幫助中隱藏，不適合作為普通使用者起步命令。

## 6. MCP 子命令

| Subcommand | 用途 |
| --- | --- |
| `agent mcp login <identifier>` | 登入 `.cursor/mcp.json` 中配置的 MCP server |
| `agent mcp list` | 列出 MCP servers 和狀態 |
| `agent mcp list-tools <identifier>` | 檢視某個 MCP 的工具和引數 |
| `agent mcp enable <identifier>` | 啟用 MCP server |
| `agent mcp disable <identifier>` | 停用 MCP server |

所有 MCP 子命令都支援 `-h, --help`。啟用 MCP 前先看 `list-tools`，知道它能做什麼，再決定是否開放給當前任務。

## 7. 常用組合

只讀審查：

```bash
agent -p --mode=ask --output-format text \
  "Review the current diff for security risks. Do not edit files."
```

計劃模式：

```bash
agent --plan "Plan a safe migration for the billing webhook"
```

明確 workspace：

```bash
agent --workspace ~/src/my-app --mode=ask "Summarize the routing architecture"
```

隔離修改：

```bash
agent --workspace ~/src/my-app --worktree \
  "Fix the flaky auth test and run the focused test"
```

受控寫入指令碼：

```bash
agent -p --force --output-format text \
  "Only edit docs/**/*.md. Do not commit or push."
```

## 8. 失敗排查

- 引數不確定：先跑 `agent help [command]`。
- 模型不可用：跑 `agent models` 或回到官方 Models & Pricing。
- 認證失敗：跑 `agent status` / `agent whoami`。
- MCP 不工作：跑 `agent mcp list`，再看 `list-tools`。
- 輸出難解析：改用 `--output-format json`。
- 寫錯工作區：顯式加 `--workspace <path>`。

<details>
<summary>深讀：為什麼引數頁要和許可權頁一起讀</summary>

引數不是純輸入選項。`--force`、`--sandbox`、`--approve-mcps`、`--trust` 都會改變 Agent 的實際操作邊界。

如果團隊只複製命令，不理解這些引數，會把“方便”誤當成“安全”。上線指令碼必須把許可權引數寫進 review checklist。
</details>

## 本章自檢

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

1. 為什麼預設 Agent mode 不需要 `--mode=agent`？
2. `--workspace` 和 `--worktree` 分別解決什麼問題？
3. 哪些引數會顯著擴大許可權邊界？

透過標準：你能為只讀審查、隔離修改、CI 寫入和 MCP 除錯各寫一條命令，並解釋每個引數的作用。

## 官方來源

- [Cursor CLI Parameters](https://cursor.com/docs/cli/reference/parameters.md) —— 官方全域性引數、commands、MCP 子命令、arguments 和 help 說明。
- [Using Agent in CLI](https://cursor.com/docs/cli/using.md) —— 官方 CLI 使用背景。
- [Cursor CLI Permissions](https://cursor.com/docs/cli/reference/permissions.md) —— 官方許可權引數背景。
- [Cursor Worktrees](https://cursor.com/docs/configuration/worktrees.md) —— 官方 worktree 說明。

## 接下來去哪

<Cards>
  <Card title="認證" description="繼續學習 login、API key、auth token 和 CI 認證邊界。" href="/zh-Hant/docs/cursor/official/03-cli-automation/39-authentication" />
  <Card title="輸出格式" description="繼續學習 text、json、stream-json 的指令碼消費方式。" href="/zh-Hant/docs/cursor/official/03-cli-automation/42-output-format" />
</Cards>
