xiaohongshu-cli

xiaohongshu-cli — Xiaohongshu CLI Tool

Binary: xhs Credentials: browser cookies (auto-extracted) or browser-assisted QR login (--qrcode)

Setup

# 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

xhs status --yaml >/dev/null && echo "AUTH_OK" || echo "AUTH_NEEDED"

If AUTH_OK, skip to 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. Supported browsers: Chrome, Arc, Edge, Firefox, Safari, Brave, Chromium, Opera, Opera GX, Vivaldi, LibreWolf, Lynx, w3m. Then:

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:

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. 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

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

xhs hot -c food --json | jq '.data.items[:5] | .[].note_card | {title, likes: .interact_info.liked_count}'

Get user info then follow

xhs user 5f2e123 --json | jq '.data.basic_info | {nickname, user_id}'
xhs follow 5f2e123

Check notifications

xhs unread --json | jq '.data'
xhs notifications --type mentions --json | jq '.data.message_list[:5]'

Analyze all comments on a note

# 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

# 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

# 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

# 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.

Weekly Installs214Repositoryjackwener/xiaoh…gshu-cliGitHub Stars1.3KFirst Seen9 days agoSecurity AuditsGen Agent Trust HubWarnSocketPassSnykWarnInstalled oncodex205opencode205kimi-cli204gemini-cli204amp204github-copilot204