mcpField
S
supsub-auth

supsub-auth

github.com/supsub-aiOther558 installsUpdated 13w ago
Repository

About supsub-auth

supsub-auth manages SupSub CLI authentication for SupSub users and their Agents. It uses OAuth device authorization and provides status checks, logout, and automatic token renewal.

Key features

  1. 01Log in with OAuth device authorization
  2. 02Check current authentication status
  3. 03Log out and remove saved credentials
  4. 04Renew access tokens automatically

Use cases

  1. 01Authenticate when starting to use SupSub CLI
  2. 02Verify whether credentials are valid
  3. 03End a session and clear saved credentials
  4. 04Renew an access token when it expires

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/supsub-ai/supsub-cli --skill supsub-auth

After installing, type/supsub-authin Claude Code to confirm it loaded.

Details

From the project README

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），用于本地或测试环境。

Comments

Markdown supported