xhs-reader

A read-only CLI for browsing Xiaohongshu (小红书) content, designed for AI agent consumption.

Lightweight — 4 core dependencies (click, httpx, xhshow, qrcode). No browser automation.

Optional: macOS Vision OCR (--ocr), mlx-whisper video transcription (--stt).

Installation

git clone https://github.com/hammershock/xhs-cli.git
cd xhs-reader
pip install -e .

# With OCR support (macOS only)
pip install -e ".[ocr]"

# With video transcription (Apple Silicon, requires ffmpeg)
brew install ffmpeg
pip install -e ".[stt]"

# Everything
pip install -e ".[all]"

Quick Start

# Login (QR code)
xhs login

# Login with cookie string (from browser dev tools)
xhs login --cookie "a1=xxx;web_session=yyy"

# Check who you are
xhs whoami

# Browse feed
xhs feed
xhs feed -n 20

# Search notes
xhs search "美食"
xhs search "旅行" --sort popular --type video --detail

# View note detail (token auto-cached from feed/search)
xhs note <note_id>
xhs note <note_id> --ocr      # OCR images
xhs note <note_id> --stt      # Transcribe video

# Export note with all assets
xhs export <note_id> --comments --ocr --stt

# Comments
xhs comments <note_id> --replies --detail

# Search users
xhs search-user "keyword" --detail

# User profile
xhs user <user_id>

Commands

Command	Description
xhs login	Login via QR code or --cookie
xhs logout	Clear saved credentials
xhs whoami	Show current user
xhs feed	Browse recommended feed
xhs search <keyword>	Search notes
xhs search-user <keyword>	Search users
xhs note <id>	View note detail
xhs comments <id>	View comments
xhs user <id>	View user profile
xhs user-notes <id>	List user's notes
xhs export <id>	Export note to directory
xhs ocr <url>	OCR an image URL

Pagination

All listing commands support -n/--limit, --offset, and --all:

xhs search "keyword" -n 10              # first 10
xhs search "keyword" -n 10 --offset 10  # next 10
xhs search "keyword" --all              # everything

JSON Output

Most commands support --json for machine-readable output:

xhs feed --json
xhs note <id> --json
xhs note <id> --ocr --json    # includes ocr_text per image
xhs note <id> --stt --json    # includes stt_segments with timestamps

Export

Export a note to a structured directory:

xhs export <note_id> -o ~/exports --comments --ocr --stt

Creates:

<note_id>/
  content.md        # Markdown with text, image refs, OCR, transcript, comments
  meta.json         # Full API response
  images/           # Downloaded images
  video.mp4         # Downloaded video (if video note)
  comments.json     # Comments data (--comments)
  comment_images/   # Images from comments (--comments)

Token Caching

Note detail and comments require an xsec_token from Xiaohongshu. Tokens are automatically cached when you use feed or search, so xhs note <id> just works for any note you've discovered. Manual override: xhs note <id> -t <token>.

License

MIT