xiaohongshu-cli
Use xiaohongshu-cli for ALL Xiaohongshu (Little Red Book, 小红书) operations — searching notes, reading content, browsing users, liking, collecting, commenting, following, and posting. Invoke whenever the user requests any Xiaohongshu interaction.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/jackwener-xiaohongshu-cli)HTML
<a href="/listings/jackwener-xiaohongshu-cli"><img src="/api/listings/jackwener-xiaohongshu-cli/badge.svg" alt="findsafeskills safety rating" /></a>Install
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 xiaohongshu-cli # Or: pipx pipx install xiaohongshu-cli
Upgrade to the latest version:
uv tool upgrade xiaohongshu-cli # Or: pipx upgrade xiaohongshu-cli
> **Tip:** Upgrade regularly to avoid unexpected errors from outdated API handling.
From source:
git clone git@github.com:jackwener/xiaohongshu-cli.git cd xiaohongshu-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 · 252 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- ---
- name: xiaohongshu-cli
- description: Use xiaohongshu-cli for ALL Xiaohongshu (Little Red Book, 小红书) operations — searching notes, reading content, browsing users, liking, collecting, commenting, following, and posting. Invoke whenever the user requests any Xiaohongshu interaction.
- author: jackwener
- version: "0.6.4"
- tags:
- - xiaohongshu
- - xhs
- - redbook
- - 小红书
- - social-media
- - cli
- ---
- # xiaohongshu-cli — Xiaohongshu CLI Tool
- **Binary:** `xhs`
- **Credentials:** browser cookies (auto-extracted) or browser-assisted QR login (`--qrcode`)
- ## Setup
- ```bash
- # Install (requires Python 3.10+)
- uv tool install xiaohongshu-cli
- # Or: pipx install xiaohongshu-cli
- # Upgrade to latest (recommended to avoid API errors)
- uv tool upgrade xiaohongshu-cli
- # Or: pipx upgrade xiaohongshu-cli
- ```
- ## Authentication
- **IMPORTANT FOR AGENTS**: Before executing ANY xhs command, check if credentials exist first. Do NOT assume cookies are configured.
- ### Step 0: Check if already authenticated
- ```bash
- xhs status --yaml >/dev/null && echo "AUTH_OK" || echo "AUTH_NEEDED"
- ```
- If `AUTH_OK`, skip to [Command Reference](#command-reference).
- If `AUTH_NEEDED`, proceed to Step 1. Prefer `--qrcode` when browser cookie extraction is unavailable but launching a browser is acceptable.
- ### Step 1: Guide user to authenticate
- Ensure user is logged into xiaohongshu.com in any browser supported by [browser_cookie3](https://github.com/borisbabic/browser_cookie3). Supported browsers: Chrome, Arc, Edge, Firefox, Safari, Brave, Chromium, Opera, Opera GX, Vivaldi, LibreWolf, Lynx, w3m. Then:
- ```bash
- xhs login # auto-detect browser with valid cookies
- xhs login --cookie-source arc # specify browser explicitly
- xhs login --qrcode # browser-assisted QR login with terminal QR output
- ```
- Verify with:
- ```bash
- xhs status
- xhs whoami
- ```
- ### Step 2: Handle common auth issues
- | Symptom | Agent action |
- |---------|-------------|
- | `NoCookieError: No 'a1' cookie found` | Guide user to login to xiaohongshu.com in browser |
- | `NeedVerifyError: Captcha required` | Ask user to open browser, complete captcha, then retry |
- | `IpBlockedError: IP blocked` | Suggest switching network (hotspot/VPN) |
- | `SessionExpiredError` | Run `xhs login` to refresh cookies |
- ## Agent Defaults
- All machine-readable output uses the envelope documented in [SCHEMA.md](./SCHEMA.md).
- Payloads live under `.data`.
- - Non-TTY stdout → auto YAML
- - `--json` / `--yaml` → explicit format
- - `OUTPUT=json` env → global override
- - `OUTPUT=rich` env → force human output
- ## Command Reference
- ### Reading
- | Command | Description | Example |
- |---------|-------------|---------|
- | `xhs search <keyword>` | Search notes | `xhs search "美食" --sort popular --type video` |
- | `xhs read <id_or_url_or_index>` | Read a note by ID, URL, or short index | `xhs read 1` / `xhs read "https://...?xsec_token=xxx"` |
- | `xhs comments <id_or_url_or_index>` | Get comments by ID, URL, or short index | `xhs comments 1` / `xhs comments "https://...?xsec_token=..."` |
- | `xhs comments <id_or_url> --all` | Get ALL comments (auto-paginate) | `xhs comments "<url>" --all --json` |
- | `xhs sub-comments <note_id> <comment_id>` | Get replies to comment | `xhs sub-comments abc 123` |
- | `xhs user <user_id>` | View user profile | `xhs user 5f2e123` |
- | `xhs user-posts <user_id>` | List user's notes | `xhs user-posts 5f2e123 --cursor ""` |
- | `xhs feed` | Browse recommendation feed | `xhs feed --yaml` |
- | `xhs hot` | Browse trending notes | `xhs hot -c food` |
- | `xhs topics <keyword>` | Search topics/hashtags | `xhs topics "旅行"` |
- | `xhs search-user <keyword>` | Search users | `xhs search-user "摄影"` |
- | `xhs my-notes` | List own published notes | `xhs my-notes --page 0` |
- | `xhs notifications` | View notifications | `xhs notifications --type likes` |
- | `xhs unread` | Show unread counts | `xhs unread --json` |
- ### Interactions (Write)
- | Command | Description | Example |
- |---------|-------------|---------|
- | `xhs like <id_or_url_or_index>` | Like a note | `xhs like 1` / `xhs like abc123` |
- | `xhs like <id_or_url_or_index> --undo` | Unlike a note | `xhs like 1 --undo` |
- | `xhs favorite <id_or_url_or_index>` | Bookmark a note | `xhs favorite 1` |
- | `xhs unfavorite <id_or_url_or_index>` | Remove bookmark | `xhs unfavorite 1` |
- | `xhs comment <id_or_url_or_index> -c "text"` | Post a comment | `xhs comment 1 -c "好看!"` |
- | `xhs reply <id_or_url_or_index> --comment-id ID -c "text"` | Reply to comment | `xhs reply 1 --comment-id 456 -c "谢谢"` |
- | `xhs delete-comment <note_id> <comment_id>` | Delete own comment | `xhs delete-comment abc 123 -y` |
- ### Social
- | Command | Description | Example |
- |---------|-------------|---------|
- | `xhs follow <user_id>` | Follow a user | `xhs follow 5f2e123` |
- | `xhs unfollow <user_id>` | Unfollow a user | `xhs unfollow 5f2e123` |
- | `xhs favorites [user_id]` | List bookmarked notes (defaults to self) | `xhs favorites --json` |
- ### Creator
- | Command | Description | Example |
- |---------|-------------|---------|
- | `xhs post --title "..." --body "..." --images img.png` | Publish a note | `xhs post --title "Test" --body "Hello"` |
- | `xhs delete <id_or_url>` | Delete own note | `xhs delete abc123 -y` |
- ### Account
- | Command | Description |
- |---------|-------------|
- | `xhs login` | Extract cookies from browser (auto-detect) |
- | `xhs login --qrcode` | Browser-assisted QR login — terminal QR output, browser completes login |
- | `xhs status` | Check authentication status |
- | `xhs logout` | Clear cached cookies |
- | `xhs whoami` | Show current user profile |
- ## Agent Workflow Examples
- ### Search → Read → Like pipeline
- ```bash
- NOTE_ID=$(xhs search "美食推荐" --json | jq -r '.data.items[0].id')
- xhs read "$NOTE_ID" --json | jq '.data'
- xhs like "$NOTE_ID"
- ```
- ### Browse trending food notes
- ```bash
- xhs hot -c food --json | jq '.data.items[:5] | .[].note_card | {title, likes: .interact_info.liked_count}'
- ```
- ### Get user info then follow
- ```bash
- xhs user 5f2e123 --json | jq '.data.basic_info | {nickname, user_id}'
- xhs follow 5f2e123
- ```
- ### Check notifications
- ```bash
- xhs unread --json | jq '.data'
- xhs notifications --type mentions --json | jq '.data.message_list[:5]'
- ```
- ### Analyze all comments on a note
- ```bash
- # Fetch ALL comments and analyze themes
- xhs comments "$NOTE_URL" --all --json | jq '.data.comments | length'
- # Count questions
- xhs comments "$NOTE_URL" --all --json | jq '[.data.comments[] | select(.content | test("[\uff1f?]"))] | length'
- ```
- ### Daily reading workflow
- ```bash
- # Browse recommendation feed
- xhs feed --yaml
- # Interactive short-index workflow
- xhs search "旅行"
- xhs read 1
- xhs comments 1
- xhs like 1
- xhs favorite 1
- xhs comment 1 -c "收藏了"
- # Browse trending by category
- xhs hot -c food --yaml
- xhs hot -c travel --yaml
- ```
- ### QR code login
- ```bash
- # When browser cookie extraction is not available
- xhs login --qrcode
- # → Launches a browser-assisted login flow
- # → Renders QR in terminal using Unicode half-blocks
- # → Scan with Xiaohongshu app → confirm → export cookies
- ```
- ### URL to insights pipeline
- ```bash
- # User pastes a URL → read + all comments
- xhs read "https://www.xiaohongshu.com/explore/xxx?xsec_token=yyy" --json
- xhs comments "https://www.xiaohongshu.com/explore/xxx?xsec_token=yyy" --all --json
- ```
- ## Hot Categories
- Available for `xhs hot -c <category>`:
- `fashion`, `food`, `cosmetics`, `movie`, `career`, `love`, `home`, `gaming`, `travel`, `fitness`
- ## Error Codes
- Structured error codes returned in the `error.code` field:
- - `not_authenticated` — cookies expired or missing
- - `verification_required` — captcha/verification needed
- - `ip_blocked` — IP rate limited
- - `signature_error` — request signing failed
- - `api_error` — upstream API error
- - `unsupported_operation` — operation not available
- ## Limitations
- - **No video download** — cannot download note images/videos
- - **No DMs** — cannot access private messages
- - **No live streaming** — live features not supported
- - **No following/followers list** — XHS web API doesn't expose these endpoints
- - **Single account** — one set of cookies at a time
- - **Rate limited** — built-in Gaussian jitter delay (~1-1.5s) between requests; aggressive usage may trigger captchas or IP blocks
- ## Anti-Detection Notes for Agents
- - **Do NOT parallelize requests** — the built-in rate-limit delay exists for account safety
- - **Captcha recovery**: if `NeedVerifyError` occurs, the client auto-cools-down with increasing delays (5s→10s→20s→30s). Ask the user to complete captcha in browser before retrying
- - **Batch operations**: when doing bulk work (e.g., reading many notes), add `time.sleep()` between CLI calls
- - **Session stability**: all requests in a session share a consistent browser fingerprint. Restarting the CLI creates a new fingerprint 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 `xhs 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.
README.md · README · 478 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # xiaohongshu-cli
- [](https://github.com/jackwener/xiaohongshu-cli/actions/workflows/ci.yml)
- [](https://pypi.org/project/xiaohongshu-cli/)
- [](https://pypi.org/project/xiaohongshu-cli/)
- A CLI for Xiaohongshu (小红书) — search, read, interact, and post via reverse-engineered API 📕
- [English](#features) | [中文](#功能特性)
- ## More Tools
- - [bilibili-cli](https://github.com/jackwener/bilibili-cli) — Bilibili CLI for videos, users, search, and feeds
- - [twitter-cli](https://github.com/jackwener/twitter-cli) — Twitter/X CLI for timelines, bookmarks, and posting
- - [discord-cli](https://github.com/jackwener/discord-cli) — Discord CLI for local-first sync, search, and export
- - [tg-cli](https://github.com/jackwener/tg-cli) — Telegram CLI for local-first sync, search, and export
- ## Features
- - 🔐 **Auth** — auto-extract browser cookies, QR code login, status check, whoami
- - 🔍 **Search** — notes by keyword, user search, topic search
- - 📖 **Reading** — note detail, comments, sub-comments, user profiles
- - 🔢 **Short-index navigation** — open recent list results with `xhs read 1` or `xhs comments 1`
- - 📰 **Feed** — recommendation feed, hot/trending by category
- - 👥 **Social** — follow/unfollow, favorites
- - 👍 **Interactions** — like, favorite, comment, reply, delete
- - ✍️ **Creator** — post image notes, my-notes list, delete
- - 🔔 **Notifications** — unread count, mentions, likes, new followers
- - 🛡️ **Anti-detection** — consistent macOS Chrome fingerprint, `sec-ch-ua` alignment, session-stable browser identity, Gaussian jitter, captcha cooldown, exponential backoff
- - 📊 **Structured output** — commands support `--yaml` and `--json`; non-TTY stdout defaults to YAML
- - 📦 **Stable envelope** — see [SCHEMA.md](./SCHEMA.md) for `ok/schema_version/data/error`
- > **AI Agent Tip:** Prefer `--yaml` for structured output unless strict JSON is required. Non-TTY stdout defaults to YAML automatically.
- ## Installation
- ```bash
- # Recommended: uv tool (fast, isolated)
- uv tool install xiaohongshu-cli
- # Or: pipx
- pipx install xiaohongshu-cli
- ```
- Upgrade to the latest version:
- ```bash
- uv tool upgrade xiaohongshu-cli
- # Or: pipx upgrade xiaohongshu-cli
- ```
- > **Tip:** Upgrade regularly to avoid unexpected errors from outdated API handling.
- From source:
- ```bash
- git clone git@github.com:jackwener/xiaohongshu-cli.git
- cd xiaohongshu-cli
- uv sync
- ```
- ## Usage
- ```bash
- # ─── Auth ─────────────────────────────────────────
- xhs login # Extract cookies from browser
- xhs login --qrcode # Browser-assisted QR login, scan in terminal
- xhs status # Check login status
- xhs whoami # Detailed profile (fans, likes, etc)
- xhs whoami --json # Structured JSON envelope
- xhs logout # Clear saved cookies
- # ─── Search ───────────────────────────────────────
- xhs search "美食" # Search notes
- xhs search "旅行" --sort popular # Sort: general, popular, latest
- xhs search "穿搭" --type video # Filter: all, video, image
- xhs search "AI" --page 2 # Pagination
- xhs search-user "用户名" # Search users
- xhs topics "美食" # Search hashtags/topics
- # ─── Reading ──────────────────────────────────────
- xhs read 1 # Read the 1st result from the last list command
- xhs read <note_id> # Read a note (API only)
- xhs read "https://www.xiaohongshu.com/explore/xxx?xsec_token=yyy" # Read by URL (uses URL token)
- xhs comments 1 # Read comments for the 1st result from the last list command
- xhs comments "<url>" # View comments — paste URL to cache/reuse xsec_token
- xhs comments "<url>" --all # Fetch ALL comments (auto-paginate all pages)
- xhs comments "<url>" --all --json # All comments as JSON
- xhs comments <note_id> --xsec-token T # Use note_id + explicit xsec_token
- xhs comments <note_id> # Reuse cached token if available
- xhs sub-comments <note_id> <cmt_id> # View replies to a comment
- xhs user <user_id> # User profile
- xhs user-posts <user_id> # User's published notes
- xhs user-posts <user_id> --cursor X # Paginate with cursor
- # ─── Feed & Discovery ────────────────────────────
- xhs feed # Recommendation feed
- xhs hot # Hot notes (default: food)
- xhs hot -c fashion # Categories: fashion, food, cosmetics,
- # movie, career, love, home, gaming,
- # travel, fitness
- # Short index works after list commands such as search/feed/hot/user-posts/favorites/my-notes
- xhs search "黑丝"
- xhs read 1
- xhs comments 1
- xhs like 1
- xhs favorite 1
- # ─── Social ───────────────────────────────────────
- xhs favorites # My bookmarked notes (current user)
- xhs favorites <user_id> # Other user's bookmarked notes
- xhs likes # My liked notes (current user)
- xhs likes <user_id> # Other user's liked notes
- xhs follow <user_id> # Follow a user
- xhs unfollow <user_id> # Unfollow a user
- # ─── Interactions ─────────────────────────────────
- xhs like 1 # Like the 1st result from the latest note listing
- xhs like <note_id> # Like a note
- xhs like <note_id> --undo # Unlike
- xhs favorite 1 # Favorite the 1st result from the latest note listing
- xhs favorite <note_id> # Favorite (bookmark)
- xhs unfavorite 1 # Unfavorite the 1st result from the latest note listing
- xhs unfavorite <note_id> # Unfavorite
- xhs comment 1 -c "好赞!" # Comment on the 1st result from the latest note listing
- xhs comment <note_id> -c "好赞!" # Post comment
- xhs reply 1 --comment-id X -c "回复" # Reply on the 1st result from the latest note listing
- xhs reply <note_id> --comment-id X -c "回复" # Reply to comment
- xhs delete-comment <note_id> <cmt_id> # Delete own comment
- # ─── Creator ─────────────────────────────────────
- xhs my-notes # List own notes (v2 creator endpoint)
- xhs my-notes --page 1 # Next page
- xhs post --title "标题" --body "正文" --images img.jpg # Post note
- xhs delete <note_id> # Delete note
- xhs delete <note_id> -y # Skip confirmation
- # ─── Notifications ────────────────────────────────
- xhs unread # Unread counts (likes, mentions, follows)
- xhs notifications # 评论和@ notifications
- xhs notifications --type likes # 赞和收藏 notifications
- xhs notifications --type connections # 新增关注 notifications
- ```
- ## Authentication
- xiaohongshu-cli supports multiple authentication methods:
- 1. **Saved cookies** — loads from `~/.xiaohongshu-cli/cookies.json`
- 2. **Browser cookies** — auto-detects installed browsers and extracts cookies (supports Chrome, Arc, Edge, Firefox, Safari, Brave, Chromium, Opera, Vivaldi, and more)
- 3. **QR code login** — browser-assisted login with terminal QR output (`xhs login --qrcode`)
- `xhs login` automatically tries all installed browsers and uses the first one with valid cookies.
- Use `--cookie-source <browser>` to specify a browser explicitly, or `--qrcode` for browser-assisted QR login.
- Other authenticated commands automatically retry once with fresh browser cookies when the saved session has expired.
- ### Cookie TTL
- Saved cookies are valid for **7 days** by default. After that, the client automatically attempts to refresh from the browser. If browser extraction fails, the existing cookies are used with a warning.
- ### Short-Index Navigation
- After any listing command such as `search`, `feed`, `hot`, `user-posts`, `favorites`, or `my-notes`, the CLI stores the latest ordered note list in `~/.xiaohongshu-cli/index_cache.json`.
- - `xhs read <N>` opens the Nth note from the latest listing
- - `xhs comments <N>` opens comments for the Nth note from the latest listing
- - `xhs like <N>`, `xhs favorite <N>`, `xhs unfavorite <N>`, `xhs comment <N>`, and `xhs reply <N>` reuse the same short index
- - Empty listings clear the index cache, so old results are not reused by accident
- ## Environment Variables
- | Variable | Default | Description |
- |----------|---------|-------------|
- | `OUTPUT` | `auto` | Output format: `json`, `yaml`, `rich`, or `auto` (→ YAML when non-TTY) |
- ## Rate Limiting & Anti-Detection
- xiaohongshu-cli includes comprehensive anti-risk-control measures designed to minimize detection:
- ### Request Timing
- - **Gaussian jitter**: Delays between requests use a truncated Gaussian distribution (not fixed intervals) to mimic natural browsing patterns
- - **Random long pauses**: ~5% of requests include an additional 2-5 second delay simulating reading behavior
- - **Auto-retry**: Exponential backoff on HTTP 429/5xx and network errors (up to 3 retries)
- ### Browser Fingerprint Consistency
- - **UA/Platform alignment**: User-Agent, `sec-ch-ua`, `sec-ch-ua-platform`, and fingerprint fields are all consistent (macOS Chrome 145)
- - **Session-stable identity**: GPU, screen resolution, CPU cores, and other hardware fingerprint values are generated once per session and reused across all requests (real browsers don't change hardware mid-session)
- - **macOS-native values**: GPU vendors (Apple M1/M2/M3, Intel Iris), Retina screen resolutions, `MacIntel` platform — all matching a real macOS browser
- ### Captcha Cooldown
- - **Progressive backoff**: On captcha trigger (HTTP 461/471), automatically sleeps 5→10→20→30 seconds with increasing delays
- - **Adaptive rate limiting**: Request delay is permanently doubled after a captcha event to reduce future risk
- ### Signed Requests
- - All API calls use `x-s` / `x-s-common` / `x-t` signatures (reverse-engineered from web client)
- - `x-b3-traceid` and `x-xray-traceid` for distributed tracing consistency
- ## Structured Output
- All `--json` / `--yaml` output uses the shared envelope from [SCHEMA.md](./SCHEMA.md):
- ```yaml
- ok: true
- schema_version: "1"
- data: { ... }
- ```
- When stdout is not a TTY (e.g., piped or invoked by an AI agent), output defaults to YAML.
- Use `OUTPUT=yaml|json|rich|auto` to override.
- ## Use as AI Agent Skill
- xiaohongshu-cli ships with a [`SKILL.md`](./SKILL.md) that teaches AI agents how to use it.
- ### [Skills CLI](https://github.com/vercel-labs/skills) (Recommended)
- ```bash
- npx skills add jackwener/xiaohongshu-cli
- ```
- | Flag | Description |
- | --- | --- |
- | `-g` | Install globally (user-level, shared across projects) |
- | `-a claude-code` | Target a specific agent |
- | `-y` | Non-interactive mode |
- ### Manual Install
- ```bash
- mkdir -p .agents/skills
- git clone git@github.com:jackwener/xiaohongshu-cli.git .agents/skills/xiaohongshu-cli
- ```
- ### ~~OpenClaw / ClawHub~~ (Deprecated)
- > ⚠️ ClawHub install method is deprecated and no longer supported. Use [Skills CLI](#skills-cli-recommended) or Manual Install above.
- ## Project Structure
- ```text
- xhs_cli/
- ├── __init__.py
- ├── cli.py # Click entry point & command registration
- ├── client.py # XHS API client (signing, retry, rate-limit, anti-detection)
- ├── cookies.py # Cookie extraction, TTL management, auto-refresh, token cache
- ├── signing.py # Main API x-s / x-s-common signature generation
- ├── creator_signing.py # Creator API AES-128-CBC signature
- ├── constants.py # URLs, User-Agent, Chrome version, SDK config
- ├── exceptions.py # Structured exception hierarchy (6 error types)
- ├── qr_login.py # QR code login (browser-assisted terminal QR + HTTP fallback)
- ├── formatter.py # Output formatting, schema envelope, Rich rendering
- └── commands/
- ├── _common.py # Shared CLI helpers (structured_output_options, etc.)
- ├── auth.py # login/logout/status/whoami
- ├── reading.py # search/read/comments/user/feed/hot/topics/search-user
- ├── interactions.py # like/favorite/comment/reply/delete-comment
- ├── social.py # follow/unfollow/favorites
- ├── creator.py # post/my-notes/delete
- └── notifications.py # unread/notifications
- ```
- ## Development
- ```bash
- # Install dependencies
- uv sync
- # Run tests
- uv run pytest tests/ -v
- # Unit tests only (no network)
- uv run pytest tests/ -v --ignore=tests/test_integration.py -m "not smoke"
- # Smoke tests (need cookies)
- uv run pytest tests/ -v -m smoke
- # Integration tests (need cookies)
- uv run pytest tests/test_integration.py -v
- # Lint
- uv run ruff check .
- ```
- ## Troubleshooting
- **Q: `NoCookieError: No 'a1' cookie found`**
- 1. Open any browser and visit https://www.xiaohongshu.com/
- 2. Log in with your account
- 3. Run `xhs login` (auto-detects browser) or `xhs login --cookie-source <browser>`
- **Q: `NeedVerifyError: Captcha required`**
- XHS has triggered a captcha check. Open https://www.xiaohongshu.com/ in your browser, complete the captcha, then retry.
- **Q: `IpBlockedError: IP blocked by XHS`**
- Try a different network (e.g., mobile hotspot or VPN). XHS blocks IPs that make too many requests.
- **Q: `SessionExpiredError: Session expired`**
- Your cookies have expired. Run `xhs login` to refresh.
- **Q: Requests are slow**
- The built-in Gaussian jitter delay (~1-1.5s between requests) is intentional to mimic natural browsing and avoid triggering XHS's risk control. Aggressive request patterns may lead to captcha triggers or IP blocks.
- ---
- ## 推荐项目
- - [bilibili-cli](https://github.com/jackwener/bilibili-cli) — Bilibili 视频、用户、搜索与动态 CLI
- - [twitter-cli](https://github.com/jackwener/twitter-cli) — Twitter/X 时间线、书签和发推 CLI
- - [discord-cli](https://github.com/jackwener/discord-cli) — Discord 本地优先同步、检索与导出 CLI
- - [tg-cli](https://github.com/jackwener/tg-cli) — Telegram 本地优先同步、检索与导出 CLI
- ## 功能特性
- - 🔐 **认证** — 自动提取浏览器 Cookie,browser-assisted 二维码扫码登录,状态检查,用户信息
- - 🔍 **搜索** — 按关键词搜索笔记、用户、话题
- - 📖 **阅读** — 笔记详情、评论、子评论、用户主页
- - 📰 **发现** — 推荐 Feed、按分类浏览热门
- - 👥 **社交** — 关注/取关、收藏夹
- - 👍 **互动** — 点赞、收藏、评论、回复、删除
- - ✍️ **创作者** — 发布图文笔记、我的笔记列表、删除
- - 🔔 **通知** — 未读数、@、点赞、新关注
- - 🛡️ **反风控** — macOS Chrome 指纹一致性、session 级浏览器身份持久化、高斯抖动延迟、验证码自动冷却、指数退避重试
- - 📊 **结构化输出** — `--yaml` / `--json`,非 TTY 默认输出 YAML
- - 📦 **稳定 envelope** — 参见 [SCHEMA.md](./SCHEMA.md)
- ## 安装
- ```bash
- # 推荐:uv tool(快速、隔离环境)
- uv tool install xiaohongshu-cli
- # 或者:pipx
- pipx install xiaohongshu-cli
- ```
- 升级到最新版本:
- ```bash
- uv tool upgrade xiaohongshu-cli
- # 或:pipx upgrade xiaohongshu-cli
- ```
- > **提示:** 建议定期升级,避免因版本过旧导致的 API 调用异常。
- 从源码安装:
- ```bash
- git clone git@github.com:jackwener/xiaohongshu-cli.git
- cd xiaohongshu-cli
- uv sync
- ```
- ## 使用示例
- ```bash
- # 认证
- xhs login # 从浏览器提取 Cookie
- xhs login --qrcode # browser-assisted 二维码扫码登录(终端显示二维码)
- xhs status # 检查登录状态
- xhs whoami # 查看用户资料
- xhs logout # 清除缓存的 Cookie
- # 搜索
- xhs search "美食" # 搜索笔记
- xhs search "旅行" --sort popular # 排序:general, popular, latest
- xhs search-user "用户名" # 搜索用户
- xhs topics "美食" # 搜索话题
- # 阅读
- xhs read 1 # 阅读最近一次列表里的第 1 条笔记
- xhs read <note_id> # 阅读笔记(仅走 API)
- xhs read "https://...?xsec_token=..." # 粘贴网页 URL 直接阅读(使用 URL token)
- xhs comments 1 # 查看最近一次列表里的第 1 条笔记评论
- xhs comments "<url>" # 查看评论 — 粘贴 URL 以缓存/复用 xsec_token
- xhs comments "<url>" --all # 获取全部评论(自动翻页)
- xhs comments "<url>" --all --json # 全部评论,JSON 格式
- xhs comments <note_id> --xsec-token T # 用 note_id + 显式 xsec_token
- xhs comments <note_id> # 如果之前访问过 URL,会复用缓存 token
- xhs sub-comments <note_id> <cmt_id> # 查看评论的回复
- xhs user <user_id> # 用户主页
- xhs user-posts <user_id> # 用户发布的笔记
- # 发现
- xhs feed # 推荐 Feed
- xhs hot -c food # 热门笔记(按分类)
- xhs hot -c travel # 分类: fashion, food, cosmetics, movie, career,
- # love, home, gaming, travel, fitness
- # 社交
- xhs favorites # 我的收藏(自动识别当前用户)
- xhs favorites <user_id> # 其他用户的收藏
- xhs likes # 我的点赞(自动识别当前用户)
- xhs likes <user_id> # 其他用户的点赞
- xhs follow <user_id> # 关注
- xhs unfollow <user_id> # 取消关注
- # 互动
- xhs like 1 # 给最近一次列表里的第 1 条笔记点赞
- xhs like <note_id> # 点赞
- xhs like <note_id> --undo # 取消点赞
- xhs favorite 1 # 收藏最近一次列表里的第 1 条笔记
- xhs favorite <note_id> # 收藏
- xhs unfavorite 1 # 取消收藏最近一次列表里的第 1 条笔记
- xhs unfavorite <note_id> # 取消收藏
- xhs comment 1 -c "好棒!" # 给最近一次列表里的第 1 条笔记发评论
- xhs comment <note_id> -c "好棒!" # 发评论
- xhs reply 1 --comment-id X -c "谢谢" # 给最近一次列表里的第 1 条笔记回复评论
- xhs reply <note_id> --comment-id X -c "谢谢" # 回复评论
- xhs delete-comment <note_id> <cmt_id> # 删除自己的评论
- # 创作者
- xhs my-notes # 我的笔记列表
- xhs post --title "标题" --body "正文" --images img.jpg # 发布笔记
- xhs delete <note_id> # 删除笔记
- xhs delete <note_id> -y # 跳过确认
- # 通知
- xhs unread # 未读数
- xhs notifications # 评论和 @ 通知
- xhs notifications --type likes # 赞和收藏通知
- xhs notifications --type connections # 新增关注通知
- ```
- ## 认证策略
- xiaohongshu-cli 支持多种认证方式:
- 1. **已保存 Cookie** — 从 `~/.xiaohongshu-cli/cookies.json` 加载
- 2. **浏览器 Cookie** — 自动检测已安装浏览器并提取(支持 Chrome、Arc、Edge、Firefox、Safari、Brave、Chromium、Opera、Vivaldi 等)
- 3. **二维码扫码登录** — browser-assisted 登录,终端显示二维码,用小红书 App 扫码(`xhs login --qrcode`)
- Cookie 保存后有效期 **7 天**,超时后自动尝试从浏览器刷新。
- `xhs login` 会自动尝试所有已安装浏览器,使用第一个有有效 Cookie 的浏览器。也可用 `--cookie-source <browser>` 指定浏览器,或 `--qrcode` 使用 browser-assisted 二维码登录。其他需认证命令在 session 过期时会自动重试一次。
- ## 常见问题
- - `NoCookieError: No 'a1' cookie found` — 请先在任意浏览器打开 https://www.xiaohongshu.com/ 并登录,然后执行 `xhs login`
- - `NeedVerifyError` — 触发了验证码,请到浏览器中完成验证后重试
- - `IpBlockedError` — IP 被限制,尝试切换网络(手机热点或 VPN)
- - `SessionExpiredError` — Cookie 过期,执行 `xhs login` 刷新
- - 请求较慢是正常的 — 内置高斯随机延迟(~1-1.5s)是为了模拟人类浏览行为,避免触发风控
- ## 作为 AI Agent Skill 使用
- xiaohongshu-cli 自带 [`SKILL.md`](./SKILL.md),让 AI Agent 能自动学习并使用本工具。
- ### [Skills CLI](https://github.com/vercel-labs/skills)(推荐)
- ```bash
- npx skills add jackwener/xiaohongshu-cli
- ```
- | 参数 | 说明 |
- | --- | --- |
- | `-g` | 全局安装(用户级别,跨项目共享) |
- | `-a claude-code` | 指定目标 Agent |
- | `-y` | 非交互模式 |
- ### 手动安装
- ```bash
- mkdir -p .agents/skills
- git clone git@github.com:jackwener/xiaohongshu-cli.git .agents/skills/xiaohongshu-cli
- ```
- ### ~~OpenClaw / ClawHub~~(已过时)
- > ⚠️ ClawHub 安装方式已过时,不再支持。请使用上方的 Skills CLI 或手动安装。
- ## License
- Apache-2.0
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.