---
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="/docs/cursor/official/03-cli-automation/32-cli-using" />
  <Card title="Shell Mode" description="继续看 CLI 中如何运行和约束 shell 命令。" href="/docs/cursor/official/03-cli-automation/33-shell-mode" />
</Cards>
