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引數說明。