cursor-agent

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Cursor CLI Agent Skill

Cursor CLI Agent 使用指南

This skill provides a comprehensive guide and set of workflows for utilizing the Cursor CLI tool, including all features from the January 2026 update.

本指南提供了利用Cursor CLI工具的完整教程及工作流，涵盖2026年1月更新的所有功能。

Installation

安装

Standard Installation (macOS, Linux, Windows WSL)

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

bash

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

bash

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

Homebrew (macOS only)

Homebrew安装（仅macOS）

bash

brew install --cask cursor-cli

bash

brew install --cask cursor-cli

Post-Installation Setup

安装后配置

macOS:

Add to PATH in

~/.zshrc

(zsh) or

~/.bashrc

(bash):

bash

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

Restart terminal or run
```
source ~/.zshrc
```
(or
```
~/.bashrc
```
)
Requires macOS 10.15 or later
Works on both Intel and Apple Silicon Macs

Linux/Ubuntu:

Restart your terminal or source your shell config
Verify with
```
agent --version
```

Both platforms:

Commands:
```
agent
```
(primary) and
```
cursor-agent
```
(backward compatible)
Verify installation:
```
agent --version
```
or
```
cursor-agent --version
```

macOS：

在

~/.zshrc

（zsh）或

~/.bashrc

（bash）中添加到PATH：

bash

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

重启终端或执行
```
source ~/.zshrc
```
（或
```
~/.bashrc
```
）
要求macOS 10.15或更高版本
支持Intel及Apple Silicon芯片的Mac

Linux/Ubuntu：

重启终端或加载shell配置文件
执行
```
agent --version
```
验证安装

全平台通用：

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

Authentication

身份验证

Authenticate via browser:

bash

agent login

Or use API key:

bash

export CURSOR_API_KEY=your_api_key_here

通过浏览器验证：

bash

agent login

或使用API密钥：

bash

export CURSOR_API_KEY=your_api_key_here

Update

更新

Keep your CLI up to date:

bash

agent update

保持CLI版本为最新：

bash

agent update

or

或

agent upgrade

undefined

agent upgrade

undefined

Commands

命令

Interactive Mode

交互模式

Start an interactive session with the agent:

bash

agent

Start with an initial prompt:

bash

agent "Add error handling to this API"

Backward compatibility:

cursor-agent

still works but

agent

is now the primary command.

启动与Agent的交互式会话：

bash

agent

带初始提示启动：

bash

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

向后兼容：

cursor-agent

仍可使用，但

agent

为当前主命令。

Model Switching

模型切换

List all available models:

bash

agent models

列出所有可用模型：

bash

agent models

or

或

agent --list-models


Use a specific model:

```bash
agent --model gpt-5

Switch models during a session:

/models

agent --list-models


使用指定模型：

```bash
agent --model gpt-5

会话中切换模型：

/models

Session Management

会话管理

Manage your agent sessions:

List sessions:
```
agent ls
```
Resume most recent:
```
agent resume
```
Resume specific session:
```
agent --resume="[chat-id]"
```

管理Agent会话：

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

Context Selection

上下文选择

Include specific files or folders in the conversation:

@filename.ts
@src/components/

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

@filename.ts
@src/components/

Slash Commands

斜杠命令

Available during interactive sessions:

/models
- Switch between AI models interactively
/compress
- Summarize conversation and free up context window
/rules
- Create and edit rules directly from CLI
/commands
- Create and modify custom commands
/mcp enable [server-name]
- Enable an MCP server
/mcp disable [server-name]
- Disable an MCP server

交互会话中可用：

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

Keyboard Shortcuts

键盘快捷键

Shift+Enter
- Add newlines for multi-line prompts
Ctrl+D
- Exit CLI (requires double-press for safety)
Ctrl+R
- Review changes (press
```
i
```
for instructions, navigate with arrow keys)
ArrowUp
- Cycle through previous messages

Shift+Enter
- 换行以输入多行提示
Ctrl+D
- 退出CLI（需按两次以确认）
Ctrl+R
- 查看更改（按
```
i
```
获取说明，用箭头键导航）
ArrowUp
- 循环查看历史消息

Non-interactive / CI Mode

非交互/CI模式

Run the agent in a non-interactive mode, suitable for CI/CD pipelines:

bash

agent -p 'Run tests and report coverage'

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

bash

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

or

或

agent --print 'Refactor this file to use async/await'


**Output formats:**

```bash

agent --print '重构此文件以使用async/await'


**输出格式：**

```bash

Plain text (default)

纯文本（默认）

agent -p 'Analyze code' --output-format text

agent -p '分析代码' --output-format text

Structured JSON

结构化JSON

agent -p 'Find bugs' --output-format json

agent -p '查找Bug' --output-format json

Real-time streaming JSON

实时流式JSON

agent -p 'Run tests' --output-format stream-json --stream-partial-output


**Force mode (auto-apply changes without confirmation):**

```bash
agent -p 'Fix all linting errors' --force

Media support:

bash

agent -p 'Analyze this screenshot: screenshot.png'

agent -p '运行测试' --output-format stream-json --stream-partial-output


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

```bash
agent -p '修复所有代码检查错误' --force

媒体支持：

bash

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

