xhs-cli（XHS CLI 搜索）

[!NOTE] An alternative package xiaohongshu-cli is available, which uses a reverse-engineered API and runs faster. This package (xhs-cli) uses a headless browser (camoufox) approach — slower but more resilient against risk-control detection. Choose whichever best fits your needs.

xhs-cli Skill

A CLI tool for interacting with Xiaohongshu (小红书). Use it to search notes, read details, browse user profiles, and perform interactions like liking, favoriting, and commenting.

Prerequisites

# Install (requires Python 3.8+)
uv tool install xhs-cli
# Or: pipx install xhs-cli

Authentication

All commands require valid cookies to function.

xhs status                     # Check saved login session (no browser extraction)
xhs login                      # Auto-extract Chrome cookies
xhs login --cookie "a1=..."    # Or provide cookies manually

Authentication first uses saved local cookies. If unavailable, it auto-detects local Chrome cookies via browser-cookie3. If extraction fails, QR code login is available.

Command Reference

Search

xhs search "咖啡"              # Search notes (rich table output)
xhs search "咖啡" --json       # Raw JSON output

Read Note

# View note (xsec_token auto-resolved from search cache)
xhs read <note_id>
xhs read <note_id> --comments  # Include comments
xhs read <note_id> --xsec-token <token>  # Manual token
xhs read <note_id> --json

User

# Look up user profile (by internal user_id, hex format)
xhs user <user_id>
xhs user <user_id> --json

# List user's published notes
xhs user-posts <user_id>
xhs user-posts <user_id> --json

# Followers / Following
xhs followers <user_id>
xhs following <user_id>

Discovery

xhs feed                       # Explore page recommended feed
xhs feed --json
xhs topics "旅行"              # Search topics/hashtags
xhs topics "旅行" --json

Interactions (require login)

# Like / Unlike (xsec_token auto-resolved)
xhs like <note_id>
xhs like <note_id> --undo

# Favorite / Unfavorite
xhs favorite <note_id>
xhs favorite <note_id> --undo

# Comment
xhs comment <note_id> "好棒！"

# Delete your own note
xhs delete <note_id>

Favorites

xhs favorites                  # List your favorites
xhs favorites --max 10         # Limit count
xhs favorites --json

Post

xhs post "标题" --image photo1.jpg --image photo2.jpg --content "正文"
xhs post "标题" --image photo1.jpg --content "正文" --json

Account

xhs status                     # Quick saved-session check
xhs whoami                     # Full profile info
xhs whoami --json
xhs login                      # Login
xhs logout                     # Clear cookies

JSON Output

Major query commands support --json for machine-readable output:

xhs search "咖啡" --json | jq '.[0].id'           # First note ID
xhs whoami --json | jq '.userInfo.userId'          # Your user ID
xhs favorites --json | jq '.[0].displayTitle'      # First favorite title

Common Patterns for AI Agents

# Get your user ID for further queries
xhs whoami --json | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('userInfo',{}).get('userId',''))"

# Search and get note IDs (xsec_token auto-cached for later use)
xhs search "topic" --json | python3 -c "import sys,json; [print(n['id']) for n in json.load(sys.stdin)[:3]]"

# Check login before performing actions
xhs status && xhs like <note_id>

# Read a note with comments for summarization
xhs read <note_id> --comments --json

Error Handling

• Commands exit with code 0 on success, non-zero on failure
• Error messages are prefixed with ❌
• Login-required commands show clear instruction to run xhs login
• xsec_token is auto-resolved from cache; manual --xsec-token available as fallback

Safety Notes

• Do not ask users to share raw cookie values in chat logs.
• Prefer auto-extraction via xhs login over manual cookie input.
• If auth fails, ask the user to re-login via xhs login.