redbook: a Xiaohongshu CLI that authenticates with your Chrome cookies

The gap redbook fills: Xiaohongshu has no public API for this

Xiaohongshu does not offer an open API for reading notes, listing a creator's posts or posting content, so anything built on top of it has to go through the same web endpoints the browser uses. redbook takes that route deliberately. The README states the tool uses browser Cookie authentication and needs no API key, which means setup is one login in Chrome rather than an application and approval process. The audience is stated in the project description: it is built for AI agents. The README leans into this with an onboarding path where you paste a sentence into Claude Code, Cursor, Codex, Windsurf or OpenClaw and the agent installs the package and runs redbook whoami to confirm the connection. Humans can use it directly too, and every command runs standalone. The work it targets is concrete: which keywords have traffic, who the top creators are in a niche, what a viral note's title hook looks like, whether a note has been silently throttled, and what to reply to in a comment section.

How authentication actually works, and why Windows is different

The CLI reads cookies from an installed browser. By default it looks at Chrome, with safari and firefox selectable through --cookie-source, and it auto-detects Chrome profiles unless you pass --chrome-profile with a name such as "Profile 1". On macOS the README warns that a Keychain prompt may appear and tells you to click Always Allow. On Windows the situation is worse: Chrome 127 and later use App-Bound Encryption, so the CLI launches Chrome in headless mode to read the cookies, and the README says Chrome must be closed first. If that extraction fails, the fallback is --cookie-string with a value copied from Chrome DevTools in the form "a1=...; web_session=...". There is a resolution order for credentials that matters if you run this on a server or in CI: --cookie-string, then the REDBOOK_COOKIE_STRING environment variable, then REDBOOK_COOKIE_FILE, then ~/.redbook/cookies.json, and finally the local browser. The auth subcommand manages that file, with auth export writing the browser session to the default path, auth save taking a manual cookie string, and auth path and auth inspect reporting where the file is and which keys it holds without printing the values. The README is explicit that the cookie file is a plaintext credential, written with 0600 permissions, and should not be committed or pasted into logs. There is also a --platform flag that forces the xhs backend for mainland China or rednote for the global version, with automatic detection when neither is given, and --global as a shorthand for the rednote backend.

The command surface: read, analyse, report, post

Search is the entry point: redbook search "AI编程" --sort popular takes --sort with general, popular or latest, --type with all, video or image, and --page. Reading is redbook read <url> and redbook comments <url> --all. For creator work there is user, user-posts and account-report, where account-report takes a file of account IDs or profile URLs, one per line, ignores lines starting with #, and accepts --month 2026-07. The README notes that account-report pulls only the first page per account by default and marks the result complete: false when more pages exist, so full history needs --all or --max-pages. The JSON output carries per-note likes, comments, collects, shares, total engagement, publish time and webUrl. The analysis commands are analyze-viral, which breaks down hook, engagement and structure for one note, and viral-template, which extracts a content template from one to three notes and takes --comment-pages (default 3). There is a health command for detecting silent throttling, which the README says works through a hidden level field in the creator backend API, and a favorites/collect/uncollect/boards/board group for bookmark management, including other users' public collections. Posting is redbook post with --title, --body and --images, plus a --private flag. The render command turns a Markdown file into Xiaohongshu-style PNG cards using local Chrome, with seven colour styles (purple, xiaohongshu, mint, sunset, ocean, elegant, dark), and the README marks it as requiring optional dependencies. The project is TypeScript, MIT licensed, and the README states Node.js 22 or newer is required, with macOS, Windows and Linux supported.

batch-reply is built around the assumption that you will be detected

