---
title: "Cursor CLI 与 Headless 自动化"
description: "把 Cursor Agent 从编辑器带到终端、脚本、CI 和受控自动化。"
verifiedAt: "2026-05-09"
---

Cursor CLI 的价值不是"换个地方聊天"，而是把 Agent 放进 terminal、git、scripts、CI、PR review 和自动化流水线。Headless（无界面 / 非交互）模式更进一步，让任务可以非交互执行。边界也更严格：非交互越多，权限、输出和回退越要明确。

> [!NOTE]
> **本章目标**：你会判断什么时候用编辑器 Agent，什么时候用 CLI，什么时候进入 headless，并能写出可审计的只读脚本和小范围写入脚本。

## 1. 安装与第一次启动

官方安装命令：

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

# Windows PowerShell
irm 'https://cursor.com/install?win32=true' | iex

# 安装完成后直接启动交互
agent
```

`agent` 是 Cursor CLI 的可执行命令。第一次启动会要求登录，认证完毕后即可在终端直接对话。

> [!WARNING]
> **企业 / 安全敏感环境**：`curl ... \| bash` 模式直接执行远程脚本，部分公司安全策略禁止。建议先 `curl https://cursor.com/install -fsS -o /tmp/cursor-install.sh` 下载脚本审查，再 `bash /tmp/cursor-install.sh`，或通过内部软件分发系统下发。Cursor 也有 macOS / Windows 桌面版安装包可选，CLI 是可选项。

## 2. CLI 适合什么

编辑器适合边看代码边协作；CLI 适合贴近工程命令和自动化系统。

CLI 适合：

- 终端里快速问项目结构。
- 对当前 git diff 做只读 review。
- 批量生成报告。
- 在 CI 中输出检查结果。
- 通过 script 固定 prompt 和 output format。
- 把任务 handoff 到 Cloud Agent。

不适合：

- 需要大量视觉交互的 UI 调整。
- 需要人工逐步审查的复杂改动却没有 review gate。
- 生产部署、删除、数据库迁移这类高风险自动写入。

## 3. 三种模式仍然重要

Cursor CLI 支持 Agent、Plan、Ask。和编辑器一样，模式决定风险。

```bash
agent --mode=ask "explain how billing is initialized"
agent --plan "plan a safe migration from REST to GraphQL"
agent "fix the failing checkout parser test and show the diff"
```

判断：

- 只读理解：`--mode=ask`。
- 复杂任务先方案：`--plan` 或 `--mode=plan`。
- 明确小任务：默认 Agent。

很多 CLI 事故来自把 Ask 任务用 Agent 执行，或者把 Plan 任务直接写入。

### 把任务推到 Cloud Agent（mid-conversation handoff）

在交互会话中，把消息开头加 `&` 可以把任务推到 Cloud Agent 继续跑——本地终端关掉它也不会停。适合长任务边喝咖啡边跑：

```text
& 把整个 auth module 重构为 JWT，并补完整测试
```

