1.0.0 • Published 1 month agoCLI

@aronnaxlin/bgm-cli

Licence

AGPL-3.0-only

Version

1.0.0

Deps

Size

552 kB

Vulns

Weekly

Stars

Summary Dependency Versions

bgm-cli

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

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

快速开始

运行要求

Node.js >= 20

安装

npm / npx：

npx @aronnax/bgm-cli --help
npm install -g @aronnax/bgm-cli

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 登录：

bgm --init

bgm --init 会优先提供官方登录，也保留 Access Token 作为第二种渠道。如果你已经有 Token，也可以直接保存：

bgm auth set-token YOUR_ACCESS_TOKEN
bgm auth token-status

代理

如果你所在网络访问 Bangumi API 不稳定，可以为所有 CLI 请求设置 HTTP/HTTPS 代理：

bgm proxy set http://127.0.0.1:7890
bgm proxy show

临时使用也可以通过环境变量：

BGM_PROXY=http://127.0.0.1:7890 bgm subject get 8

代理优先级为：bgm proxy set 持久化配置 > BGM_PROXY > HTTPS_PROXY / HTTP_PROXY。

常用命令

bgm user me
bgm notify --limit 10
bgm subject search "Heike Monogatari" --type anime --limit 5
bgm subject get 348335
bgm subject comments 348335 --limit 5
bgm character search "明日香" --limit 3
bgm person search "庵野" --limit 3
bgm collection get 348335
bgm collection indexes --limit 5
bgm episode list 348335 --type main --limit 10
bgm episode comments 348335 1
bgm episode watch 348335 1
bgm blog --help
bgm group list --sort members --limit 10
bgm user friends --limit 5
bgm group user --limit 5
bgm index user --limit 5
bgm trending subjects --type anime --limit 5
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 官方没有隶属关系。
普通用户默认应优先使用 bgm --init 里的官方登录；Access Token 保留为兼容和脚本场景渠道，OAuth / 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。