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 和工作流说明。