CLI 参数

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

阅读目标：读完本章，你应该能选择 --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. 非交互参数

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

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. 常用组合

只读审查：

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

计划模式：

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

明确 workspace：

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

隔离修改：

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

受控写入脚本：

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

深读：为什么参数页要和权限页一起读

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

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

本章自检

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

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

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

官方来源

Cursor CLI Parameters —— 官方全局参数、commands、MCP 子命令、arguments 和 help 说明。
Using Agent in CLI —— 官方 CLI 使用背景。
Cursor CLI Permissions —— 官方权限参数背景。
Cursor Worktrees —— 官方 worktree 说明。