---
title: "CLI 认证"
description: "基于 Cursor 官方 Authentication 文档解释浏览器登录、API key、状态检查、登出、CI secrets 和认证排障。"
verifiedAt: "2026-05-09"
---

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

> [!NOTE]
> **阅读目标**：读完本章，你应该能判断当前场景该用 `agent login` 还是 `CURSOR_API_KEY`，并能处理未登录、SSL 和 endpoint 类问题。

## 1. 认证方式怎么选

| 场景 | 推荐方式 | 原因 |
| --- | --- | --- |
| 个人本机终端 | Browser authentication | 操作最简单，凭据本地安全存储 |
| 新人 onboarding | Browser authentication | 容易确认账号和授权状态 |
| CI / GitHub Actions | API key | 无浏览器交互，适合 secrets 注入 |
| 自动化脚本 | API key | 可通过环境变量控制生命周期 |
| 临时排障 | `agent status` | 先确认身份，不要盲目重登 |

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

## 2. 浏览器登录

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

```bash
agent login
agent status
agent logout
```

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

登录后先跑：

```bash
agent status
```

它会显示：

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

登出用：

```bash
agent logout
```

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

## 3. API key 认证

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

推荐用环境变量：

```bash
export CURSOR_API_KEY=your_api_key_here
agent "implement user authentication"
```

也可以用命令行 flag：

```bash
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 注入：

```yaml
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`。

<details>
<summary>深读：为什么 CI 不应该复用个人登录态</summary>

CI 是共享、可复制、可审计的运行环境。个人登录态通常绑定本机交互和本地凭据，不适合迁移到 runner。

CI 应该使用可轮换、可最小授权、可审计的 API key，并通过 secrets 系统注入。这样出现问题时可以直接吊销和更换，而不是排查某个人机器上的登录状态。
</details>

## 本章自检

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

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

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

## 官方来源

- [Cursor CLI Authentication](https://cursor.com/docs/cli/reference/authentication.md) —— 官方浏览器登录、API key、状态检查和排障说明。
- [Cursor GitHub Actions](https://cursor.com/docs/cli/github-actions.md) —— 官方 CI 中 `CURSOR_API_KEY` 使用方式。
- [Cursor CLI Parameters](https://cursor.com/docs/cli/reference/parameters.md) —— 官方 `--api-key` 参数说明。

## 接下来去哪

<Cards>
  <Card title="CLI 权限" description="继续学习 Shell、Read、Write、WebFetch 和 MCP permissions。" href="/docs/cursor/official/03-cli-automation/40-permissions" />
  <Card title="GitHub Actions" description="回到 CI secrets 和 restricted autonomy workflow。" href="/docs/cursor/official/03-cli-automation/36-github-actions" />
</Cards>
