---
title: "Cursor CLI 总览"
description: "基于 Cursor 官方 CLI 文档解释交互模式、非交互模式、Cloud Agent handoff、session 恢复、sandbox 和上线验收边界。"
verifiedAt: "2026-05-09"
---

Cursor CLI 是把 Cursor Agent 放进终端的入口。它适合两类场景：人在终端里交互式改代码，以及脚本、CI、自动化流程里用 print mode 输出结果。

> [!NOTE]
> **阅读目标**：读完本章，你应该能判断什么时候用 `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`。

```bash
# macOS / Linux / WSL
curl https://cursor.com/install -fsS | bash

# 进入交互式会话
agent

# 带初始任务进入会话
agent "review the authentication module and explain the risks"
```

Windows 原生 PowerShell 使用单独安装入口：

```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` | 适合调研，不适合交付修改 |

```bash
agent --mode=ask "explain how billing is initialized"
agent --plan "plan a safe migration from REST to GraphQL"
```

如果你要把 CLI 教给团队，先讲这三种模式。很多失败不是 Agent 能力问题，而是把“只读理解”“方案设计”和“直接改代码”混在一起。

## 4. 交互式与非交互式

交互式适合探索、修改和审查：

```bash
agent
agent "fix the failing checkout test and show the diff before finalizing"
```

非交互式适合脚本、CI 和批处理：

```bash
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 具有写入权限，所以上线前要固定三件事：

1. 输入 prompt：包含范围、限制、验收方式。
2. 输出格式：人工阅读用 text，机器消费用 json。
3. 失败处理：退出码、日志归档、PR 评论或人工 gate。

## 5. CLI 能接哪些能力

Cursor CLI 不是一个孤立 binary。它会复用 Cursor 的多项能力。

```mermaid
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 可以恢复历史会话：

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

中途把任务交给 Cloud Agent，可以在消息前加 `&`：

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

这里的商业级用法是：本地先把任务定义清楚，再交给云端。不要把半截上下文、未说明权限的任务直接推到 Cloud Agent，否则回来只会得到一组难审查的改动。

## 7. Sandbox、sudo 和权限

CLI 可通过 `/sandbox` 或 `--sandbox <mode>` 控制命令执行环境。官方文档当前写法是 `enabled` 或 `disabled`。

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

<details>
<summary>深读：为什么不建议一开始就把 CLI 接进 CI 自动改代码</summary>

CI 环境通常缺少完整的人类判断上下文。它知道测试失败，但未必知道产品取舍、安全边界和发布节奏。

更稳的路线是先让 CLI 在 CI 里做只读审查、总结失败、生成候选修复建议；等输出格式、日志和 review gate 稳定后，再逐步开放更高权限的自动修复流程。
</details>

## 本章自检

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

1. `agent -p` 为什么不等于只读安全模式？
2. 什么时候应该用 `--mode=ask` 而不是默认 Agent mode？
3. CLI 自动化上线前必须固定哪三类边界？

通过标准：你能写出一份团队 CLI 使用规则，明确安装、模式、权限、输出格式、日志和人工审查入口。

## 官方来源

- [Cursor CLI Overview](https://cursor.com/docs/cli/overview.md) —— 官方 CLI 总览、交互模式、非交互模式、Cloud Agent handoff、sessions、sandbox、Max Mode 和 sudo prompt。
- [Cursor CLI Installation](https://cursor.com/docs/cli/installation.md) —— 官方安装、PATH、验证和更新说明。
- [Cursor CLI Using Agent](https://cursor.com/docs/cli/using.md) —— 官方模式、prompting、MCP、ACP、rules、shortcuts、worktrees、history 和 non-interactive mode。

## 接下来去哪

<Cards>
  <Card title="CLI 安装" description="从安装、PATH、版本验证和更新策略开始落地。" href="/docs/cursor/official/03-cli-automation/31-cli-installation" />
  <Card title="CLI 使用方式" description="继续学习模式切换、上下文选择、review、history 和 worktree。" href="/docs/cursor/official/03-cli-automation/32-cli-using" />
</Cards>
