beervid-app-cli

BEERVID 第三方应用 Open API 的 TypeScript CLI 和 Claude Code Skill，提供 TikTok 视频发布、账号授权、数据查询等完整能力。

安装与调用

全局安装

npm install -g beervid-app-cli
beervid --help

npx 免安装调用

npx beervid-app-cli --help
npx beervid-app-cli config --show
npx beervid-app-cli upload --file ./video.mp4

node 直接调用

# 克隆仓库后先构建
npm install && npm run build

# 通过 node 运行入口文件
node dist/cli.mjs --help
node dist/cli.mjs config --show

导出类型

构建后包根会导出 CLI 相关类型，可直接在 TypeScript 中引用：

import type { PublishCommandOptions, PublishTTFlowCommandOptions } from 'beervid-app-cli'

在 Claude Code / Codex / Antigravity 中使用（以下说明面向 AI Agent）

方式一：通过 npx skills add 安装（推荐）

npx skills add Lupeiwen0/beervid-app-cli

安装后 Skill 会自动注册到你的 skills 目录中，Claude Code 等 Agent 即可发现和调用。

方式二：手动安装

如果你是 Claude Code、Codex、Antigravity，或任何支持 Skill 的 AI Agent，请严格按下面规则执行：

• 用户把 GitHub 仓库链接发给你，不等于这个 Skill 已经安装到你的 skills 目录中。
• 只有当 skills/beervid-app-cli/ 目录被完整安装到你的 skills 目录后，才算这个 Skill 可用。

你必须先把以下目录复制到你自己的 skills 目录中：

skills/beervid-app-cli/
  SKILL.md
  skill.json
  QUICKSTART.md
  FAQ.md
  references/
  docs/
  example/

安装完成后，你应从 skills 目录中的 SKILL.md 加载本 Skill，而不是只读取仓库根目录里的 README.md 或 package.json。

对 AI Agent 来说，应这样区分：

• 目标是使用 CLI：安装 npm 包即可。
• 目标是使用 Skill：必须额外安装 Skill 文件；仓库链接本身不完成这一步。

配置

# 方式一：通过 config 命令持久化（推荐）
beervid config --app-key "your-api-key"

# 方式二：通过环境变量（优先级高于 config）
export BEERVID_APP_KEY="your-api-key"
export BEERVID_APP_BASE_URL="https://open.beervid.ai"  # 可选，有默认值

# 查看当前配置
beervid config --show

功能概览

| 命令 | 功能 | |------|------| | beervid config | 设置/查看全局配置（APP_KEY、BASE_URL） | | beervid get-oauth-url | 获取 TT/TTS OAuth 授权链接 | | beervid get-account-info | 查询账号信息 | | beervid upload | 上传视频（支持本地文件和 URL） | | beervid publish | 发布视频（普通/挂车） | | beervid poll-status | 轮询发布状态 | | beervid query-video | 查询视频统计数据 | | beervid query-products | 查询 TTS 商品列表 | | beervid publish-tt-flow | TT 完整发布流程：上传、发布、轮询、查数 | | beervid publish-tts-flow | TTS 完整发布流程：查商品、选商品、上传、发布 |

快速示例

beervid get-oauth-url --type tt
beervid upload --file ./video.mp4
beervid publish --type normal --business-id biz_123 --video-url https://cdn.beervid.ai/uploads/xxx.mp4

完整流程示例

# TT：上传 -> 发布 -> 轮询 -> 查询数据
beervid publish-tt-flow --business-id biz_123 --file ./video.mp4 --caption "My video"

# TTS：自动选商品 -> 上传 -> 挂车发布
beervid publish-tts-flow --creator-id open_user_abc --file ./video.mp4

# TTS：交互式选商品
beervid publish-tts-flow --creator-id open_user_abc --file ./video.mp4 --interactive

# TTS：手动指定商品
beervid publish-tts-flow --creator-id open_user_abc --file ./video.mp4 --product-id prod_123 --product-title "Widget"

TT / TTS 账号关联说明

• TTS 账号可用于挂车发布和商品查询，但不能直接查询视频数据。
• 如果同一达人既要走 TTS 挂车发布，又要查询该账号的视频数据，需要分别完成 TTS 和 TT 两种 OAuth 授权。
• 官方当前没有提供 uno_id 这类可直接关联 TT/TTS 账号的稳定字段。
• 当前推荐在授权后调用 account/info，以两边返回的 username 作为关联键，在你方系统里建立 TT 和 TTS 的软关联。
• 真正调用 API 时仍然使用各自的业务主键：TTS 用 creatorUserOpenId，TT 用 businessId；username 只用于你方系统内的关联映射。

详细用法见 SKILL.md。完整 API 参考见 references/api-reference.md。

落地文档

面向接入方后端工程师的项目落地建议：

| 文档 | 内容 | |------|------| | 数据表字段建议 | accounts/videos/products 表结构设计 | | OAuth 回调存储建议 | State Token 防 CSRF、回调持久化、异步头像同步 | | TT 轮询任务建议 | 阶梯递增轮询间隔、Cron/队列三层保障 | | TTS 商品缓存建议 | 全量拉取、缓存过期、图片 URL 解析 | | 失败重试与幂等建议 | 各 API 幂等性分析、指数退避、幂等键设计 |

示例工程

三种接入场景的可运行示例：

| 示例 | 场景 | 入口 | |------|------|------| | Standard | 纯 Node.js 脚本，快速验证 | npx tsx tt-publish-flow.ts | | Express | Express 后端服务，含 OAuth 回调 | npx tsx server.ts | | Next.js | Next.js App Router API Route | npm run dev |