weibo-cli — Weibo CLI Tool

Binary: weibo Credentials: browser cookies (auto-extracted) or QR code login

Setup

# Install (requires Python 3.10+)
git clone git@github.com:jackwener/weibo-cli.git
cd weibo-cli && uv sync

Authentication

IMPORTANT FOR AGENTS: Before executing ANY weibo command, check if credentials exist first. Do NOT assume cookies are configured.

Step 0: Check if already authenticated

weibo status 2>/dev/null && echo "AUTH_OK" || echo "AUTH_NEEDED"

If AUTH_OK, skip to Command Reference. If AUTH_NEEDED, proceed to Step 1.

Step 1: Guide user to authenticate

Method A: Browser cookie extraction (recommended)

Ensure user is logged into weibo.com in any supported browser (Chrome, Arc, Edge, Firefox, Brave, Chromium, Opera, Vivaldi, Safari, LibreWolf). weibo-cli auto-extracts cookies.

weibo login
weibo login --qrcode          # QR code login directly (skip browser cookies)
weibo status

Method B: QR code login

weibo login
# → Renders QR in terminal using Unicode half-blocks
# → Scan with Weibo App (我的 → 扫一扫) → confirm

Step 2: Handle common auth issues

Output Format

Default: Rich table (human-readable)

weibo hot                              # Pretty table output

JSON / YAML: structured output

weibo hot --json                       # JSON to stdout
weibo hot --yaml                       # YAML output
weibo hot --json | jq '.realtime[:3]'  # Filter with jq

Non-TTY stdout defaults to YAML automatically.

Command Reference

Reading

Account

Agent Workflow Examples

Browse hot topics and read details

# Get hot search topics
MBLOG=$(weibo hot --json | jq -r '.realtime[0].mblog_id // empty')
# Read a specific weibo
weibo detail Qw06Kd98p --json | jq '{text: .text_raw, likes: .attitudes_count, comments: .comments_count}'

Analyze user profile

weibo profile 1699432410 --json | jq '.user | {name: .screen_name, followers: .followers_count, posts: .statuses_count}'
weibo weibos 1699432410 --count 3 --json

Read comments on a weibo

weibo comments Qw06Kd98p --json | jq '.data[:5] | .[].text_raw'

Daily monitoring workflow

# Top 10 hot topics
weibo hot --json | jq '.realtime[:10] | .[] | {rank, word, num}'

# Trending sidebar
weibo trending --yaml

# Hot feed
weibo feed --count 5 --json

Error Codes

Structured error codes returned in CLI output:

• not_authenticated — cookies expired or missing
• rate_limited — too many requests
• invalid_params — missing or invalid parameters
• qr_expired — QR code has expired
• api_error — upstream Weibo API error

Limitations

• Read-only — no posting, liking, or retweeting
• No DMs — cannot access private messages
• Single account — one set of credentials at a time
• Rate limited — built-in Gaussian jitter delay (~1s) between requests

Anti-Detection Notes for Agents

• Do NOT parallelize requests — the built-in rate-limit delay exists for account safety
• Batch operations: when doing bulk work (e.g., reading many profiles), add delays between CLI calls
• Session stability: all requests share consistent Chrome 145 headers per session

Safety Notes

• Do not ask users to share raw cookie values in chat logs.
• Prefer local browser cookie extraction over manual secret copy/paste.
• If auth fails, ask the user to re-login via weibo login.
• Agent should treat cookie values as secrets (do not echo to stdout unnecessarily).
• Built-in rate-limit delay protects accounts; do not bypass it.