Cursor CLI AI 编程工具

精选 Cursor CLI 常用指令与核心速查备忘单，涵盖高频用法、配置参数与实用技巧。 Cursor CLI (agent) 是 Cursor AI 编程代理的终端命令行接口——直接在命令行中运行代理级任务、自动化脚本和 CI/CD 流水线。

Star 项目
关注 X (Twitter)
赞赏饮咖啡

#🚀 入门指引

#Hello World 示例

# 启动交互式 Agent 代理会话
$ agent

# 单次 Prompt 任务 (打印输出模式)
$ agent -p "List all TODO comments in this repo"

# 提问模式 (只读模式，不修改代码)
$ agent --mode=ask "How does auth work here?"

# 仅设计计划 (不作实际代码编辑)
$ agent --plan "Refactor the payment module"

#安装指引 (Install)

macOS / Linux / WSL

$ curl https://cursor.com/install -fsS | bash

Windows (PowerShell)

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

安装后配置 (Post-install)

# 如有需要，添加至环境变量 PATH
export PATH="$HOME/.local/bin:$PATH"

# 验证安装版本
$ agent --version

# 升级至最新版本
$ agent update

#核心概念

概念名称 详细说明与定义
代理模式 (Agent mode) 完全访问权限：读取、写入修改、运行 Shell 命令
计划模式 (Plan mode) 仅只读分析，不进行任何代码编辑修改
问答模式 (Ask mode) Q&A 问答/解疑释惑，仅只读
云端代理 (Cloud agent) 委派任务至远程 Cursor 云端执行
会话 (Session) 带有历史上下文记录的已保存对话
工作树 (Worktree) 独立的 Git 分支隔离环境
ACP 协议 Agent Client Protocol (基于 stdio 的 JSON-RPC)
MCP 协议 外部工具/数据源扩展接入协议

#CLI 选项 Flag 参数

#会话与模式

Flag 参数 含义与功能描述
--mode=plan 计划模式（仅只读分析，不做代码修改）
--mode=ask 问答模式（仅 Q&A 答疑，只读）
--plan --mode=plan 的简写形式
-p, --print 无头/打印模式（非交互式直接输出）
-c, --cloud 以云端代理 (Cloud Agent) 模式启动
--continue 继续上一次的对话会话
--resume [chatId] 恢复指定的特定会话
-n, --name 为当前会话命名
--workspace <path> 指定工作区目录路径
--model <model> 指定使用的 AI 模型（如 sonnet-4）
--list-models 列出所有可用的模型后直接退出

#工作树与沙箱 (Worktree & Sandbox)

Flag 参数 含义与功能描述
-w, --worktree [name] 在独立的 Git Worktree 工作树中启动
--worktree-base <ref> 指定 Worktree 的基准分支/引用
--skip-worktree-setup 跳过 .cursor/worktrees.json 中的设置脚本
--sandbox <mode> 沙箱隔离模式：enabled 或 disabled
--trust 无须弹框提示直接信任当前工作区
--approve-mcps 自动批准所有的 MCP 服务器连接

#输出与权限 (Output & Permissions)

Flag 参数 含义与功能描述
--output-format <fmt> 指定输出格式：text | json | stream-json
--stream-partial-output 串流传输文本增量（仅在 stream-json 下有效）
-f, --强制执行 自动允许命令运行（除非明确禁止）
--yolo --强制执行 强制全自动允许模式的别名
--api-key <key> 认证 API 密钥（或使用环境变量 CURSOR_API_KEY）
-H, --header <h> 自定义请求头 (Name: Value)

#🛠️ 命令大全

#子命令速查矩阵

命令指令 含义说明
agent [prompt] 启动交互式会话或非交互打印模式
agent ls 列出所有可恢复的历史会话
agent resume 恢复最新一次的聊天会话
agent login 进行 Cursor 账号身份验证登录
agent logout 退出登录并清除保存的身份凭据
agent status 查看当前的认证状态 / whoami
agent update 升级 Cursor CLI 至最新版本
agent about 显示版本、系统与账号信息
agent models 列出所有可用的 AI 模型
agent create-chat 创建新的空对话并返回对话 ID
agent rule 交互式生成新的 Cursor Rule 规则
agent mcp 管理 MCP 服务器扩展连接
agent mcp list 列出所有已配置的 MCP 服务器
agent mcp list-tools <id> 列出特定 MCP 服务器支持的工具
agent mcp enable <id> 将指定 MCP 服务器加入已批准列表
agent mcp disable <id> 禁用指定的 MCP 服务器
agent mcp login <id> 对指定的 MCP 服务器进行身份验证
agent install-shell-integration 安装终端 Shell 集成至 ~/.zshrc
agent uninstall-shell-integration 卸载终端 Shell 集成
agent acp 启动 ACP 服务器（通过 stdio 进行 JSON-RPC）

