---
title: "CLI 使用方式"
description: "解释 Cursor CLI 的模式切换、prompting、MCP、ACP、rules、快捷键、review、上下文选择、Cloud handoff、worktree、history 和非交互模式。"
verifiedAt: "2026-05-09"
---

Cursor CLI 的使用重点不是背参数，而是把“我要它读什么、能改什么、怎么验收、失败怎么退”说清楚。

> [!NOTE]
> **阅读目标**：读完本章，你应该能用 CLI 完成一次只读调研、一次计划会话、一次带 review 的修改，并知道什么时候切换到 worktree 或 non-interactive mode。

## 1. 启动一次会话

最常见入口是直接运行：

```bash
agent
```

也可以带初始任务：

```bash
agent "find why the checkout tests are failing and propose a fix"
```

真实项目里，初始 prompt 不要只写“修一下”。至少包含四块：

- 目标：要解决什么问题。
- 范围：允许看哪些目录、改哪些模块。
- 限制：不要改什么、不要跑什么高风险命令。
- 验收：需要跑哪些测试、输出什么证据。

示例：

```text
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` | 只读理解项目 |

```bash
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 和测试验收。

可以直接这样开场：

```text
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` 释放空间。

```text
@src/auth @tests/auth
Explain how login tokens are validated. Do not edit files.
```

上下文选择的原则：

1. 先给直接相关文件。
2. 再给规则、测试、日志和错误输出。
3. 不要把整个仓库无差别塞进去。
4. 长任务中途用 `/compress`，但压缩前确认关键约束已经写清楚。

## 7. Worktree 隔离

官方支持 `--worktree`，让 Agent 在新的 Git worktree 里工作，而不是直接改当前 checkout。

```bash
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 可以列出和恢复会话：

```bash
agent ls
agent resume
agent --continue
agent --resume="chat-id-here"
```

恢复会话适合继续同一条问题链。不要把完全不同的任务塞进旧会话，否则历史上下文会干扰判断。

## 9. Command approval 和非交互模式

交互模式下，CLI 在执行终端命令前会询问 approve 或 reject。

非交互模式用 `-p` 或 `--print`：

```bash
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：

```text
& refactor the auth module and add comprehensive tests
```

建议只把这类任务交给 Cloud Agent：

- 范围清楚。
- 验收命令清楚。
- 允许修改的文件边界清楚。
- 不依赖本机私有登录态或不可复制环境。

否则它可能在云端跑很久，最后产出一组无法复现的改动。

<details>
<summary>深读：一次好的 CLI 任务应该长什么样</summary>

好的 CLI 任务不是命令很短，而是上下文足够明确。它应该告诉 Agent 当前目标、禁止动作、允许修改范围、验证命令和最终输出格式。

对于真实项目，建议先用 Ask mode 获取现状，再用 Plan mode 固定方案，最后再进入 Agent mode 修改。这个顺序慢一点，但能显著降低误改和无效 diff。
</details>

## 本章自检

完成本章后，用这 3 个问题检查自己是否真正理解：

1. `@`、`/compress` 和 rules 文件分别解决什么上下文问题？
2. 为什么当前工作区有未提交改动时应该优先考虑 `--worktree`？
3. 非交互模式接入 CI 前必须如何限制权限和输出？

通过标准：你能用 CLI 完成一次 Ask、一次 Plan、一次 Agent 修改，并通过 Ctrl+R、git diff 和测试命令验收。

## 官方来源

- [Using Agent in CLI](https://cursor.com/docs/cli/using.md) —— 官方说明模式、prompting、MCP、ACP、rules、快捷键、review、上下文选择、Cloud handoff、worktrees、history、command approval 和 non-interactive mode。
- [Cursor CLI Overview](https://cursor.com/docs/cli/overview.md) —— 官方说明 CLI 总体入口、sessions、sandbox 和 handoff。
- [Terminal Setup](https://cursor.com/docs/cli/reference/terminal-setup.md) —— 官方终端快捷键配置和兼容性说明。
- [Cursor Worktrees](https://cursor.com/docs/configuration/worktrees.md) —— 官方 worktree 位置、清理和相关限制说明。

## 接下来去哪

<Cards>
  <Card title="Shell Mode" description="继续学习 CLI 中 shell 命令执行和命令审批边界。" href="/docs/cursor/official/03-cli-automation/33-shell-mode" />
  <Card title="Headless" description="继续学习 non-interactive/headless 自动化。" href="/docs/cursor/official/03-cli-automation/35-headless" />
</Cards>
