Cursor CLI 新手完全指南：从安装到自动化工作流

发布日期：2026-06-11 | 话题：Cursor CLI / AI 编程 / Terminal Agent / Cursor 使用教程 / Composer 2.5

Cursor CLI 是 Cursor（Anysphere 公司）推出的终端版 AI 编程 Agent，一行 curl https://cursor.com/install -fsS | bash 安装完毕，无需打开 IDE 就能在任何终端环境中运行同一套 Agent——包括 Composer 2.5、GPT-5.5、Opus 4.8、Gemini 3.1 Pro 等多家前沿模型（来源：Cursor 官方网站，2026-06）。它有三种运行模式：Interactive（TUI 交互式对话）、Headless（-p 参数无头执行，适合 CI/CD 和脚本）、Shell Mode（Agent 直接运行 shell 命令，带安全检查）。MCP 支持 Linear、GitHub、Figma 等外部服务接入，Hooks 系统可在生命周期关键节点注入自定义脚本，Cursor SDK（TypeScript + Python）支持自定义工具、子 Agent 嵌套和灵活存储方案。本文覆盖从安装登录到 GitHub Actions 集成的完整新手链路，以及 5 个典型工作流场景，帮助开发者快速把 Cursor CLI 接入现有的自动化体系。

---

Cursor CLI 是 Cursor 在 2025-2026 年推出的终端版 AI 编程 Agent，允许开发者不打开 IDE 就在任何终端环境中使用 Cursor Agent——同一套模型、同一套工具，一行命令安装完毕，适配 macOS、Linux 和 Windows（来源：Cursor 官方网站，2026-06）。它和 Cursor IDE 的核心区别是：IDE 适合有 GUI 的本地开发，CLI 适合服务器、CI/CD、自动化脚本和 SSH 远程环境。本文从安装配置到核心功能，覆盖 Interactive Agent、Headless 无头模式、Shell Mode、GitHub Actions 集成和 MCP 接入全链路，是专为新手设计的一站式操作手册。

---

Cursor CLI 是什么：和 Cursor IDE 的关系

Cursor IDE 是 VS Code fork，有图形界面、Tab 自动补全、Agents 面板；Cursor CLI 是把同一个 Agent 引擎搬到了终端里（来源：Cursor 官方网站，2026-06）：

维度	Cursor IDE	Cursor CLI
运行环境	图形界面	纯终端，无 GUI 依赖
适用场景	本地日常开发	服务器、CI/CD、自动化脚本
安装方式	下载安装包	一行 curl 命令
Tab 补全	有（Composer 2.5 驱动）	无
Agent 能力	完整	完整（与 IDE 等价）
MCP 支持	完整	完整（Figma MCP 暂不支持 Cloud）
Bugbot 代码审查	有	Coming soon

Cursor CLI 的定位是"Same commands, any environment"——无论你在哪里跑代码，都能接入同一个 Agent（来源：Cursor 官方网站，2026-06）。

---

第一步：安装 Cursor CLI

macOS / Linux

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

安装完成后，执行 cursor-agent 或 cursor 进入 TUI 界面（来源：Cursor 官方网站，2026-06）。

Windows

# PowerShell
irm https://cursor.com/install -Outfile install.ps1; ./install.ps1

Windows 支持原生 PowerShell 和 WSL2（来源：Cursor 官方网站，2026-06）。

验证安装

cursor-agent --version

登录

首次运行会提示登录 Cursor 账号。建议使用 Cursor 订阅账号登录，享受订阅内包含的模型配额：

cursor-agent
# 首次运行自动弹出登录流程

Hobby（免费）计划可使用限额 Agent 请求；Individual Pro（$20/月）有扩展限额；Teams（$40/用户/月）支持团队共享配额和集中计费（来源：Cursor 定价页，2026-06）。

---

核心界面：TUI 和基础命令

