A CLI for Weibo (微博) — search, browse hot topics, read timelines, and explore user profiles from the terminal 🐦
Overview
A CLI for Weibo (微博) — search, browse hot topics, read timelines, and explore user profiles from the terminal 🐦
README
weibo-cli
A CLI for Weibo (微博) — search, browse hot topics, read timelines, and explore user profiles from the terminal 🐦
More Tools
- twitter-cli — Twitter/X CLI for timelines, bookmarks, and posting
- xiaohongshu-cli — Xiaohongshu (小红书) CLI for notes and account workflows
- bilibili-cli — Bilibili CLI for videos, users, search, and feeds
- discord-cli — Discord CLI for local-first sync, search, and export
- tg-cli — Telegram CLI for local-first sync, search, and export
English
Features
Read:
- Hot search: browse real-time trending topics and hashtags
- Hot timeline: browse the trending feed
- Home feed: browse your following timeline
- Search: find weibos by keyword
- Search trends: real-time trending sidebar data
- Weibo detail: view a weibo with full text, media, and stats
- Comments: read comments on any weibo
- Reposts: view forwards/reposts of any weibo
- User profiles: view user info, stats, and bio
- User weibos: browse a user’s published weibos
- Following: view a user’s following list
- Followers: view a user’s follower list
- Structured output: export any data as JSON or YAML for scripting and AI agent integration
AI Agent Tip: Prefer
--yamlfor structured output unless strict JSON is required. Non-TTY stdout defaults to YAML automatically. Use--countto limit results.
Auth & Anti-Detection:
- Cookie auth: auto-extract from Arc/Chrome/Edge/Firefox/Brave/Chromium/Opera/Vivaldi
- QR code login: terminal-rendered QR code for Weibo App scan
- Credential persistence: auto-save to
~/.config/weibo-cli/credential.jsonwith 7-day TTL - Anti-detection: Chrome 145 User-Agent, Gaussian jitter, exponential backoff
- Session auto-refresh: stale credentials trigger browser cookie re-extraction
Installation
# Recommended: uv tool (fast, isolated)
uv tool install kabi-weibo-cli
# Alternative: pipx
pipx install kabi-weibo-cli
Upgrade to the latest version:
uv tool upgrade kabi-weibo-cli
Install from source:
git clone [email protected]:jackwener/weibo-cli.git
cd weibo-cli
uv sync
Quick Start
# Login (auto-extract browser cookies or QR scan)
weibo login
# Browse hot search
weibo hot
# Search weibos by keyword
weibo search "科技"
# View hot timeline
weibo feed
# Check a weibo
weibo detail Qw06Kd98p
Usage
# ─── Auth ─────────────────────────────────────────
weibo login # Extract cookies from browser / QR login
weibo login --qrcode # QR code login directly (skip browser)
weibo login --cookie-source chrome # Extract from specific browser
weibo logout # Clear saved credentials
weibo status # Check login status
weibo me # Show current user profile
# ─── Hot & Trending ────────────────────────────
weibo hot # Hot search list (50+ topics)
weibo hot --count 10 # Limit results
weibo hot --json # JSON output
weibo trending # Real-time search trends
weibo trending --count 10 # Limit results
weibo trending --yaml # YAML output
# ─── Search ─────────────────────────────────────
weibo search # Search weibos by keyword
weibo search "科技" --count 5 # Limit results
weibo search "科技" --page 2 --json # Paginate + JSON output
# ─── Feed ───────────────────────────────────────
weibo feed # Hot timeline
weibo feed --count 5 # Limit results
weibo feed --json # JSON output
weibo home # Following timeline
weibo home --count 10 # Limit count
# ─── Weibo Detail ───────────────────────────────
weibo detail # View weibo with full stats
weibo detail Qw06Kd98p --json # JSON output
# ─── Comments & Reposts ─────────────────────────
weibo comments # View comments
weibo comments Qw06Kd98p --count 10 # Limit count
weibo comments Qw06Kd98p --json # JSON output
weibo reposts # View reposts/forwards
weibo reposts Qw06Kd98p --count 5 # Limit count
# ─── User ───────────────────────────────────────
weibo profile # User profile
weibo profile 1699432410 --json # JSON output
weibo weibos # User's weibos
weibo weibos 1699432410 --count 5 # Limit count
weibo following # User's following list
weibo followers # User's follower list
Authentication
weibo-cli uses this auth priority:
- Saved credentials — loads from
~/.config/weibo-cli/credential.json - Browser cookies (recommended) — auto-extract from Arc/Chrome/Edge/Firefox/Brave/Chromium/Opera/Vivaldi/Safari/LibreWolf
- QR code login — terminal QR code, scan with Weibo App
Browser extraction is recommended — it forwards ALL Weibo cookies and is closest to normal browser traffic.
Cookie TTL is 7 days by default. After expiry, the client automatically attempts browser re-extraction.
Troubleshooting
⚠️ 未登录— Runweibo loginto authenticate会话已过期— Cookie expired, runweibo logout && weibo loginUnable to get key for cookie decryption(macOS Keychain):- SSH sessions:
security unlock-keychain ~/Library/Keychains/login.keychain-db - Local terminal: Open Keychain Access → search “Chrome Safe Storage” → Access Control → add Terminal → Save
- SSH sessions:
- Requests are slow — intentional Gaussian jitter delay (~1s) to avoid triggering Weibo’s risk control
Best Practices (Avoiding Bans)
- Keep request volumes low — use
--count 10instead of--count 100 - Don’t run too frequently — the built-in rate limiter adds randomized delays
- Use browser cookie extraction — provides full cookie fingerprint
- Cookie values are stored locally and never uploaded
Output Modes
- Default Rich table for interactive terminal reading
--jsonfor scripts and agent pipelines--yamlfor structured output (auto-detected when stdout is not a TTY)
Development
# Install dev dependencies
uv sync --extra dev --extra yaml
# Lint + tests
uv run ruff check .
uv run pytest tests/ -v
# Smoke tests (require browser cookies)
uv run pytest tests/ -v -m smoke
Project Structure
weibo_cli/
├── __init__.py
├── cli.py # Click entry point (16 commands)
├── client.py # WeiboClient (17 API methods, rate-limit, retry)
├── auth.py # QR login + browser-cookie3 + credential persistence
├── constants.py # API endpoints, headers, Chrome 145 UA
├── exceptions.py # WeiboApiError hierarchy (6 error types)
└── commands/
├── _common.py # structured_output_options, handle_command, strip_html, format_count
├── auth.py # login/logout/status/me
├── search.py # hot/feed/detail/comments/trending/search
└── personal.py # profile/weibos/following/followers/reposts/home
Use as AI Agent Skill
weibo-cli ships with a SKILL.md so AI agents can execute common Weibo workflows.
Skills CLI (Recommended)
npx skills add jackwener/weibo-cli
| Flag | Description |
|---|---|
-g |
Install globally (user-level, shared across projects) |
-a claude-code |
Target a specific agent |
-y |
Non-interactive mode |
Manual Install
mkdir -p .agents/skills
git clone [email protected]:jackwener/weibo-cli.git .agents/skills/weibo-cli
OpenClaw / ClawHub (Deprecated)
⚠️ ClawHub install method is deprecated and no longer supported. Use Skills CLI or Manual Install above.
中文
功能特性
阅读:
- 🔥 热搜：实时热门话题和标签
- 📰 热门 Feed：热门时间线
- 🏠 关注者 Feed：关注用户的时间线
- 🔍 搜索：按关键词搜索微博
- 📈 搜索趋势：实时搜索趋势侧边栏
- 📝 微博详情：查看完整正文、媒体和统计数据
- 💬 评论：查看微博评论
- 🔁 转发：查看微博转发
- 👤 用户资料：用户信息和统计
- 📋 用户微博：浏览用户已发布的微博列表
- 👥 关注列表：查看用户的关注列表
- 👥 粉丝列表：查看用户的粉丝列表
- 📊 结构化输出：支持 JSON 和 YAML，便于脚本和 AI Agent 集成
AI Agent 提示： 需要结构化输出时优先使用
--yaml，除非下游必须是 JSON。stdout 不是 TTY 时默认输出 YAML。
认证与反风控:
- Cookie 认证：支持 Arc/Chrome/Edge/Firefox/Brave 等 10+ 浏览器自动提取
- 二维码登录：终端渲染二维码，用微博 APP 扫码
- 凭证持久化：自动保存到
~/.config/weibo-cli/credential.json，7 天 TTL - 反检测：Chrome 145 User-Agent、高斯抖动延迟、指数退避重试
- 会话自动刷新：过期凭证自动触发浏览器 Cookie 重提取
安装
# 推荐：uv tool（快速、隔离环境）
uv tool install kabi-weibo-cli
# 或者：pipx
pipx install kabi-weibo-cli
升级到最新版本：
uv tool upgrade kabi-weibo-cli
从源码安装：
git clone [email protected]:jackwener/weibo-cli.git
cd weibo-cli
uv sync
使用示例
# 认证
weibo login # 从浏览器提取 Cookie / 二维码扫码
weibo login --qrcode # 直接二维码扫码登录
weibo login --cookie-source chrome # 指定浏览器提取
weibo logout # 清除已保存凭证
weibo status # 检查登录状态
weibo me # 查看当前用户信息
# 热搜
weibo hot # 热搜列表（50+ 条）
weibo hot --count 10 # 限制数量
weibo hot --json # JSON 输出
weibo trending # 搜索趋势
# 搜索
weibo search "科技" # 按关键词搜索微博
weibo search "科技" --count 5 # 限制数量
weibo search "科技" --page 2 # 翻页
# Feed
weibo feed # 热门时间线
weibo feed --count 5 # 限制数量
weibo home # 关注者时间线
# 微博详情与评论
weibo detail Qw06Kd98p # 查看微博
weibo comments Qw06Kd98p # 查看评论
weibo reposts Qw06Kd98p # 查看转发
# 用户
weibo profile 1699432410 # 用户资料
weibo weibos 1699432410 # 用户微博列表
weibo following 1699432410 # 用户关注列表
weibo followers 1699432410 # 用户粉丝列表
常见问题
⚠️ 未登录— 执行weibo login认证会话已过期— Cookie 过期，执行weibo logout && weibo login- 请求较慢是正常的 — 内置高斯随机延迟（~1s）是为了模拟人类浏览行为，避免触发风控
作为 AI Agent Skill 使用
Skills CLI（推荐）
npx skills add jackwener/weibo-cli
| 参数 | 说明 |
|---|---|
-g |
全局安装（用户级别，跨项目共享） |
-a claude-code |
指定目标 Agent |
-y |
非交互模式 |
手动安装
mkdir -p .agents/skills
git clone [email protected]:jackwener/weibo-cli.git .agents/skills/weibo-cli
License
Apache-2.0
Recommended Tools
Try a different keyword or remove a filter.
Install
npx skillfish add jackwener/weibo-cli