CLI 認證
基於 Cursor 官方 Authentication 文件解釋瀏覽器登入、API key、狀態檢查、登出、CI secrets 和認證排障。
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引數說明。