进入 Cursor CLI 后，你会看到一个类似聊天的终端 TUI（Terminal UI）。以下是最常用的内置命令（来源：Cursor 官方网站，2026-06）：

命令	功能
/model	切换底层模型（Auto / Composer 2.5 / GPT-5.5 / Opus 4.8 等）
/model Auto	让 Cursor 自动选择最合适的模型
/review	触发 Bugbot 代码审查（选择 /review-bugbot 或 /review-security）
@文件名	将指定文件注入 Agent 上下文
!命令	在 Agent 对话中直接运行 shell 命令
Ctrl+C	中断当前 Agent 任务

可用模型列表

Cursor CLI 接入多家厂商的前沿模型（来源：Cursor 官方网站，2026-06）：

Auto                # 智能选择
Composer 2.5        # Cursor 自研，驱动 Bugbot
GPT-5.5 Extra High Fast
GPT-5.5 High Fast
Opus 4.8
Gemini 3.1 Pro
Grok 4.3

/model Auto 模式让 Cursor 根据任务复杂度和当前配额自动路由，是日常使用的推荐设置。

---

三种运行模式详解

模式一：Interactive Agent（交互式）

最常见的使用方式——在终端里和 Agent 对话，实时查看进度和结果：

# 进入 TUI，开始对话
cursor-agent

# 指定工作目录
cursor-agent --workspace ~/projects/my-app

进入 TUI 后，像使用 Claude Code 或 ChatGPT 一样直接描述任务：

你：给 src/api/users.py 添加分页支持，每页默认 20 条，支持 page 和 page_size 参数

Agent：好的，我来查看当前的 users.py 实现...
[Agent 自动读取文件、生成修改、展示 diff]

Session 管理：CLI 的 session history 绑定到工作区目录。切换 --workspace 后，之前的对话历史不会自动迁移（来源：Cursor 论坛，2026-06）。

模式二：Headless / 非交互式（-p 参数）

适合脚本化自动执行，无需人工交互，适用于 CI/CD、批处理任务：

# -p 参数：传入 prompt，直接执行，完成后退出
cursor-agent -p "检查 src/ 目录下所有 .py 文件的类型注解覆盖率，输出报告"

# 指定工作区 + 无头执行
cursor-agent --workspace ~/projects/app -p "为 src/api/ 下所有接口生成 OpenAPI 注释"

# 结合管道使用
echo "为 $(cat modified_files.txt) 中的每个文件生成 docstring" | cursor-agent -p -

Headless 模式不显示 TUI，直接输出结果到 stdout，可以被脚本捕获处理（来源：Cursor 官方网站，2026-06）。

模式三：Shell Mode

Shell Mode 允许 Agent 在对话中直接运行 shell 命令，带有安全检查和输出展示（来源：Cursor 官方网站，2026-06）：

# 在 TUI 中用 ! 前缀运行命令
你：!ls -la src/
你：!git log --oneline -10
你：!pytest tests/ -v

Shell Mode 的安全检查会在执行破坏性命令（如 rm、git push --force）前提示确认，可以通过 permissions.json 配置 allow/block 规则：

{
  "autoRun": {
    "allow_instructions": [
      "Read-only inspections and git status checks are fine."
    ],
    "block_instructions": [
      "Always pause delete operations and force pushes for manual review."
    ]
  }
}

---

MCP 集成：扩展 Agent 能力

Cursor CLI 完整支持 MCP（Model Context Protocol），可接入各类外部服务（来源：Cursor 官方网站，2026-06）：

已验证可用的 MCP（CLI 环境）：

• Linear MCP（项目管理，/linear 命令）
• GitHub MCP（代码仓库操作）
• Figma MCP（在 CLI 环境可用；注意：Cloud Agents 环境暂不支持 Figma MCP）

MCP 配置路径（~/.cursor/mcp.json 或项目 .cursor/mcp.json）：

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_TOKEN"
      }
    },
    "linear": {
      "command": "npx",
      "args": ["-y", "@linear/mcp-server"],
      "env": {
        "LINEAR_API_KEY": "YOUR_KEY"
      }
    }
  }
}

