Skill: jackwener/xiaohongshu-cli (version 0.2.1)

--- 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: "1.0.0" tags: - xiaohongshu - xhs - redbook - 小红书 - social-media - cli --- # xiaohongshu-cli — Xiaohongshu CLI Tool **Binary:** `xhs` **Credentials:** browser cookies (auto-extracted via `--cookie-source`) ## Setup ```bash # Install (requires Python 3.10+) uv tool install xiaohongshu-cli # Or: pipx install 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. ### Step 1: Guide user to authenticate Ensure user is logged into xiaohongshu.com in one of: Chrome, Edge, Firefox, Safari, Brave. Then: ```bash xhs login # auto-extract cookies xhs login --cookie-source firefox # specify browser ``` 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>` | Read a note (URL auto-extracts xsec_token) | `xhs read "https://...?xsec_token=xxx"` | | `xhs comments <id_or_url>` | Get comments (xsec_token required — paste URL) | `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>` | Like a note | `xhs like abc123` | | `xhs like <id_or_url> --undo` | Unlike a note | `xhs like abc123 --undo` | | `xhs favorite <id_or_url>` | Bookmark a note | `xhs favorite abc123` | | `xhs unfavorite <id_or_url>` | Remove bookmark | `xhs unfavorite abc123` | | `xhs comment <id_or_url> -c "text"` | Post a comment | `xhs comment abc123 -c "好看！"` | | `xhs reply <id_or_url> --comment-id ID -c "text"` | Reply to comment | `xhs reply abc123 --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` | Verify and display cookie status | | `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 # Browse trending by category xhs hot -c food --yaml xhs hot -c travel --yaml ``` ### 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.


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)