Cursor 进终端了：CLI 早期 beta 怎么用

编辑器里用久了 Cursor，很多人会想：终端里能不能也直接喊它改代码。官方现在给的入口就叫 Cursor CLI，命令是 agent。装完之后，你可以在当前仓库里开一轮对话，也可以用打印模式丢进脚本和 CI。

下面按官方文档把安装、登录、三种模式、无头脚本和几个容易踩的坑过一遍。更细的参数以 Cursor CLI 概览 为准。

安装

macOS、Linux、WSL 一条命令：

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

Windows 原生用 PowerShell：

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

装完先确认二进制在不在：

agent --version

默认会落到 ~/.local/bin。bash 用户把这一行写进 ~/.bashrc，zsh 写进 ~/.zshrc：

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

CLI 默认会自动更新。想手动拉最新版，跑 agent update。

登录

日常推荐浏览器登录：

agent login
agent status

login 会打开默认浏览器，用你的 Cursor 账号授权，凭据存在本机。机器没有图形界面时，先设 NO_OPEN_BROWSER=1，再把打印出来的 URL 拷到能开浏览器的地方。

脚本和 CI 用 API Key。在 Cursor Dashboard 的 API Keys 里生成一把，然后二选一：

export CURSOR_API_KEY=your_api_key_here
agent "implement user authentication"

或者一次性传进去（别把密钥写进仓库）：

agent --api-key "$CURSOR_API_KEY" "implement user authentication"

agent status 能看到你有没有登录、账号信息和当前 endpoint。报 Not authenticated 时，先重新 agent login，或检查环境变量有没有带上。

三种模式

CLI 和编辑器共用同一套模式，Shift+Tab 轮换，也可以用斜杠命令或启动参数。

进仓库根目录就能开一轮：

agent
agent "refactor the auth module to use JWT tokens"

想先摸清项目再改，用 Ask；任务边界还糊着，用 Plan。官方也建议在提示里把意图写死，比如加上 “do not write any code”，避免它提前动文件。

对话里常用的键

• @ 把文件或目录挂进上下文
• Shift+Enter 换行再提交（iTerm2、Ghostty、Kitty、Warp、Zed 可用）
• tmux 里换行用 Ctrl+J，Shift+Enter 经常不生效
• Ctrl+R 回看这次改了哪些文件，i 补一句后续指令
• /summarize 压缩上下文（/compress 是别名）
• / 菜单里选 Skill，回车只作用于这一条；Option+Enter 会把它当成 Custom Mode 挂着，直到你退出
• Ctrl+D 退出，和普通 shell 一样要按两下
• 它要跑终端命令时会先问你 y/n

需要提权时，CLI 会弹出遮罩过的 sudo 密码框，密码走本机 IPC，模型看不到。沙箱用 /sandbox 或 --sandbox enabled / --sandbox disabled，设置会留下来。

中途想把活丢到云上继续跑，消息前面加 &：

之后可以在 cursor.com/agents 用网页或手机接着看。

无头模式：脚本和 CI

加 -p / --print 就是非交互。默认输出 text，只要最终答案；脚本里要结构化结果，用 --output-format json 或 stream-json。

agent -p "find and fix performance issues" --model "gpt-5"
agent -p "review these changes for security issues" --output-format text

打印模式里 Agent 有完整工具权限。真要改文件，还得加 --force（也叫 --yolo）。不加的话，它只会提出改动，不会落盘：

agent -p --force "Refactor this code to use modern ES6+ syntax"

批量给源文件补注释可以这样套：

find src/ -name "*.js" | while read file; do
  agent -p --force "Add comprehensive JSDoc comments to $file"
done

图片、截图直接把路径写进提示即可，Agent 会自己读文件。

会话和工作树

不想每次从零开始：

agent ls
agent resume
agent --continue
agent --resume="chat-id-here"

怕它直接改当前工作区，加 -w / --worktree。Cursor 会在 ~/.cursor/worktrees/ 下开一份 checkout，清理规则和编辑器里的 worktree 一样。需要指定仓库根目录时再加 --workspace：

agent --worktree "upgrade the test runner and fix any broken snapshots"
agent --workspace ~/src/my-app --worktree auth-fix "fix the flaky auth test and open a PR"

规则和 MCP

CLI 会读项目里的 .cursor/rules，也会把仓库根目录的 AGENTS.md、CLAUDE.md 当成规则一起用。MCP 走你已经配好的 mcp.json，编辑器里能用的服务器，终端里同一套。

另外还支持 ACP：agent acp 会在 stdio 上当一个 JSON-RPC 服务，方便自己写客户端嵌进去。日常写代码用不到，做自定义 IDE 集成时再看 ACP 文档。

几个容易踩的坑

1. 装完找不到 agent：多半是 ~/.local/bin 没进 PATH，先 agent --version 验证。
2. 脚本跑了但文件没变：打印模式要同时带 --force，否则只出建议。
3. tmux 里 Enter 怪：换行用 Ctrl+J，不要死磕 Shift+Enter。
4. CI 里浏览器弹不出来：用 CURSOR_API_KEY，不要在流水线里跑 agent login。
5. 无头模式会写文件、会跑命令。先在 Ask 或小范围 worktree 里试，再把 --force 丢进流水线。

更完整的参数表在 Using Agent in CLI 和 Headless CLI。登录细节见 Authentication。