#会话管理 (Session Management)

# 列出可恢复的会话列表
$ agent ls

# 继续上一次的会话
$ agent --continue

# 按会话 ID 恢复特定的会话
$ agent --resume abc123

# 恢复最新一次的会话
$ agent resume

#认证与账号 (Auth & Account)

$ agent login
$ agent logout
$ agent status     # 或: agent whoami
$ agent about      # 查看版本及账号信息
$ agent models     # 查看可用的模型列表

#执行模式 (Execution Modes)

#代理模式 (Agent Mode)

拥有完全的代理权限 — 可读取文件、编辑写入代码、运行 Shell 命令及使用全部工具。

$ agent
$ agent "Fix the bug in auth.ts"

未指定 --mode 选项时的默认执行模式。

#计划模式 (Plan Mode)

只读分析模式。在不给代码库做任何实际编辑修改的前提下提供架构/设计计划方案。

$ agent --plan
$ agent --mode=plan "Refactor auth"

无法修改文件或运行终端命令。

#问答模式 (Ask Mode)

问答交流风格。解释代码逻辑、回答技术问题 — 不修改代码、不运行 Shell 命令。

$ agent --mode=ask
$ agent --mode=ask "How does caching work?"

适合在没有任何风险的前提下快速阅读理解代码。

#无头模式与脚本编写

#管道与脚本用法

# 总结代码 Diff 改动
$ git diff | agent -p "Summarize these changes"

# 审查代码文件
$ cat src/auth.ts | agent -p "Find security issues"

# 处理应用日志
$ tail -200 app.log | agent -p "Identify errors"

# 在 Prompt 中引用图片
$ agent -p "Describe this diagram: /path/to/image.png"

输出格式化选项：

# 纯文本格式（默认）
$ agent -p "task" --output-format text

# 完整 JSON 格式响应
$ agent -p "task" --output-format json

# 串流 JSON 增量输出
$ agent -p "task" --output-format stream-json

# 实时串流文本块输出
$ agent -p "task" --output-format stream-json \
    --stream-partial-output

#CI / CD 流水线集成

# 允许所有文件编辑修改
$ agent -p "Update changelog" --强制执行

# 从环境变量读取 API Key 运行
$ CURSOR_API_KEY=xxx agent -p "Run tests"

# 受信工作区（跳过所有提示弹框）
$ agent -p "Deploy" --trust

# 指定特定工作区目录
$ agent -p "Analyze" --workspace /repo

批量脚本化处理：

for f in src/**/*.ts; do
  agent -p "Add JSDoc to $f" --强制执行
done

#Git Worktrees 隔离环境

#隔离运行环境

Worktree 会在 ~/.cursor/worktrees/<repo>/<name> 中创建一个隔离的 Git 分支环境 — 保持主工作树干净整洁。

# 自动命名的 Worktree
$ agent -w

# 指定名称的 Worktree
$ agent -w feature-auth

# 基于指定分支创建 Worktree
$ agent -w fix --worktree-base main

# 跳过初始化安装脚本
$ agent -w feature --skip-worktree-setup

在 .cursor/worktrees.json 中配置 Worktrees 初始化脚本：

{
  "setup": ["npm install", "cp .env.example .env"]
}

#Worktree 文件包含设置

控制哪些本地配置文件需要复制到新 Worktree 环境中：

# .worktreeinclude (支持 Glob 匹配模式)
.env
.env.local
secrets/
node_modules/

匹配这些模式的文件将在创建新 Worktree 时自动从主工作树中复制过去。

#Shell 命令模式 (Shell Mode)

#Shell 命令执行

Shell 模式直接运行在系统的 $SHELL 环境中。可以通过 cd 链接多条命令：

# 切换目录后运行代理命令
cd /my/project && agent "optimize this"

# 会话中的 Shell 命令
$ ls -la              # 运行在 $SHELL 中
$ npm test            # 运行测试
$ git status          # Git 操作

Shell 操作控制快捷键：

