xhs-cli

> [!NOTE]
> An alternative package [xiaohongshu-cli](https://github.com/jackwener/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

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

## Authentication

All commands require valid cookies to function.

```bash
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

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

### Read Note

```bash
# 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

```bash
# 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

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

### Interactions (require login)

```bash
# 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

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

### Post

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

### Account

```bash
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:

```bash
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

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