supsub-auth

supsub-auth スキル

SupSub CLI にログイン、ログアウトし、認証状態を確認します。

前提条件

• インストール：curl -fsSL https://raw.githubusercontent.com/SupSub-AI/supsub-cli/master/scripts/install.sh | bash（ネイティブインストール。~/.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 フラグや SUPSUB_API_KEY のような設定方法はありません。
• トークンは自動更新されます：access_token の有効期限は約 24 時間です。CLI は期限切れ前、または 401 を受け取ったときに、refresh_token を使ってトークンを自動更新し、設定ファイルに書き戻します。処理はバックグラウンドで行われます。refresh_token の有効期限は約 14 日です。これも無効になった場合にのみ、supsub auth login を再度実行する必要があります。

コマンド

ログイン

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 に出力されます。

---

ステータスの確認

supsub auth status

現在ログイン中のユーザー、マスクされた認証情報、およびそのソースを表示します。通常の OAuth ログイン後は api_key_source が config になります（認証情報は設定ファイル内の access_token です）。api_key フィールドには、マスクされたアクセストークンが表示されます（CLI は sk_live_*** というプレフィックスで表示しますが、実際に API Key が存在するわけではありません）。

supsub auth status
supsub auth status -o json

JSON の形式：

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

未認証の場合は、終了コード 2（UNAUTHORIZED）で終了し、ユーザーに supsub auth login の実行を促すメッセージを表示します。

---

ログアウト

supsub auth logout

~/.supsub/config.json から保存済みの認証情報を削除します。

supsub auth logout
supsub auth logout -o json

JSON モードでは {"success":true,"data":{}} が出力されます。

---

エージェントの使用上の注意

• 他の supsub サブコマンドを呼び出す前に、supsub auth status を実行して認証情報が有効であることを確認してください。
• 未ログインの場合や、任意のコマンドが exit 2（UNAUTHORIZED）を返した場合は、ユーザーに「未ログイン」と伝えるだけで終わらせないでください：supsub auth login を直接実行して、ユーザーのブラウザーで認証を開始してください（このコマンドはブラウザーを自動的に開き、認証が完了するまで待機します。十分に長いタイムアウト（例：10 分）を設定してください。ユーザーはブラウザーで確認ボタンをクリックするだけで、ターミナルでの入力は不要です）。認証に成功したら、元のコマンドを再試行してください。ブラウザーが使えない場合やヘッドレス環境の場合は、代わりに SUPSUB_NO_BROWSER=1 supsub auth login をユーザーに案内してください。
• CLI は API Key ログインに対応しておらず、--api-key フラグや 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()）し、終了コード 2 で終了します。この場合にのみ supsub auth login を再度実行する必要があります。
  • 更新リクエスト自体でネットワークエラーまたはサーバー 5xx が発生 → 認証情報は保持され、クリアされません。終了コード 10（NETWORK）で終了するため、後で再試行するだけで構いません。これを理由にユーザーに再ログインを促さないでください。
• JSON の解析には -o json を使用してください。一般的な終了コード：0 OK、2 UNAUTHORIZED、3 PLAN_EXPIRED、10 NETWORK、11 SERVER、64 INVALID_ARGS。
• カスタム API base URL：SUPSUB_API_URL を設定します（デフォルトは https://supsub.net）。ローカル環境またはテスト環境で使用します。