快捷键 执行动作
Ctrl+C 取消当前正在运行的 Shell 命令
Ctrl+O 展开 / 查看完整的命令输出日志
Tab 将当前命令添加至允许规则列表

#Shell 提示注意事项

  • 每条终端命令均运行在 $SHELL (zsh/bash/fish) 环境中
  • 每条命令的默认超时时间为 30 秒
  • 使用 cd dir && cmd 来执行特定目录下的命令
  • 开启 Shell 集成可以显著提升代理对终端的上下文感知力：
$ agent install-shell-integration
# 将挂钩脚本添加至 ~/.zshrc 中

#MCP 服务器

#配置 MCP 服务器

用户级全局配置存放在 ~/.cursor/mcp.json，项目级配置存放在 .cursor/mcp.json：

stdio 本地进程服务器 (Node.js)

{
  "mcpServers": {
    "my-tool": {
      "command": "npx",
      "args": ["-y", "my-mcp-server"],
      "env": { "API_KEY": "value" }
    }
  }
}

stdio 本地进程服务器 (Python)

{
  "mcpServers": {
    "my-tool": {
      "command": "python",
      "args": ["-m", "my_mcp_server"]
    }
  }
}

HTTP / SSE 远程服务器

{
  "mcpServers": {
    "remote-tool": {
      "url": "https://my-server.com/mcp"
    }
  }
}

#MCP 管理指令

# 列出所有已配置的服务器
$ agent mcp list

# 查看指定服务器支持的工具列表
$ agent mcp list-tools my-tool

# 启用并批准指定的服务器
$ agent mcp enable my-tool

# 禁用指定的服务器
$ agent mcp disable my-tool

# 对指定的服务器进行身份验证
$ agent mcp login my-tool

# 在会话中自动批准所有 MCP 工具
$ agent --approve-mcps

#ACP 代理客户端协议 (ACP Protocol)

#ACP 协议概述

ACP (Agent Client Protocol) 协议通过 stdio 将 Cursor Agent 作为 JSON-RPC 2.0 服务器进行暴露。适合构建自定义的 IDE 扩展插件或无头客户端。

# 启动 ACP 服务器
$ agent acp

# 带有 API Key 启动
$ agent --api-key "$CURSOR_API_KEY" acp

请求处理流：

initialize
authenticate (cursor_login)
session/new  或  session/load
session/prompt
  → session/update (串流增量响应)
  → session/request_permission (工具执行权限请求)
session/cancel  (可选)

权限响应结果类型：

响应值 效果与行为
allow-once 仅批准本次执行
allow-always 始终批准该工具
reject-once 仅拒绝本次执行

#ACP 扩展 API 方法

通过 ACP 发送的 Cursor 扩展方法：

方法名称 类型 详细作用与用途
cursor/ask_question 阻塞式 多选询问提示
cursor/create_plan 阻塞式 请求方案批准
cursor/update_todos 通知型 更新待办事项状态列表
cursor/task 通知型 子代理任务执行状态
cursor/generate_image 通知型 图像生成事件回调

极简 Node.js 客户端代码示例：

const agent = spawn('agent', ['acp'], { stdio: ['pipe', 'pipe', 'inherit'] });
// 发送 initialize → authenticate → session/new → session/prompt

通过 ACP 集成的第三方 IDE：

  • JetBrains 系列 (IntelliJ, WebStorm, PyCharm)
  • Neovim（通过 avante.nvim 插件）
  • Zed 编辑器扩展
  • 支持扩展定制的各类代码编辑器

#云端代理 (Cloud Agents)

#云端代理模式

云端代理在 Cursor 云端基础设施中远程运行任务。适合长耗时或高并发的并行工作负载。

# 启动云端代理选择器
$ agent -c
$ agent --cloud

# 带有 Initial Prompt 启动云端代理
$ agent -c "Migrate all tests to Vitest"

云端代理包含如下优势：

  • 远程云端执行（不占用本地计算机资源）
  • 并行任务分配委派
  • 适合长时间常驻运行的工作流

#子代理类型 (Subagent Types)

当使用 ACP 或云端代理时，可以显式指定子代理的类型：

类型名称 详细说明
explore 代码库探索与调研
browser_use Web 网页浏览器自动化
computer_use 桌面 GUI 自动化操作
shell Shell 终端命令执行
video_review 视频内容分析与审查
{ custom: "type" } 自定义扩展子代理类型

#🔗 参考资源