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

Symptom	Agent action
⚠️ 未登录	Guide user to login to weibo.com in browser, then run weibo login
会话已过期	Run weibo logout && weibo login
Cookie extraction hangs	Browser may be running; close browser and retry

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

Command	Description	Example
weibo hot	Hot search list (50+ topics)	weibo hot --count 10 --json
weibo trending	Real-time search trends	weibo trending --count 10 --yaml
weibo search <keyword>	Search weibos by keyword	weibo search "科技" --count 5 --json
weibo feed	Hot timeline	weibo feed --count 5 --json
weibo home	Following timeline	weibo home --count 10 --json
weibo detail <mblogid>	View weibo with stats	weibo detail Qw06Kd98p --json
weibo comments <mblogid>	View comments	weibo comments Qw06Kd98p --count 10
weibo reposts <mblogid>	View reposts/forwards	weibo reposts Qw06Kd98p --count 5
weibo profile <uid>	User profile	weibo profile 1699432410 --json
weibo weibos <uid>	User's published weibos	weibo weibos 1699432410 --count 5
weibo following <uid>	User's following list	weibo following 1699432410
weibo followers <uid>	User's follower list	weibo followers 1699432410

Account

Command	Description
weibo login	Extract cookies from browser / QR login
weibo login --qrcode	QR code login directly (skip browser)
weibo login --cookie-source <browser>	Extract from specific browser
weibo logout	Clear saved credentials
weibo status	Check authentication status
weibo me	Show current user profile

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.