Supsub Auth

supsub-auth Skill

Log in, log out, and check authentication status for the SupSub CLI.

Prerequisites

• 安装：curl -fsSL https://raw.githubusercontent.com/SupSub-AI/supsub-cli/master/scripts/install.sh | bash（native 安装，装到 ~/.local、支持后台自动更新）；或包管理器 npm i -g @supsub/cli / pnpm add -g @supsub/cli
• 登录凭证保存在 ~/.supsub/config.json（目录权限 0700，文件权限 0600）。supsub auth login 走 OAuth 设备授权，成功后写入 access_token / refresh_token。CLI 不支持 API Key 登录，没有 --api-key flag / SUPSUB_API_KEY 这一类入口。
• 令牌会自动续期：access_token 约 24 小时到期，CLI 在过期前（或收到 401 时）用 refresh_token 自动换新令牌并写回配置文件，全程无感。refresh_token 约 14 天有效，只有它也失效时才需要重新 supsub auth login。

Commands

Log in

supsub auth login

supsub auth login 会自动打开浏览器，走 OAuth 设备授权流程（Device Authorization）完成登录；授权成功后把 access_token / refresh_token 写入 ~/.supsub/config.json。这是 CLI 唯一的登录方式（不支持 API Key 登录）。

# 自动打开浏览器完成授权
supsub auth login

# 无头 / e2e 环境：跳过自动打开浏览器，手动复制终端里的链接去授权
SUPSUB_NO_BROWSER=1 supsub auth login

JSON 模式 (-o json) 下，登录成功 stdout 输出 {"success":true,"data":{"client_id":"supsub-cli","email":"...","name":"..."}}（email / name 来自登录后拉取的用户信息；若拉取失败这两个字段缺省，退化为 {"client_id":"supsub-cli"}）；提示信息走 stderr。

Check status

supsub auth status

Shows the current logged-in user, the masked credential, and its source。正常 OAuth 登录后 api_key_source 为 config（凭证来自配置文件里的 access_token）；api_key 字段是脱敏后的访问令牌（CLI 沿用 sk_live_*** 前缀展示，并非真有 API Key）。

supsub auth status
supsub auth status -o json

JSON shape:

{
  "success": true,
  "data": {
    "email": "...",
    "name": "...",
    "client_id": "supsub-cli",
    "api_key_source": "config",
    "api_key": "sk_live_***xxxx"
  }
}

If unauthenticated, exits with code 2 (UNAUTHORIZED) and a message asking the user to run supsub auth login.

Log out

supsub auth logout

Removes saved credentials from ~/.supsub/config.json.

supsub auth logout
supsub auth logout -o json

JSON 模式下输出 {"success":true,"data":{}}。

Agent Usage Notes

• 在调用其他 supsub 子命令之前先跑 supsub auth status，确认凭证有效。
• 未登录 / 任意命令返回 exit 2（UNAUTHORIZED）时不要止步于告知用户「未登录」：直接运行 supsub auth login 为用户打开浏览器授权（命令会自动打开浏览器并阻塞等待授权，请用足够长的超时，如 10 分钟；用户只需在浏览器点确认，无需在终端输入任何内容），授权成功后重试原命令。无浏览器 / 无头环境再回退为提示用户 SUPSUB_NO_BROWSER=1 supsub auth login。
• CLI 不支持 API Key 登录，也没有 --api-key flag / SUPSUB_API_KEY 环境变量；登录唯一入口是 supsub auth login（OAuth 设备授权）。
• 请求所用 Bearer 凭证由 resolveApiKey() 解析，优先级（高 → 低）：配置文件 access_token（OAuth 设备授权令牌）> 配置文件 bearer_token（高级用法：手动从浏览器粘贴的临时会话 token）。
• 401 响应会先尝试自动续期（用 refresh_token 换新令牌后重试原请求，见 src/http/token-refresh.ts）：
  • 续期成功 → 命令正常返回，用户无感，无需重新登录；
  • refresh_token 也已失效 → 清除全部凭证（clearAuth()）并以 exit code 2 退出，此时才需要重新 supsub auth login；
  • 续期请求本身网络异常 / 服务端 5xx → 凭证保留不清，以 exit code 10（NETWORK）退出，让用户稍后重试即可，不要据此让用户重新登录。
• 解析 JSON 时使用 -o json；常见 exit code：0 OK，2 UNAUTHORIZED，3 PLAN_EXPIRED，10 NETWORK，11 SERVER，64 INVALID_ARGS。
• 自定义 API base URL：设置 SUPSUB_API_URL（默认 https://supsub.net），用于本地或测试环境。