---
title: "CLI 参数"
description: "基于 Cursor 官方 Parameters 参考解释全局参数、commands、MCP 子命令、prompt 参数和常用组合。"
verifiedAt: "2026-05-09"
---

CLI 参数是把 Cursor Agent 从“人手动聊天”变成“可重复命令”的关键。这里重点不是背全表，而是知道哪些参数会改变权限、输出、认证和工作区。

> [!NOTE]
> **阅读目标**：读完本章，你应该能选择 `--mode`、`--print`、`--output-format`、`--force`、`--sandbox`、`--workspace`、`--worktree` 等参数，并能组合出安全的脚本入口。

## 1. 全局参数分组

| 分组 | 参数 |
| --- | --- |
| 版本和帮助 | `-v, --version`、`-h, --help` |
| 认证 | `--api-key <key>`、环境变量 `CURSOR_API_KEY` |
| 请求定制 | `-H, --header <header>` |
| 非交互 | `-p, --print`、`--output-format <format>`、`--stream-partial-output` |
| 会话恢复 | `--resume [chatId]`、`--continue` |
| 模型和模式 | `--model <model>`、`--mode <mode>`、`--plan`、`--list-models` |
| 权限 | `-f, --force`、`--yolo`、`--sandbox <mode>`、`--approve-mcps`、`--trust` |
| 工作区 | `--workspace <path>`、`--worktree` |

官方参数页明确：`--mode <mode>` 当前设置 `plan` 或 `ask`；Agent 是默认模式，不需要写 `--mode=agent`。

## 2. 非交互参数

```bash
agent -p "Review the current diff. Do not edit files."
agent -p --output-format json "Return risks as JSON"
agent -p --output-format stream-json --stream-partial-output "Analyze the project"
```

参数含义：

| 参数 | 用途 |
| --- | --- |
| `-p, --print` | 输出到 console，适合 scripts / non-interactive |
| `--output-format text` | 默认格式，适合人读 |
| `--output-format json` | 适合机器解析最终结果 |
| `--output-format stream-json` | 适合实时进度和工具调用流 |
| `--stream-partial-output` | 在 `stream-json` 下输出增量文本 delta |

脚本里不要用自然语言 text 做强解析。需要机器消费就用 JSON。

## 3. 权限参数

| 参数 | 作用 | 风险 |
| --- | --- | --- |
| `-f, --force` | 除非明确 deny，否则强制允许命令 | 可能放大写入和 shell 风险 |
| `--yolo` | `--force` alias | 语义上更适合实验，不适合作默认生产入口 |
| `--sandbox enabled` | 启用 sandbox | 更安全，可能限制部分命令 |
| `--sandbox disabled` | 关闭 sandbox | 高风险，需说明理由 |
| `--approve-mcps` | 自动批准 MCP servers | 可能暴露外部工具能力 |
| `--trust` | headless mode 中信任 workspace | 只用于受控仓库和 runner |

生产脚本里先问一句：这条参数会不会让 Agent 更容易写文件、跑命令、访问网络或连接外部系统？如果会，就需要额外审计。

## 4. 工作区和 worktree

```bash
agent --workspace ~/src/my-app "Explain project structure"
agent --workspace ~/src/my-app --worktree "Fix the flaky auth test"
```

| 参数 | 用途 |
| --- | --- |
| `--workspace <path>` | 明确 workspace directory |
| `--worktree` | 在 `~/.cursor/worktrees` 下新建 Git worktree 运行 |

当前 shell 所在目录不可靠时，用 `--workspace`。当前 checkout 有未提交改动、任务风险较大或要并行试方案时，用 `--worktree`。

## 5. 常用 commands