配置完成后，Agent 在 CLI 会话中自动加载这些工具（来源：Cursor 论坛 MCP 相关讨论，2026-06）。

---

Hooks：在 Agent 生命周期注入自定义逻辑

Cursor CLI 的 Hooks 系统允许在 Agent 运行的关键节点插入自定义脚本，例如敏感词检测、自动日志、完成通知等（来源：Cursor 论坛，2026-06）：

// ~/.cursor/hooks.json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "shell",
        "command": "python3 ~/.cursor/hooks/check_command.py"
      }
    ],
    "Stop": [
      {
        "command": "python3 ~/.cursor/hooks/notify_done.py"
      }
    ]
  }
}

注意：Hooks 配置需要在 Cursor CLI 中审查信任后才能生效，防止恶意 hooks 注入（来源：Cursor 论坛，2026-06）。

---

GitHub Actions 集成

在 GitHub Actions 中使用 Cursor CLI，实现 PR 自动审查和 CI 自动修复（来源：Cursor 官方网站，2026-06）：

# .github/workflows/cursor-review.yml
name: Cursor Code Review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Install Cursor CLI
        run: curl https://cursor.com/install -fsS | bash
        
      - name: Run Cursor Review
        env:
          CURSOR_API_KEY: ${{ secrets.CURSOR_API_KEY }}
        run: |
          cursor-agent -p "审查这个 PR 的代码质量，
          重点检查：类型安全、错误处理、潜在 Bug，
          输出 Markdown 格式报告"
          
      - name: Auto-fix lint errors
        env:
          CURSOR_API_KEY: ${{ secrets.CURSOR_API_KEY }}
        run: |
          cursor-agent -p "修复 src/ 目录中所有 ESLint 报错，
          不改变代码逻辑，只修复格式和规范问题"

目前进度：Bugbot 的 /review 命令支持已在路线图上，"support in CLI coming soon"（来源：Cursor changelog，2026-06-10）。

---

Cursor SDK：程序化控制 Agent

对于需要更深度集成的场景，Cursor 提供 TypeScript 和 Python SDK（来源：Cursor changelog，2026-06）：

// TypeScript SDK
import { Agent } from '@cursor/sdk';

const agent = await Agent.create({
  workspace: '/path/to/project',
  model: 'composer-2-5',
  local: {
    autoReview: true,
    customTools: [
      {
        name: 'get_jira_ticket',
        description: '获取 Jira 工单详情',
        handler: async ({ ticketId }) => fetchJiraTicket(ticketId)
      }
    ]
  }
});

const result = await agent.send('为 #JIRA-123 对应的功能添加单元测试');
console.log(result.text);

# Python SDK
from cursor_sdk import Agent

agent = Agent.create(
    workspace="/path/to/project",
    model="composer-2-5"
)
result = agent.send("检查数据库迁移文件是否有冲突")
print(result.text)

SDK 特性（来源：Cursor changelog，2026-06-04）：

• Custom Tools：直接传函数给 Agent，无需搭建 MCP 服务器
• Auto-review：通过 permissions.json 的自然语言规则控制哪些工具调用自动执行
• Nested Subagents：子 Agent 可以再派生子 Agent，无深度限制
• JSONL / SQLite 存储：选择持久化 session 的方式，便于 CI 中 resume

---

典型工作流：5 个常见场景

场景一：SSH 服务器上的代码审查

# SSH 到远程服务器后
ssh user@server
cursor-agent -p "检查 /var/www/app/src/ 的代码，找出明显的安全漏洞和潜在 Bug，输出优先级排序的报告"

场景二：批量代码迁移

# 把所有 Python 2 print 语句迁移到 Python 3 格式
cursor-agent -p "把 src/ 目录下所有 Python 文件中的 print 语句改为 print() 函数调用，
保留原有内容，不改变任何业务逻辑"

