CLI 认证

Cursor CLI 支持两类认证：浏览器登录和 API key。个人终端优先用浏览器登录；脚本、CI/CD 和自动化环境使用 API key。

1. 认证方式怎么选

不要把 API key 当成本地登录的默认替代。能用浏览器登录的本机场景，用 agent login 更清晰。

2. 浏览器登录

官方推荐的浏览器登录流程：

agent login
agent status
agent logout

agent login 会打开默认浏览器并要求你用 Cursor 账号认证。完成后，凭据会安全存储在本地。

登录后先跑：

agent status

它会显示：

• 是否已经认证。
• 当前账号信息。
• 当前 endpoint 配置。

登出用：

agent logout

这会清除本地存储的认证信息。共享机器、录屏环境和排障结束后都应该显式登出。

3. API key 认证

API key 用在 automation、scripts、CI/CD。先从 Cursor Dashboard 的 Integrations 下生成 user API key。

推荐用环境变量：

export CURSOR_API_KEY=your_api_key_here
agent "implement user authentication"

也可以用命令行 flag：

agent --api-key your_api_key_here "implement user authentication"

商业级实践里，环境变量优于命令行 flag。命令行参数更容易进入 shell history、process list、CI log 或排障截图。

4. CI secrets 边界

GitHub Actions 中用 repository 或 organization secrets 注入：

env:
  CURSOR_API_KEY: ${{ secrets.CURSOR_API_KEY }}

上线前检查：

• key 不写进仓库。
• key 不写进 prompt。
• key 不打印到日志。
• 只给需要的 repo 或 org scope。
• 离职、泄露、runner 异常后能轮换。

API key 是自动化身份，不是“团队万能钥匙”。不同项目和环境最好使用不同 secret，方便审计和吊销。

5. 认证排障

Not authenticated

• 本机运行 agent login。
• CI 检查 CURSOR_API_KEY 是否存在。
• 确认 secret 名称和 workflow env 名称一致。

SSL certificate errors

• 开发或受管网络中可按官方说明使用 --insecure。
• 企业环境优先配置可信 CA，不要长期依赖 insecure。

Endpoint issues

• 使用 --endpoint 指定自定义 API endpoint。
• 用 agent status 检查当前 endpoint。

账号不对

• 先 agent status 看当前账号。
• 再 agent logout，重新 agent login。

本章自检

完成本章后，用这 3 个问题检查自己是否真正理解：

1. 为什么个人本机优先用 agent login？
2. 为什么 CI 中推荐 CURSOR_API_KEY 环境变量，而不是 --api-key 明文参数？
3. agent status 能帮助确认哪些认证事实？

通过标准：你能为本机、GitHub Actions 和自托管 runner 分别写出认证方案，并说明 key 存储、日志和轮换边界。

官方来源

• Cursor CLI Authentication —— 官方浏览器登录、API key、状态检查和排障说明。
• Cursor GitHub Actions —— 官方 CI 中 CURSOR_API_KEY 使用方式。
• Cursor CLI Parameters —— 官方 --api-key 参数说明。

接下来去哪