v0.2.0

xhs can now read public Xiaohongshu data without a cookie, the profile login
wall is fixed, the exit codes are honest, crawl grew into a small scraping
engine, and the docs are rewritten around how to use each command.

Read without a cookie

The signed JSON API answers -101 needs login to an anonymous caller, but the
web client ships the data inside the server-rendered page as
window.__INITIAL_STATE__. xhs now reads that page first and only falls back
to the signed API when you pass a logged-in cookie.

• note and feed work anonymously.
• user, user --notes, and related work from a cold IP and get rate-walled
  once the IP is hot.
• comments, search, suggest, tag, and me still need a cookie, since
  the site does not server-render them.

The new pkg/xhshtml package extracts __INITIAL_STATE__ from the HTML and
cleans up the undefined/NaN the page leaves in its JSON.

The profile login-wall fix

An in-site Referer header made the site treat a profile fetch as an in-app
navigation and bounce it to /login. Dropping the Referer on web reads
returns the full page. xhs also detects a redirect to /login and reports it
as a surface that needs a cookie instead of a confusing network error.

Honest exit codes

A walled or login-only surface now exits 3 (needs a cookie) instead of exiting
0 with empty output or 6 with a wrapped error. note and user return the
underlying error when a batch resolves nothing, so a fully blocked run fails
loudly.

A crawl engine

xhs crawl walks outward from seed notes and streams connected records as
JSONL, one file per kind, into an output directory. It writes notes.jsonl,
users.jsonl, and comments.jsonl as it goes, so a run that stops early still
leaves usable data on disk.

xhs crawl <note-id> --token <t> --out ./data --comments
xhs feed --category food -o url | xhs crawl - --out ./data

Usage-first docs

The docs lead with how to use each command. The new commands reference shows
every command with the call and a sample of what it prints.

Install

go install github.com/tamnd/xiaohongshu-cli/cmd/xhs@latest

Or download a prebuilt binary below, or run ghcr.io/tamnd/xhs:0.2.0.

v0.1.0

The first release of xhs, a command line for public Xiaohongshu data. One
pure-Go binary, no paid API key.

What it does

• Resolve notes, creator profiles, comments, search results, the recommendation
  homefeed, related notes, and topics into flat records with stable snake_case
  fields and a fetched_at timestamp.
• Stream results as JSONL, one record per line, or pick table, json, csv,
  tsv, yaml, url, or raw with -o. --fields selects columns,
  --template renders each record, -n caps the count.
• Parse ids, urls, and xsec_tokens out of any link with xhs id, and pipe one
  command into the next: xhs search coffee -o url | xhs note -.
• Crawl connected records from seed notes into JSONL files with xhs crawl.

How it talks to the site

xhs signs its own requests and bootstraps an anonymous web session, then caches
it on disk. The signer and the session are reimplemented from scratch by
observing the public web client; no third-party code is vendored.

Xiaohongshu blocks datacenter IP ranges and rate-limits every IP hard. From a
residential connection the public surfaces are reachable at the default polite
pace. Opening a note needs its xsec_token, which travels with the note in
listings and share URLs. The personalized surfaces need a logged-in cookie
passed with --cookie or XHS_COOKIE.

Install

go install github.com/tamnd/xiaohongshu-cli/cmd/xhs@latest

Or download a prebuilt binary below, or run the container image:

docker run --rm ghcr.io/tamnd/xhs:0.1.0 --help