场景三：自动生成 Git commit 信息

# 根据 diff 生成 commit message
git diff --staged | cursor-agent -p "根据以下 git diff 生成一条符合 Conventional Commits 规范的 commit message，
只输出 commit message 本身，不要解释：
$(cat -)"

场景四：定期文档更新（cron job）

# crontab -e 中配置
0 9 * * 1 cursor-agent --workspace ~/projects/my-api \
  -p "检查 src/api/ 目录，更新 README.md 中的 API 端点文档，
  确保文档和代码实现一致" >> ~/logs/cursor-doc-update.log 2>&1

场景五：PR 前的本地预检

# 推送前本地跑一遍检查
cursor-agent -p "/review-bugbot --pre-push 检查 HEAD 和 main 之间的差异，
找出可能导致 CI 失败的问题" 

---

新手常见问题

Q：Cursor CLI 和 Claude Code、OpenAI Codex 有什么区别？

三者都是 Terminal AI 编程 Agent，核心差异在模型和生态：Cursor CLI 底层可切换 Composer 2.5、GPT-5.5、Opus 4.8 等多家模型，有 Cursor 自研的 Tab 补全模型和 Bugbot，是 Cursor IDE 生态的终端延伸；Claude Code 底层使用 Anthropic Claude 模型，有 MCP 和 Skills 扩展体系；Codex 底层是 OpenAI GPT-5.x，有 AGENTS.md 和 Hooks 系统。三者均支持 GitHub Actions 集成，可以并用（来源：Cursor 官方网站，2026-06）。

Q：Cursor CLI 免费吗？

Hobby 计划（$0）可以免费使用，但有 Agent 请求次数限制。Individual Pro（$20/月）有扩展限额和完整模型访问权。Teams（$40/用户/月）增加团队计费和 Bugbot 等企业功能（来源：Cursor 定价页，2026-06）。

Q：-p 参数和直接交互有什么区别？

-p 是 headless/非交互模式：传入 prompt 后直接执行，完成后退出，输出写入 stdout，适合脚本化和 CI/CD；直接运行 cursor-agent 是交互模式，有 TUI 界面，支持多轮对话和实时反馈（来源：Cursor 官方网站，2026-06）。

Q：Session history 在切换目录后会丢失吗？

会。Cursor CLI 的 session history 绑定到启动时的工作区（--workspace）。切换到不同的 workspace 会开启一个新 session，原来的对话历史不会自动迁移。如果需要在新目录继续之前的任务，建议手动在 prompt 中提供必要的上下文（来源：Cursor 论坛，2026-06）。

Q：MCP 配置在 CLI 里和 IDE 里是共用的吗？

是的。CLI 和 IDE 共用 ~/.cursor/mcp.json（全局）和 .cursor/mcp.json（项目级）的配置。但有一个例外：Figma MCP 目前在 CLI 和 IDE 中可用，但在 Cloud Agents 环境中尚不支持（来源：Cursor 论坛，2026-06）。

---

总结

Cursor CLI 的上手路径很短：一行命令安装，cursor-agent 进 TUI，-p 参数无头执行，GitHub Actions 里直接调用——覆盖了绝大多数开发者的日常需求。进阶后的三个提升点是：用 MCP 接入外部系统、用 Hooks 定制生命周期行为、用 Cursor SDK 在代码里程序化驱动 Agent。Cursor CLI 支持的模型矩阵（Composer 2.5 / GPT-5.5 / Opus 4.8 / Gemini 3.1 Pro / Grok 4.3）让它成为目前模型选择最灵活的 Terminal AI 编程工具之一，而 Bugbot 的 CLI 支持上线后，从 commit 到 PR 的全链路自动化将彻底就位（来源：Cursor 官方网站 + changelog，2026-06）。

---

参考资料

• Cursor CLI 官方页面
• 七牛云 AI 推理服务