| Command | 用途 |
| --- | --- |
| `agent login` | 登录 Cursor |
| `agent logout` | 登出并清除认证 |
| `agent status` / `agent whoami` | 查看认证状态 |
| `agent about` | 查看版本、系统和账号信息 |
| `agent models` | 列出可用模型 |
| `agent mcp` | 管理 MCP servers |
| `agent acp` | 启动 ACP server，高级集成 |
| `agent update` | 更新 Cursor Agent |
| `agent ls` | 列出历史会话 |
| `agent resume` | 恢复最近会话 |
| `agent create-chat` | 创建空会话并返回 ID |
| `agent generate-rule` / `agent rule` | 交互式生成 Cursor rule |
| `agent install-shell-integration` | 安装 shell integration 到 `~/.zshrc` |
| `agent uninstall-shell-integration` | 移除 shell integration |
| `agent help [command]` | 查看命令帮助 |

`agent acp` 是自定义 ACP client 和高级集成入口，默认帮助中隐藏，不适合作为普通用户起步命令。

## 6. MCP 子命令

| Subcommand | 用途 |
| --- | --- |
| `agent mcp login <identifier>` | 登录 `.cursor/mcp.json` 中配置的 MCP server |
| `agent mcp list` | 列出 MCP servers 和状态 |
| `agent mcp list-tools <identifier>` | 查看某个 MCP 的工具和参数 |
| `agent mcp enable <identifier>` | 启用 MCP server |
| `agent mcp disable <identifier>` | 禁用 MCP server |

所有 MCP 子命令都支持 `-h, --help`。启用 MCP 前先看 `list-tools`，知道它能做什么，再决定是否开放给当前任务。

## 7. 常用组合

只读审查：

```bash
agent -p --mode=ask --output-format text \
  "Review the current diff for security risks. Do not edit files."
```

计划模式：

```bash
agent --plan "Plan a safe migration for the billing webhook"
```

明确 workspace：

```bash
agent --workspace ~/src/my-app --mode=ask "Summarize the routing architecture"
```

隔离修改：

```bash
agent --workspace ~/src/my-app --worktree \
  "Fix the flaky auth test and run the focused test"
```

受控写入脚本：

```bash
agent -p --force --output-format text \
  "Only edit docs/**/*.md. Do not commit or push."
```

## 8. 失败排查

- 参数不确定：先跑 `agent help [command]`。
- 模型不可用：跑 `agent models` 或回到官方 Models & Pricing。
- 认证失败：跑 `agent status` / `agent whoami`。
- MCP 不工作：跑 `agent mcp list`，再看 `list-tools`。
- 输出难解析：改用 `--output-format json`。
- 写错工作区：显式加 `--workspace <path>`。

<details>
<summary>深读：为什么参数页要和权限页一起读</summary>

参数不是纯输入选项。`--force`、`--sandbox`、`--approve-mcps`、`--trust` 都会改变 Agent 的实际操作边界。

如果团队只复制命令，不理解这些参数，会把“方便”误当成“安全”。上线脚本必须把权限参数写进 review checklist。
</details>

## 本章自检

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

1. 为什么默认 Agent mode 不需要 `--mode=agent`？
2. `--workspace` 和 `--worktree` 分别解决什么问题？
3. 哪些参数会显著扩大权限边界？

通过标准：你能为只读审查、隔离修改、CI 写入和 MCP 调试各写一条命令，并解释每个参数的作用。

## 官方来源

- [Cursor CLI Parameters](https://cursor.com/docs/cli/reference/parameters.md) —— 官方全局参数、commands、MCP 子命令、arguments 和 help 说明。
- [Using Agent in CLI](https://cursor.com/docs/cli/using.md) —— 官方 CLI 使用背景。
- [Cursor CLI Permissions](https://cursor.com/docs/cli/reference/permissions.md) —— 官方权限参数背景。
- [Cursor Worktrees](https://cursor.com/docs/configuration/worktrees.md) —— 官方 worktree 说明。

## 接下来去哪

<Cards>
  <Card title="认证" description="继续学习 login、API key、auth token 和 CI 认证边界。" href="/docs/cursor/official/03-cli-automation/39-authentication" />
  <Card title="输出格式" description="继续学习 text、json、stream-json 的脚本消费方式。" href="/docs/cursor/official/03-cli-automation/42-output-format" />
</Cards>
