supsub-auth

supsub-auth Skill

Prerequisites

Install:curl -fsSL https://raw.githubusercontent.com/SupSub-AI/supsub-cli/master/scripts/install.sh | bash(native install, installed to ~/.local, supports background auto-update); or package manager npm i -g @supsub/cli / pnpm add -g @supsub/cli
Login credentials are saved in ~/.supsub/config.json(directory permissions 0700, file permissions 0600).supsub auth login uses OAuth device authorization, and on success writes access_token / refresh_token。The CLI does not support API Key login, there is no --api-key flag / SUPSUB_API_KEY entry point of this kind.
Tokens are automatically renewed：access_token expires in about 24 hours; the CLI uses refresh_token before expiration (or upon receiving a 401) to automatically exchange for a new token and write it back to the config file, all seamlessly.refresh_token is valid for about 14 days; only when it also becomes invalid do you need to supsub auth login。

Commands

Log in

supsub auth login

supsub auth login will automatically open the browser and complete login via the OAuth device authorization flow (Device Authorization); after successful authorization, write access_token / refresh_token to ~/.supsub/config.json. This is the CLI's only login method (API Key login is not supported).

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

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

In JSON mode (-o json), on successful login stdout outputs {"success":true,"data":{"client_id":"supsub-cli","email":"...","name":"..."}}（email / name comes from the user information fetched after login; if the fetch fails, these two fields are omitted, degrading to {"client_id":"supsub-cli"}); prompt messages go to stderr.

Check status

supsub auth status

Shows the current logged-in user, the masked credential, and its source. After a normal OAuth login, api_key_source is config(the credential comes from the access_token）；api_key field in the config file is the masked access token (the CLI continues to display the sk_live_*** prefix; it is not an actual 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

In JSON mode, outputs {"success":true,"data":{}}。

Agent Usage Notes

Before calling other supsub subcommands, first run supsub auth statusto confirm the credential is valid.
When not logged in / any command returns exit 2 (UNAUTHORIZED), do not stop at telling the user "not logged in": directly run supsub auth login to open browser authorization for the user (the command will automatically open the browser and block waiting for authorization, so use a sufficiently long timeout, such as 10 minutes; the user only needs to click confirm in the browser and does not need to enter anything in the terminal), and after successful authorization retry the original command. In a browserless / headless environment, fall back to prompting the user SUPSUB_NO_BROWSER=1 supsub auth login。
CLI API Key login is not supported, and there is no --api-key flag / SUPSUB_API_KEY environment variable; the only login entry point is supsub auth login(OAuth device authorization).
The Bearer credential used for requests is resolved by resolveApiKey() , priority (high → low): config file access_token(OAuth device authorization token) > config file bearer_token(advanced usage: a temporary session token manually pasted from the browser).
A 401 response willfirst attempt automatic renewal(use refresh_token to exchange for a new token and then retry the original request, see src/http/token-refresh.ts）：
- renewal succeeds → the command returns normally, seamlessly for the user, no need to log in again;
- refresh_token has also become invalid → clear all credentials (clearAuth()) and exit with exit code 2 , only then is it necessary to supsub auth login；
- the renewal request itself has a network error / server 5xx → credentials are retained and not cleared, exit with exit code 10(NETWORK) and exits, so the user can simply retry later;do nothave the user log in again based on this.
When parsing JSON, use -o json; common exit codes:0 OK，2 UNAUTHORIZED，3 PLAN_EXPIRED，10 NETWORK，11 SERVER，64 INVALID_ARGS。
Custom API base URL: set SUPSUB_API_URL(default https://supsub.net), for local or test environments.