140 lines
9.0 KiB
Plaintext
140 lines
9.0 KiB
Plaintext
# catbus
|
||
|
||
> catbus (猫巴士, "all aboard, every platform") is a TypeScript CLI that drives the web APIs of 10 Chinese and global platforms — Xiaohongshu (xhs), Douyin, TikTok, Bilibili, Kuaishou, Weibo, Xianyu, Taobao, JD and X — through one uniform command syntax and one JSON output format.
|
||
> Capabilities are ported from cv-cat's open-source Python projects and rewritten in TypeScript. Only Node is required at runtime. Version 0.1.0; web endpoints of all 10 platforms are ported; app / pc endpoints are planned.
|
||
|
||
## What catbus does
|
||
|
||
- One command, `catbus <platform> <resource> <action> [args] [options]`, for every platform.
|
||
- Same meaning, same name: a platform's main content unit (note, video, post, tweet, product) is always `item`; searching is always `search`; liking is always `like`. The same command takes the same options and returns the same normalized shape on every platform.
|
||
- stdout carries only JSON; logs, prompts, progress and QR codes go to stderr. Human-facing text (help, error `message` / `hint`) is in Chinese; command names, options, JSON fields and error codes are English.
|
||
- Sessions are stored locally in `~/.catbus/` per platform × endpoint × account. No telemetry; nothing is uploaded.
|
||
|
||
## Install
|
||
|
||
Requires Node `^22.22.2 || ^24.15.0 || >=26.0.0`. No Python or compiler needed. Supported: win32 / darwin / linux, x64 / arm64 (glibc and musl).
|
||
|
||
From npm:
|
||
|
||
```bash
|
||
npm i -g catbus-cli
|
||
catbus doctor
|
||
```
|
||
|
||
From source:
|
||
|
||
```bash
|
||
git clone https://github.com/cv-cat/catbus.git
|
||
cd catbus
|
||
npm ci
|
||
npm run assets:jd && npm run assets:ocr # captcha models
|
||
npm run build
|
||
npm link
|
||
catbus doctor
|
||
```
|
||
|
||
## Command syntax
|
||
|
||
```
|
||
catbus <platform> <resource> <action> [args...] [options...]
|
||
catbus <global-command>
|
||
```
|
||
|
||
- Global commands: `platforms [platform]`, `doctor`, `auth list`, `config get|set|unset|list`, `version`.
|
||
- Global options: `-a/--account <name>`, `-e/--endpoint web|app|pc` (default web), `-o/--output json|jsonl`, `--raw`, `--proxy <url>`, `-v`, `-q`, `-y/--yes`, `-h/--help`.
|
||
- Paging: one page by default; `--limit N`, `--all`, `--cursor <page.cursor>`.
|
||
- Standard filters: `--sort general|latest|popular|views|comments|collects|sales|price_asc|price_desc`, `--type all|video|image|text|article|goods`, `--time all|day|week|month|half_year|year`, `--kind recommend|hot|following` (feed list). Each platform supports a subset; a standard value the platform lacks returns `UNSUPPORTED`, a non-standard value returns `USAGE`.
|
||
- Arguments accept IDs, URLs (including share short links), natural identifiers (Bilibili BV id, X handle) and `me` for users. Every output object has `id` and `url` that can be passed to the next command. For xhs, pass URLs (they carry `xsec_token`).
|
||
- Resources: `auth user item product comment feed live keyword notice msg media folder series history topic poi`, plus platform extensions (e.g. bilibili `danmaku` `dynamic` `article` `draft`, jd `order` `cart` `coupon`, x `article`).
|
||
- Dangerous operations (every `delete`, `msg revoke`, bilibili `item coin` / `item triple`, `live send --gift`) need `-y` unless both stdin and stderr are TTYs (then catbus asks y/N).
|
||
- Platform-native words are not aliases: `catbus xhs note get` returns `UNSUPPORTED` with a hint pointing to `catbus xhs item get`.
|
||
- Help: `catbus --help`, `catbus <platform> --help`, `catbus <platform> <resource> --help`, `catbus <platform> <resource> <action> --help`.
|
||
|
||
Examples:
|
||
|
||
```bash
|
||
catbus bilibili item get BV1xx411c7mD
|
||
catbus xhs item search 露营 --sort latest --limit 50
|
||
catbus douyin comment list "<video URL>" --limit 100 -o jsonl
|
||
catbus x user get elonmusk
|
||
catbus jd item search 机械键盘 --sort sales
|
||
catbus bilibili live listen <room> --duration 10m
|
||
catbus xhs item download "<note URL>" --dir ./downloads
|
||
catbus xianyu msg send "还在吗" --item "<listing URL>"
|
||
catbus platforms douyin
|
||
```
|
||
|
||
## Platforms
|
||
|
||
| id | Name | Aliases | item = | Login methods (default first) |
|
||
|---|---|---|---|---|
|
||
| xhs | 小红书 Xiaohongshu | xiaohongshu, rednote | note | qrcode, sms, cookie (scope: creator) |
|
||
| douyin | 抖音 Douyin | dy | post (video or images) | qrcode, sms, cookie |
|
||
| tiktok | TikTok | tt | video | cookie |
|
||
| bilibili | B 站 Bilibili | bili, b | video submission | qrcode, sms, password, cookie |
|
||
| kuaishou | 快手 Kuaishou | ks | post (video or images) | qrcode, sms, cookie |
|
||
| weibo | 微博 Weibo | wb | weibo post | cookie |
|
||
| xianyu | 闲鱼 Xianyu | goofish, xy | second-hand listing | qrcode, cookie |
|
||
| taobao | 淘宝 Taobao | tb | product | cookie |
|
||
| jd | 京东 JD | jingdong | product SKU | qrcode, sms, cookie |
|
||
| x | X | twitter | tweet | cookie |
|
||
|
||
Per-platform command support: [docs/capabilities.md](docs/capabilities.md), or `catbus platforms <platform>` (JSON: each command's `status` is `implemented` or `planned`, `auth`, `upstream` = full / partial / none, and `note`).
|
||
|
||
## Login
|
||
|
||
- All web commands except `auth` require login; otherwise `AUTH_REQUIRED` (exit 3) with the login command in `error.hint`.
|
||
- QR code: `catbus <platform> auth login` draws the QR code on stderr and saves a PNG to `~/.catbus/cache/<platform>/`.
|
||
- Cookie: `catbus <platform> auth login --method cookie --cookie "<Cookie>"` (`--method` can be omitted on tiktok, weibo, taobao, x, where cookie is the only method). `--cookie` accepts a string, `@file`, `-` (stdin), or an exported cookie JSON array; douyin / tiktok also accept a JSON object with device data (tickets, certificates, private keys) needed for writes. Copy the full `Cookie` request header from DevTools → Network; `document.cookie` misses HttpOnly session cookies.
|
||
- Accounts: `-a <name>` selects an account; `catbus <platform> auth list|use|status|logout`; `catbus auth list` for all platforms.
|
||
- `CATBUS_HOME` overrides `~/.catbus`. Directories 0700, files 0600.
|
||
- Proxy: `catbus config set proxy <url>`, `catbus config set <platform>.proxy <url>`, or `--proxy`. `HTTP(S)_PROXY` is not read.
|
||
|
||
## Output
|
||
|
||
Envelope (exactly one per call with `-o json`):
|
||
|
||
```json
|
||
{ "ok": true, "platform": "xhs", "endpoint": "web", "resource": "item", "action": "get",
|
||
"account": "default", "data": {}, "page": null, "error": null }
|
||
```
|
||
|
||
- On error: `ok: false`, `data: null`, `error: { code, message, hint, detail }`.
|
||
- List commands set `page: { cursor, has_more }`.
|
||
- `-o jsonl`: one `data` entry per line on stdout; a summary envelope on stderr at the end.
|
||
- `--raw`: platform original objects instead of normalized ones.
|
||
- Normalized types: `User`, `Item`, `Comment`, `Live`, `Event`, `Message`, `Conversation`, `Notice`, `Media`, `Folder`, … — fields always present (`null` / `[]` when missing), IDs are strings, counts are integers, times are ISO 8601 with timezone. Full definitions: [AGENTS.md section 6](AGENTS.md).
|
||
|
||
## Exit codes
|
||
|
||
`0` success · `1` ERROR · `2` USAGE / UNSUPPORTED / CONFIRM_REQUIRED · `3` AUTH_REQUIRED / AUTH_EXPIRED · `4` NOT_IMPLEMENTED (planned endpoint or capability) · `5` RISK_CONTROL (`detail.kind`: captcha / rate_limit / blocked) · `6` NETWORK · `7` UPSTREAM (platform business error, original code in `detail`)
|
||
|
||
## Known limitations
|
||
|
||
- Douyin write operations are limited by device risk control (publish returns RISK_CONTROL); read-only commands work.
|
||
- Xiaohongshu QR login currently fails with a captcha challenge (HTTP 471); use cookie import. Comments occasionally hit HTTP 461 and recover.
|
||
- TikTok write operations need browser session data beyond the Cookie string.
|
||
- Planned (○) commands return NOT_IMPLEMENTED; app / pc endpoints are all planned.
|
||
- Details: the "已知限制" (known limitations) section of each file in [docs/platforms/](docs/platforms/README.md).
|
||
|
||
## Docs
|
||
|
||
- [README.md](README.md): overview (Chinese)
|
||
- [README.en.md](README.en.md): overview (English)
|
||
- [AGENTS.md](AGENTS.md): the specification — commands (section 4), sessions (5), output (6), architecture (7), conventions (8) (Chinese)
|
||
- [docs/capabilities.md](docs/capabilities.md): capability matrix, generated from the registry
|
||
- [docs/upstream-map.md](docs/upstream-map.md): upstream porting map
|
||
- [.claude/skills/catbus/SKILL.md](.claude/skills/catbus/SKILL.md): agent skill (install with `npx skills add cv-cat/catbus`); per-platform notes in `platforms/`, task guides in `workflows/`
|
||
- [.github/CONTRIBUTING.md](.github/CONTRIBUTING.md), [.github/TESTING.md](.github/TESTING.md), [.github/SECURITY.md](.github/SECURITY.md), [CHANGELOG.md](CHANGELOG.md)
|
||
|
||
## Upstream projects
|
||
|
||
All by cv-cat: [Spider_XHS](https://github.com/cv-cat/Spider_XHS), [DouYin_Spider](https://github.com/cv-cat/DouYin_Spider), [TiktokApis](https://github.com/cv-cat/TiktokApis), [BilibiliApis](https://github.com/cv-cat/BilibiliApis), [KuaiShou-Spider](https://github.com/cv-cat/KuaiShou-Spider), [WeiboApis](https://github.com/cv-cat/WeiboApis), [XianYuApis](https://github.com/cv-cat/XianYuApis), [TaoBaoApis](https://github.com/cv-cat/TaoBaoApis), [JdApis](https://github.com/cv-cat/JdApis), [XApis](https://github.com/cv-cat/XApis)
|
||
|
||
## Links
|
||
|
||
- GitHub: https://github.com/cv-cat/catbus (default branch `master`)
|
||
- Author: cv-cat — https://github.com/cv-cat
|
||
- Issues: https://github.com/cv-cat/catbus/issues
|
||
- License: MIT
|