CLI 使用方式
解释 Cursor CLI 的模式切换、prompting、MCP、ACP、rules、快捷键、review、上下文选择、Cloud handoff、worktree、history 和非交互模式。
Cursor CLI 的使用重点不是背参数，而是把“我要它读什么、能改什么、怎么验收、失败怎么退”说清楚。
阅读目标：读完本章，你应该能用 CLI 完成一次只读调研、一次计划会话、一次带 review 的修改，并知道什么时候切换到 worktree 或 non-interactive mode。
1. 启动一次会话
最常见入口是直接运行：
agent也可以带初始任务：
agent "find why the checkout tests are failing and propose a fix"真实项目里，初始 prompt 不要只写“修一下”。至少包含四块：
- 目标：要解决什么问题。
- 范围：允许看哪些目录、改哪些模块。
- 限制：不要改什么、不要跑什么高风险命令。
- 验收：需要跑哪些测试、输出什么证据。
示例：
Investigate why the checkout smoke test fails.
Stay within packages/checkout and tests/checkout.
Do not change billing code.
Before editing, summarize the root cause and the files you plan to touch.
After editing, run the focused test and show the git diff.2. 模式切换
CLI 支持 Agent、Plan、Ask 三种模式。
| 模式 | 使用方式 | 适合任务 |
|---|---|---|
| Agent | 默认模式，不需要额外 flag | 真实编码、改文件、跑命令 |
| Plan | /plan、--plan、--mode=plan、Shift+Tab | 先设计方案、澄清问题 |
| Ask | /ask、--mode=ask | 只读理解项目 |
agent --mode=ask "explain how routing works in this app"
agent --plan "design a safe migration for the auth middleware"判断很简单：不知道该不该改，就先 Ask；知道要改但方案不清楚，就先 Plan；范围和验收都清楚，再 Agent。
3. Prompting 和工具边界
官方文档提醒，清楚表达 intent 会得到更好结果。尤其是当你不希望 Agent 写代码时，要明确写出类似 do not write any code 的限制。
Cursor Agent 可使用文件操作、搜索、shell 命令和 web access。CLI 场景里要额外补三条约束：
- shell 命令需要先说明目的。
- 写文件前需要说明预计修改点。
- 所有改动要回到 diff 和测试验收。
可以直接这样开场：
Do not write any code yet.
First inspect the project rules, then summarize the relevant files and propose a 3-step plan.
Ask before making edits.4. MCP、ACP 和 rules
Cursor CLI 会读取与编辑器相同的扩展上下文。
| 能力 | CLI 行为 | 商业级注意点 |
|---|---|---|
| MCP | 自动检测并尊重 mcp.json | 不要把高权限 MCP 默认暴露给自动化 |
| ACP | agent acp 可作为 ACP server 通过 stdio 通信 | 适合自定义 client，需处理 JSON-RPC 边界 |
| Rules | 支持 .cursor/rules | 项目规则应写清楚测试、风格和禁止动作 |
| Compatibility rules | 读取根目录 AGENTS.md 和 CLAUDE.md | 多 Agent 项目要避免规则互相冲突 |
这意味着 CLI 不是“干净无上下文”的命令。它会继承项目规则和工具配置，所以排查异常时也要看这些文件。
5. 输入、快捷键和 review
官方列出的常用交互：
| 操作 | 快捷键或命令 |
|---|---|
| 历史消息 | ArrowUp |
| 模式轮换 | Shift+Tab |
| 多行输入 | Shift+Enter、Ctrl+J 或 Alt+Enter |
| 退出 CLI | Ctrl+D |
| Review changes | Ctrl+R |
| Review 中追加说明 | i |
| Review 中切换文件 | ArrowLeft / ArrowRight |
tmux 用户要特别注意：Shift+Enter 可能不稳定，官方建议必要时使用 Ctrl+J，并参考 Terminal Setup。
Review 是 CLI 修改任务的关键环节。不要只看 Agent 的总结，要进入 review 看每个文件的 diff，再决定是否继续。
6. 选择上下文和压缩上下文
在 CLI 里可以用 @ 选择文件和目录放入上下文。上下文太满时，用 /compress 释放空间。
@src/auth @tests/auth
Explain how login tokens are validated. Do not edit files.上下文选择的原则：
- 先给直接相关文件。
- 再给规则、测试、日志和错误输出。
- 不要把整个仓库无差别塞进去。
- 长任务中途用
/compress，但压缩前确认关键约束已经写清楚。
7. Worktree 隔离
官方支持 --worktree，让 Agent 在新的 Git worktree 里工作，而不是直接改当前 checkout。
agent --worktree "upgrade the test runner and fix broken snapshots"
agent --workspace ~/src/my-app --worktree "fix the flaky auth test and open a PR"Cursor CLI worktrees 默认位于 ~/.cursor/worktrees。适合这些情况：
- 你当前工作区有未提交改动。
- 要让 Agent 做较大改动，但不想污染主 checkout。
- 同时跑多个候选方案。
- 需要把风险任务和日常开发隔离。
不适合这些情况：
- 任务必须直接基于当前未提交改动。
- 你还不熟悉 worktree 清理规则。
- 项目里有不支持多 checkout 的本地服务或锁文件。
8. History 和恢复
CLI 可以列出和恢复会话：
agent ls
agent resume
agent --continue
agent --resume="chat-id-here"恢复会话适合继续同一条问题链。不要把完全不同的任务塞进旧会话，否则历史上下文会干扰判断。
9. Command approval 和非交互模式
交互模式下，CLI 在执行终端命令前会询问 approve 或 reject。
非交互模式用 -p 或 --print：
agent -p "review this diff for security issues. Do not edit files." --output-format text
agent --print "summarize test failures as JSON" --output-format json官方文档提醒：non-interactive mode 中 Cursor 具有完整写入权限。所以自动化里必须把“不写文件”“只审查”“只输出 JSON”等限制写进 prompt，并用权限、runner、git diff 和 review gate 双重兜底。
10. Cloud Agent handoff
在会话里用 & 可以把任务推给 Cloud Agent：
& refactor the auth module and add comprehensive tests建议只把这类任务交给 Cloud Agent：
- 范围清楚。
- 验收命令清楚。
- 允许修改的文件边界清楚。
- 不依赖本机私有登录态或不可复制环境。
否则它可能在云端跑很久，最后产出一组无法复现的改动。
深读：一次好的 CLI 任务应该长什么样
好的 CLI 任务不是命令很短，而是上下文足够明确。它应该告诉 Agent 当前目标、禁止动作、允许修改范围、验证命令和最终输出格式。
对于真实项目，建议先用 Ask mode 获取现状，再用 Plan mode 固定方案，最后再进入 Agent mode 修改。这个顺序慢一点，但能显著降低误改和无效 diff。
本章自检
完成本章后，用这 3 个问题检查自己是否真正理解：
@、/compress和 rules 文件分别解决什么上下文问题？- 为什么当前工作区有未提交改动时应该优先考虑
--worktree？ - 非交互模式接入 CI 前必须如何限制权限和输出？
通过标准：你能用 CLI 完成一次 Ask、一次 Plan、一次 Agent 修改，并通过 Ctrl+R、git diff 和测试命令验收。
官方来源
- Using Agent in CLI —— 官方说明模式、prompting、MCP、ACP、rules、快捷键、review、上下文选择、Cloud handoff、worktrees、history、command approval 和 non-interactive mode。
- Cursor CLI Overview —— 官方说明 CLI 总体入口、sessions、sandbox 和 handoff。
- Terminal Setup —— 官方终端快捷键配置和兼容性说明。
- Cursor Worktrees —— 官方 worktree 位置、清理和相关限制说明。