CLI 认证
基于 Cursor 官方 Authentication 文档解释浏览器登录、API key、状态检查、登出、CI secrets 和认证排障。
📖 本篇术语速查表
| 英文 / 缩写 | 中文 | 一句话解释 |
|---|---|---|
| CLI 认证 | auth | CLI 的登录认证方式。 |
| 凭据缓存 | cache | 登录后保存的凭据。 |
| CI 认证 | ci auth | 自动化环境的认证方式。 |
不想读完？把下面这段提示词丢给 AI 帮你跑完——帮你配好 Cursor CLI 的认证，避免凭据泄露。
你是 Cursor CLI 认证配置顾问，帮我按环境配好认证，避免凭据泄露。
【角色】
你清楚 CLI 的认证方式、凭据缓存、CI / headless 环境的认证差异、凭据安全。
【输入】
- 我在什么环境用（本地 / CI / 远程）：___
- 有什么凭据：___
- 是否无人值守：___
- 安全要求：___
【工作流程】
1. 按环境推荐认证方式
2. 给配置步骤和凭据存放
3. 处理 CI / headless 的认证
4. 标出凭据安全点
【输出规范】
▌一、推荐认证方式
▌二、配置步骤
▌三、CI / headless 认证
▌四、凭据安全
【硬约束】
- 凭据走环境变量 / 安全存储，不明文
- 受管理环境按策略
- 远程优先最小权限凭据
- 不确定的认证标注需查官方文档
- 给的步骤能照做
- 每条结论落到可照做步骤，不空泛
- 给的每条结论都要落到具体可照做的步骤或示例，不停留在「建议」「考虑一下」这类没法直接执行的空泛表述Cursor CLI 支持两类认证：浏览器登录和 API key。个人终端优先用浏览器登录；脚本、CI/CD 和自动化环境使用 API key。
阅读目标：读完本章，你应该能判断当前场景该用 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. 浏览器登录
官方推荐的浏览器登录流程：
agent login
agent status
agent logoutagent 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。
深读：为什么 CI 不应该复用个人登录态
CI 是共享、可复制、可审计的运行环境。个人登录态通常绑定本机交互和本地凭据，不适合迁移到 runner。
CI 应该使用可轮换、可最小授权、可审计的 API key，并通过 secrets 系统注入。这样出现问题时可以直接吊销和更换，而不是排查某个人机器上的登录状态。
本章自检
完成本章后，用这 3 个问题检查自己是否真正理解：
- 为什么个人本机优先用
agent login？ - 为什么 CI 中推荐
CURSOR_API_KEY环境变量，而不是--api-key明文参数？ agent status能帮助确认哪些认证事实？
通过标准：你能为本机、GitHub Actions 和自托管 runner 分别写出认证方案，并说明 key 存储、日志和轮换边界。
官方来源
- Cursor CLI Authentication —— 官方浏览器登录、API key、状态检查和排障说明。
- Cursor GitHub Actions —— 官方 CI 中
CURSOR_API_KEY使用方式。 - Cursor CLI Parameters —— 官方
--api-key参数说明。