mcpField
X
xhs-cli

xhs-cli

github.com/jackwenerMarketing & growth674104 installsUpdated 3w ago
Repository

About xhs-cli

xhs-cli is a command-line tool for interacting with Xiaohongshu. It supports content search, note and profile viewing, account interactions, and posting, with machine-readable JSON output for supported queries.

Key features

  1. 01Search notes and topics
  2. 02Read notes and comments
  3. 03View profiles and user posts
  4. 04Like, favorite, and comment
  5. 05Publish image posts
  6. 06JSON output

Use cases

  1. 01Search Xiaohongshu topics
  2. 02Review profiles and published notes
  3. 03Manage likes and favorites from the CLI
  4. 04Publish posts with images

MCP support

The input does not describe MCP integration or support.

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/jackwener/xhs-cli --skill xhs-cli

After installing, type/xhs-cliin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

README.md
pyproject.toml
.gitignore
README_EN.md
CHANGELOG.md
LICENSE
.github/workflows/
publish.yml
ci.yml
scripts/
smoke_local.sh
tests/
conftest.py
test_auth.py
test_cli.py
test_client.py
test_integration.py
xhs_cli/
__init__.py
auth.py
exceptions.py
cli.py
client.py

Details

From the project README

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.

Comments

Markdown supported