CLI 引數

📖 本篇術語速查表

英文 / 縮寫	中文	一句話解釋
CLI 引數	args	控制 CLI 行為的命令列引數。
許可權引數	permission	控制 sandbox / approval 的引數。
設定覆蓋	override	臨時覆蓋設定的引數。

不想讀完？把下面這段提示詞丟給 AI 幫你跑完——幫你用對 Cursor CLI 引數（許可權優先、臨時覆蓋）。

你是 Cursor CLI 引數設定顧問，幫我用對啟動引數，許可權先管住、臨時需求用覆蓋。

【角色】
你清楚 CLI 引數的分類、許可權引數優先、怎麼臨時覆蓋設定、怎麼組合最常用引數。

【輸入】
- 我要跑的任務和風險：___
- 臨時一次還是常用：___
- 對許可權的要求：___
- 是否多場景：___

【工作流程】
1. 按用途歸類要用的引數
2. 先定許可權引數
3. 臨時需求用覆蓋
4. 常用組合固化

【輸出規範】
▌一、引數用途歸類
▌二、許可權引數設定
▌三、臨時覆蓋用法
▌四、常用組合

【硬約束】
- 許可權引數預設最小
- 臨時放開用覆蓋，不輕易改全域
- 不確定的引數標註需查官方文件
- 給的引數能直接用
- 高危引數提醒
- 每條結論落到可照做步驟，不空泛
- 給的每條結論都要落到具體可照做的步驟或示例，不停留在「建議」「考慮一下」這類沒法直接執行的空泛表述
- 不確定的引數、設定或格式一律以官方文件為準，給的示例標註適用版本，避免照搬過時寫法誤導

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

閱讀目標：讀完本章，你應該能選擇 --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. 非互動引數

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

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. 常用組合

只讀審查：

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

計劃模式：

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

明確 workspace：

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

隔離修改：

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

受控寫入指令碼：

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

深讀：為什麼引數頁要和許可權頁一起讀

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

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

本章自檢

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

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

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

官方來源

Cursor CLI Parameters —— 官方全域引數、commands、MCP 子命令、arguments 和 help 說明。
Using Agent in CLI —— 官方 CLI 使用背景。
Cursor CLI Permissions —— 官方許可權引數背景。
Cursor Worktrees —— 官方 worktree 說明。