bgm-cli

简体中文 | 繁體中文（台灣） | English

bgm-cli 是一个面向 Bangumi 的命令行工具，目标是让用户尽快在终端里完成常见读取、查询和部分写入操作。

快速开始

运行要求

• Node.js >= 20

安装

macOS / Linux：

curl -fsSL https://raw.githubusercontent.com/aronnaxlin/bgm-cli/main/scripts/install-remote.sh | sh

Windows PowerShell：

irm https://raw.githubusercontent.com/aronnaxlin/bgm-cli/main/scripts/install-remote.ps1 | iex

如果你已经在本地 clone 了仓库，也可以直接运行：

./bgm --help

认证

推荐路径是使用 Bangumi Access Token：

bgm --init

如果你已经有 Token，也可以直接保存：

bgm auth set-token YOUR_ACCESS_TOKEN
bgm auth status

常用命令

bgm user me
bgm subject search "Heike Monogatari" --type anime --limit 5
bgm subject get 348335
bgm collection get 348335
bgm episode list 348335 --type main --limit 10
bgm episode watch 348335 1
bgm blog --help
bgm group list --sort members --limit 10
bgm status --site bgm.tv
bgm --json user me

文档索引

• 本项目同时提供可安装的 Skills，适合让 AI / Agent 直接安装并操作 bgm-cli。
• 可以通过 npx skills add aronnaxlin/bgm-cli 添加本项目的 Skills。
• docs/README.md：文档总入口
• docs/guide.zh-CN.md：主体导览、推荐使用路径、安装与常见使用方式
• docs/features.zh-CN.md：完整功能列表与命令索引
• docs/implementation.zh-CN.md：配置模型、输出模型、收藏语义、仓库结构与开发说明
• docs/experimental.zh-CN.md：实验性功能、OAuth / Turnstile / private session / hosted backend 说明
• oauth-backend/README.md：可选自托管 OAuth backend 的部署说明
• SKILLS.md：给 AI / Agent 的仓库与操作入口

核心风险与边界

• 本项目不是 Bangumi 官方产品，与 Bangumi 官方没有隶属关系。
• 普通用户默认应优先使用 Access Token；OAuth、private session、hosted backend 都不应视为默认主路径。
• 一部分社区写操作依赖 Turnstile，且个别实验性写操作目前仍可能遇到 Bangumi 服务端失败。
• 如果要做脚本集成，建议优先使用 --json，不要依赖人类可读输出的文本格式。
• Bangumi 建议客户端使用可识别开发者和应用身份的自定义 User-Agent。

致谢与承认

• 感谢 bgm.tv 提供 Bangumi 主站与社区生态。
• 感谢 bangumi/server-private 提供 private API 相关实现参考。
• 感谢 bangumi/api 提供公开 API 相关实现与文档基础。
• 感谢 bgm-status.ry.mk 提供社区维护的 Bangumi 可用性状态观测能力；该服务作者为 wataame。
• 本仓库会尽量反映当前可验证的 Bangumi 行为约束，但不承诺覆盖网站上的全部功能，也不承诺第三方站点行为长期稳定不变。

许可证

本仓库使用 AGPL-3.0-only 许可证。详见 LICENSE。