suya auth

suya auth 管理 CLI 如何针对 Subaya API 进行认证。关于两种凭据模式的概念性概览，请参见认证与 API 密钥。

`suya auth login`

通过 OAuth 浏览器流程交互式登录。

suya auth login
suya auth login --no-browser

标志	描述
`--no-browser`	不启动浏览器。打印一个短代码，供你在任意设备上批准（即下文的设备流程）。

默认情况下，CLI 使用环回重定向打开浏览器，并在本地存储所得到的令牌。当浏览器与 CLI 位于同一台机器上时，这是最快的路径——重定向目标是 127.0.0.1，因此必须如此。

如果浏览器无法打开，或者重定向始终没有回来（这通常意味着你的浏览器在别处——SSH、容器、远程开发机），CLI 会自动切换到设备流程。你不需要重新启动任何东西。

对于 agent 和 CI，更推荐设置 SUBAYA_API_KEY 而非登录——完全不涉及浏览器。

无浏览器登录（设备流程）

当运行 suya 的机器本身没有浏览器时使用这种方式：通过 SSH、在容器内、在远程构建机上。

suya auth login --no-browser

CLI 会打印一个代码和两个链接，然后等待：

  Open this link on any device:  https://subaya-dev.com/auth/device?user_code=KHTM-BQWD
  Or go to https://subaya-dev.com/auth/device and enter:  KHTM-BQWD

Waiting for approval... (Ctrl-C to cancel)

在任何有浏览器的设备上打开该页面——你的笔记本电脑、你的手机——如果尚未登录则先登录，核对屏幕上的代码与终端中的代码一致，然后批准。该页面会写明是哪台机器发起的请求，因此你能分辨出哪次是你自己的登录、哪次不是你发起的。CLI 会在几秒内察觉，保存令牌，并打印它所登录的账户。

全程不需要向终端回填任何内容，因此这种方式在脚本或 agent 中和在 shell 中一样可用。

注意：

该代码有效期为 10 分钟，且只能使用一次。如果过期，请重新运行命令以获取一个新的。
批准即授予 CLI 以你的身份、在你当前活动的组织中的访问权限。若要针对另一个组织登录，请先在控制台中切换组织，然后重新运行 suya auth login。
如果这次登录不是你发起的，请点击 Deny——不会签发任何令牌。

`suya auth logout`

登出并撤销本地存储的令牌。

suya auth logout

`suya auth status`

显示你的本地认证状态。这不会调用服务器——它报告 CLI 在磁盘上拥有哪些凭据。

suya auth status

`suya auth whoami`

调用服务器（/api/auth/cli/whoami）并打印你当前凭据所解析到的身份。它对两种凭据都有效： suya auth login 得到的令牌，以及 SUBAYA_API_KEY。在把某个密钥交给 CI 之前，用它来确认该密钥已正确接线。

export SUBAYA_API_KEY="sk_live_..."
suya auth whoami

如果凭据被拒绝，whoami 会说明原因，而不是只报告失败：

原因	含义
`unknown_key`	该 API 密钥无法识别——已撤销、已过期，或从未存在过。请在控制台的 Settings → API keys 下签发一个新的。
`wrong_environment`	该密钥格式正确，但属于另一个环境（见下文）。消息中会包含应该到哪里签发正确的密钥。
`unknown_token`	你的登录令牌已过期或已被撤销。请重新运行 `suya auth login`。
`no_credential`	完全没有出示任何凭据。请设置 `SUBAYA_API_KEY` 或运行 `suya auth login`。

密钥按环境区分

API 密钥在前缀中携带其所属环境，且一个密钥只对它被签发时对应的主机有效：

sk_live_… — 生产 API（https://subaya-dev.com），也就是 --host 的默认值。
sk_test_… — 保留给非生产环境。

把 sk_test_ 密钥发送到生产主机会被以 wrong_environment 拒绝，而不是笼统的“无效密钥” ——因此如果你看到这个原因，正确的做法是签发一个对应类型的密钥，而不是去排查某个被撤销的密钥。请在控制台的 Settings → API keys 下，在你打算调用的那个环境上签发密钥。

另请参见

快速开始 — 登录并运行你的第一次仿真。
CLI 概览 — 全局标志和完整的命令界面。