⚠️ Using with AI Agents / Automation (tmux required)

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

CRITICAL: When running Cursor CLI from automated environments (AI agents, scripts, subprocess calls), the CLI requires a real TTY. Direct execution will hang indefinitely.

The Solution: Use tmux

bash

undefined

重要提示： 在自动化环境（AI Agents、脚本、子进程调用）中运行Cursor CLI时，CLI需要真实的TTY。直接执行会导致无限挂起。

解决方案：使用tmux

bash

undefined

1. Install tmux if not available

1. 若未安装则安装tmux

sudo apt install tmux # Ubuntu/Debian brew install tmux # macOS

2. Create a tmux session

2. 创建tmux会话

tmux kill-session -t cursor 2>/dev/null || true tmux new-session -d -s cursor

3. Navigate to project

3. 导航到项目目录

tmux send-keys -t cursor "cd /path/to/project" Enter sleep 1

4. Run Cursor agent

4. 运行Cursor Agent

tmux send-keys -t cursor "agent 'Your task here'" Enter

5. Handle workspace trust prompt (first run)

5. 处理工作区信任提示（首次运行）

sleep 3 tmux send-keys -t cursor "a" # Trust workspace

sleep 3 tmux send-keys -t cursor "a" # 信任工作区

6. Wait for completion

6. 等待任务完成

sleep 60 # Adjust based on task complexity

sleep 60 # 根据任务复杂度调整时长

7. Capture output

7. 捕获输出

tmux capture-pane -t cursor -p -S -100

8. Verify results

8. 验证结果

ls -la /path/to/project/


**Why this works:**
- tmux provides a persistent pseudo-terminal (PTY)
- Cursor's TUI requires interactive terminal capabilities
- Direct `agent` calls from subprocess/exec hang without TTY

**What does NOT work:**
```bash

ls -la /path/to/project/


**为什么此方法有效：**
- tmux提供持久化伪终端（PTY）
- Cursor的TUI需要交互式终端能力
- 从子进程/exec直接调用`agent`会因无TTY而挂起

**无效方法：**
```bash

❌ These will hang indefinitely:

❌ 这些会无限挂起：

agent "task" # No TTY agent -p "task" # No TTY
subprocess.run(["agent", ...]) # No TTY script -c "agent ..." /dev/null # May crash Cursor

undefined

agent "task" # 无TTY agent -p "task" # 无TTY
subprocess.run(["agent", ...]) # 无TTY script -c "agent ..." /dev/null # 可能导致Cursor崩溃

undefined

Rules & Configuration

规则与配置

The agent automatically loads rules from:

```
.cursor/rules
```
```
AGENTS.md
```
```
CLAUDE.md
```

Use

/rules

command to create and edit rules directly from the CLI.

Agent会自动从以下位置加载规则：

```
.cursor/rules
```
```
AGENTS.md
```
```
CLAUDE.md
```

使用

/rules

命令可直接从CLI创建和编辑规则。

MCP Integration

MCP集成

MCP servers are automatically loaded from

mcp.json

configuration.

Enable/disable servers on the fly:

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

Note: Server names with spaces are fully supported.

MCP服务器会自动从

mcp.json

配置文件加载。

动态启用/禁用服务器：

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

注意： 支持名称含空格的服务器。

Workflows

工作流

Code Review

代码审查

Perform a code review on the current changes or a specific branch:

bash

agent -p 'Review the changes in the current branch against main. Focus on security and performance.'

对当前变更或特定分支进行代码审查：

bash

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

Refactoring

代码重构

Refactor code for better readability or performance:

bash

agent -p 'Refactor src/utils.ts to reduce complexity and improve type safety.'

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

bash

agent -p '重构src/utils.ts以降低复杂度并提高类型安全性。'

Debugging

调试

Analyze logs or error messages to find the root cause:

bash

agent -p 'Analyze the following error log and suggest a fix: [paste log here]'

分析日志或错误信息以找到根本原因：

bash

agent -p '分析以下错误日志并建议修复方案：[粘贴日志内容]'

Git Integration

Git集成

Automate git operations with context awareness:

bash

agent -p 'Generate a commit message for the staged changes adhering to conventional commits.'

结合上下文感知自动化Git操作：

bash

agent -p '为暂存的变更生成符合约定式提交规范的提交信息。'

Batch Processing (CI/CD)

批量处理（CI/CD）

Run automated checks in CI pipelines:

bash

undefined

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

bash

undefined

Set API key in CI environment

在CI环境中设置API密钥

export CURSOR_API_KEY=$CURSOR_API_KEY

Run security audit with JSON output

运行安全审计并输出JSON结果

agent -p 'Audit this codebase for security vulnerabilities' --output-format json --force

agent -p '审计此代码库以查找安全漏洞' --output-format json --force

Generate test coverage report

生成测试覆盖率报告

agent -p 'Run tests and generate coverage report' --output-format text

undefined

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

undefined

Multi-file Analysis

多文件分析

Use context selection to analyze multiple files:

bash

agent

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

bash

agent

Then in interactive mode:

然后在交互模式中：

@src/api/ @src/models/ Review the API implementation for consistency with our data models

undefined

@src/api/ @src/models/ 审查API实现与数据模型的一致性

undefined