xhs-cli

Category: Tools & Productivity | Uploader: jackwener | Downloads: 0 | Version: v1.0（Latest）

CLI skill for Xiaohongshu (小红书, RedNote, XHS) to search notes, read posts, browse profiles, like, favorite, comment, and publish from the terminal

Changelog: Source: GitHub https://github.com/jackwener/xhs-cli

Directory Structure

Current level: Root

📁 .github/
- 📁 workflows/
  - 📄 ci.yml 688 B
  - 📄 publish-clawhub.yml 1.6 KB
  - 📄 publish.yml 882 B
📁 scripts/
- 📄 smoke_local.sh 2.0 KB
📁 tests/
- 📄 conftest.py 940 B
- 📄 test_auth.py 6.5 KB
- 📄 test_cli.py 11.7 KB
- 📄 test_client.py 5.7 KB
- 📄 test_integration.py 9.9 KB
📁 xhs_cli/
- 📄 __init__.py 72 B
- 📄 auth.py 24.2 KB
- 📄 cli.py 37.9 KB
- 📄 client.py 54.3 KB
- 📄 exceptions.py 315 B
📄 .gitignore 205 B
📄 CHANGELOG.md 1.7 KB
📄 LICENSE 10.5 KB
📄 pyproject.toml 1.7 KB
📄 README.md 6.9 KB
📄 README_EN.md 7.1 KB
📄 SKILL.md 4.0 KB
📄 uv.lock 921.6 KB

SKILL.md

---
name: xhs-cli
description: CLI skill for Xiaohongshu (小红书, RedNote, XHS) to search notes, read posts, browse profiles, like, favorite, comment, and publish from the terminal
author: jackwener
version: "1.0.0"
tags:
  - xhs
  - xiaohongshu
  - 小红书
  - rednote
  - social-media
  - cli
---

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

Comments 0

Latest | Hot

Please login before commenting.

No comments yet. Be the first one!

xhs-cli

Directory Structure

SKILL.md

Report

Notice