CLI 安裝

安裝 Cursor CLI 的表面動作只有一個命令，但真實交付要確認 shell、PATH、版本、認證、網路和更新策略都可控。

閱讀目標：讀完本章，你應該能在一臺新機器上安裝 agent，並能解釋為什麼終端能找到它、當前版本是什麼、如何更新，以及 CI 裡哪些前置條件不能省。

1. 官方安裝命令

macOS、Linux、WSL 使用官方 install endpoint：

curl https://cursor.com/install -fsS | bash

Windows 原生 PowerShell 使用：

irm 'https://cursor.com/install?win32=true' | iex

這兩個入口來自 Cursor 官方文件。企業或受管機器上，如果安全策略不允許直接執行遠端指令碼，可以先讓安全負責人審查安裝指令碼，再透過內部軟體分發系統下發。

2. 驗證是否安裝成功

安裝後先驗證二進位制是否可用。

agent --version

如果提示 command not found，不要急著重灌，先檢查 PATH。官方文件要求把 ~/.local/bin 放進 PATH。

zsh：

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

bash：

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

驗證順序建議固定成這樣：

which agent
agent --version
agent

which agent 解決“到底執行的是哪個 binary”，agent --version 解決“版本是否可記錄”，最後再進入互動會話。

3. 第一次執行

第一次執行使用互動式入口：

agent

不要一上來就讓它改專案。第一次執行只做三件事：

確認 CLI 能啟動。
確認認證流程能完成。
確認當前 shell 能正確輸入、換行和退出。

退出可用 Ctrl+D。如果終端對 Shift+Enter 支援不好，後續在使用篇裡再配置 terminal setup。

4. 更新策略

官方文件說明 Cursor CLI 預設會嘗試自動更新。手動更新命令是：

agent update

個人機器可以接受自動更新；團隊環境建議記錄兩類資訊：

專案	個人機器	團隊/CI
更新節奏	預設自動更新即可	版本升級前先跑 smoke test
版本記錄	`agent --version` 截圖或日誌	寫進 runner 映象、devcontainer 或機器基線
回退方式	重灌舊版本或等待修復	保留上一個可用 runner 映象

CLI 更新會影響命令引數、輸出格式、模型可用性和許可權預設值。凡是接進 CI 或自動化的流程，都要把版本變化當成釋出風險處理。

5. 團隊安裝基線

團隊裡不要只發一句安裝命令，至少寫清楚這些約束：

支援平臺：macOS、Linux、WSL、Windows native。
推薦 shell：zsh 或 bash，並確認 ~/.local/bin 在 PATH 前部。
最低驗證：which agent、agent --version、agent --mode=ask。
專案規則：CLI 會讀取 .cursor/rules，也會讀取專案根目錄的 AGENTS.md 和 CLAUDE.md。
MCP 配置：CLI 會尊重已有 mcp.json，不要把本地私有工具預設帶進 CI。
許可權策略：第一次團隊培訓預設從 Ask mode 和 Plan mode 開始。

agent --mode=ask "read the project rules and summarize what this repository is for"
agent --plan "plan how to add a small smoke test without editing files yet"

這兩條命令適合作為新成員 onboarding，因為它們能同時驗證 CLI、專案規則和模式邊界。

6. CI 和自動化前置條件

把 CLI 放進 CI 前，先確認這些問題都有答案：

檢查項	為什麼重要
runner 能找到 `agent`	PATH 在非互動 shell 中經常不同
認證方式可續期	本地登入態不能直接假設在 CI 存在
輸出格式固定	自動化系統需要穩定解析
許可權預設收緊	CI 裡的寫許可權和 secrets 風險更高
日誌不洩密	prompt、檔案路徑、token、命令輸出可能進入日誌
失敗碼可處理	pipeline 需要明確 pass / fail / needs-review

生產 CI 的第一階段建議只做只讀任務：

agent -p "review the current diff for risky changes. Do not edit files." --output-format text

等日誌、許可權、輸出格式和人工 gate 全部穩定後，再考慮自動修復類任務。

7. 常見安裝問題

agent: command not found

先檢查 ~/.local/bin 是否在 PATH。
開啟新 shell 或 source ~/.zshrc / source ~/.bashrc。
在 tmux、CI、IDE terminal 中分別驗證，因為它們的 shell 初始化檔案可能不同。

agent --version 可用，但 agent 無法正常登入

檢查網路代理、公司防火牆和瀏覽器登入流程。
區分 Cursor app 登入、CLI 登入和團隊策略限制。

版本更新後自動化失敗

先記錄更新前後 agent --version。
回看是否依賴了不穩定的自然語言輸出。
對機器消費結果使用 --output-format json，並給解析邏輯做相容檢查。

深讀：為什麼安裝篇也要講規則檔案

CLI 啟動成功只說明 binary 可用，不說明它在專案裡行為正確。

Cursor CLI 會讀取專案規則和相容規則檔案。對於教程站、企業儲存庫、開源專案來說，規則檔案決定了 Agent 的安全邊界、程式碼風格、測試方式和禁止動作。安裝驗收不檢查規則讀取，就等於只驗證了工具外殼。

本章自檢

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

為什麼 agent --version 比直接執行 agent 更適合做安裝驗收？
為什麼 CI 裡經常需要單獨處理 PATH？
自動更新對自動化流程可能帶來哪些風險？

透過標準：你能在一臺新機器上完成安裝，並留下 which agent、agent --version、PATH 配置和第一次 Ask mode 驗證結果。

官方來源

Cursor CLI Installation —— 官方安裝命令、PATH、驗證和更新說明。
Cursor CLI Overview —— 官方 CLI 入口、模式、sessions、sandbox 和 handoff。
Cursor CLI Using Agent —— 官方規則檔案、MCP、history、non-interactive 和工作流說明。