catbus

catbus (Cat Bus) is a command-line tool that uses the same set of commands and the same JSON format to call the web interfaces of 10 platforms. stdout contains only JSON, while logs, prompts, and QR codes go to stderr.

First verify that it works:

catbus version

catbus doctor

. If the

catbus

command cannot be found, tell the user how to install it (the npm package

catbus-cli

, or

npm link

from the source); do not install it yourself.

Read the relevant files for the task

This file contains only the overview. Before acting, read one or two additional files based on the task; there is no need to read all of them.

Task	Read
Involving a specific platform	`platforms/<id>.md` : what it can and cannot do, how to pass parameters, and common pitfalls
Searching, collecting, exporting, pagination, downloading, and cross-platform comparison	workflows/collect.md
Write operations such as publishing, commenting, liking, favoriting, following, and deleting	workflows/write.md
Live-stream chat monitoring and direct messages	workflows/live-msg.md
Command errors: not logged in, risk control, unsupported, or network issues	workflows/errors.md
Checking a command's parameters, options, and output fields	reference/commands.md

Platforms

Platform	id	Aliases	What `item` represents	Login	File
RedNote	`xhs`	`xiaohongshu` `rednote`	Note	cookie (QR-code sign-in is often blocked)	platforms/xhs.md
Douyin	`douyin`	`dy`	Work	QR-code sign-in	platforms/douyin.md
TikTok	`tiktok`	`tt`	Video	cookie / session JSON	platforms/tiktok.md
Bilibili	`bilibili`	`bili` `b`	Submission	QR-code sign-in	platforms/bilibili.md
Kuaishou	`kuaishou`	`ks`	Work	QR-code sign-in	platforms/kuaishou.md
Weibo	`weibo`	`wb`	Post	cookie	platforms/weibo.md
Xianyu	`xianyu`	`goofish` `xy`	Listing	QR-code sign-in	platforms/xianyu.md
Taobao	`taobao`	`tb`	Product	cookie	platforms/taobao.md
JD	`jd`	`jingdong`	Product SKU	QR-code sign-in	platforms/jd.md
X	`x`	`twitter`	Post	cookie	platforms/x.md

Not yet supported: Instagram, YouTube, Facebook, Zhihu, WeChat Official Accounts, Toutiao, Dewu, Pinduoduo, Meituan, and Dianping are under development. Attempting to execute them now will result in an “Unknown platform” error (

USAGE

). When users ask about them, say directly that they are not supported; do not attempt to invoke them, and do not substitute another platform.

Command syntax

catbus <platform> <resource> <action> [参数...] [选项...]

Resource and action must use canonical terms, and they are identical across all platforms: notes, videos, posts, and products are all called
```
item
```
; search is called
```
search
```
; favorites folders are called
```
folder
```
; and direct messages are called
```
msg
```
. Native terms such as
```
note
```
,
```
video
```
, or
```
tweet
```
will cause an
```
UNSUPPORTED
```
error, and the
```
hint
```
will provide the canonical term.
Parameters accept IDs, URLs (including shared short links), and native platform identifiers (Bilibili BV IDs and X usernames). The user parameter can also be
```
me
```
. Every output object includes
id
and
url
, which can be passed directly to the next command; RedNote always requires
```
url
```
.
Positional arguments beginning with
```
-
```
go after
```
--
```
. Options can appear anywhere.
```
-e app|pc
```
has not been implemented (
```
NOT_IMPLEMENTED
```
); use only the default web interface.

Check capabilities before making a call

Capabilities vary significantly between platforms, so check before calling rather than guessing:

bash

catbus platforms xhs              # JSON: each command's status (implemented / planned), auth, and note
catbus xhs item search --help     # Parameters, options, filter values, login requirements, and output types

A command with a
```
planned
```
status will cause a
```
NOT_IMPLEMENTED
```
error; do not call it. The
```
note
```
field lists limitations, such as “only supports me,” so check it before invoking the command.
Filter values for
```
--sort
```
,
```
--type
```
, and
```
--time
```
differ between platforms; use
```
--help
```
as the source of truth.
The “Can do / Cannot do” section in a platform file is only a summary. If it conflicts with
```
catbus platforms
```
, the latter takes precedence.

Envelope and exit codes

stdout contains exactly one envelope. When using

-o jsonl

, each line contains one

data

object, and the summary envelope is on the final line of stderr:

json

{ "ok": true, "platform": "bilibili", "resource": "item", "action": "get", "account": "default",
  "data": {}, "page": null, "error": null }

On failure,

ok

is false and

error

{code, message, hint, detail}

. Read
error.hint
first; it indicates the next command or action to take.

Exit code	code	One-line meaning
0	—	Success
2	`USAGE` / `UNSUPPORTED` / `CONFIRM_REQUIRED`	Invalid arguments / platform unavailable / dangerous operation not confirmed
3	`AUTH_REQUIRED` / `AUTH_EXPIRED`	Ask the user to log in
4	`NOT_IMPLEMENTED`	Planned; do not retry
5	`RISK_CONTROL`	Risk control triggered; stop and do not retry
6	`NETWORK`	Network / proxy issue
7	`UPSTREAM`	Platform business error; the original code is in `detail`
1	`ERROR`	Other error

See workflows/errors.md for how to handle each error.

Hard rules

These rules apply to every task:

Delegate login to the user. QR-code sign-in requires the user's phone, while SMS codes, passwords, and cookies must be provided by the user. Give the user the login command from the
```
hint
```
and have them run it in their own terminal. Do not request or store passwords, verification codes, or cookies, and do not read, print, or modify credential files under
```
~/.catbus/
```
.
Confirm write operations first. Publishing, commenting, liking, following, sending direct messages, and deleting will genuinely change the user's account. Do not perform them unless the user explicitly requests it; add
```
-y
```
to a dangerous operation only after the user approves that specific action.
Published content is private by default (
```
--visibility private
```
) unless the user explicitly wants it to be public. For platforms that only support public visibility, such as Xianyu, X, and Bilibili posts, first tell the user that the content will be published publicly.
Do not proactively contact people: Do not send direct messages, comments, @ mentions, or follow requests to others unless the user has provided both the target and the content. Do not send messages in bulk.
Stop when risk control is triggered: Do not retry in a loop after
```
RISK_CONTROL
```
. Leave an interval between consecutive requests to the same platform, and do not run them concurrently.
Report accurately: If the results are empty, fields are null, or a command is unsupported, report the situation honestly and do not fabricate data.

catbus

NPX Install

Tags

SKILL.md Content (Chinese)

catbus

Read the relevant files for the task

Platforms

Command syntax

Check capabilities before making a call

Envelope and exit codes

Hard rules