Skip to content
Back to search

weibo-cli

SkillWorks with Claude CodeGitHub

Use weibo-cli for ALL Weibo (微博) operations — keyword search, hot search, trending topics, timelines, weibo details, comments, reposts, user profiles, and follower/following lists. Invoke whenever user requests any Weibo interaction.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/jackwener--weibo-cli/badge.svg)](/listings/jackwener--weibo-cli)

HTML

<a href="/listings/jackwener--weibo-cli"><img src="/api/listings/jackwener--weibo-cli/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

# 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 git@github.com:jackwener/weibo-cli.git
cd weibo-cli
uv sync

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 181 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: weibo-cli
  3. description: Use weibo-cli for ALL Weibo (微博) operations — keyword search, hot search, trending topics, timelines, weibo details, comments, reposts, user profiles, and follower/following lists. Invoke whenever user requests any Weibo interaction.
  4. author: jackwener
  5. version: "0.2.1"
  6. tags:
  7. - weibo
  8. - sina
  9. - 微博
  10. - social-media
  11. - cli
  12. ---
  13. # weibo-cli — Weibo CLI Tool
  14. **Binary:** `weibo`
  15. **Credentials:** browser cookies (auto-extracted) or QR code login
  16. ## Setup
  17. ```bash
  18. # Install (requires Python 3.10+)
  19. git clone git@github.com:jackwener/weibo-cli.git
  20. cd weibo-cli && uv sync
  21. ```
  22. ## Authentication
  23. **IMPORTANT FOR AGENTS**: Before executing ANY weibo command, check if credentials exist first. Do NOT assume cookies are configured.
  24. ### Step 0: Check if already authenticated
  25. ```bash
  26. weibo status 2>/dev/null && echo "AUTH_OK" || echo "AUTH_NEEDED"
  27. ```
  28. If `AUTH_OK`, skip to [Command Reference](#command-reference).
  29. If `AUTH_NEEDED`, proceed to Step 1.
  30. ### Step 1: Guide user to authenticate
  31. **Method A: Browser cookie extraction (recommended)**
  32. 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.
  33. ```bash
  34. weibo login
  35. weibo login --qrcode # QR code login directly (skip browser cookies)
  36. weibo status
  37. ```
  38. **Method B: QR code login**
  39. ```bash
  40. weibo login
  41. # → Renders QR in terminal using Unicode half-blocks
  42. # → Scan with Weibo App (我的 → 扫一扫) → confirm
  43. ```
  44. ### Step 2: Handle common auth issues
  45. | Symptom | Agent action |
  46. |---------|-------------|
  47. | `⚠️ 未登录` | Guide user to login to weibo.com in browser, then run `weibo login` |
  48. | `会话已过期` | Run `weibo logout && weibo login` |
  49. | Cookie extraction hangs | Browser may be running; close browser and retry |
  50. ## Output Format
  51. ### Default: Rich table (human-readable)
  52. ```bash
  53. weibo hot # Pretty table output
  54. ```
  55. ### JSON / YAML: structured output
  56. ```bash
  57. weibo hot --json # JSON to stdout
  58. weibo hot --yaml # YAML output
  59. weibo hot --json | jq '.realtime[:3]' # Filter with jq
  60. ```
  61. Non-TTY stdout defaults to YAML automatically.
  62. ## Command Reference
  63. ### Reading
  64. | Command | Description | Example |
  65. |---------|-------------|---------|
  66. | `weibo hot` | Hot search list (50+ topics) | `weibo hot --count 10 --json` |
  67. | `weibo trending` | Real-time search trends | `weibo trending --count 10 --yaml` |
  68. | `weibo search <keyword>` | Search weibos by keyword | `weibo search "科技" --count 5 --json` |
  69. | `weibo feed` | Hot timeline | `weibo feed --count 5 --json` |
  70. | `weibo home` | Following timeline | `weibo home --count 10 --json` |
  71. | `weibo detail <mblogid>` | View weibo with stats | `weibo detail Qw06Kd98p --json` |
  72. | `weibo comments <mblogid>` | View comments | `weibo comments Qw06Kd98p --count 10` |
  73. | `weibo reposts <mblogid>` | View reposts/forwards | `weibo reposts Qw06Kd98p --count 5` |
  74. | `weibo profile <uid>` | User profile | `weibo profile 1699432410 --json` |
  75. | `weibo weibos <uid>` | User's published weibos | `weibo weibos 1699432410 --count 5` |
  76. | `weibo following <uid>` | User's following list | `weibo following 1699432410` |
  77. | `weibo followers <uid>` | User's follower list | `weibo followers 1699432410` |
  78. ### Account
  79. | Command | Description |
  80. |---------|-------------|
  81. | `weibo login` | Extract cookies from browser / QR login |
  82. | `weibo login --qrcode` | QR code login directly (skip browser) |
  83. | `weibo login --cookie-source <browser>` | Extract from specific browser |
  84. | `weibo logout` | Clear saved credentials |
  85. | `weibo status` | Check authentication status |
  86. | `weibo me` | Show current user profile |
  87. ## Agent Workflow Examples
  88. ### Browse hot topics and read details
  89. ```bash
  90. # Get hot search topics
  91. MBLOG=$(weibo hot --json | jq -r '.realtime[0].mblog_id // empty')
  92. # Read a specific weibo
  93. weibo detail Qw06Kd98p --json | jq '{text: .text_raw, likes: .attitudes_count, comments: .comments_count}'
  94. ```
  95. ### Analyze user profile
  96. ```bash
  97. weibo profile 1699432410 --json | jq '.user | {name: .screen_name, followers: .followers_count, posts: .statuses_count}'
  98. weibo weibos 1699432410 --count 3 --json
  99. ```
  100. ### Read comments on a weibo
  101. ```bash
  102. weibo comments Qw06Kd98p --json | jq '.data[:5] | .[].text_raw'
  103. ```
  104. ### Daily monitoring workflow
  105. ```bash
  106. # Top 10 hot topics
  107. weibo hot --json | jq '.realtime[:10] | .[] | {rank, word, num}'
  108. # Trending sidebar
  109. weibo trending --yaml
  110. # Hot feed
  111. weibo feed --count 5 --json
  112. ```
  113. ## Error Codes
  114. Structured error codes returned in CLI output:
  115. - `not_authenticated` — cookies expired or missing
  116. - `rate_limited` — too many requests
  117. - `invalid_params` — missing or invalid parameters
  118. - `qr_expired` — QR code has expired
  119. - `api_error` — upstream Weibo API error
  120. ## Limitations
  121. - **Read-only** — no posting, liking, or retweeting
  122. - **No DMs** — cannot access private messages
  123. - **Single account** — one set of credentials at a time
  124. - **Rate limited** — built-in Gaussian jitter delay (~1s) between requests
  125. ## Anti-Detection Notes for Agents
  126. - **Do NOT parallelize requests** — the built-in rate-limit delay exists for account safety
  127. - **Batch operations**: when doing bulk work (e.g., reading many profiles), add delays between CLI calls
  128. - **Session stability**: all requests share consistent Chrome 145 headers per session
  129. ## Safety Notes
  130. - Do not ask users to share raw cookie values in chat logs.
  131. - Prefer local browser cookie extraction over manual secret copy/paste.
  132. - If auth fails, ask the user to re-login via `weibo login`.
  133. - Agent should treat cookie values as secrets (do not echo to stdout unnecessarily).
  134. - Built-in rate-limit delay protects accounts; do not bypass it.
README.md · README · 355 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # weibo-cli
  2. [![CI](https://github.com/jackwener/weibo-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/jackwener/weibo-cli/actions/workflows/ci.yml)
  3. [![PyPI version](https://badge.fury.io/py/kabi-weibo-cli.svg)](https://pypi.org/project/kabi-weibo-cli/)
  4. [![Python](https://img.shields.io/badge/python-%3E%3D3.10-blue.svg)](https://pypi.org/project/kabi-weibo-cli/)
  5. A CLI for Weibo (微博) — search, browse hot topics, read timelines, and explore user profiles from the terminal 🐦
  6. [English](#english) | [中文](#中文)
  7. ## More Tools
  8. - [twitter-cli](https://github.com/jackwener/twitter-cli) — Twitter/X CLI for timelines, bookmarks, and posting
  9. - [xiaohongshu-cli](https://github.com/jackwener/xiaohongshu-cli) — Xiaohongshu (小红书) CLI for notes and account workflows
  10. - [bilibili-cli](https://github.com/jackwener/bilibili-cli) — Bilibili CLI for videos, users, search, and feeds
  11. - [discord-cli](https://github.com/jackwener/discord-cli) — Discord CLI for local-first sync, search, and export
  12. - [tg-cli](https://github.com/jackwener/tg-cli) — Telegram CLI for local-first sync, search, and export
  13. ## English
  14. ### Features
  15. **Read:**
  16. - Hot search: browse real-time trending topics and hashtags
  17. - Hot timeline: browse the trending feed
  18. - Home feed: browse your following timeline
  19. - Search: find weibos by keyword
  20. - Search trends: real-time trending sidebar data
  21. - Weibo detail: view a weibo with full text, media, and stats
  22. - Comments: read comments on any weibo
  23. - Reposts: view forwards/reposts of any weibo
  24. - User profiles: view user info, stats, and bio
  25. - User weibos: browse a user's published weibos
  26. - Following: view a user's following list
  27. - Followers: view a user's follower list
  28. - Structured output: export any data as JSON or YAML for scripting and AI agent integration
  29. > **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.
  30. **Auth & Anti-Detection:**
  31. - Cookie auth: auto-extract from Arc/Chrome/Edge/Firefox/Brave/Chromium/Opera/Vivaldi
  32. - QR code login: terminal-rendered QR code for Weibo App scan
  33. - Credential persistence: auto-save to `~/.config/weibo-cli/credential.json` with 7-day TTL
  34. - Anti-detection: Chrome 145 User-Agent, Gaussian jitter, exponential backoff
  35. - Session auto-refresh: stale credentials trigger browser cookie re-extraction
  36. ### Installation
  37. ```bash
  38. # Recommended: uv tool (fast, isolated)
  39. uv tool install kabi-weibo-cli
  40. # Alternative: pipx
  41. pipx install kabi-weibo-cli
  42. ```
  43. Upgrade to the latest version:
  44. ```bash
  45. uv tool upgrade kabi-weibo-cli
  46. ```
  47. Install from source:
  48. ```bash
  49. git clone git@github.com:jackwener/weibo-cli.git
  50. cd weibo-cli
  51. uv sync
  52. ```
  53. ### Quick Start
  54. ```bash
  55. # Login (auto-extract browser cookies or QR scan)
  56. weibo login
  57. # Browse hot search
  58. weibo hot
  59. # Search weibos by keyword
  60. weibo search "科技"
  61. # View hot timeline
  62. weibo feed
  63. # Check a weibo
  64. weibo detail Qw06Kd98p
  65. ```
  66. ### Usage
  67. ```bash
  68. # ─── Auth ─────────────────────────────────────────
  69. weibo login # Extract cookies from browser / QR login
  70. weibo login --qrcode # QR code login directly (skip browser)
  71. weibo login --cookie-source chrome # Extract from specific browser
  72. weibo logout # Clear saved credentials
  73. weibo status # Check login status
  74. weibo me # Show current user profile
  75. # ─── Hot & Trending ────────────────────────────
  76. weibo hot # Hot search list (50+ topics)
  77. weibo hot --count 10 # Limit results
  78. weibo hot --json # JSON output
  79. weibo trending # Real-time search trends
  80. weibo trending --count 10 # Limit results
  81. weibo trending --yaml # YAML output
  82. # ─── Search ─────────────────────────────────────
  83. weibo search <keyword> # Search weibos by keyword
  84. weibo search "科技" --count 5 # Limit results
  85. weibo search "科技" --page 2 --json # Paginate + JSON output
  86. # ─── Feed ───────────────────────────────────────
  87. weibo feed # Hot timeline
  88. weibo feed --count 5 # Limit results
  89. weibo feed --json # JSON output
  90. weibo home # Following timeline
  91. weibo home --count 10 # Limit count
  92. # ─── Weibo Detail ───────────────────────────────
  93. weibo detail <mblogid> # View weibo with full stats
  94. weibo detail Qw06Kd98p --json # JSON output
  95. # ─── Comments & Reposts ─────────────────────────
  96. weibo comments <mblogid> # View comments
  97. weibo comments Qw06Kd98p --count 10 # Limit count
  98. weibo comments Qw06Kd98p --json # JSON output
  99. weibo reposts <mblogid> # View reposts/forwards
  100. weibo reposts Qw06Kd98p --count 5 # Limit count
  101. # ─── User ───────────────────────────────────────
  102. weibo profile <uid> # User profile
  103. weibo profile 1699432410 --json # JSON output
  104. weibo weibos <uid> # User's weibos
  105. weibo weibos 1699432410 --count 5 # Limit count
  106. weibo following <uid> # User's following list
  107. weibo followers <uid> # User's follower list
  108. ```
  109. ### Authentication
  110. weibo-cli uses this auth priority:
  111. 1. **Saved credentials** — loads from `~/.config/weibo-cli/credential.json`
  112. 2. **Browser cookies** (recommended) — auto-extract from Arc/Chrome/Edge/Firefox/Brave/Chromium/Opera/Vivaldi/Safari/LibreWolf
  113. 3. **QR code login** — terminal QR code, scan with Weibo App
  114. Browser extraction is recommended — it forwards ALL Weibo cookies and is closest to normal browser traffic.
  115. Cookie TTL is **7 days** by default. After expiry, the client automatically attempts browser re-extraction.
  116. ### Troubleshooting
  117. - `⚠️ 未登录` — Run `weibo login` to authenticate
  118. - `会话已过期` — Cookie expired, run `weibo logout && weibo login`
  119. - `Unable to get key for cookie decryption` (macOS Keychain):
  120. - **SSH sessions**: `security unlock-keychain ~/Library/Keychains/login.keychain-db`
  121. - **Local terminal**: Open **Keychain Access** → search **"Chrome Safe Storage"** → **Access Control** → add Terminal → **Save**
  122. - Requests are slow — intentional Gaussian jitter delay (~1s) to avoid triggering Weibo's risk control
  123. ### Best Practices (Avoiding Bans)
  124. - **Keep request volumes low** — use `--count 10` instead of `--count 100`
  125. - **Don't run too frequently** — the built-in rate limiter adds randomized delays
  126. - **Use browser cookie extraction** — provides full cookie fingerprint
  127. - Cookie values are stored locally and never uploaded
  128. ### Output Modes
  129. - Default **Rich table** for interactive terminal reading
  130. - `--json` for scripts and agent pipelines
  131. - `--yaml` for structured output (auto-detected when stdout is not a TTY)
  132. ### Development
  133. ```bash
  134. # Install dev dependencies
  135. uv sync --extra dev --extra yaml
  136. # Lint + tests
  137. uv run ruff check .
  138. uv run pytest tests/ -v
  139. # Smoke tests (require browser cookies)
  140. uv run pytest tests/ -v -m smoke
  141. ```
  142. ### Project Structure
  143. ```text
  144. weibo_cli/
  145. ├── __init__.py
  146. ├── cli.py # Click entry point (16 commands)
  147. ├── client.py # WeiboClient (17 API methods, rate-limit, retry)
  148. ├── auth.py # QR login + browser-cookie3 + credential persistence
  149. ├── constants.py # API endpoints, headers, Chrome 145 UA
  150. ├── exceptions.py # WeiboApiError hierarchy (6 error types)
  151. └── commands/
  152. ├── _common.py # structured_output_options, handle_command, strip_html, format_count
  153. ├── auth.py # login/logout/status/me
  154. ├── search.py # hot/feed/detail/comments/trending/search
  155. └── personal.py # profile/weibos/following/followers/reposts/home
  156. ```
  157. ### Use as AI Agent Skill
  158. weibo-cli ships with a [`SKILL.md`](./SKILL.md) so AI agents can execute common Weibo workflows.
  159. #### [Skills CLI](https://github.com/vercel-labs/skills) (Recommended)
  160. ```bash
  161. npx skills add jackwener/weibo-cli
  162. ```
  163. | Flag | Description |
  164. | --- | --- |
  165. | `-g` | Install globally (user-level, shared across projects) |
  166. | `-a claude-code` | Target a specific agent |
  167. | `-y` | Non-interactive mode |
  168. #### Manual Install
  169. ```bash
  170. mkdir -p .agents/skills
  171. git clone git@github.com:jackwener/weibo-cli.git .agents/skills/weibo-cli
  172. ```
  173. #### ~~OpenClaw / ClawHub~~ (Deprecated)
  174. > ⚠️ ClawHub install method is deprecated and no longer supported. Use [Skills CLI](#skills-cli-recommended) or Manual Install above.
  175. ---
  176. ## 中文
  177. ### 功能特性
  178. **阅读:**
  179. - 🔥 热搜:实时热门话题和标签
  180. - 📰 热门 Feed:热门时间线
  181. - 🏠 关注者 Feed:关注用户的时间线
  182. - 🔍 搜索:按关键词搜索微博
  183. - 📈 搜索趋势:实时搜索趋势侧边栏
  184. - 📝 微博详情:查看完整正文、媒体和统计数据
  185. - 💬 评论:查看微博评论
  186. - 🔁 转发:查看微博转发
  187. - 👤 用户资料:用户信息和统计
  188. - 📋 用户微博:浏览用户已发布的微博列表
  189. - 👥 关注列表:查看用户的关注列表
  190. - 👥 粉丝列表:查看用户的粉丝列表
  191. - 📊 结构化输出:支持 JSON 和 YAML,便于脚本和 AI Agent 集成
  192. > **AI Agent 提示:** 需要结构化输出时优先使用 `--yaml`,除非下游必须是 JSON。stdout 不是 TTY 时默认输出 YAML。
  193. **认证与反风控:**
  194. - Cookie 认证:支持 Arc/Chrome/Edge/Firefox/Brave 等 10+ 浏览器自动提取
  195. - 二维码登录:终端渲染二维码,用微博 APP 扫码
  196. - 凭证持久化:自动保存到 `~/.config/weibo-cli/credential.json`,7 天 TTL
  197. - 反检测:Chrome 145 User-Agent、高斯抖动延迟、指数退避重试
  198. - 会话自动刷新:过期凭证自动触发浏览器 Cookie 重提取
  199. ### 安装
  200. ```bash
  201. # 推荐:uv tool(快速、隔离环境)
  202. uv tool install kabi-weibo-cli
  203. # 或者:pipx
  204. pipx install kabi-weibo-cli
  205. ```
  206. 升级到最新版本:
  207. ```bash
  208. uv tool upgrade kabi-weibo-cli
  209. ```
  210. 从源码安装:
  211. ```bash
  212. git clone git@github.com:jackwener/weibo-cli.git
  213. cd weibo-cli
  214. uv sync
  215. ```
  216. ### 使用示例
  217. ```bash
  218. # 认证
  219. weibo login # 从浏览器提取 Cookie / 二维码扫码
  220. weibo login --qrcode # 直接二维码扫码登录
  221. weibo login --cookie-source chrome # 指定浏览器提取
  222. weibo logout # 清除已保存凭证
  223. weibo status # 检查登录状态
  224. weibo me # 查看当前用户信息
  225. # 热搜
  226. weibo hot # 热搜列表(50+ 条)
  227. weibo hot --count 10 # 限制数量
  228. weibo hot --json # JSON 输出
  229. weibo trending # 搜索趋势
  230. # 搜索
  231. weibo search "科技" # 按关键词搜索微博
  232. weibo search "科技" --count 5 # 限制数量
  233. weibo search "科技" --page 2 # 翻页
  234. # Feed
  235. weibo feed # 热门时间线
  236. weibo feed --count 5 # 限制数量
  237. weibo home # 关注者时间线
  238. # 微博详情与评论
  239. weibo detail Qw06Kd98p # 查看微博
  240. weibo comments Qw06Kd98p # 查看评论
  241. weibo reposts Qw06Kd98p # 查看转发
  242. # 用户
  243. weibo profile 1699432410 # 用户资料
  244. weibo weibos 1699432410 # 用户微博列表
  245. weibo following 1699432410 # 用户关注列表
  246. weibo followers 1699432410 # 用户粉丝列表
  247. ```
  248. ### 常见问题
  249. - `⚠️ 未登录` — 执行 `weibo login` 认证
  250. - `会话已过期` — Cookie 过期,执行 `weibo logout && weibo login`
  251. - 请求较慢是正常的 — 内置高斯随机延迟(~1s)是为了模拟人类浏览行为,避免触发风控
  252. ### 作为 AI Agent Skill 使用
  253. #### [Skills CLI](https://github.com/vercel-labs/skills)(推荐)
  254. ```bash
  255. npx skills add jackwener/weibo-cli
  256. ```
  257. | 参数 | 说明 |
  258. | --- | --- |
  259. | `-g` | 全局安装(用户级别,跨项目共享) |
  260. | `-a claude-code` | 指定目标 Agent |
  261. | `-y` | 非交互模式 |
  262. #### 手动安装
  263. ```bash
  264. mkdir -p .agents/skills
  265. git clone git@github.com:jackwener/weibo-cli.git .agents/skills/weibo-cli
  266. ```
  267. ## License
  268. Apache-2.0

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.