kabi-weibo-cli 0.2.0

A CLI for Weibo (微博) — search, browse hot topics, read timelines, explore user profiles from the terminal

weibo-cli

A CLI for Weibo (微博) — search, browse hot topics, read timelines, and explore user profiles from the terminal 🐦

English | 中文

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 --yaml for structured output unless strict JSON is required. Non-TTY stdout defaults to YAML automatically. Use --count to 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.json with 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 [e-mail]: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 <keyword>                 # 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 <mblogid>                 # View weibo with full stats
weibo detail Qw06Kd98p --json          # JSON output

# ─── Comments & Reposts ─────────────────────────
weibo comments <mblogid>               # View comments
weibo comments Qw06Kd98p --count 10    # Limit count
weibo comments Qw06Kd98p --json        # JSON output
weibo reposts <mblogid>                # View reposts/forwards
weibo reposts Qw06Kd98p --count 5      # Limit count

# ─── User ───────────────────────────────────────
weibo profile <uid>                    # User profile
weibo profile 1699432410 --json        # JSON output
weibo weibos <uid>                     # User's weibos
weibo weibos 1699432410 --count 5      # Limit count
weibo following <uid>                  # User's following list
weibo followers <uid>                  # User's follower list

Authentication

weibo-cli uses this auth priority:

1. Saved credentials — loads from ~/.config/weibo-cli/credential.json
2. Browser cookies (recommended) — auto-extract from Arc/Chrome/Edge/Firefox/Brave/Chromium/Opera/Vivaldi/Safari/LibreWolf
3. 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

• ⚠️ 未登录 — Run weibo login to authenticate
• 会话已过期 — Cookie expired, run weibo logout && weibo login
• Unable 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
• 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 10 instead 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
• --json for scripts and agent pipelines
• --yaml for 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 [e-mail]: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 [e-mail]: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 [e-mail]:jackwener/weibo-cli.git .agents/skills/weibo-cli

License

Apache-2.0