Cursor CLI 总览
基于 Cursor 官方 CLI 文档解释交互模式、非交互模式、Cloud Agent handoff、session 恢复、sandbox 和上线验收边界。
Cursor CLI 是把 Cursor Agent 放进终端的入口。它适合两类场景：人在终端里交互式改代码，以及脚本、CI、自动化流程里用 print mode 输出结果。
阅读目标：读完本章，你应该能判断什么时候用 agent，什么时候继续留在编辑器里，并能为 CLI 自动化设计最小可控边界。
1. Cursor CLI 解决什么问题
编辑器里的 Agent 适合边看文件边修改；CLI 适合贴近 shell、仓库和自动化系统。
| 场景 | 更适合的入口 | 原因 |
|---|---|---|
| 临时理解一段代码 | CLI Ask mode | 不需要打开完整编辑器，也不应该写文件 |
| 修改本地项目 | CLI Agent mode 或编辑器 Agent | 两者都能读写文件，取决于你是否更常在终端工作 |
| 先设计方案 | CLI Plan mode | 先问清楚、产出计划，再决定是否写代码 |
| CI 里做审查 | CLI print mode | 可以固定 prompt、输出格式和失败处理 |
| 长任务离线继续 | Cloud Agent handoff | 把当前任务推到云端继续执行 |
最重要的不是“CLI 更方便”，而是它让 Agent 能进入现有工程链路：terminal、git、scripts、CI、issue、PR 和日志系统。
2. 基本入口
官方给出的最小路径是：安装后运行 agent。
# macOS / Linux / WSL
curl https://cursor.com/install -fsS | bash
# 进入交互式会话
agent
# 带初始任务进入会话
agent "review the authentication module and explain the risks"Windows 原生 PowerShell 使用单独安装入口：
irm 'https://cursor.com/install?win32=true' | iex生产环境不要只记命令。还要记录安装来源、版本号、PATH 位置、认证方式、执行目录和权限模式。
3. 三种工作模式
Cursor CLI 支持与编辑器 Agent 一致的模式。
| Mode | 作用 | 进入方式 | 风险边界 |
|---|---|---|---|
| Agent | 完整工具访问，适合真实编码任务 | 默认模式，不需要额外 flag | 可能写文件、跑命令，需要 review |
| Plan | 先设计方案和澄清问题 | --plan、--mode=plan、/plan、Shift+Tab | 不应急着写代码 |
| Ask | 只读理解项目 | --mode=ask、/ask | 适合调研，不适合交付修改 |
agent --mode=ask "explain how billing is initialized"
agent --plan "plan a safe migration from REST to GraphQL"如果你要把 CLI 教给团队，先讲这三种模式。很多失败不是 Agent 能力问题，而是把“只读理解”“方案设计”和“直接改代码”混在一起。
4. 交互式与非交互式
交互式适合探索、修改和审查：
agent
agent "fix the failing checkout test and show the diff before finalizing"非交互式适合脚本、CI 和批处理：
agent -p "review the current git diff for security issues" --output-format text
agent --print "summarize the failing tests and suggest the next command"非交互式不是低风险模式。官方文档明确说明 non-interactive mode 里 Cursor 具有写入权限，所以上线前要固定三件事：
- 输入 prompt：包含范围、限制、验收方式。
- 输出格式：人工阅读用 text，机器消费用 json。
- 失败处理：退出码、日志归档、PR 评论或人工 gate。
5. CLI 能接哪些能力
Cursor CLI 不是一个孤立 binary。它会复用 Cursor 的多项能力。
flowchart TD
CLI["agent CLI"] --> Modes["Agent / Plan / Ask"]
CLI --> Rules[".cursor/rules + AGENTS.md + CLAUDE.md"]
CLI --> MCP["mcp.json MCP servers"]
CLI --> ACP["agent acp over stdio"]
CLI --> Sessions["agent ls / resume / continue"]
CLI --> Worktree["--worktree isolated checkout"]
CLI --> Cloud["& Cloud Agent handoff"]这也是为什么 CLI 自动化要先做边界设计：它可能读取项目规则、调用 MCP、执行 shell、写代码、恢复历史会话，也可能把任务交给 Cloud Agent。
6. Session 和 Cloud handoff
CLI 可以恢复历史会话：
agent ls
agent resume
agent --continue
agent --resume="chat-id-here"中途把任务交给 Cloud Agent，可以在消息前加 &：
& refactor the auth module and add regression tests这里的商业级用法是：本地先把任务定义清楚，再交给云端。不要把半截上下文、未说明权限的任务直接推到 Cloud Agent，否则回来只会得到一组难审查的改动。
7. Sandbox、sudo 和权限
CLI 可通过 /sandbox 或 --sandbox <mode> 控制命令执行环境。官方文档当前写法是 enabled 或 disabled。
agent --sandbox enabled "run the test suite and diagnose failures"需要 sudo 的命令会触发安全的密码输入提示。这里要坚持一个边界：能不用提权就不用提权；确实需要时，任务说明必须写清楚为什么需要、预期改哪里、失败后如何恢复。
8. 上线验收清单
把 Cursor CLI 放进团队流程前，至少验收这些项：
- 安装可复现：新机器能安装、
agent --version有输出。 - PATH 明确：shell、tmux、CI runner 都能找到
agent。 - 认证清楚：本地、CI、团队成员使用不同凭据边界。
- 模式清楚：Ask、Plan、Agent 的使用场景写进团队 SOP。
- 权限可审计：sandbox、command approval、sudo、MCP 都有默认策略。
- 输出可消费：脚本使用固定
--output-format，日志可追踪。 - 变更可回退：所有写入任务都经过 git diff、测试和 review。
深读：为什么不建议一开始就把 CLI 接进 CI 自动改代码
CI 环境通常缺少完整的人类判断上下文。它知道测试失败，但未必知道产品取舍、安全边界和发布节奏。
更稳的路线是先让 CLI 在 CI 里做只读审查、总结失败、生成候选修复建议；等输出格式、日志和 review gate 稳定后，再逐步开放更高权限的自动修复流程。
本章自检
完成本章后，用这 3 个问题检查自己是否真正理解：
agent -p为什么不等于只读安全模式？- 什么时候应该用
--mode=ask而不是默认 Agent mode？ - CLI 自动化上线前必须固定哪三类边界？
通过标准：你能写出一份团队 CLI 使用规则，明确安装、模式、权限、输出格式、日志和人工审查入口。
官方来源
- Cursor CLI Overview —— 官方 CLI 总览、交互模式、非交互模式、Cloud Agent handoff、sessions、sandbox、Max Mode 和 sudo prompt。
- Cursor CLI Installation —— 官方安装、PATH、验证和更新说明。
- Cursor CLI Using Agent —— 官方模式、prompting、MCP、ACP、rules、shortcuts、worktrees、history 和 non-interactive mode。