CLI 安裝
安裝 Cursor CLI、處理 PATH、驗證版本、更新 Agent，並給出團隊和 CI 環境的上線檢查。
📖 本篇術語速查表
| 英文 / 縮寫 | 中文 | 一句話解釋 |
|---|---|---|
| 安裝 | install | 把 Cursor CLI 裝到系統。 |
| PATH | 環境路徑 | 讓終端能找到 cli 命令。 |
| 版本管理 | version | 更新和鎖定 CLI 版本。 |
不想讀完？把下面這段提示詞丟給 AI 幫你跑完——幫你把 Cursor CLI 裝好、配進 PATH 並驗證可用。
你是 Cursor CLI 安裝顧問，幫我把 CLI 裝好、配進 PATH 並驗證能用。
【角色】
你熟悉 Cursor CLI 在各系統的安裝方式、PATH 設定、版本更新。
【輸入】
- 我的作業系統：___
- 是否有許可權裝全域命令：___
- 是否需要鎖定版本：___
- 遇到的安裝問題：___
【工作流程】
1. 給對應系統的安裝步驟
2. 設定 PATH 讓終端找到命令
3. 驗證安裝成功
4. 說明怎麼更新 / 鎖版本
【輸出規範】
▌一、安裝步驟
▌二、PATH 設定
▌三、驗證可用
▌四、更新 / 鎖版本
【硬約束】
- 步驟按我的系統給
- 全域安裝注意許可權
- 不確定的細節標註需查官方文件
- 給的命令能直接跑
- 驗證步驟明確
- 每條結論落到可照做步驟，不空泛
- 給的每條結論都要落到具體可照做的步驟或示例，不停留在「建議」「考慮一下」這類沒法直接執行的空泛表述安裝 Cursor CLI 的表面動作只有一個命令，但真實交付要確認 shell、PATH、版本、認證、網路和更新策略都可控。
閱讀目標：讀完本章，你應該能在一臺新機器上安裝 agent，並能解釋為什麼終端能找到它、目前版本是什麼、如何更新，以及 CI 裡哪些前置條件不能省。
1. 官方安裝命令
macOS、Linux、WSL 使用官方 install endpoint：
curl https://cursor.com/install -fsS | bashWindows 原生 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 ~/.zshrcbash：
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc驗證順序建議固定成這樣：
which agent
agent --version
agentwhich 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 和工作流說明。