Cursor CLI Agent 技能

本技能提供一份全面的 Cursor CLI 工具使用指南及配套工作流，涵盖 2026 年 1 月更新中的全部功能。

安装

标准安装（macOS、Linux、Windows WSL）

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

Homebrew（仅 macOS）

brew install --cask cursor-cli

安装后配置

macOS：

• 将路径添加至 ~/.zshrc（zsh）或 ~/.bashrc（bash）：

  export PATH="$HOME/.local/bin:$PATH"
  

• 重启终端，或运行 source ~/.zshrc（或 source ~/.bashrc）
• 要求 macOS 10.15 或更高版本
• 兼容 Intel 与 Apple Silicon Mac

Linux/Ubuntu：

• 重启终端，或重新加载 shell 配置文件
• 使用 agent --version 验证安装

所有平台通用：

• 可用命令：agent（主命令）和 cursor-agent（向后兼容）
• 验证安装：agent --version 或 cursor-agent --version

认证

通过浏览器完成认证：

agent login

或使用 API 密钥：

export CURSOR_API_KEY=your_api_key_here

更新

保持 CLI 版本最新：

agent update
# 或
agent upgrade

命令

交互模式

启动与 agent 的交互式会话：

agent

启动时附带初始提示：

agent "为该 API 添加错误处理逻辑"

向后兼容说明： cursor-agent 命令仍可使用，但 agent 现已成为主命令。

模型切换

列出所有可用模型：

agent models
# 或
agent --list-models

指定使用某模型：

agent --model gpt-5

在会话中动态切换模型：

/models

会话管理

管理 agent 会话：

• 列出会话： agent ls
• 恢复最近一次会话： agent resume
• 恢复指定会话： agent --resume="[chat-id]"

上下文选择

在对话中包含特定文件或目录：

@filename.ts
@src/components/

斜杠命令

在交互式会话中可用：

• /models —— 交互式切换 AI 模型
• /compress —— 汇总当前对话并释放上下文窗口空间
• /rules —— 直接从 CLI 创建并编辑规则
• /commands —— 创建并修改自定义命令
• /mcp enable [server-name] —— 启用 MCP 服务器
• /mcp disable [server-name] —— 禁用 MCP 服务器

键盘快捷键

• Shift+Enter —— 插入换行符，支持多行输入
• Ctrl+D —— 退出 CLI（需连续按两次以确保安全）
• Ctrl+R —— 审查变更（按 i 查看操作说明，使用方向键导航）
• ArrowUp —— 循环浏览历史消息

非交互模式 / CI 模式

以非交互方式运行 agent，适用于 CI/CD 流水线：

agent -p '运行测试并报告覆盖率'
# 或
agent --print '将此文件重构为使用 async/await'

输出格式：

# 纯文本（默认）
agent -p '分析代码' --output-format text

# 结构化 JSON
agent -p '查找代码缺陷' --output-format json

# 实时流式 JSON
agent -p '运行测试' --output-format stream-json --stream-partial-output

强制模式（自动应用变更，无需确认）：

agent -p '修复所有 lint 错误' --force

媒体支持：

agent -p '分析该截图：screenshot.png'

⚠️ 与 AI Agent / 自动化工具配合使用（需 tmux）

重要提示： 当从自动化环境（如 AI Agent、脚本、子进程调用）运行 Cursor CLI 时，CLI 必须连接真实的 TTY。直接执行会导致进程无限挂起。

解决方案：使用 tmux

# 1. 若未安装 tmux，请先安装
sudo apt install tmux  # Ubuntu/Debian
brew install tmux      # macOS

# 2. 创建 tmux 会话
tmux kill-session -t cursor 2>/dev/null || true
tmux new-session -d -s cursor

# 3. 切换至项目目录
tmux send-keys -t cursor "cd /path/to/project" Enter
sleep 1

# 4. 运行 Cursor agent
tmux send-keys -t cursor "agent 'Your task here'" Enter

# 5. 处理 workspace trust 提示（首次运行时）
sleep 3
tmux send-keys -t cursor "a"  # 信任 workspace

# 6. 等待任务完成
sleep 60  # 根据任务复杂度调整

# 7. 捕获输出内容
tmux capture-pane -t cursor -p -S -100

# 8. 验证结果
ls -la /path/to/project/

原理说明：

• tmux 提供持久化的伪终端（PTY）
• Cursor 的 TUI 需要具备交互能力的终端环境
• 在子进程或 exec 中直接调用 agent 且无 TTY 将导致挂起

以下方式均不可用（将无限挂起）：

# ❌ 这些方式将无限挂起：
agent "task"                    # 无 TTY
agent -p "task"                 # 无 TTY  
subprocess.run(["agent", ...])  # 无 TTY
script -c "agent ..." /dev/null # 可能导致 Cursor 崩溃

规则与配置

agent 会自动加载以下位置的规则：

• .cursor/rules
• AGENTS.md
• CLAUDE.md

使用 /rules 命令可直接从 CLI 创建和编辑规则。

MCP 集成

MCP 服务器将自动从 mcp.json 配置文件中加载。

可动态启用或禁用服务器：

/mcp enable server-name
/mcp disable server-name

注意： 服务器名称中包含空格是完全支持的。

工作流

代码审查

对当前变更或指定分支执行代码审查：

agent -p '审查当前分支相对于 main 分支的变更，重点关注安全性和性能。'

重构

对代码进行重构以提升可读性或性能：

agent -p '重构 src/utils.ts，降低复杂度并增强类型安全性。'

调试

分析日志或错误信息以定位根本原因：

agent -p '分析以下错误日志并提出修复建议：[在此粘贴日志]'

Git 集成

结合上下文智能自动化 Git 操作：

agent -p '为已暂存的变更生成符合 conventional commits 规范的提交信息。'

批量处理（CI/CD）

在 CI 流水线中运行自动化检查：

# 在 CI 环境中设置 API 密钥
export CURSOR_API_KEY=$CURSOR_API_KEY

# 以 JSON 格式运行安全审计（强制模式）
agent -p '对该代码库进行安全漏洞审计' --output-format json --force

# 生成测试覆盖率报告
agent -p '运行测试并生成覆盖率报告' --output-format text

多文件分析

利用上下文选择功能分析多个文件：

agent
# 然后在交互模式中输入：
@src/api/
@src/models/
Review the API implementation for consistency with our data models