The most interesting design decision in the README is the throttling on batch-reply. The command takes --strategy with questions, top-engaged or all-unanswered, a --template supporting {author} and {content} placeholders, --max capped at 30, and --delay with a documented minimum of 180000 milliseconds, or three minutes, defaulting to 300000 milliseconds. The delay is not fixed: the README says a random jitter of roughly 30 percent is added automatically because Xiaohongshu detects evenly spaced automated behaviour. Without a template the command runs in preview mode, and --dry-run forces preview regardless, so the intended flow is to inspect the plan before sending. The README also advises a maximum of one or two batch reply sessions per note per day. Two things follow from this. First, the tool's authors treat detection as a normal operating condition rather than an edge case. Second, batch-reply is not a growth tool: at a five-minute default interval, ten replies take the better part of an hour. Anyone expecting to clear a comment section quickly is looking at the wrong command.

Where redbook breaks: xsec_token, pagination and the posting path

The README documents a failure mode for user lookups that is worth reading before you build anything on top. If you pass only a user ID and the backend returns code=-1, the fix is to supply a profile URL copied from search results or the browser address bar, because those URLs carry an xsec_token. There are explicit --xsec-token and --xsec-source flags for this, with pc_search shown as the source value. In other words, a bare numeric ID is not reliably enough to fetch a profile, and the token is a parameter you have to acquire from a browsing session. Pagination is the second soft spot: account-report defaults to one page per account and signals incompleteness with complete: false rather than fetching everything. The third is posting. The README states plainly that post is prone to triggering captchas and points to a separate explanation further down the document, which is not included in the material available here, so the exact mitigation is unknown. If your workflow depends on unattended publishing, that is the part to test before committing. There is also no mention of rate limits on search or read, no retry policy, and no statement about what happens when the session expires mid-run.

What you are trading against a general scraping stack

The obvious alternative is a general-purpose browser automation or scraping framework: Playwright or Puppeteer driving a logged-in Chrome profile, with your own parsing layer on top. The difference in approach is where the Xiaohongshu-specific knowledge lives. With Playwright you own the selectors, the endpoint shapes, the sorting parameters, the xsec_token handling and the throttling logic. redbook ships those as commands and flags: --sort popular, --type video, --comment-pages, the jittered batch-reply delay, the hidden level field behind health. That is a real saving if your goal is analysis rather than infrastructure. It is a loss if you need to reach an endpoint the CLI does not wrap, because you are then back to writing a scraper anyway, just with an extra dependency in the tree. A second alternative is simply doing the research by hand in the browser: slower, but immune to cookie extraction problems, Chrome version changes and the code=-1 token dance. The honest framing is that redbook is a convenience layer over endpoints that were never meant to be called programmatically, and it inherits that status.

Maintenance cost and what the MIT licence does not cover

The repository shows three releases in the material provided: v0.7.2 in April 2026, v0.8.0 in June 2026 and v0.8.1 in July 2026, with the last push on the same day as v0.8.1. That cadence suggests active maintenance, though the material does not say what changed between versions. The maintenance burden you take on is not in the code but in the environment: Chrome's cookie encryption changed once already (the Windows 127 App-Bound Encryption note), Xiaohongshu can change its endpoints or its anti-automation behaviour at any time, and the code=-1 pattern shows the API already gates some reads behind tokens. Expect to update the package when a command starts failing, and expect cookie extraction to be the first thing to break. On licensing, the project is MIT, which permits commercial use and modification, but the licence covers the code only. It says nothing about whether automated reading or posting on Xiaohongshu complies with the platform's terms of service or with applicable law in your jurisdiction, and nothing about the consequences of your account being flagged. That is a question for your own counsel, not for the repository.

Editorial conclusion

Adopt redbook if you are doing keyword research, competitor account reporting or bulk comment triage on Xiaohongshu and you are comfortable running a tool that reads your Chrome session. Do not adopt it if you need a stable, documented, vendor-supported API, or if you are on Windows with Chrome 127 or newer and cannot close Chrome during a run. Verify three things first: that redbook whoami succeeds on your machine, that account-report returns complete: true for the accounts you care about, and that your cookie file at ~/.redbook/cookies.json is not inside a Git working tree.

Official sources

1. License: MIT
2. lucasygu/redbook on GitHub
3. Project website
4. README
5. Releases