SupSub CLI

外观

安装 ​

本文只讲「如何装上并登录到可用」；完整命令清单见命令参考。

在用 AI 助手？可以让它替你装

把这句话发给 Claude Code / Cursor 等助手，安装、技能包、登录一步到位：

请阅读 https://raw.githubusercontent.com/SupSub-AI/supsub-cli/master/docs/cli-installation-guide.md 并据此帮我安装并配置 SupSub CLI

环境要求 ​

  • 支持平台：macOS（x64 / arm64）、Linux（x64 / arm64）、Windows（x64）。CLI 本体是预编译可执行文件，运行时不依赖 Node。
  • native 安装：仅需 curl 与 tar（macOS / Linux 自带），无需 Node。
  • npm 安装：需 Node.js ≥ 20（仅用于执行 npm 安装与 postinstall 下载脚本）。
  • 网络：安装期间需访问 registry.npmjs.org 与 github.com（从 GitHub Release 下载对应平台 binary）。

第 1 步　安装 ​

方式一：native 安装（推荐，macOS / Linux） ​

shell
curl -fsSL https://raw.githubusercontent.com/SupSub-AI/supsub-cli/master/scripts/install.sh | bash

装到用户目录 ~/.local（版本并存于 ~/.local/share/supsub/versions/，~/.local/bin/supsub 为指向当前版本的链接），永不需要 sudo，且支持后台静默自动更新与一键回滚。看到 安装成功 🎉 即完成。

若脚本提示 ~/.local/bin 不在 PATH，把它加入 shell 配置后重开终端：

shell
export PATH="$HOME/.local/bin:$PATH"

方式二：npm（跨平台，含 Windows） ​

shell
npm i -g @supsub/cli

安装过程中 postinstall 会自动从 GitHub Release 下载与当前系统匹配的预编译 binary，并在全局 bin 目录创建 supsub 链接。npm 安装为手动更新，不做后台自动更新。

用 pnpm 安装

也可用 pnpm add -g @supsub/cli。注意 postinstall 的链接逻辑以 npm 全局 bin 为准；若用 pnpm 安装后 supsub 不在 PATH，请确认 npm 全局 bin 目录（npm prefix -g 下的 bin）已加入 PATH，或改用 npm i -g。

第 2 步　配置 Agent Skills ​

在 Claude Code / Cursor 等 agent 中使用 supsub 时，需要安装配套技能包，agent 才能用自然语言正确驱动 supsub：

shell
# Claude Code 插件市场
/plugin marketplace add SupSub-AI/supsub-cli
/plugin install supsub-cli@supsub
shell
# 其他兼容 agent（skills CLI）：静默安装仓库内全部 skills 到当前项目（./.agents/skills/）
npx -y skills add SupSub-AI/supsub-cli --skill '*' -y

详见让 AI 助手帮你用。纯手工使用终端可跳过此步。

第 3 步　登录 ​

shell
supsub auth login
  • 默认走浏览器 OAuth 设备授权：终端打印授权链接与授权码，并自动打开浏览器；用户在浏览器确认后，CLI 即自动完成登录。
  • 授权成功后凭证写入 ~/.supsub/config.json，终端展示当前用户「昵称 <邮箱>」。

Agent / 无头环境：设 SUPSUB_NO_BROWSER=1 跳过自动打开浏览器，再从终端输出里提取授权链接（形如 请在浏览器打开 https://…）交用户在浏览器完成授权：

shell
SUPSUB_NO_BROWSER=1 supsub auth login

令牌续期与失效说明见登录与凭证。

第 4 步　验证 ​

shell
supsub auth status

输出当前登录用户（邮箱 / 昵称）、凭证来源与套餐状态；退出码 0 表示已登录可用。供 agent 解析时加 -o json：

shell
supsub --output json auth status

升级 ​

shell
supsub update            # 自更新到最新版本（并同步本地 skills）
supsub update --check    # 只检查是否有新版本，不实际更新
supsub doctor            # 自检：安装方式、当前版本、上次更新检查、PATH、skills 同步状态

native 安装还会在后台静默自动升级（新版本下次启动生效）。npm 安装也可用包管理器：npm i -g @supsub/cli@latest。完整说明见升级与 Skills 同步。

卸载 ​

shell
# native 安装
rm -rf ~/.local/share/supsub ~/.local/bin/supsub

# npm 安装
npm rm -g @supsub/cli

凭证文件 ~/.supsub/config.json 不随卸载删除；如需彻底清理，手动删除该目录即可。