catbus/README.en.md

One command. Ten platforms.
RedNote (Xiaohongshu) · Douyin · TikTok · Bilibili · Kuaishou · Weibo · Xianyu · Taobao · JD.com · X
_{Coming soon: Instagram · YouTube · Facebook · Zhihu · WeChat Official Accounts · Toutiao · Poizon (Dewu) · Pinduoduo · Meituan · Dianping}

简体中文 · English · 繁體中文 · 日本語 · 한국어

Quick start · Capabilities · Platforms · Examples · For agents

Every platform has its own APIs, its own request signing, its own login flow and its own data format. catbus puts them all on one bus: one set of commands, one JSON shape, one home for your logins. To switch platforms, you change a single word.

✨ What is catbus

catbus (猫巴士) is a command-line tool that drives the web endpoints of 10 major Chinese and global platforms through one unified syntax: search, details, comments, users, feeds, downloads, publishing, direct messages, live-stream chat and more.

catbus xhs      item search 露营 --sort latest
catbus douyin   item search 露营 --sort latest
catbus bilibili item search 露营 --sort latest
catbus x        item search camping --sort latest

Four platforms, four nearly identical commands, and JSON output with the same structure. Notes, posts, videos and tweets are all just item; searching is always search; liking is always like. Learn it once, and you can use all ten platforms.

🚀 Why catbus

🧭 Same meaning, same name A capability that means the same thing uses the same command, the same options and the same output on every platform. Reach for a platform's native term (note, aweme, tweet…) and catbus will tell you which word to use instead.	📦 Node is all you need No Python, no compiler, no system dependencies. Every native dependency ships prebuilt binaries covering x64 / arm64 on Windows, macOS and Linux (musl included), and all 8 target systems are smoke-tested one by one in CI.
🤖 Built for AI agents stdout carries nothing but JSON, exit codes are stable, and errors come with the next command to run. catbus platforms prints the complete list of capabilities. Ships with an agent skill and llms.txt.	🔐 Your logins never leave your machine QR code, SMS and cookie import are all supported. Credentials are isolated per platform × endpoint × account under ~/.catbus/ (0700 / 0600), and you can switch between accounts at any time. No data is collected or uploaded, and there is no telemetry.
🧪 Byte-for-byte faithful to upstream The URL, header order, cookies, body and signature of every request are compared byte for byte against the upstream implementation, with randomness and the clock pinned. 560+ golden files and 940+ offline tests guard every change.	🛡️ A browser-grade network stack TLS / HTTP2 fingerprints that match real Chrome, upstream signing JS running unmodified in a sandbox, and slider and click-to-select CAPTCHAs solved automatically with local ONNX and OpenCV.

📊 By the numbers

🚌 Platforms	⌨️ Implemented commands	🧪 Golden files	✅ Offline tests	💻 Target systems
10	300+	560+	940+	8

🏗️ Architecture

• One registry drives everything: command parsing, the four levels of --help, catbus platforms and the capability matrix are all generated from the same registry, so they can never contradict each other.
• One platform, one set of files: client handles sessions and signing, api maps one-to-one onto upstream methods, normalize turns raw data into the unified types, and resolve lets IDs, links, share short links and me all work as arguments.
• Extensible: the spec reserves room for app / pc endpoints; non-JS upstreams will plug in through the provider protocol.

🤖 Built for AI agents

catbus was designed from day one to be called by programs:

catbus platforms douyin | jq '.data.commands[] | select(.status=="implemented") | .resource + " " + .action'

• Self-describing: the login requirements, implementation status and upstream support of every platform and every command are one command away.
• Predictable: success and failure share the same envelope, { ok, data, page, error }; error.hint spells out the next command to run.
• Chainable: every output object carries an id and a url, so one command's result can be fed straight into the next.
• Well-behaved: dangerous operations require an explicit -y, posts can be published as visible only to you, and risk control is reported plainly as RISK_CONTROL — never silently retried.

Install the catbus skill into Claude Code, Cursor, Codex and other agents with one command:

npx skills add cv-cat/catbus

The skill loads on demand: a one-page overview, plus sub-files that are read only when a task touches a given platform or kind of work (collecting, publishing, live & DMs, troubleshooting). Safety rules are built in — logins stay with you, writes need confirmation, posts default to private, and it stops on risk control.

⚡ On board in 30 seconds

npm i -g catbus-cli

catbus doctor                 # check your environment
catbus bilibili auth login    # log in by scanning a QR code
catbus bilibili item search 猫 --limit 20

You can also use Docker or install from source; see Quick start for the full steps.

📚 Documentation

The guides below are in Chinese.

🚀 Quick start	From installation to your first data export
🔑 Login · ⚙️ Configuration · 🐳 Docker	QR code / cookies, multiple accounts, proxies, containers
📤 Output and errors	Envelope, normalized types, pagination, exit codes
🧭 Platform guides · 🗂️ Capability matrix	What each platform supports and how to pass arguments
🧪 Example scripts	Cross-platform search, exporting comments, backing up posts, recording live chat
📐 AGENTS.md	The catbus spec itself
❓ FAQ	Why log in? What to do about risk control…

🤝 Contributing

Issues and PRs are welcome — new platforms, new commands, fixes for platform API changes, documentation improvements, all of it. Before you start, please read CONTRIBUTING.md and AGENTS.md (spec first; every request needs a golden test). Please report security issues privately as described in SECURITY.md.

📈 Star history

🍔 Community groups

If you're into scraping and AI agents, come join the group chats (in Chinese).

If a group is full or a QR code has expired, open an issue or let the author know on WeChat / QQ.

group-1	group-2	group-3	group-4 (2,000-member QQ group)

⚠️ Disclaimer

• This project is intended solely for learning and research. Do not use it for commercial purposes or for any unlawful purpose.
• When using it, comply with each platform's user agreement and terms of service, as well as the laws and regulations of your jurisdiction. Do not collect or disseminate other people's private data, and do not place excessive request load on the platforms.
• Automated operations may trigger the platforms' risk controls, resulting in CAPTCHAs, rate limiting or even account bans. Users bear sole responsibility for any and all consequences arising from their use of this project.
• This project is not affiliated with any of the platforms mentioned above, nor has it been authorized or endorsed by them. All platform names and trademarks are the property of their respective owners.

📄 License

MIT © 2026 cv-cat

_{All aboard, every platform. · 上车，开往任何平台}