登录认证
tcb login 用于登录腾讯云账号，授权 CloudBase CLI 操作你的云开发资源。未登录时，大多数命令会提示先登录。
登录方式怎么选
| 场景 | 推荐命令 | 说明 |
|---|---|---|
| 本机开发（默认） | tcb login | 设备码授权，终端输出链接与用户码，同时自动打开浏览器 |
| 国际站账号 | tcb login --intl true | 同时持久化站点配置 |
| 远程服务器 / SSH | tcb login | 默认设备码流程，无需端口映射 |
| 容器 / 无头环境 / AI Agent | tcb login | 无浏览器时只输出链接与用户码 |
| CI/CD 非交互 | tcb login --apiKeyId <SecretId> --apiKey <SecretKey> | 账号级云 API 密钥 |
| 环境级长期凭证 | tcb login --cloudbase-api-key <key> -e <envId> | 权限限定在指定环境 |
| 临时密钥 | tcb login --apiKeyId <SecretId> --apiKey <SecretKey> --token <Token> | 适合短期授权 |
| 本机，走本地回调 | tcb login --flow web | 回调由本机 127.0.0.1 接收，无需输入用户码 |
| 企业自建授权服务 | tcb login --endpoint <url> | 仅设备码流程生效 |
本机登录（默认）
在终端执行：
tcb login
CLI 默认使用设备码授权（OAuth 2.0 Device Authorization Grant，RFC 8628），不要求发起登录的终端与完成确认的浏览器在同一台机器上：
- 执行
tcb login，CLI 输出授权链接（verification_uri）和用户码（user_code），并尝试自动打开浏览器 - 在浏览器中确认授权（如未自动打开，手动复制链接访问）
- CLI 自动轮询授权状态，完成后保存本地登录态
已登录且凭证有效时，tcb login 直接返回「您已登录，无需再次登录！」，不会再走授权流程。要换方式或换账号，先 tcb logout。
本地回调授权
在有图形界面的本机，可以让 CLI 拉起浏览器并通过本地回调完成授权，无需手动输入用户码：
tcb login --flow web
该模式下，CLI 在本机启动临时 HTTP 服务并监听随机端口，授权结果由 http://127.0.0.1:<port> 接收，因此要求本机既能打开浏览器，也能接收该本地回调（等待回调默认超时 10 分钟）。远程服务器、容器、无头环境请使用默认的设备码流程。
💡
--flow可选device（默认）与web。TCB_NO_BROWSER=true只在--flow web下生效，用于禁止自动打开浏览器；设备码流程不读取该变量。
云 API 密钥登录
如果已有腾讯云云 API 密钥，可以交互式输入完成登录：
tcb login --key
按提示输入 SecretId 和 SecretKey。密钥可在 云 API 密钥管理 页面创建或查看。
⚠️ 安全提示：腾讯云 API 密钥可以操作您名下的所有腾讯云资源，请妥善保存并定期更换密钥；更换后请及时删除旧密钥。
远程服务器与 SSH
直接使用默认的设备码流程即可：
tcb login
复制终端输出的授权链接和用户码，在本地或其他可访问浏览器的设备上打开并确认授权。CLI 会自动轮询结果，不需要端口映射，也不要求本地回调。
容器、无头环境与 AI Agent
设备码流程不依赖浏览器和本地回调，适用于：
- Docker / Kubernetes 容器、无图形界面的服务器
- Agent、CI Runner 等自动化环境
- AI 编程助手（如 Claude Code、OpenAI Codex）通过 MCP 工具或脚本调用 CloudBase CLI
tcb login
无浏览器时，自动打开浏览器这一步会失败并被忽略，授权链接与用户码照常输出。远程确认授权后，CLI 自动完成登录。TCB_NO_BROWSER=true 只对 --flow web 生效，无头环境用不上。
CI/CD 与非交互式登录
云 API 密钥（账号级）
通过 --apiKeyId 与 --apiKey 直接传入腾讯云云 API 密钥，适合脚本和流水线：
tcb login --apiKeyId <SecretId> --apiKey <SecretKey>
临时密钥额外传入 --token：
tcb login --apiKeyId <SecretId> --apiKey <SecretKey> --token <Token>
⚠️ 账号级密钥可以操作你名下的所有腾讯云资源，请存放在 CI 的 Secrets 中，不要写入仓库；定期轮换并及时删除旧密钥。
环境级 API Key
使用 CloudBase 环境级长期凭证，权限范围限定在指定环境内，更适合环境隔离授权：
tcb login --cloudbase-api-key <key> -e <envId>
必须配合 -e/--env-id 指定环境。创建方式见 API Key 管理。
GitHub Actions 示例
- name: Login to CloudBase
run: npx @cloudbase/cli login --cloudbase-api-key ${{ secrets.CLOUDBASE_API_KEY }} -e ${{ secrets.CLOUDBASE_ENV_ID }}
国际站登录
国际站账号请在登录时显式指定站点：
tcb login --intl true
--intl true会让本次登录立即使用国际站（授权页与 OAuth 端点同时切换），并将站点配置持久化，后续命令默认使用国际站- 切回国内站：
tcb login --intl false，或tcb config set isIntl false - 也可以先执行
tcb config set isIntl true，再执行tcb login - 站点优先级：
--intl> 配置文件isIntl> 环境变量TCB_IS_INTL> 默认国内站 - 站点与地域相互独立：切换站点不会改变 region。国际站环境通常位于新加坡，后续命令需要指定地域时请加
-r ap-singapore（例如tcb env list -r ap-singapore）
自定义授权端点
企业用户可将设备码授权指向自建服务：
tcb login --endpoint https://your-auth-server.example.com
CLI 会使用指定 Endpoint，依次调用 /device/code 和 /token 接口获取凭证。该选项仅在 --flow device（默认）时生效；自建服务需遵循 CloudBase CLI Device Flow 协议，详见 设备码授权概览 与 企业自建设备码授权服务。
验证登录状态
tcb env list
能够列出环境即表示登录成功。如果提示未登录、凭证失效或列表为空，请重新执行 tcb login；国际站账号还需确认地域参数（见国际站登录）。
登出与切换账号
tcb logout
tcb logout 会清除本地登录凭证（包括项目级凭证）和当前环境记录。需要切换账号时，登出后重新执行 tcb login 即可。
凭证存储与安全
- 登录凭证保存在 CLI 配置目录的
auth.json，默认路径为~/.config/.cloudbase/（遵循XDG_CONFIG_HOME） - 使用环境级 API Key 登录时，凭证可能写入项目级存储（与登录时的项目目录一致）
auth.json包含身份凭据，请勿提交到仓库或分享给他人- 长期密钥优先通过 CI Secrets 或环境变量注入，避免硬编码在脚本和配置文件中
常见问题
登录成功但 tcb env list 为空？
- 账号下尚未创建环境，请前往控制台创建
- 国际站账号未指定地域：尝试
tcb env list -r ap-singapore - 子账号权限不足，参见 子账号登录说明
浏览器无法打开或授权页打不开？
使用默认设备码流程，手动复制终端输出的链接和用户码。TCB_NO_BROWSER=true 对设备码流程无效，只影响 --flow web。
--flow web 回调失败？
该模式要求本机可访问 127.0.0.1 的随机端口。远程服务器、容器或存在端口限制时，请改用默认的 --flow device。
已登录但提示无权限？
检查账号与环境归属。环境级 API Key 只能操作创建时指定的环境，账号级密钥则受 CAM 权限策略限制。