xiaohongshu-cliSAFE

From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: xiaohongshu-cli
description: Use xiaohongshu-cli for ALL Xiaohongshu (Little Red Book, 小红书) operations — searching notes, reading content, browsing users, liking, collecting, commenting, following, and posting. Invoke whenever the user requests any Xiaohongshu interaction.
author: jackwener
version: "0.6.4"
tags:
  - xiaohongshu
  - xhs
  - redbook
  - 小红书
  - social-media
  - cli
---

# xiaohongshu-cli — Xiaohongshu CLI Tool

**Binary:** `xhs`
**Credentials:** browser cookies (auto-extracted) or browser-assisted QR login (`--qrcode`)

## Setup

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

# Upgrade to latest (recommended to avoid API errors)
uv tool upgrade xiaohongshu-cli
# Or: pipx upgrade xiaohongshu-cli
```

## Authentication

**IMPORTANT FOR AGENTS**: Before executing ANY xhs command, check if credentials exist first. Do NOT assume cookies are configured.

### Step 0: Check if already authenticated

```bash
xhs status --yaml >/dev/null && echo "AUTH_OK" || echo "AUTH_NEEDED"
```

If `AUTH_OK`, skip to [Command Reference](#command-reference).
If `AUTH_NEEDED`, proceed to Step 1. Prefer `--qrcode` when browser cookie extraction is unavailable but launching a browser is acceptable.

### Step 1: Guide user to authenticate

Ensure user is logged into xiaohongshu.com in any browser supported by [browser_cookie3](https://github.com/borisbabic/browser_cookie3). Supported browsers: Chrome, Arc, Edge, Firefox, Safari, Brave, Chromium, Opera, Opera GX, Vivaldi, LibreWolf, Lynx, w3m. Then:

```bash
xhs login                              # auto-detect browser with valid cookies
xhs login --cookie-source arc          # specify browser explicitly
xhs login --qrcode                     # browser-assisted QR login with terminal QR output
```

Verify with:

```bash
xhs status
xhs whoami
```

### Step 2: Handle common auth issues

| Symptom | Agent action |
|---------|-------------|
| `NoCookieError: No 'a1' cookie found` | Guide user to login to xiaohongshu.com in browser |
| `NeedVerifyError: Captcha required` | Ask user to open browser, complete captcha, then retry |
| `IpBlockedError: IP blocked` | Suggest switching network (hotspot/VPN) |
| `SessionExpiredError` | Run `xhs login` to refresh cookies |

## Agent Defaults

All machine-readable output uses the envelope documented in [SCHEMA.md](./SCHEMA.md).
Payloads live under `.data`.

- Non-TTY stdout → auto YAML
- `--json` / `--yaml` → explicit format
- `OUTPUT=json` env → global override
- `OUTPUT=rich` env → force human output

## Command Reference

### Reading

| Command | Description | Example |
|---------|-------------|---------|
| `xhs search <keyword>` | Search notes | `xhs search "美食" --sort popular --type video` |
| `xhs read <id_or_url_or_index>` | Read a note by ID, URL, or short index | `xhs read 1` / `xhs read "https://...?xsec_token=xxx"` |
| `xhs comments <id_or_url_or_index>` | Get comments by ID, URL, or short index | `xhs comments 1` / `xhs comments "https://...?xsec_token=..."` |
| `xhs comments <id_or_url> --all` | Get ALL comments (auto-paginate) | `xhs comments "<url>" --all --json` |
| `xhs sub-comments <note_id> <comment_id>` | Get replies to comment | `xhs sub-comments abc 123` |
| `xhs user <user_id>` | View user profile | `xhs user 5f2e123` |
| `xhs user-posts <user_id>` | List user's notes | `xhs user-posts 5f2e123 --cursor ""` |
| `xhs feed` | Browse recommendation feed | `xhs feed --yaml` |
| `xhs hot` | Browse trending notes | `xhs hot -c food` |
| `xhs topics <keyword>` | Search topics/hashtags | `xhs topics "旅行"` |
| `xhs search-user <keyword>` | Search users | `xhs search-user "摄影"` |
| `xhs my-notes` | List own published notes | `xhs my-notes --page 0` |
| `xhs notifications` | View notifications | `xhs notifications --type likes` |
| `xhs unread` | Show unread counts | `xhs unread --json` |

### Interactions (Write)

| Command | Description | Example |
|---------|-------------|---------|
| `xhs like <id_or_url_or_index>` | Like a note | `xhs like 1` / `xhs like abc123` |
| `xhs like <id_or_url_or_index> --undo` | Unlike a note | `xhs like 1 --undo` |
| `xhs favorite <id_or_url_or_index>` | Bookmark a note | `xhs favorite 1` |
| `xhs unfavorite <id_or_url_or_index>` | Remove bookmark | `xhs unfavorite 1` |
| `xhs comment <id_or_url_or_index> -c "text"` | Post a comment | `xhs comment 1 -c "好看!"` |
| `xhs reply <id_or_url_or_index> --comment-id ID -c "text"` | Reply to comment | `xhs reply 1 --comment-id 456 -c "谢谢"` |
| `xhs delete-comment <note_id> <comment_id>` | Delete own comment | `xhs delete-comment abc 123 -y` |

### Social

| Command | Description | Example |
|---------|-------------|---------|
| `xhs follow <user_id>` | Follow a user | `xhs follow 5f2e123` |
| `xhs unfollow <user_id>` | Unfollow a user | `xhs unfollow 5f2e123` |
| `xhs favorites [user_id]` | List bookmarked notes (defaults to self) | `xhs favorites --json` |

### Creator

| Command | Description | Example |
|---------|-------------|---------|
| `xhs post --title "..." --body "..." --images img.png` | Publish a note | `xhs post --title "Test" --body "Hello"` |
| `xhs delete <id_or_url>` | Delete own note | `xhs delete abc123 -y` |

### Account

| Command | Description |
|---------|-------------|
| `xhs login` | Extract cookies from browser (auto-detect) |
| `xhs login --qrcode` | Browser-assisted QR login — terminal QR output, browser completes login |
| `xhs status` | Check authentication status |
| `xhs logout` | Clear cached cookies |
| `xhs whoami` | Show current user profile |

## Agent Workflow Examples

### Search → Read → Like pipeline

```bash
NOTE_ID=$(xhs search "美食推荐" --json | jq -r '.data.items[0].id')
xhs read "$NOTE_ID" --json | jq '.data'
xhs like "$NOTE_ID"
```

### Browse trending food notes

```bash
xhs hot -c food --json | jq '.data.items[:5] | .[].note_card | {title, likes: .interact_info.liked_count}'
```

### Get user info then follow

```b

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

declared (3 observation(s))

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (5)

x1 = hashlib.md5(content.encode("utf-8")).hexdigest()

envelope = json.loads(base64.b64decode(envelope_b64))

env1 = json.loads(base64.b64decode(r1["x-s"][4:]))

env2 = json.loads(base64.b64decode(r2["x-s"][4:]))

Gates applied: no_behavioural_pass, no_license.

[![ModelsAtlas audit: xiaohongshu-cli](https://modelsatlas.com/skills/jackwener/xiaohongshu-cli/badge.svg)](https://modelsatlas.com/skills/jackwener/xiaohongshu-cli/)

Not your listing, or something out of date? Claim or update your listing.