---
title: "CLI 安裝"
description: "安裝 Cursor CLI、處理 PATH、驗證版本、更新 Agent，並給出團隊和 CI 環境的上線檢查。"
verifiedAt: "2026-05-09"
---

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

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

## 1. 官方安裝命令

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

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

Windows 原生 PowerShell 使用：

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

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

## 2. 驗證是否安裝成功

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

```bash
agent --version
```

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

zsh：

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

bash：

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

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

```bash
which agent
agent --version
agent
```

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

## 3. 第一次執行

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

```bash
agent
```

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

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

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

## 4. 更新策略

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

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

```bash
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 的第一階段建議只做只讀任務：

```bash
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`，並給解析邏輯做相容檢查。

<details>
<summary>深讀：為什麼安裝篇也要講規則檔案</summary>

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

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

## 本章自檢

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

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

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

## 官方來源

- [Cursor CLI Installation](https://cursor.com/docs/cli/installation.md) —— 官方安裝命令、PATH、驗證和更新說明。
- [Cursor CLI Overview](https://cursor.com/docs/cli/overview.md) —— 官方 CLI 入口、模式、sessions、sandbox 和 handoff。
- [Cursor CLI Using Agent](https://cursor.com/docs/cli/using.md) —— 官方規則檔案、MCP、history、non-interactive 和工作流說明。

## 接下來去哪

<Cards>
  <Card title="CLI 使用方式" description="繼續學習實際會話、模式切換、review 和上下文選擇。" href="/zh-Hant/docs/cursor/official/03-cli-automation/32-cli-using" />
  <Card title="Shell Mode" description="繼續看 CLI 中如何執行和約束 shell 命令。" href="/zh-Hant/docs/cursor/official/03-cli-automation/33-shell-mode" />
</Cards>