跑起来之后可以在 [cursor.com/agents](https://cursor.com/agents) 网页端或移动端继续跟进。

### 恢复历史会话（Sessions）

```bash
agent ls                  # 列所有历史对话
agent resume              # 恢复最近一个
agent --continue          # 继续上一个会话
agent --resume="chat-id"  # 指定 chat id 恢复
```

会话恢复保留了完整上下文，适合长任务跨天继续，或者本地切到不同终端窗口接着干。

## 4. Headless 是自动化入口，不是无监管入口

Headless 的核心是 print mode（打印模式，非交互输出到 stdout 而非进入 REPL）：`agent -p` 或 `agent --print`。它适合 scripts、CI、批处理和自动报告。

只读示例：

```bash
agent -p --output-format text \
  "Review the current git diff for correctness and security risks. Do not edit files."
```

可写示例需要显式边界：

```bash
agent -p --force --output-format text \
  "Only edit src/public-api.ts. Add missing JSDoc for exported functions. Do not edit any other file."
```

关键点：

- `agent -p` 适合输出建议或报告。
- 写入脚本必须显式使用 `--force` 或 `--yolo`（you-only-live-once，跳过所有确认的极简写入开关，比 `--force` 更激进），并限制文件范围。
- 只读脚本要明确写 `Do not edit files`。
- 写入脚本前检查 git 工作区。

## 5. 输出格式决定能否自动化

官方 Headless 文档支持 text、json、stream-json：

| 格式 | 何时用 |
|---|---|
| `text` | 人读摘要 / PR 评论 / 日志摘要 |
| `json` | 机器解析最终结果，schema 由 prompt 锁死 |
| `stream-json` | 长任务实时进度 / 工具调用流，适合需要边跑边渲染的 UI |

机器消费不要靠字符串截取。要么要求 JSON schema，要么用 `jq` 或正式 parser 处理。

```bash
agent -p --output-format json \
  "Return exactly JSON with keys: findings, riskLevel, recommendedCommands."
```

## 6. 只读审查脚本

第一阶段建议只做 review，不写文件。

```bash
#!/usr/bin/env bash
set -euo pipefail

agent -p --output-format text \
  "Review the current git diff for:
  - correctness risks
  - security risks
  - missing tests

  Do not edit files.
  Return concise findings with file paths when possible."
```

这个脚本适合放在本地 pre-review、人工触发的 CI job 或 PR 辅助评论。它的价值是稳定产出风险清单，而不是替代测试。

## 7. 小范围写入脚本

写入必须更严格。

```bash
#!/usr/bin/env bash
set -euo pipefail

test -z "$(git status --short)"

agent -p --force --output-format text \
  "Only edit src/public-api.ts.
  Add JSDoc comments to exported functions.
  Do not change runtime behavior.
  After editing, summarize exact changes."

git diff -- src/public-api.ts
```

上线标准：

- 工作区干净。
- 文件范围固定。
- 禁止触碰 secrets、lockfile、配置和无关模块。
- 运行后展示 diff。
- 跑 focused test、lint 或 build。
- 失败时能丢弃分支或 revert commit。

## 8. GitHub Actions：先 restricted autonomy

官方 GitHub Actions 文档有 full autonomy 和 restricted autonomy 两种思路。

生产 CI 默认用 restricted autonomy：

- Agent 负责分析和有限文件修改。
- deterministic workflow step（确定性工作流步骤，命令行为可预测、不依赖 AI 推理的固定 step）负责 branch、commit、push、PR comment。
- `CURSOR_API_KEY` 只走 GitHub Secrets。
- permissions 明确 allow / deny。
- 默认 deny `Shell(git)`、`Shell(gh)` 和 `.env*` 写入。

不要一开始就让 Agent 在 CI 里同时负责理解问题、修改文件、提交、推送和评论 PR。职责拆开，日志和回退才清楚。

## 9. 商业级上线清单

把 CLI / headless 放进团队流程前，确认：

- 安装来源、PATH、版本验证可复现。
- 本地、CI、团队成员的认证边界分开。
- Ask、Plan、Agent 使用场景写清楚。
- `agent -p` 默认只读。
- 写入脚本要求干净 Git 工作区。
- 输出格式固定，机器消费用 JSON。
- CI secrets 不进日志和 prompt。
- Git / gh / deploy 由 deterministic step 执行。
- 每个自动化都有日志、退出码和人工 gate。

## 官方来源

- [Cursor CLI Overview](https://cursor.com/docs/cli/overview.md)：官方 CLI 总览、interactive / print mode、Cloud Agent handoff、sessions、sandbox 和 sudo prompt。
- [Using Headless CLI](https://cursor.com/docs/cli/headless.md)：官方 print mode、`--force` / `--yolo`、输出格式、API key 和脚本示例。
- [Cursor GitHub Actions](https://cursor.com/docs/cli/github-actions.md)：官方 CI 安装、`CURSOR_API_KEY`、full autonomy、restricted autonomy 和 permissions。
- [Cursor CLI Output Format](https://cursor.com/docs/cli/reference/output-format.md)：官方 text、json、stream-json 输出格式。

## 接下来去哪

<Cards>
  <Card title="上一篇" description="先把 Skills、Subagents 和 Hooks 的边界分清。" href="/docs/cursor/understanding/07-skills-subagents-hooks" />
  <Card title="下一篇" description="继续理解 Cloud Agent、Bugbot 和 Review 的团队流程。" href="/docs/cursor/understanding/09-cloud-agent-bugbot-review" />
  <Card title="官方 Headless" description="查看官方重组页里的 headless 脚本与输出格式。" href="/docs/cursor/official/03-cli-automation/35-headless" />
</Cards>
