{"id":"94a4826a-fcf3-49a2-b81e-d3ffd398ee50","entityType":"agent","slug":"clawhub-jackwener-xiaohongshu-cli","name":"xiaohongshu-cli","canonicalUrl":"https://www.xpersona.co/agent/clawhub-jackwener-xiaohongshu-cli","canonicalPath":"/agent/clawhub-jackwener-xiaohongshu-cli","generatedAt":"2026-10-12T19:57:56.730Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-11T21:12:33.861Z","emptyReason":null},"description":"Use xiaohongshu-cli for ALL Xiaohongshu (Little Red Book, 小红书) operations — searching notes, reading content, browsing users, liking, collecting, commenting,... Skill: xiaohongshu-cli Owner: jackwener Summary: Use xiaohongshu-cli for ALL Xiaohongshu (Little Red Book, 小红书) operations — searching notes, reading content, browsing users, liking, collecting, commenting,... Tags: latest:0.2.1 Version history: v0.2.1 | 2026-03-10T17:15:55.955Z | user Release 0.2.1 v0.1.4 | 2026-03-08T18:16:50.706Z | user Sync SKILL.md: add 小红书 tag, safety notes v0.1.3 | 2026-03-05T17:59:13.818Z | u","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 992 downloads reported by the source. Last updated 10/11/2026.","installCommand":"clawhub skill install s176j4v65c2r3ydppd13q6pm0h885k6x:xiaohongshu-cli","sourceUrl":"https://clawhub.ai/jackwener/xiaohongshu-cli","homepage":"https://clawhub.ai/jackwener/skills/xiaohongshu-cli","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/jackwener/xiaohongshu-cli","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/jackwener/skills/xiaohongshu-cli","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":60,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"Use xiaohongshu-cli for ALL Xiaohongshu (Little Red Book, 小红书) operations — searching notes, reading content, browsing users, liking, collecting, commenting,..."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-11T21:12:33.861Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T21:12:33.861Z","emptyReason":null},"stars":null,"forks":null,"downloads":992,"likes":null,"task":null,"library":null,"packageName":null,"latestVersion":"0.2.1","tractionLabel":"992 downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T21:12:33.790Z","emptyReason":null},"lastUpdatedAt":"2026-10-11T21:12:33.861Z","lastCrawledAt":"2026-10-11T21:12:33.790Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-12T21:12:33.790Z","lastVerifiedAt":null,"highlights":[{"version":"0.2.1","createdAt":"2026-03-10T17:15:55.955Z","changelog":"Release 0.2.1","fileCount":33,"zipByteSize":59801},{"version":"0.1.4","createdAt":"2026-03-08T18:16:50.706Z","changelog":"Sync SKILL.md: add 小红书 tag, safety notes","fileCount":17,"zipByteSize":48441},{"version":"0.1.3","createdAt":"2026-03-05T17:59:13.818Z","changelog":"Release 0.1.3","fileCount":17,"zipByteSize":48260},{"version":"0.1.2","createdAt":"2026-03-05T17:28:12.110Z","changelog":"Release 0.1.2","fileCount":16,"zipByteSize":44961},{"version":"0.1.1","createdAt":"2026-03-05T16:02:37.063Z","changelog":"Add delete command, post --json detail output, and smoke post-delete rollback","fileCount":16,"zipByteSize":39183},{"version":"0.1.0","createdAt":"2026-03-05T08:59:14.436Z","changelog":"Initial release: search, read, like, favorite, comment for Xiaohongshu","fileCount":14,"zipByteSize":32297}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s176j4v65c2r3ydppd13q6pm0h885k6x:xiaohongshu-cli","setupComplexity":"low","setupSteps":["Setup complexity is classified as HIGH. You must provision dedicated cloud infrastructure or an isolated VM. Do not run this directly on your local workstation.","Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-jackwener-xiaohongshu-cli/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-jackwener-xiaohongshu-cli/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-jackwener-xiaohongshu-cli/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-jackwener-xiaohongshu-cli/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-jackwener-xiaohongshu-cli/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-jackwener-xiaohongshu-cli/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-12T19:57:56.729Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-jackwener-xiaohongshu-cli/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-jackwener-xiaohongshu-cli/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-jackwener-xiaohongshu-cli/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-jackwener-xiaohongshu-cli/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"high","updatedAt":"2026-10-11T21:12:33.861Z","emptyReason":null},"readme":"Skill: xiaohongshu-cli\n\nOwner: jackwener\n\nSummary: Use xiaohongshu-cli for ALL Xiaohongshu (Little Red Book, 小红书) operations — searching notes, reading content, browsing users, liking, collecting, commenting,...\n\nTags: latest:0.2.1\n\nVersion history:\n\nv0.2.1 | 2026-03-10T17:15:55.955Z | user\n\nRelease 0.2.1\n\nv0.1.4 | 2026-03-08T18:16:50.706Z | user\n\nSync SKILL.md: add 小红书 tag, safety notes\n\nv0.1.3 | 2026-03-05T17:59:13.818Z | user\n\nRelease 0.1.3\n\nv0.1.2 | 2026-03-05T17:28:12.110Z | user\n\nRelease 0.1.2\n\nv0.1.1 | 2026-03-05T16:02:37.063Z | user\n\nAdd delete command, post --json detail output, and smoke post-delete rollback\n\nv0.1.0 | 2026-03-05T08:59:14.436Z | user\n\nInitial release: search, read, like, favorite, comment for Xiaohongshu\n\nArchive index:\n\nArchive v0.2.1: 33 files, 59801 bytes\n\nFiles: pyproject.toml (1577b), README.md (17584b), SCHEMA.md (686b), skill-card.md (2570b), SKILL.md (8167b), tests/__init__.py (0b), tests/conftest.py (87b), tests/test_anti_detection.py (5241b), tests/test_cli.py (6032b), tests/test_client.py (2068b), tests/test_cookies.py (2912b), tests/test_creator_signing.py (2466b), tests/test_formatter.py (1262b), tests/test_integration.py (14644b), tests/test_signing.py (7806b), tests/test_smoke.py (2486b), xhs_cli/__init__.py (90b), xhs_cli/cli.py (3464b), xhs_cli/client.py (26528b), xhs_cli/commands/__init__.py (0b), xhs_cli/commands/_common.py (2683b), xhs_cli/commands/auth.py (3934b), xhs_cli/commands/creator.py (3055b), xhs_cli/commands/interactions.py (4311b), xhs_cli/commands/reading.py (11240b), xhs_cli/commands/social.py (2698b), xhs_cli/constants.py (605b), xhs_cli/cookies.py (6963b), xhs_cli/creator_signing.py (1806b), xhs_cli/exceptions.py (1976b), xhs_cli/formatter.py (16974b), xhs_cli/signing.py (23949b), _meta.json (134b)\n\nFile v0.2.1:SKILL.md\n\n---\nname: xiaohongshu-cli\ndescription: 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.\nauthor: jackwener\nversion: \"1.0.0\"\ntags:\n  - xiaohongshu\n  - xhs\n  - redbook\n  - 小红书\n  - social-media\n  - cli\n---\n\n# xiaohongshu-cli — Xiaohongshu CLI Tool\n\n**Binary:** `xhs`\n**Credentials:** browser cookies (auto-extracted via `--cookie-source`)\n\n## Setup\n\n```bash\n# Install (requires Python 3.10+)\nuv tool install xiaohongshu-cli\n# Or: pipx install xiaohongshu-cli\n```\n\n## Authentication\n\n**IMPORTANT FOR AGENTS**: Before executing ANY xhs command, check if credentials exist first. Do NOT assume cookies are configured.\n\n### Step 0: Check if already authenticated\n\n```bash\nxhs status --yaml >/dev/null && echo \"AUTH_OK\" || echo \"AUTH_NEEDED\"\n```\n\nIf `AUTH_OK`, skip to [Command Reference](#command-reference).\nIf `AUTH_NEEDED`, proceed to Step 1.\n\n### Step 1: Guide user to authenticate\n\nEnsure user is logged into xiaohongshu.com in one of: Chrome, Edge, Firefox, Safari, Brave. Then:\n\n```bash\nxhs login                              # auto-extract cookies\nxhs login --cookie-source firefox      # specify browser\n```\n\nVerify with:\n\n```bash\nxhs status\nxhs whoami\n```\n\n### Step 2: Handle common auth issues\n\n| Symptom | Agent action |\n|---------|-------------|\n| `NoCookieError: No 'a1' cookie found` | Guide user to login to xiaohongshu.com in browser |\n| `NeedVerifyError: Captcha required` | Ask user to open browser, complete captcha, then retry |\n| `IpBlockedError: IP blocked` | Suggest switching network (hotspot/VPN) |\n| `SessionExpiredError` | Run `xhs login` to refresh cookies |\n\n## Agent Defaults\n\nAll machine-readable output uses the envelope documented in [SCHEMA.md](./SCHEMA.md).\nPayloads live under `.data`.\n\n- Non-TTY stdout → auto YAML\n- `--json` / `--yaml` → explicit format\n- `OUTPUT=json` env → global override\n- `OUTPUT=rich` env → force human output\n\n## Command Reference\n\n### Reading\n\n| Command | Description | Example |\n|---------|-------------|---------|\n| `xhs search <keyword>` | Search notes | `xhs search \"美食\" --sort popular --type video` |\n| `xhs read <id_or_url>` | Read a note (URL auto-extracts xsec_token) | `xhs read \"https://...?xsec_token=xxx\"` |\n| `xhs comments <id_or_url>` | Get comments (xsec_token required — paste URL) | `xhs comments \"https://...?xsec_token=...\"` |\n| `xhs comments <id_or_url> --all` | Get ALL comments (auto-paginate) | `xhs comments \"<url>\" --all --json` |\n| `xhs sub-comments <note_id> <comment_id>` | Get replies to comment | `xhs sub-comments abc 123` |\n| `xhs user <user_id>` | View user profile | `xhs user 5f2e123` |\n| `xhs user-posts <user_id>` | List user's notes | `xhs user-posts 5f2e123 --cursor \"\"` |\n| `xhs feed` | Browse recommendation feed | `xhs feed --yaml` |\n| `xhs hot` | Browse trending notes | `xhs hot -c food` |\n| `xhs topics <keyword>` | Search topics/hashtags | `xhs topics \"旅行\"` |\n| `xhs search-user <keyword>` | Search users | `xhs search-user \"摄影\"` |\n| `xhs my-notes` | List own published notes | `xhs my-notes --page 0` |\n| `xhs notifications` | View notifications | `xhs notifications --type likes` |\n| `xhs unread` | Show unread counts | `xhs unread --json` |\n\n### Interactions (Write)\n\n| Command | Description | Example |\n|---------|-------------|---------|\n| `xhs like <id_or_url>` | Like a note | `xhs like abc123` |\n| `xhs like <id_or_url> --undo` | Unlike a note | `xhs like abc123 --undo` |\n| `xhs favorite <id_or_url>` | Bookmark a note | `xhs favorite abc123` |\n| `xhs unfavorite <id_or_url>` | Remove bookmark | `xhs unfavorite abc123` |\n| `xhs comment <id_or_url> -c \"text\"` | Post a comment | `xhs comment abc123 -c \"好看！\"` |\n| `xhs reply <id_or_url> --comment-id ID -c \"text\"` | Reply to comment | `xhs reply abc123 --comment-id 456 -c \"谢谢\"` |\n| `xhs delete-comment <note_id> <comment_id>` | Delete own comment | `xhs delete-comment abc 123 -y` |\n\n### Social\n\n| Command | Description | Example |\n|---------|-------------|---------|\n| `xhs follow <user_id>` | Follow a user | `xhs follow 5f2e123` |\n| `xhs unfollow <user_id>` | Unfollow a user | `xhs unfollow 5f2e123` |\n| `xhs favorites [user_id]` | List bookmarked notes (defaults to self) | `xhs favorites --json` |\n\n### Creator\n\n| Command | Description | Example |\n|---------|-------------|---------|\n| `xhs post --title \"...\" --body \"...\" --images img.png` | Publish a note | `xhs post --title \"Test\" --body \"Hello\"` |\n| `xhs delete <id_or_url>` | Delete own note | `xhs delete abc123 -y` |\n\n### Account\n\n| Command | Description |\n|---------|-------------|\n| `xhs login` | Verify and display cookie status |\n| `xhs status` | Check authentication status |\n| `xhs logout` | Clear cached cookies |\n| `xhs whoami` | Show current user profile |\n\n## Agent Workflow Examples\n\n### Search → Read → Like pipeline\n\n```bash\nNOTE_ID=$(xhs search \"美食推荐\" --json | jq -r '.data.items[0].id')\nxhs read \"$NOTE_ID\" --json | jq '.data'\nxhs like \"$NOTE_ID\"\n```\n\n### Browse trending food notes\n\n```bash\nxhs hot -c food --json | jq '.data.items[:5] | .[].note_card | {title, likes: .interact_info.liked_count}'\n```\n\n### Get user info then follow\n\n```bash\nxhs user 5f2e123 --json | jq '.data.basic_info | {nickname, user_id}'\nxhs follow 5f2e123\n```\n\n### Check notifications\n\n```bash\nxhs unread --json | jq '.data'\nxhs notifications --type mentions --json | jq '.data.message_list[:5]'\n```\n\n### Analyze all comments on a note\n\n```bash\n# Fetch ALL comments and analyze themes\nxhs comments \"$NOTE_URL\" --all --json | jq '.data.comments | length'\n# Count questions\nxhs comments \"$NOTE_URL\" --all --json | jq '[.data.comments[] | select(.content | test(\"[\\uff1f?]\"))] | length'\n```\n\n### Daily reading workflow\n\n```bash\n# Browse recommendation feed\nxhs feed --yaml\n\n# Browse trending by category\nxhs hot -c food --yaml\nxhs hot -c travel --yaml\n```\n\n### URL to insights pipeline\n\n```bash\n# User pastes a URL → read + all comments\nxhs read \"https://www.xiaohongshu.com/explore/xxx?xsec_token=yyy\" --json\nxhs comments \"https://www.xiaohongshu.com/explore/xxx?xsec_token=yyy\" --all --json\n```\n\n## Hot Categories\n\nAvailable for `xhs hot -c <category>`:\n`fashion`, `food`, `cosmetics`, `movie`, `career`, `love`, `home`, `gaming`, `travel`, `fitness`\n\n## Error Codes\n\nStructured error codes returned in the `error.code` field:\n- `not_authenticated` — cookies expired or missing\n- `verification_required` — captcha/verification needed\n- `ip_blocked` — IP rate limited\n- `signature_error` — request signing failed\n- `api_error` — upstream API error\n- `unsupported_operation` — operation not available\n\n## Limitations\n\n- **No video download** — cannot download note images/videos\n- **No DMs** — cannot access private messages\n- **No live streaming** — live features not supported\n- **No following/followers list** — XHS web API doesn't expose these endpoints\n- **Single account** — one set of cookies at a time\n- **Rate limited** — built-in Gaussian jitter delay (~1-1.5s) between requests; aggressive usage may trigger captchas or IP blocks\n\n## Anti-Detection Notes for Agents\n\n- **Do NOT parallelize requests** — the built-in rate-limit delay exists for account safety\n- **Captcha recovery**: if `NeedVerifyError` occurs, the client auto-cools-down with increasing delays (5s→10s→20s→30s). Ask the user to complete captcha in browser before retrying\n- **Batch operations**: when doing bulk work (e.g., reading many notes), add `time.sleep()` between CLI calls\n- **Session stability**: all requests in a session share a consistent browser fingerprint. Restarting the CLI creates a new fingerprint session\n\n## Safety Notes\n\n- Do not ask users to share raw cookie values in chat logs.\n- Prefer local browser cookie extraction over manual secret copy/paste.\n- If auth fails, ask the user to re-login via `xhs login`.\n- Agent should treat cookie values as secrets (do not echo to stdout unnecessarily).\n- Built-in rate-limit delay protects accounts; do not bypass it.\n\nFile v0.2.1:README.md\n\n# xiaohongshu-cli\n\n[![CI](https://github.com/jackwener/xiaohongshu-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/jackwener/xiaohongshu-cli/actions/workflows/ci.yml)\n[![Python](https://img.shields.io/badge/python-%3E%3D3.10-blue.svg)](https://pypi.org/project/xiaohongshu-cli/)\n\nA CLI for Xiaohongshu (小红书) — search, read, interact, and post via reverse-engineered API 📕\n\n[English](#features) | [中文](#功能特性)\n\n## More Tools\n\n- [bilibili-cli](https://github.com/jackwener/bilibili-cli) — Bilibili CLI for videos, users, search, and feeds\n- [twitter-cli](https://github.com/jackwener/twitter-cli) — Twitter/X CLI for timelines, bookmarks, and posting\n- [discord-cli](https://github.com/jackwener/discord-cli) — Discord CLI for local-first sync, search, and export\n- [tg-cli](https://github.com/jackwener/tg-cli) — Telegram CLI for local-first sync, search, and export\n\n## Features\n\n- 🔐 **Auth** — auto-extract browser cookies, status check, whoami\n- 🔍 **Search** — notes by keyword, user search, topic search\n- 📖 **Reading** — note detail, comments, sub-comments, user profiles\n- 📰 **Feed** — recommendation feed, hot/trending by category\n- 👥 **Social** — follow/unfollow, favorites\n- 👍 **Interactions** — like, favorite, comment, reply, delete\n- ✍️ **Creator** — post image notes, my-notes list, delete\n- 🔔 **Notifications** — unread count, mentions, likes, new followers\n- 🛡️ **Anti-detection** — consistent macOS Chrome fingerprint, `sec-ch-ua` alignment, session-stable browser identity, Gaussian jitter, captcha cooldown, exponential backoff\n- 📊 **Structured output** — commands support `--yaml` and `--json`; non-TTY stdout defaults to YAML\n- 📦 **Stable envelope** — see [SCHEMA.md](./SCHEMA.md) for `ok/schema_version/data/error`\n\n> **AI Agent Tip:** Prefer `--yaml` for structured output unless strict JSON is required. Non-TTY stdout defaults to YAML automatically.\n\n## Installation\n\n```bash\n# Recommended: uv tool (fast, isolated)\nuv tool install xiaohongshu-cli\n\n# Or: pipx\npipx install xiaohongshu-cli\n```\n\nFrom source:\n\n```bash\ngit clone git@github.com:jackwener/xiaohongshu-cli.git\ncd xiaohongshu-cli\nuv sync\n```\n\n## Usage\n\n```bash\n# ─── Auth ─────────────────────────────────────────\nxhs login                             # Extract cookies from browser\nxhs status                            # Check login status\nxhs whoami                            # Detailed profile (fans, likes, etc)\nxhs whoami --json                     # Structured JSON envelope\nxhs logout                            # Clear saved cookies\n\n# ─── Search ───────────────────────────────────────\nxhs search \"美食\"                      # Search notes\nxhs search \"旅行\" --sort popular       # Sort: general, popular, latest\nxhs search \"穿搭\" --type video         # Filter: all, video, image\nxhs search \"AI\" --page 2              # Pagination\nxhs search-user \"用户名\"               # Search users\nxhs topics \"美食\"                      # Search hashtags/topics\n\n# ─── Reading ──────────────────────────────────────\nxhs read <note_id>                     # Read a note\nxhs read \"https://www.xiaohongshu.com/explore/xxx?xsec_token=yyy\"  # Read by URL (auto-extracts xsec_token)\nxhs comments \"<url>\"                   # View comments — paste URL to auto-extract xsec_token\nxhs comments \"<url>\" --all             # Fetch ALL comments (auto-paginate all pages)\nxhs comments \"<url>\" --all --json      # All comments as JSON\nxhs comments <note_id> --xsec-token T  # Use note_id + explicit xsec_token\nxhs sub-comments <note_id> <cmt_id>   # View replies to a comment\nxhs user <user_id>                     # User profile\nxhs user-posts <user_id>              # User's published notes\nxhs user-posts <user_id> --cursor X   # Paginate with cursor\n\n# ─── Feed & Discovery ────────────────────────────\nxhs feed                              # Recommendation feed\nxhs hot                               # Hot notes (default: food)\nxhs hot -c fashion                    # Categories: fashion, food, cosmetics,\n                                      #   movie, career, love, home, gaming,\n                                      #   travel, fitness\n\n# ─── Social ───────────────────────────────────────\nxhs favorites                          # My bookmarked notes (current user)\nxhs favorites <user_id>                # Other user's bookmarked notes\nxhs follow <user_id>                   # Follow a user\nxhs unfollow <user_id>                 # Unfollow a user\n\n# ─── Interactions ─────────────────────────────────\nxhs like <note_id>                     # Like a note\nxhs like <note_id> --undo             # Unlike\nxhs favorite <note_id>                 # Favorite (bookmark)\nxhs unfavorite <note_id>               # Unfavorite\nxhs comment <note_id> -c \"好赞！\"     # Post comment\nxhs reply <note_id> --comment-id X -c \"回复\"  # Reply to comment\nxhs delete-comment <note_id> <cmt_id> # Delete own comment\n\n# ─── Creator ─────────────────────────────────────\nxhs my-notes                           # List own notes (v2 creator endpoint)\nxhs my-notes --page 1                 # Next page\nxhs post --title \"标题\" --body \"正文\" --images img.jpg  # Post note\nxhs delete <note_id>                   # Delete note\nxhs delete <note_id> -y               # Skip confirmation\n\n# ─── Notifications ────────────────────────────────\nxhs unread                             # Unread counts (likes, mentions, follows)\nxhs notifications                      # 评论和@ notifications\nxhs notifications --type likes        # 赞和收藏 notifications\nxhs notifications --type connections   # 新增关注 notifications\n```\n\n## Authentication\n\nxiaohongshu-cli uses a 2-tier authentication strategy:\n\n1. **Saved cookies** — loads from `~/.xiaohongshu-cli/cookies.json`\n2. **Browser cookies** — auto-extracts from Chrome, Firefox, Safari, Edge, Brave\n\n`xhs login` always refreshes cookies from the selected browser and overwrites the local cache.\nOther authenticated commands automatically retry once with fresh browser cookies when the saved session has expired.\n\nMost commands require authentication. Use `--cookie-source` to specify browser (default: chrome; also supports firefox, edge, safari, brave).\n\n### Cookie TTL\n\nSaved cookies are valid for **7 days** by default. After that, the client automatically attempts to refresh from the browser. If browser extraction fails, the existing cookies are used with a warning.\n\n## Environment Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `OUTPUT` | `auto` | Output format: `json`, `yaml`, `rich`, or `auto` (→ YAML when non-TTY) |\n\n## Rate Limiting & Anti-Detection\n\nxiaohongshu-cli includes comprehensive anti-risk-control measures designed to minimize detection:\n\n### Request Timing\n- **Gaussian jitter**: Delays between requests use a truncated Gaussian distribution (not fixed intervals) to mimic natural browsing patterns\n- **Random long pauses**: ~5% of requests include an additional 2-5 second delay simulating reading behavior\n- **Auto-retry**: Exponential backoff on HTTP 429/5xx and network errors (up to 3 retries)\n\n### Browser Fingerprint Consistency\n- **UA/Platform alignment**: User-Agent, `sec-ch-ua`, `sec-ch-ua-platform`, and fingerprint fields are all consistent (macOS Chrome)\n- **Session-stable identity**: GPU, screen resolution, CPU cores, and other hardware fingerprint values are generated once per session and reused across all requests (real browsers don't change hardware mid-session)\n- **macOS-native values**: GPU vendors (Apple M1/M2/M3, Intel Iris), Retina screen resolutions, `MacIntel` platform — all matching a real macOS browser\n\n### Captcha Cooldown\n- **Progressive backoff**: On captcha trigger (HTTP 461/471), automatically sleeps 5→10→20→30 seconds with increasing delays\n- **Adaptive rate limiting**: Request delay is permanently doubled after a captcha event to reduce future risk\n\n### Signed Requests\n- All API calls use `x-s` / `x-s-common` / `x-t` signatures (reverse-engineered from web client)\n- `x-b3-traceid` and `x-xray-traceid` for distributed tracing consistency\n\n## Structured Output\n\nAll `--json` / `--yaml` output uses the shared envelope from [SCHEMA.md](./SCHEMA.md):\n```yaml\nok: true\nschema_version: \"1\"\ndata: { ... }\n```\n\nWhen stdout is not a TTY (e.g., piped or invoked by an AI agent), output defaults to YAML.\nUse `OUTPUT=yaml|json|rich|auto` to override.\n\n## Use as AI Agent Skill\n\nxiaohongshu-cli ships with a [`SKILL.md`](./SKILL.md) that teaches AI agents how to use it.\n\n### Claude Code / Antigravity\n\n```bash\n# Clone into your project's skills directory\nmkdir -p .agents/skills\ngit clone git@github.com:jackwener/xiaohongshu-cli.git .agents/skills/xiaohongshu-cli\n\n# Or just copy the SKILL.md\ncurl -o .agents/skills/xiaohongshu-cli/SKILL.md \\\n  https://raw.githubusercontent.com/jackwener/xiaohongshu-cli/main/SKILL.md\n```\n\n### OpenClaw / ClawHub\n\n```bash\nclawhub install xiaohongshu-cli\n```\n\n## Project Structure\n\n```text\nxhs_cli/\n├── __init__.py\n├── cli.py              # Click entry point & command registration\n├── client.py           # XHS API client (signing, retry, rate-limit, anti-detection)\n├── cookies.py          # Cookie extraction, TTL management, auto-refresh\n├── signing.py          # Main API x-s / x-s-common signature generation\n├── creator_signing.py  # Creator API AES-128-CBC signature\n├── constants.py        # URLs, User-Agent, Chrome version, SDK config\n├── exceptions.py       # Structured exception hierarchy (6 error types)\n├── formatter.py        # Output formatting, schema envelope, Rich rendering\n└── commands/\n    ├── _common.py      # Shared CLI helpers (structured_output_options, etc.)\n    ├── auth.py         # login/logout/status/whoami\n    ├── reading.py      # search/read/comments/user/feed/hot/topics\n    ├── interactions.py  # like/favorite/comment/reply/delete-comment\n    ├── social.py       # follow/unfollow/favorites\n    ├── creator.py      # post/my-notes/delete\n    └── notifications.py # unread/notifications\n```\n\n## Development\n\n```bash\n# Install dependencies\nuv sync\n\n# Run tests\nuv run pytest tests/ -v\n\n# Unit tests only (no network)\nuv run pytest tests/ -v --ignore=tests/test_integration.py -m \"not smoke\"\n\n# Smoke tests (need cookies)\nuv run pytest tests/ -v -m smoke\n\n# Integration tests (need cookies)\nuv run pytest tests/test_integration.py -v\n\n# Lint\nuv run ruff check .\n```\n\n## Troubleshooting\n\n**Q: `NoCookieError: No 'a1' cookie found`**\n\n1. Open Chrome/Edge and visit https://www.xiaohongshu.com/\n2. Log in with your account\n3. Run `xhs login --cookie-source chrome`\n\n**Q: `NeedVerifyError: Captcha required`**\n\nXHS has triggered a captcha check. Open https://www.xiaohongshu.com/ in your browser, complete the captcha, then retry.\n\n**Q: `IpBlockedError: IP blocked by XHS`**\n\nTry a different network (e.g., mobile hotspot or VPN). XHS blocks IPs that make too many requests.\n\n**Q: `SessionExpiredError: Session expired`**\n\nYour cookies have expired. Run `xhs login` to refresh.\n\n**Q: Requests are slow**\n\nThe built-in Gaussian jitter delay (~1-1.5s between requests) is intentional to mimic natural browsing and avoid triggering XHS's risk control. Aggressive request patterns may lead to captcha triggers or IP blocks.\n\n---\n\n## 推荐项目\n\n- [bilibili-cli](https://github.com/jackwener/bilibili-cli) — Bilibili 视频、用户、搜索与动态 CLI\n- [twitter-cli](https://github.com/jackwener/twitter-cli) — Twitter/X 时间线、书签和发推 CLI\n- [discord-cli](https://github.com/jackwener/discord-cli) — Discord 本地优先同步、检索与导出 CLI\n- [tg-cli](https://github.com/jackwener/tg-cli) — Telegram 本地优先同步、检索与导出 CLI\n\n## 功能特性\n\n- 🔐 **认证** — 自动提取浏览器 Cookie，状态检查，用户信息\n- 🔍 **搜索** — 按关键词搜索笔记、用户、话题\n- 📖 **阅读** — 笔记详情、评论、子评论、用户主页\n- 📰 **发现** — 推荐 Feed、按分类浏览热门\n- 👥 **社交** — 关注/取关、收藏夹\n- 👍 **互动** — 点赞、收藏、评论、回复、删除\n- ✍️ **创作者** — 发布图文笔记、我的笔记列表、删除\n- 🔔 **通知** — 未读数、@、点赞、新关注\n- 🛡️ **反风控** — macOS Chrome 指纹一致性、session 级浏览器身份持久化、高斯抖动延迟、验证码自动冷却、指数退避重试\n- 📊 **结构化输出** — `--yaml` / `--json`，非 TTY 默认输出 YAML\n- 📦 **稳定 envelope** — 参见 [SCHEMA.md](./SCHEMA.md)\n\n## 安装\n\n```bash\n# 推荐：uv tool（快速、隔离环境）\nuv tool install xiaohongshu-cli\n\n# 或者：pipx\npipx install xiaohongshu-cli\n```\n\n从源码安装：\n\n```bash\ngit clone git@github.com:jackwener/xiaohongshu-cli.git\ncd xiaohongshu-cli\nuv sync\n```\n\n## 使用示例\n\n```bash\n# 认证\nxhs login                             # 从浏览器提取 Cookie\nxhs status                            # 检查登录状态\nxhs whoami                            # 查看用户资料\nxhs logout                            # 清除缓存的 Cookie\n\n# 搜索\nxhs search \"美食\"                      # 搜索笔记\nxhs search \"旅行\" --sort popular       # 排序：general, popular, latest\nxhs search-user \"用户名\"               # 搜索用户\nxhs topics \"美食\"                      # 搜索话题\n\n# 阅读\nxhs read <note_id>                     # 阅读笔记\nxhs read \"https://...?xsec_token=...\"  # 粘贴网页 URL 直接阅读（自动提取 token）\nxhs comments \"<url>\"                   # 查看评论 — 粘贴 URL 自动提取 xsec_token\nxhs comments \"<url>\" --all             # 获取全部评论（自动翻页）\nxhs comments \"<url>\" --all --json      # 全部评论，JSON 格式\nxhs comments <note_id> --xsec-token T  # 用 note_id + 显式 xsec_token\nxhs sub-comments <note_id> <cmt_id>   # 查看评论的回复\nxhs user <user_id>                     # 用户主页\nxhs user-posts <user_id>              # 用户发布的笔记\n\n# 发现\nxhs feed                              # 推荐 Feed\nxhs hot -c food                       # 热门笔记（按分类）\nxhs hot -c travel                     # 分类: fashion, food, cosmetics, movie, career,\n                                      #       love, home, gaming, travel, fitness\n\n# 社交\nxhs favorites                          # 我的收藏（自动识别当前用户）\nxhs favorites <user_id>                # 其他用户的收藏\nxhs follow <user_id>                   # 关注\nxhs unfollow <user_id>                 # 取消关注\n\n# 互动\nxhs like <note_id>                     # 点赞\nxhs like <note_id> --undo              # 取消点赞\nxhs favorite <note_id>                 # 收藏\nxhs unfavorite <note_id>               # 取消收藏\nxhs comment <note_id> -c \"好棒！\"      # 发评论\nxhs reply <note_id> --comment-id X -c \"谢谢\"  # 回复评论\nxhs delete-comment <note_id> <cmt_id>  # 删除自己的评论\n\n# 创作者\nxhs my-notes                           # 我的笔记列表\nxhs post --title \"标题\" --body \"正文\" --images img.jpg  # 发布笔记\nxhs delete <note_id>                   # 删除笔记\nxhs delete <note_id> -y                # 跳过确认\n\n# 通知\nxhs unread                             # 未读数\nxhs notifications                      # 评论和 @ 通知\nxhs notifications --type likes         # 赞和收藏通知\nxhs notifications --type connections   # 新增关注通知\n```\n\n## 认证策略\n\nxiaohongshu-cli 采用两级认证策略：\n\n1. **已保存 Cookie** — 从 `~/.xiaohongshu-cli/cookies.json` 加载\n2. **浏览器 Cookie** — 自动从 Chrome、Firefox、Safari、Edge、Brave 提取\n\nCookie 保存后有效期 **7 天**，超时后自动尝试从浏览器刷新。\n\n`xhs login` 会强制从浏览器重新提取并覆盖本地缓存。其他需认证命令在 session 过期时会自动重试一次。\n\n## 常见问题\n\n- `NoCookieError: No 'a1' cookie found` — 请先在 Chrome/Edge 打开 https://www.xiaohongshu.com/ 并登录，然后执行 `xhs login`\n- `NeedVerifyError` — 触发了验证码，请到浏览器中完成验证后重试\n- `IpBlockedError` — IP 被限制，尝试切换网络（手机热点或 VPN）\n- `SessionExpiredError` — Cookie 过期，执行 `xhs login` 刷新\n- 请求较慢是正常的 — 内置高斯随机延迟（~1-1.5s）是为了模拟人类浏览行为，避免触发风控\n\n## 作为 AI Agent Skill 使用\n\nxiaohongshu-cli 自带 [`SKILL.md`](./SKILL.md)，让 AI Agent 能自动学习并使用本工具。\n\n### Claude Code / Antigravity\n\n```bash\nmkdir -p .agents/skills\ngit clone git@github.com:jackwener/xiaohongshu-cli.git .agents/skills/xiaohongshu-cli\n```\n\n### OpenClaw / ClawHub\n\n```bash\nclawhub install xiaohongshu-cli\n```\n\n## License\n\nApache-2.0\n\nFile v0.2.1:_meta.json\n\n{\n  \"ownerId\": \"kn757vsv03fbpevrxybjc424wh828377\",\n  \"slug\": \"xiaohongshu-cli\",\n  \"version\": \"0.2.1\",\n  \"publishedAt\": 1773162955955\n}\n\nFile v0.2.1:SCHEMA.md\n\n# Structured Output Schema\n\n`xiaohongshu-cli` uses a shared agent-friendly envelope for machine-readable output.\n\n## Success\n\n```yaml\nok: true\nschema_version: \"1\"\ndata: ...\n```\n\n## Error\n\n```yaml\nok: false\nschema_version: \"1\"\nerror:\n  code: not_authenticated\n  message: need login\n```\n\n## Notes\n\n- `--yaml` and `--json` both use this envelope\n- non-TTY stdout defaults to YAML\n- reading and search commands return their payload under `data`\n- `status` returns `data.authenticated` plus `data.user`\n- `whoami` returns `data.user`\n- common `error.code` values include `not_authenticated`, `verification_required`, `ip_blocked`, `signature_error`, `unsupported_operation`, and `api_error`\n\nFile v0.2.1:skill-card.md\n\n## Description:\n\nUse xiaohongshu-cli for Xiaohongshu operations including searching notes, reading content, browsing users, liking, collecting, commenting, following, and posting.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[jackwener](https://clawhub.ai/user/jackwener)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nExternal users and developers use this skill to let an agent operate the xiaohongshu-cli tool for Xiaohongshu reading, discovery, account interaction, and creator workflows. It is intended for authenticated CLI use with local browser cookies and structured YAML or JSON output.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill can use local browser-session cookies and perform authenticated Xiaohongshu actions.\n\nMitigation: Use a dedicated browser profile or test account, avoid sharing raw cookie values, and clear cached cookies with xhs logout when finished.\n\nRisk: Mutating commands can like, collect, comment, follow, post, or delete account content.\n\nMitigation: Review every mutating command before execution and require explicit user confirmation for account-changing actions.\n\nRisk: Aggressive or parallel requests may trigger captcha, rate limits, or IP blocks.\n\nMitigation: Do not parallelize requests; respect built-in delays and pause for browser captcha completion when verification is required.\n\nRisk: Integration tests and real API workflows may contact Xiaohongshu with live credentials.\n\nMitigation: Do not run integration tests casually; run only in an intentional test environment with credentials suitable for that purpose.\n\n## Reference(s):\n\n- [ClawHub skill page](https://clawhub.ai/jackwener/skills/xiaohongshu-cli)\n- [README](README.md)\n- [Structured Output Schema](SCHEMA.md)\n- [PyPI package](https://pypi.org/project/xiaohongshu-cli/)\n\n## Skill Output:\n\n**Output Type(s):** [Text, Markdown, Shell commands, Configuration, Guidance]\n\n**Output Format:** [Markdown guidance with inline shell commands; CLI results are YAML or JSON envelopes.]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Uses local browser-cookie authentication and may trigger authenticated account actions.]\n\n## Skill Version(s):\n\n0.2.1 (source: ClawHub release metadata and pyproject.toml)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v0.2.1:pyproject.toml\n\n[build-system]\nrequires = [\"hatchling\"]\nbuild-backend = \"hatchling.build\"\n\n[project]\nname = \"xiaohongshu-cli\"\nversion = \"0.2.1\"\ndescription = \"A CLI for Xiaohongshu (Red) — search, read, interact via reverse-engineered API\"\nreadme = \"README.md\"\nlicense = \"Apache-2.0\"\nrequires-python = \">=3.10\"\nauthors = [{ name = \"jackwener\", email = \"jakevingoo@gmail.com\" }]\nkeywords = [\"xiaohongshu\", \"xhs\", \"redbook\", \"cli\", \"api\"]\nclassifiers = [\n    \"Development Status :: 3 - Alpha\",\n    \"Environment :: Console\",\n    \"License :: OSI Approved :: Apache Software License\",\n    \"Programming Language :: Python :: 3\",\n    \"Topic :: Utilities\",\n]\ndependencies = [\n    \"httpx>=0.27\",\n    \"click>=8.0\",\n    \"rich>=13.0\",\n    \"browser-cookie3>=0.19\",\n    \"pycryptodome>=3.20\",\n    \"PyYAML>=6.0\",\n]\n\n[project.optional-dependencies]\ndev = [\"pytest>=8.0\", \"pytest-asyncio>=0.23\", \"ruff>=0.11.0\", \"mypy>=1.15.0\"]\n\n[project.urls]\nHomepage = \"https://github.com/jackwener/xiaohongshu-cli\"\nRepository = \"https://github.com/jackwener/xiaohongshu-cli\"\nIssues = \"https://github.com/jackwener/xiaohongshu-cli/issues\"\n\n[project.scripts]\nxhs = \"xhs_cli.cli:cli\"\n\n[tool.hatch.build.targets.wheel]\npackages = [\"xhs_cli\"]\n\n[tool.ruff]\ntarget-version = \"py310\"\nline-length = 120\n\n[tool.ruff.lint]\nselect = [\"E\", \"F\", \"I\", \"B\", \"UP\"]\n\n[tool.mypy]\npython_version = \"3.10\"\nignore_missing_imports = true\ncheck_untyped_defs = true\n\n[tool.pytest.ini_options]\ntestpaths = [\"tests\"]\npython_files = [\"test_*.py\"]\naddopts = \"-m 'not smoke'\"\nmarkers = [\"smoke: real-API integration tests (run with: pytest -m smoke)\"]\n\nArchive v0.1.4: 17 files, 48441 bytes\n\nFiles: CHANGELOG.md (1725b), pyproject.toml (1760b), README_EN.md (7298b), README.md (7103b), scripts/smoke_local.sh (2092b), SKILL.md (4131b), tests/conftest.py (940b), tests/test_auth.py (6677b), tests/test_cli.py (11987b), tests/test_client.py (5857b), tests/test_integration.py (10138b), xhs_cli/__init__.py (72b), xhs_cli/auth.py (24773b), xhs_cli/cli.py (38860b), xhs_cli/client.py (55575b), xhs_cli/exceptions.py (315b), _meta.json (134b)\n\nFile v0.1.4:SKILL.md\n\n---\nname: xhs-cli\ndescription: CLI skill for Xiaohongshu (小红书, RedNote, XHS) to search notes, read posts, browse profiles, like, favorite, comment, and publish from the terminal\nauthor: jackwener\nversion: \"1.0.0\"\ntags:\n  - xhs\n  - xiaohongshu\n  - 小红书\n  - rednote\n  - social-media\n  - cli\n---\n\n# xhs-cli Skill\n\nA CLI tool for interacting with Xiaohongshu (小红书). Use it to search notes, read details, browse user profiles, and perform interactions like liking, favoriting, and commenting.\n\n## Prerequisites\n\n```bash\n# Install (requires Python 3.8+)\nuv tool install xhs-cli\n# Or: pipx install xhs-cli\n```\n\n## Authentication\n\nAll commands require valid cookies to function.\n\n```bash\nxhs status                     # Check saved login session (no browser extraction)\nxhs login                      # Auto-extract Chrome cookies\nxhs login --cookie \"a1=...\"    # Or provide cookies manually\n```\n\nAuthentication first uses saved local cookies. If unavailable, it auto-detects local Chrome cookies via browser-cookie3. If extraction fails, QR code login is available.\n\n## Command Reference\n\n### Search\n\n```bash\nxhs search \"咖啡\"              # Search notes (rich table output)\nxhs search \"咖啡\" --json       # Raw JSON output\n```\n\n### Read Note\n\n```bash\n# View note (xsec_token auto-resolved from search cache)\nxhs read <note_id>\nxhs read <note_id> --comments  # Include comments\nxhs read <note_id> --xsec-token <token>  # Manual token\nxhs read <note_id> --json\n```\n\n### User\n\n```bash\n# Look up user profile (by internal user_id, hex format)\nxhs user <user_id>\nxhs user <user_id> --json\n\n# List user's published notes\nxhs user-posts <user_id>\nxhs user-posts <user_id> --json\n\n# Followers / Following\nxhs followers <user_id>\nxhs following <user_id>\n```\n\n### Discovery\n\n```bash\nxhs feed                       # Explore page recommended feed\nxhs feed --json\nxhs topics \"旅行\"              # Search topics/hashtags\nxhs topics \"旅行\" --json\n```\n\n### Interactions (require login)\n\n```bash\n# Like / Unlike (xsec_token auto-resolved)\nxhs like <note_id>\nxhs like <note_id> --undo\n\n# Favorite / Unfavorite\nxhs favorite <note_id>\nxhs favorite <note_id> --undo\n\n# Comment\nxhs comment <note_id> \"好棒！\"\n\n# Delete your own note\nxhs delete <note_id>\n```\n\n### Favorites\n\n```bash\nxhs favorites                  # List your favorites\nxhs favorites --max 10         # Limit count\nxhs favorites --json\n```\n\n### Post\n\n```bash\nxhs post \"标题\" --image photo1.jpg --image photo2.jpg --content \"正文\"\nxhs post \"标题\" --image photo1.jpg --content \"正文\" --json\n```\n\n### Account\n\n```bash\nxhs status                     # Quick saved-session check\nxhs whoami                     # Full profile info\nxhs whoami --json\nxhs login                      # Login\nxhs logout                     # Clear cookies\n```\n\n## JSON Output\n\nMajor query commands support `--json` for machine-readable output:\n\n```bash\nxhs search \"咖啡\" --json | jq '.[0].id'           # First note ID\nxhs whoami --json | jq '.userInfo.userId'          # Your user ID\nxhs favorites --json | jq '.[0].displayTitle'      # First favorite title\n```\n\n## Common Patterns for AI Agents\n\n```bash\n# Get your user ID for further queries\nxhs whoami --json | python3 -c \"import sys,json; d=json.load(sys.stdin); print(d.get('userInfo',{}).get('userId',''))\"\n\n# Search and get note IDs (xsec_token auto-cached for later use)\nxhs search \"topic\" --json | python3 -c \"import sys,json; [print(n['id']) for n in json.load(sys.stdin)[:3]]\"\n\n# Check login before performing actions\nxhs status && xhs like <note_id>\n\n# Read a note with comments for summarization\nxhs read <note_id> --comments --json\n```\n\n## Error Handling\n\n- Commands exit with code 0 on success, non-zero on failure\n- Error messages are prefixed with ❌\n- Login-required commands show clear instruction to run `xhs login`\n- `xsec_token` is auto-resolved from cache; manual `--xsec-token` available as fallback\n\n## Safety Notes\n\n- Do not ask users to share raw cookie values in chat logs.\n- Prefer auto-extraction via `xhs login` over manual cookie input.\n- If auth fails, ask the user to re-login via `xhs login`.\n\nFile v0.1.4:README.md\n\n# xhs-cli\n\n**中文** | [English](README_EN.md)\n\n[![PyPI](https://img.shields.io/pypi/v/xhs-cli)](https://pypi.org/project/xhs-cli/)\n[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)\n\n小红书命令行工具 — 在终端中搜索笔记、查看主页、点赞、收藏、评论。\n\n## 推荐项目\n\n- [twitter-cli](https://github.com/jackwener/twitter-cli) - 在终端中操作 X/Twitter 的 CLI 工具\n- [bilibili-cli](https://github.com/jackwener/bilibili-cli) - 哔哩哔哩 CLI 工具\n\n## 功能\n\n- **搜索** — 按关键词搜索笔记，Rich 表格展示\n- **阅读** — 查看笔记内容、数据、评论\n- **用户资料** — 查看用户信息、笔记、粉丝、关注\n- **推荐 Feed** — 获取探索页推荐内容\n- **话题** — 搜索话题标签\n- **互动** — 点赞/取消、收藏/取消、评论、删除笔记\n- **发布** — 发布图文笔记\n- **认证** — 自动提取 Chrome cookie，或扫码登录（终端二维码渲染）\n- **JSON 输出** — 所有数据命令支持 `--json`\n- **Token 自动缓存** — `xsec_token` 搜索后自动缓存，后续命令免手动传\n\n## 命令一览\n\n| 分类 | 命令 | 说明 |\n|------|------|------|\n| Auth | `login`, `logout`, `status`, `whoami` | 登录、退出、状态检查、查看个人资料 |\n| Read | `search`, `read`, `feed`, `topics` | 搜索笔记、阅读详情、推荐 Feed、搜索话题 |\n| Users | `user`, `user-posts`, `followers`, `following` | 查看资料、列出笔记/粉丝/关注 |\n| Engage | `like`, `unlike`, `comment`, `delete` | 点赞、取消点赞、评论、删除笔记 |\n| Favorites | `favorite`, `unfavorite`, `favorites` | 收藏、取消收藏、查看收藏列表 |\n| Post | `post` | 发布图文笔记 |\n\n> 所有数据命令支持 `--json` 输出。`xsec_token` 自动缓存，无需手动传递。\n\n## 安装\n\n需要 Python 3.8+。\n\n```bash\n# 推荐：使用 uv\nuv tool install xhs-cli\n\n# 或使用 pipx\npipx install xhs-cli\n```\n\n<details>\n<summary>从源码安装（开发用）</summary>\n\n```bash\ngit clone git@github.com:jackwener/xhs-cli.git\ncd xhs-cli\nuv sync\n```\n\n</details>\n\n## 本地一键冒烟测试\n\n在本地已登录（有 `~/.xhs-cli/cookies.json`）的情况下，直接运行：\n\n```bash\n./scripts/smoke_local.sh\n```\n\n可选地传递 pytest 参数（例如只跑某个用例）：\n\n```bash\n./scripts/smoke_local.sh -k whoami\n```\n\n默认只跑无副作用命令（`integration and not live_mutation`）。如需额外验证\n`like/favorite/comment/post/delete`，显式开启：\n\n```bash\nXHS_SMOKE_MUTATION=1 ./scripts/smoke_local.sh\n```\n\n可选环境变量：\n\n```bash\nXHS_SMOKE_COMMENT_TEXT=\"smoke test comment\"\nXHS_SMOKE_POST_IMAGES=\"/abs/a.jpg,/abs/b.jpg\"\nXHS_SMOKE_POST_TITLE=\"smoke title\"\nXHS_SMOKE_POST_CONTENT=\"smoke content\"\n```\n\n## 使用\n\n### 登录\n\n```bash\n# 自动从 Chrome 提取 cookie（推荐）\nxhs login\n\n# 强制使用二维码登录（用于排查登录问题）\nxhs login --qrcode\n\n# 手动提供 cookie 字符串（至少包含 a1 和 web_session）\nxhs login --cookie \"a1=xxx; web_session=yyy\"\n\n# 快速检查已保存的登录状态（不启动浏览器，不读取浏览器 cookie）\nxhs status\n\n# 查看个人资料\nxhs whoami\nxhs whoami --json\n\n# 退出登录\nxhs logout\n```\n\n### 搜索\n\n```bash\nxhs search \"咖啡\"\nxhs search \"咖啡\" --json\n```\n\n### 阅读笔记\n\n```bash\n# 查看笔记（xsec_token 从缓存自动解析）\nxhs read <note_id>\n\n# 包含评论\nxhs read <note_id> --comments\n\n# 手动指定 xsec_token\nxhs read <note_id> --xsec-token <token>\n```\n\n### 用户\n\n```bash\n# 查看用户资料（使用内部 user_id，非小红书号）\nxhs user <user_id>\n\n# 列出用户笔记\nxhs user-posts <user_id>\n\n# 粉丝 / 关注\nxhs followers <user_id>\nxhs following <user_id>\n```\n\n### 推荐 & 话题\n\n```bash\nxhs feed\nxhs topics \"旅行\"\n```\n\n### 互动\n\n```bash\n# 点赞 / 取消（xsec_token 自动解析）\nxhs like <note_id>\nxhs like <note_id> --undo\n\n# 收藏 / 取消\nxhs favorite <note_id>\nxhs favorite <note_id> --undo\n\n# 评论\nxhs comment <note_id> \"好棒！\"\n\n# 删除自己的笔记\nxhs delete <note_id>\n\n# 查看收藏列表\nxhs favorites\nxhs favorites --max 10\n```\n\n### 发布笔记\n\n```bash\nxhs post \"标题\" --image photo1.jpg --image photo2.jpg --content \"正文内容\"\nxhs post \"标题\" --image photo1.jpg --content \"正文内容\" --json\n```\n\n### 其他\n\n```bash\nxhs --version\nxhs -v search \"咖啡\"   # 调试日志\nxhs --help\n```\n\n## 架构\n\n```\nCLI (click) → XhsClient (camoufox 浏览器)\n                  ↓ 导航到真实页面\n              window.__INITIAL_STATE__ → 提取结构化数据\n```\n\n使用 [camoufox](https://github.com/daijro/camoufox)（反指纹 Firefox）像真实用户一样浏览小红书。数据从页面的 `window.__INITIAL_STATE__` 中提取，与正常浏览完全一致。\n\n## 工作原理\n\n1. **认证** — 优先读取 `~/.xhs-cli/cookies.json`；未命中时通过 browser-cookie3 从本地 Chrome 提取 cookie，失败则 fallback 到扫码登录（终端半块字符二维码，`▀ ▄ █`）。\n2. **登录态校验** — 登录后会校验会话是否为有效非 guest 会话，并做 feed/search 可用性探活；探活失败会提示重新登录。\n3. **浏览** — 使用 camoufox 导航到真实页面，所有流量与正常用户浏览一致。\n4. **数据提取** — 从 `window.__INITIAL_STATE__` 提取结构化数据。\n5. **Token 缓存** — 搜索/Feed 后 `xsec_token` 自动缓存到 `~/.xhs-cli/token_cache.json`。\n6. **互动操作** — 点赞、收藏、评论通过点击真实 DOM 按钮实现。\n\n## 作为 AI Agent Skill 使用\n\nxhs-cli 自带 [`SKILL.md`](./SKILL.md)，让 AI Agent 能自动学习并使用本工具。\n\n### Claude Code / Antigravity\n\n```bash\n# 克隆到项目的 skills 目录\nmkdir -p .agents/skills\ngit clone git@github.com:jackwener/xhs-cli.git .agents/skills/xhs-cli\n\n# 或者只复制 SKILL.md\ncurl -o .agents/skills/xhs-cli/SKILL.md \\\n  https://raw.githubusercontent.com/jackwener/xhs-cli/main/SKILL.md\n```\n\n添加后，支持 `.agents/skills/` 的 AI Agent 会自动发现并使用 xhs-cli 命令。\n\n### OpenClaw / ClawHub\n\n官方支持 [OpenClaw](https://openclaw.ai) 和 [ClawHub](https://docs.openclaw.ai/tools/clawhub) 生态。通过 ClawHub 安装：\n\n```bash\nclawhub install xiaohongshu-cli\n```\n\n安装后即可在 OpenClaw 中直接使用所有 xhs-cli 命令。\n\n## 注意事项\n\n- Cookie 存储在 `~/.xhs-cli/cookies.json`，权限 `0600`。\n- `xhs status` 只检查本地已保存 cookie，不会触发浏览器 cookie 提取。\n- `xhs login --cookie` 要求 cookie 至少包含 `a1` 和 `web_session`。\n- 登录后会自动做可用性探活；若会话仍为 guest/风控受限，会提示重新登录。\n- `xhs post` 可能要求额外登录创作平台（`https://creator.xiaohongshu.com`）。\n- 使用 headless Firefox，不会弹出浏览器窗口。\n- 首次运行需下载 camoufox 浏览器（`python -m camoufox fetch`）。\n- 用户资料查询需要内部 user_id（十六进制），不是小红书号。\n\n## License\n\nApache License 2.0\n\nFile v0.1.4:_meta.json\n\n{\n  \"ownerId\": \"kn757vsv03fbpevrxybjc424wh828377\",\n  \"slug\": \"xiaohongshu-cli\",\n  \"version\": \"0.1.4\",\n  \"publishedAt\": 1772993810706\n}\n\nFile v0.1.4:CHANGELOG.md\n\n# Changelog\n\nAll notable changes to this project will be documented in this file.\n\n## v0.1.2 - 2026-03-06\n\n### Added\n\n- Added terminal QR rendering with half-block characters (`▀`, `▄`, `█`) for QR login.\n- Added post-login session usability probing (feed/search) to detect limited/guest sessions.\n- Added stricter and broader test coverage for auth, CLI login flows, and publish heuristics.\n- Added `qrcode` dependency for terminal QR rendering.\n\n### Changed\n\n- Strengthened cookie requirements for saved/manual auth:\n  - Required cookies are now `a1` + `web_session`.\n- Improved QR login robustness:\n  - Force switch to QR login tab when possible.\n  - Better QR payload extraction heuristics to avoid homepage/logo false matches.\n  - Better QR fallback element selection for screenshots.\n- Improved login success detection:\n  - Treat guest sessions as invalid.\n  - Accept non-guest page state as a login success signal (not only session cookie change).\n- Improved operation reliability:\n  - Tightened success criteria for publish/comment/delete flows.\n  - Added strict data-wait timeout path to reduce silent empty results.\n- Updated `whoami --json` to include normalized top-level fields when resolvable.\n- Updated docs (`README.md` and `README_EN.md`) to match current login/auth behavior.\n\n### Fixed\n\n- Fixed transient cookie verification flow to avoid unintended QR login fallback.\n- Fixed favorites note ID extraction regex to support alphanumeric note IDs.\n- Fixed cross-platform cookie save behavior by handling `chmod` failures safely.\n- Fixed multiple false-positive success cases in interaction and publish flows.\n\n### Validation\n\n- `ruff check .` passes.\n- `pytest -q` passes (`66 passed, 21 deselected`).\n\nFile v0.1.4:README_EN.md\n\n# xhs-cli\n\n[中文](README.md) | **English**\n\n[![PyPI](https://img.shields.io/pypi/v/xhs-cli)](https://pypi.org/project/xhs-cli/)\n[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)\n\nA command-line tool for [Xiaohongshu (小红书)](https://www.xiaohongshu.com) — search notes, view profiles, like, favorite, and comment, all from your terminal.\n\n## Recommended Projects\n\n- [twitter-cli](https://github.com/jackwener/twitter-cli) - A CLI tool for X/Twitter workflows\n- [bilibili-cli](https://github.com/jackwener/bilibili-cli) - A CLI tool for Bilibili workflows\n\n## Features\n\n- **Search** — search notes by keyword with rich table output\n- **Read** — view note content, stats, and comments\n- **User Profile** — view user info, posts, followers, following\n- **Feed** — get recommended content from explore page\n- **Topics** — search for topics and hashtags\n- **Engage** — like/unlike, favorite/unfavorite, comment, delete\n- **Post** — publish image notes\n- **Auth** — auto-extract cookies from Chrome, or login via QR code (terminal-rendered)\n- **JSON output** — `--json` flag for all data commands\n- **Auto token** — `xsec_token` is cached and auto-resolved\n\n## Commands\n\n| Category | Commands | Description |\n|----------|----------|-------------|\n| Auth | `login`, `logout`, `status`, `whoami` | Login, logout, check status, view profile |\n| Read | `search`, `read`, `feed`, `topics` | Search notes, read details, explore feed, find topics |\n| Users | `user`, `user-posts`, `followers`, `following` | View profile, list posts/followers/following |\n| Engage | `like`, `unlike`, `comment`, `delete` | Like, unlike, comment, delete notes |\n| Favorites | `favorite`, `unfavorite`, `favorites` | Favorite, unfavorite, list all favorites |\n| Post | `post` | Publish a new image note |\n\n> All data commands support `--json` for raw JSON output. `xsec_token` is auto-cached and auto-resolved.\n\n## Installation\n\nRequires Python 3.8+.\n\n```bash\n# Recommended: using uv\nuv tool install xhs-cli\n\n# Or using pipx\npipx install xhs-cli\n```\n\n<details>\n<summary>Install from source (for development)</summary>\n\n```bash\ngit clone git@github.com:jackwener/xhs-cli.git\ncd xhs-cli\nuv sync\n```\n\n</details>\n\n## One-Command Local Smoke Test\n\nWith a valid saved session (`~/.xhs-cli/cookies.json`), run:\n\n```bash\n./scripts/smoke_local.sh\n```\n\nYou can pass extra pytest arguments, for example:\n\n```bash\n./scripts/smoke_local.sh -k whoami\n```\n\nBy default, only non-mutating smoke is executed\n(`integration and not live_mutation`). To also verify\n`like/favorite/comment/post/delete`, opt in explicitly:\n\n```bash\nXHS_SMOKE_MUTATION=1 ./scripts/smoke_local.sh\n```\n\nOptional environment variables:\n\n```bash\nXHS_SMOKE_COMMENT_TEXT=\"smoke test comment\"\nXHS_SMOKE_POST_IMAGES=\"/abs/a.jpg,/abs/b.jpg\"\nXHS_SMOKE_POST_TITLE=\"smoke title\"\nXHS_SMOKE_POST_CONTENT=\"smoke content\"\n```\n\n## Usage\n\n### Login\n\n```bash\n# Auto-extract cookies from Chrome (recommended)\nxhs login\n\n# Force QR code login (useful for troubleshooting auth)\nxhs login --qrcode\n\n# Or provide cookie string manually (must include a1 and web_session)\nxhs login --cookie \"a1=xxx; web_session=yyy\"\n\n# Quick check for saved login session\n# (no browser needed, no browser-cookie extraction)\nxhs status\n\n# Show profile info\nxhs whoami\nxhs whoami --json\n\n# Logout\nxhs logout\n```\n\n### Search\n\n```bash\nxhs search \"咖啡\"\nxhs search \"咖啡\" --json\n```\n\n### Read Note\n\n```bash\n# View note (xsec_token auto-resolved from cache)\nxhs read <note_id>\n\n# Include comments\nxhs read <note_id> --comments\n\n# Provide xsec_token manually if needed\nxhs read <note_id> --xsec-token <token>\n```\n\n### User\n\n```bash\n# View user profile (uses internal user_id, not Red ID)\nxhs user <user_id>\n\n# List user's published notes\nxhs user-posts <user_id>\n\n# Followers / following\nxhs followers <user_id>\nxhs following <user_id>\n```\n\n### Feed & Topics\n\n```bash\nxhs feed\nxhs topics \"travel\"\n```\n\n### Interactions\n\n```bash\n# Like / Unlike (xsec_token auto-resolved)\nxhs like <note_id>\nxhs like <note_id> --undo\n\n# Favorite / Unfavorite\nxhs favorite <note_id>\nxhs favorite <note_id> --undo\n\n# Comment\nxhs comment <note_id> \"nice post!\"\n\n# Delete your own note\nxhs delete <note_id>\n\n# List your favorites\nxhs favorites\nxhs favorites --max 10\n```\n\n### Post\n\n```bash\nxhs post \"Title\" --image photo1.jpg --image photo2.jpg --content \"Body text\"\nxhs post \"Title\" --image photo1.jpg --content \"Body text\" --json\n```\n\n### Other\n\n```bash\nxhs --version\nxhs -v search \"咖啡\"   # debug logging\nxhs --help\n```\n\n## Architecture\n\n```\nCLI (click) → XhsClient (camoufox browser)\n                  ↓ navigate to real pages\n              window.__INITIAL_STATE__ → extract structured data\n```\n\nUses [camoufox](https://github.com/daijro/camoufox) (anti-fingerprint Firefox) to browse Xiaohongshu like a real user. Data is extracted from `window.__INITIAL_STATE__` — completely indistinguishable from normal browsing.\n\n## How It Works\n\n1. **Authentication** — First reads `~/.xhs-cli/cookies.json`; if missing, extracts cookies from local Chrome via browser-cookie3. Falls back to QR code login if extraction fails (terminal half-block rendering with `▀ ▄ █`).\n2. **Session Validation** — After login, the CLI verifies that the session is non-guest and probes feed/search usability. If probe fails, it asks for re-login.\n3. **Browsing** — Each operation navigates to real pages using camoufox, making all traffic look like normal user browsing.\n4. **Data Extraction** — Structured data is pulled from `window.__INITIAL_STATE__`.\n5. **Token Caching** — After search/feed, `xsec_token` is auto-cached to `~/.xhs-cli/token_cache.json`.\n6. **Interactions** — Like, favorite, and comment work by clicking actual DOM buttons.\n\n## Use as AI Agent Skill\n\nxhs-cli ships with a [`SKILL.md`](./SKILL.md) that teaches AI agents how to use it.\n\n### Claude Code / Antigravity\n\n```bash\n# Clone into your project's skills directory\nmkdir -p .agents/skills\ngit clone git@github.com:jackwener/xhs-cli.git .agents/skills/xhs-cli\n\n# Or just copy the SKILL.md\ncurl -o .agents/skills/xhs-cli/SKILL.md \\\n  https://raw.githubusercontent.com/jackwener/xhs-cli/main/SKILL.md\n```\n\nOnce added, AI agents that support the `.agents/skills/` convention will automatically discover and use xhs-cli commands.\n\n### OpenClaw / ClawHub\n\nOfficially supports [OpenClaw](https://openclaw.ai) and [ClawHub](https://docs.openclaw.ai/tools/clawhub). Install via ClawHub:\n\n```bash\nclawhub install xiaohongshu-cli\n```\n\nAll xhs-cli commands are available in OpenClaw after installation.\n\n## Notes\n\n- Cookies are stored in `~/.xhs-cli/cookies.json` with `0600` permissions.\n- `xhs status` checks saved local cookies only and never triggers browser extraction.\n- `xhs login --cookie` requires at least `a1` and `web_session`.\n- Login runs a usability probe; guest/risk-limited sessions are treated as invalid and require re-login.\n- `xhs post` may require an extra creator-platform login at `https://creator.xiaohongshu.com`.\n- Uses headless Firefox via camoufox — no browser window is shown.\n- First run requires downloading the camoufox browser (`python -m camoufox fetch`).\n- User profile lookup requires the internal user_id (hex format), not the Red ID.\n\n## License\n\nApache License 2.0\n\nFile v0.1.4:pyproject.toml\n\n[build-system]\nrequires = [\"hatchling\"]\nbuild-backend = \"hatchling.build\"\n\n[project]\nname = \"xhs-cli\"\nversion = \"0.1.3\"\ndescription = \"A CLI for Xiaohongshu (小红书) — search, read notes, view profiles\"\nreadme = \"README.md\"\nlicense = { file = \"LICENSE\" }\nrequires-python = \">=3.8\"\nauthors = [{ name = \"jackwener\", email = \"jakevingoo@gmail.com\" }]\nkeywords = [\"xiaohongshu\", \"xhs\", \"cli\", \"redbook\", \"小红书\"]\nclassifiers = [\n    \"Development Status :: 3 - Alpha\",\n    \"Environment :: Console\",\n    \"Intended Audience :: Developers\",\n    \"License :: OSI Approved :: Apache Software License\",\n    \"Programming Language :: Python :: 3\",\n    \"Programming Language :: Python :: 3.8\",\n    \"Programming Language :: Python :: 3.9\",\n    \"Programming Language :: Python :: 3.10\",\n    \"Programming Language :: Python :: 3.11\",\n    \"Programming Language :: Python :: 3.12\",\n    \"Programming Language :: Python :: 3.13\",\n    \"Topic :: Utilities\",\n]\ndependencies = [\n    \"camoufox[geoip]>=0.4\",\n    \"playwright>=1.40\",\n    \"browser-cookie3>=0.19\",\n    \"qrcode>=7.4\",\n    \"click>=8.0\",\n    \"rich>=13.0\",\n]\n\n[project.urls]\nHomepage = \"https://github.com/jackwener/xhs-cli\"\nRepository = \"https://github.com/jackwener/xhs-cli\"\nIssues = \"https://github.com/jackwener/xhs-cli/issues\"\n\n[project.scripts]\nxhs = \"xhs_cli.cli:cli\"\n\n[dependency-groups]\ndev = [\n    \"pytest>=8.3.5\",\n    \"ruff>=0.11.0\",\n]\n\n[tool.pytest.ini_options]\nmarkers = [\n    \"integration: requires valid login session (deselect with '-m \\\"not integration\\\"')\",\n    \"live_mutation: integration tests that may mutate account state (like/favorite/comment/post)\",\n]\naddopts = \"-m 'not integration'\"\n\n[tool.ruff]\nline-length = 100\ntarget-version = \"py38\"\n\n[tool.ruff.lint]\nselect = [\"E\", \"F\", \"I\", \"B\", \"UP\"]\n\nArchive v0.1.3: 17 files, 48260 bytes\n\nFiles: CHANGELOG.md (1725b), pyproject.toml (1760b), README_EN.md (7298b), README.md (7103b), scripts/smoke_local.sh (2092b), SKILL.md (3745b), tests/conftest.py (940b), tests/test_auth.py (6677b), tests/test_cli.py (11875b), tests/test_client.py (5857b), tests/test_integration.py (10138b), xhs_cli/__init__.py (72b), xhs_cli/auth.py (24773b), xhs_cli/cli.py (38860b), xhs_cli/client.py (55575b), xhs_cli/exceptions.py (315b), _meta.json (134b)\n\nFile v0.1.3:SKILL.md\n\n---\nname: xhs-cli\ndescription: Xiaohongshu (小红书) CLI — search, read, like, favorite, comment from the terminal\n---\n\n# xhs-cli Skill\n\nA CLI tool for interacting with Xiaohongshu (小红书). Use it to search notes, read details, browse user profiles, and perform interactions like liking, favoriting, and commenting.\n\n## Prerequisites\n\n```bash\n# Install (requires Python 3.8+)\nuv tool install xhs-cli\n# Or: pipx install xhs-cli\n```\n\n## Authentication\n\nAll commands require valid cookies to function.\n\n```bash\nxhs status                     # Check saved login session (no browser extraction)\nxhs login                      # Auto-extract Chrome cookies\nxhs login --cookie \"a1=...\"    # Or provide cookies manually\n```\n\nAuthentication first uses saved local cookies. If unavailable, it auto-detects local Chrome cookies via browser-cookie3. If extraction fails, QR code login is available.\n\n## Command Reference\n\n### Search\n\n```bash\nxhs search \"咖啡\"              # Search notes (rich table output)\nxhs search \"咖啡\" --json       # Raw JSON output\n```\n\n### Read Note\n\n```bash\n# View note (xsec_token auto-resolved from search cache)\nxhs read <note_id>\nxhs read <note_id> --comments  # Include comments\nxhs read <note_id> --xsec-token <token>  # Manual token\nxhs read <note_id> --json\n```\n\n### User\n\n```bash\n# Look up user profile (by internal user_id, hex format)\nxhs user <user_id>\nxhs user <user_id> --json\n\n# List user's published notes\nxhs user-posts <user_id>\nxhs user-posts <user_id> --json\n\n# Followers / Following\nxhs followers <user_id>\nxhs following <user_id>\n```\n\n### Discovery\n\n```bash\nxhs feed                       # Explore page recommended feed\nxhs feed --json\nxhs topics \"旅行\"              # Search topics/hashtags\nxhs topics \"旅行\" --json\n```\n\n### Interactions (require login)\n\n```bash\n# Like / Unlike (xsec_token auto-resolved)\nxhs like <note_id>\nxhs like <note_id> --undo\n\n# Favorite / Unfavorite\nxhs favorite <note_id>\nxhs favorite <note_id> --undo\n\n# Comment\nxhs comment <note_id> \"好棒！\"\n\n# Delete your own note\nxhs delete <note_id>\n```\n\n### Favorites\n\n```bash\nxhs favorites                  # List your favorites\nxhs favorites --max 10         # Limit count\nxhs favorites --json\n```\n\n### Post\n\n```bash\nxhs post \"标题\" --image photo1.jpg --image photo2.jpg --content \"正文\"\nxhs post \"标题\" --image photo1.jpg --content \"正文\" --json\n```\n\n### Account\n\n```bash\nxhs status                     # Quick saved-session check\nxhs whoami                     # Full profile info\nxhs whoami --json\nxhs login                      # Login\nxhs logout                     # Clear cookies\n```\n\n## JSON Output\n\nMajor query commands support `--json` for machine-readable output:\n\n```bash\nxhs search \"咖啡\" --json | jq '.[0].id'           # First note ID\nxhs whoami --json | jq '.userInfo.userId'          # Your user ID\nxhs favorites --json | jq '.[0].displayTitle'      # First favorite title\n```\n\n## Common Patterns for AI Agents\n\n```bash\n# Get your user ID for further queries\nxhs whoami --json | python3 -c \"import sys,json; d=json.load(sys.stdin); print(d.get('userInfo',{}).get('userId',''))\"\n\n# Search and get note IDs (xsec_token auto-cached for later use)\nxhs search \"topic\" --json | python3 -c \"import sys,json; [print(n['id']) for n in json.load(sys.stdin)[:3]]\"\n\n# Check login before performing actions\nxhs status && xhs like <note_id>\n\n# Read a note with comments for summarization\nxhs read <note_id> --comments --json\n```\n\n## Error Handling\n\n- Commands exit with code 0 on success, non-zero on failure\n- Error messages are prefixed with ❌\n- Login-required commands show clear instruction to run `xhs login`\n- `xsec_token` is auto-resolved from cache; manual `--xsec-token` available as fallback\n\nFile v0.1.3:README.md\n\n# xhs-cli\n\n**中文** | [English](README_EN.md)\n\n[![PyPI](https://img.shields.io/pypi/v/xhs-cli)](https://pypi.org/project/xhs-cli/)\n[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)\n\n小红书命令行工具 — 在终端中搜索笔记、查看主页、点赞、收藏、评论。\n\n## 推荐项目\n\n- [twitter-cli](https://github.com/jackwener/twitter-cli) - 在终端中操作 X/Twitter 的 CLI 工具\n- [bilibili-cli](https://github.com/jackwener/bilibili-cli) - 哔哩哔哩 CLI 工具\n\n## 功能\n\n- **搜索** — 按关键词搜索笔记，Rich 表格展示\n- **阅读** — 查看笔记内容、数据、评论\n- **用户资料** — 查看用户信息、笔记、粉丝、关注\n- **推荐 Feed** — 获取探索页推荐内容\n- **话题** — 搜索话题标签\n- **互动** — 点赞/取消、收藏/取消、评论、删除笔记\n- **发布** — 发布图文笔记\n- **认证** — 自动提取 Chrome cookie，或扫码登录（终端二维码渲染）\n- **JSON 输出** — 所有数据命令支持 `--json`\n- **Token 自动缓存** — `xsec_token` 搜索后自动缓存，后续命令免手动传\n\n## 命令一览\n\n| 分类 | 命令 | 说明 |\n|------|------|------|\n| Auth | `login`, `logout`, `status`, `whoami` | 登录、退出、状态检查、查看个人资料 |\n| Read | `search`, `read`, `feed`, `topics` | 搜索笔记、阅读详情、推荐 Feed、搜索话题 |\n| Users | `user`, `user-posts`, `followers`, `following` | 查看资料、列出笔记/粉丝/关注 |\n| Engage | `like`, `unlike`, `comment`, `delete` | 点赞、取消点赞、评论、删除笔记 |\n| Favorites | `favorite`, `unfavorite`, `favorites` | 收藏、取消收藏、查看收藏列表 |\n| Post | `post` | 发布图文笔记 |\n\n> 所有数据命令支持 `--json` 输出。`xsec_token` 自动缓存，无需手动传递。\n\n## 安装\n\n需要 Python 3.8+。\n\n```bash\n# 推荐：使用 uv\nuv tool install xhs-cli\n\n# 或使用 pipx\npipx install xhs-cli\n```\n\n<details>\n<summary>从源码安装（开发用）</summary>\n\n```bash\ngit clone git@github.com:jackwener/xhs-cli.git\ncd xhs-cli\nuv sync\n```\n\n</details>\n\n## 本地一键冒烟测试\n\n在本地已登录（有 `~/.xhs-cli/cookies.json`）的情况下，直接运行：\n\n```bash\n./scripts/smoke_local.sh\n```\n\n可选地传递 pytest 参数（例如只跑某个用例）：\n\n```bash\n./scripts/smoke_local.sh -k whoami\n```\n\n默认只跑无副作用命令（`integration and not live_mutation`）。如需额外验证\n`like/favorite/comment/post/delete`，显式开启：\n\n```bash\nXHS_SMOKE_MUTATION=1 ./scripts/smoke_local.sh\n```\n\n可选环境变量：\n\n```bash\nXHS_SMOKE_COMMENT_TEXT=\"smoke test comment\"\nXHS_SMOKE_POST_IMAGES=\"/abs/a.jpg,/abs/b.jpg\"\nXHS_SMOKE_POST_TITLE=\"smoke title\"\nXHS_SMOKE_POST_CONTENT=\"smoke content\"\n```\n\n## 使用\n\n### 登录\n\n```bash\n# 自动从 Chrome 提取 cookie（推荐）\nxhs login\n\n# 强制使用二维码登录（用于排查登录问题）\nxhs login --qrcode\n\n# 手动提供 cookie 字符串（至少包含 a1 和 web_session）\nxhs login --cookie \"a1=xxx; web_session=yyy\"\n\n# 快速检查已保存的登录状态（不启动浏览器，不读取浏览器 cookie）\nxhs status\n\n# 查看个人资料\nxhs whoami\nxhs whoami --json\n\n# 退出登录\nxhs logout\n```\n\n### 搜索\n\n```bash\nxhs search \"咖啡\"\nxhs search \"咖啡\" --json\n```\n\n### 阅读笔记\n\n```bash\n# 查看笔记（xsec_token 从缓存自动解析）\nxhs read <note_id>\n\n# 包含评论\nxhs read <note_id> --comments\n\n# 手动指定 xsec_token\nxhs read <note_id> --xsec-token <token>\n```\n\n### 用户\n\n```bash\n# 查看用户资料（使用内部 user_id，非小红书号）\nxhs user <user_id>\n\n# 列出用户笔记\nxhs user-posts <user_id>\n\n# 粉丝 / 关注\nxhs followers <user_id>\nxhs following <user_id>\n```\n\n### 推荐 & 话题\n\n```bash\nxhs feed\nxhs topics \"旅行\"\n```\n\n### 互动\n\n```bash\n# 点赞 / 取消（xsec_token 自动解析）\nxhs like <note_id>\nxhs like <note_id> --undo\n\n# 收藏 / 取消\nxhs favorite <note_id>\nxhs favorite <note_id> --undo\n\n# 评论\nxhs comment <note_id> \"好棒！\"\n\n# 删除自己的笔记\nxhs delete <note_id>\n\n# 查看收藏列表\nxhs favorites\nxhs favorites --max 10\n```\n\n### 发布笔记\n\n```bash\nxhs post \"标题\" --image photo1.jpg --image photo2.jpg --content \"正文内容\"\nxhs post \"标题\" --image photo1.jpg --content \"正文内容\" --json\n```\n\n### 其他\n\n```bash\nxhs --version\nxhs -v search \"咖啡\"   # 调试日志\nxhs --help\n```\n\n## 架构\n\n```\nCLI (click) → XhsClient (camoufox 浏览器)\n                  ↓ 导航到真实页面\n              window.__INITIAL_STATE__ → 提取结构化数据\n```\n\n使用 [camoufox](https://github.com/daijro/camoufox)（反指纹 Firefox）像真实用户一样浏览小红书。数据从页面的 `window.__INITIAL_STATE__` 中提取，与正常浏览完全一致。\n\n## 工作原理\n\n1. **认证** — 优先读取 `~/.xhs-cli/cookies.json`；未命中时通过 browser-cookie3 从本地 Chrome 提取 cookie，失败则 fallback 到扫码登录（终端半块字符二维码，`▀ ▄ █`）。\n2. **登录态校验** — 登录后会校验会话是否为有效非 guest 会话，并做 feed/search 可用性探活；探活失败会提示重新登录。\n3. **浏览** — 使用 camoufox 导航到真实页面，所有流量与正常用户浏览一致。\n4. **数据提取** — 从 `window.__INITIAL_STATE__` 提取结构化数据。\n5. **Token 缓存** — 搜索/Feed 后 `xsec_token` 自动缓存到 `~/.xhs-cli/token_cache.json`。\n6. **互动操作** — 点赞、收藏、评论通过点击真实 DOM 按钮实现。\n\n## 作为 AI Agent Skill 使用\n\nxhs-cli 自带 [`SKILL.md`](./SKILL.md)，让 AI Agent 能自动学习并使用本工具。\n\n### Claude Code / Antigravity\n\n```bash\n# 克隆到项目的 skills 目录\nmkdir -p .agents/skills\ngit clone git@github.com:jackwener/xhs-cli.git .agents/skills/xhs-cli\n\n# 或者只复制 SKILL.md\ncurl -o .agents/skills/xhs-cli/SKILL.md \\\n  https://raw.githubusercontent.com/jackwener/xhs-cli/main/SKILL.md\n```\n\n添加后，支持 `.agents/skills/` 的 AI Agent 会自动发现并使用 xhs-cli 命令。\n\n### OpenClaw / ClawHub\n\n官方支持 [OpenClaw](https://openclaw.ai) 和 [ClawHub](https://docs.openclaw.ai/tools/clawhub) 生态。通过 ClawHub 安装：\n\n```bash\nclawhub install xiaohongshu-cli\n```\n\n安装后即可在 OpenClaw 中直接使用所有 xhs-cli 命令。\n\n## 注意事项\n\n- Cookie 存储在 `~/.xhs-cli/cookies.json`，权限 `0600`。\n- `xhs status` 只检查本地已保存 cookie，不会触发浏览器 cookie 提取。\n- `xhs login --cookie` 要求 cookie 至少包含 `a1` 和 `web_session`。\n- 登录后会自动做可用性探活；若会话仍为 guest/风控受限，会提示重新登录。\n- `xhs post` 可能要求额外登录创作平台（`https://creator.xiaohongshu.com`）。\n- 使用 headless Firefox，不会弹出浏览器窗口。\n- 首次运行需下载 camoufox 浏览器（`python -m camoufox fetch`）。\n- 用户资料查询需要内部 user_id（十六进制），不是小红书号。\n\n## License\n\nApache License 2.0\n\nFile v0.1.3:_meta.json\n\n{\n  \"ownerId\": \"kn757vsv03fbpevrxybjc424wh828377\",\n  \"slug\": \"xiaohongshu-cli\",\n  \"version\": \"0.1.3\",\n  \"publishedAt\": 1772733553818\n}\n\nFile v0.1.3:CHANGELOG.md\n\n# Changelog\n\nAll notable changes to this project will be documented in this file.\n\n## v0.1.2 - 2026-03-06\n\n### Added\n\n- Added terminal QR rendering with half-block characters (`▀`, `▄`, `█`) for QR login.\n- Added post-login session usability probing (feed/search) to detect limited/guest sessions.\n- Added stricter and broader test coverage for auth, CLI login flows, and publish heuristics.\n- Added `qrcode` dependency for terminal QR rendering.\n\n### Changed\n\n- Strengthened cookie requirements for saved/manual auth:\n  - Required cookies are now `a1` + `web_session`.\n- Improved QR login robustness:\n  - Force switch to QR login tab when possible.\n  - Better QR payload extraction heuristics to avoid homepage/logo false matches.\n  - Better QR fallback element selection for screenshots.\n- Improved login success detection:\n  - Treat guest sessions as invalid.\n  - Accept non-guest page state as a login success signal (not only session cookie change).\n- Improved operation reliability:\n  - Tightened success criteria for publish/comment/delete flows.\n  - Added strict data-wait timeout path to reduce silent empty results.\n- Updated `whoami --json` to include normalized top-level fields when resolvable.\n- Updated docs (`README.md` and `README_EN.md`) to match current login/auth behavior.\n\n### Fixed\n\n- Fixed transient cookie verification flow to avoid unintended QR login fallback.\n- Fixed favorites note ID extraction regex to support alphanumeric note IDs.\n- Fixed cross-platform cookie save behavior by handling `chmod` failures safely.\n- Fixed multiple false-positive success cases in interaction and publish flows.\n\n### Validation\n\n- `ruff check .` passes.\n- `pytest -q` passes (`66 passed, 21 deselected`).\n\nFile v0.1.3:README_EN.md\n\n# xhs-cli\n\n[中文](README.md) | **English**\n\n[![PyPI](https://img.shields.io/pypi/v/xhs-cli)](https://pypi.org/project/xhs-cli/)\n[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)\n\nA command-line tool for [Xiaohongshu (小红书)](https://www.xiaohongshu.com) — search notes, view profiles, like, favorite, and comment, all from your terminal.\n\n## Recommended Projects\n\n- [twitter-cli](https://github.com/jackwener/twitter-cli) - A CLI tool for X/Twitter workflows\n- [bilibili-cli](https://github.com/jackwener/bilibili-cli) - A CLI tool for Bilibili workflows\n\n## Features\n\n- **Search** — search notes by keyword with rich table output\n- **Read** — view note content, stats, and comments\n- **User Profile** — view user info, posts, followers, following\n- **Feed** — get recommended content from explore page\n- **Topics** — search for topics and hashtags\n- **Engage** — like/unlike, favorite/unfavorite, comment, delete\n- **Post** — publish image notes\n- **Auth** — auto-extract cookies from Chrome, or login via QR code (terminal-rendered)\n- **JSON output** — `--json` flag for all data commands\n- **Auto token** — `xsec_token` is cached and auto-resolved\n\n## Commands\n\n| Category | Commands | Description |\n|----------|----------|-------------|\n| Auth | `login`, `logout`, `status`, `whoami` | Login, logout, check status, view profile |\n| Read | `search`, `read`, `feed`, `topics` | Search notes, read details, explore feed, find topics |\n| Users | `user`, `user-posts`, `followers`, `following` | View profile, list posts/followers/following |\n| Engage | `like`, `unlike`, `comment`, `delete` | Like, unlike, comment, delete notes |\n| Favorites | `favorite`, `unfavorite`, `favorites` | Favorite, unfavorite, list all favorites |\n| Post | `post` | Publish a new image note |\n\n> All data commands support `--json` for raw JSON output. `xsec_token` is auto-cached and auto-resolved.\n\n## Installation\n\nRequires Python 3.8+.\n\n```bash\n# Recommended: using uv\nuv tool install xhs-cli\n\n# Or using pipx\npipx install xhs-cli\n```\n\n<details>\n<summary>Install from source (for development)</summary>\n\n```bash\ngit clone git@github.com:jackwener/xhs-cli.git\ncd xhs-cli\nuv sync\n```\n\n</details>\n\n## One-Command Local Smoke Test\n\nWith a valid saved session (`~/.xhs-cli/cookies.json`), run:\n\n```bash\n./scripts/smoke_local.sh\n```\n\nYou can pass extra pytest arguments, for example:\n\n```bash\n./scripts/smoke_local.sh -k whoami\n```\n\nBy default, only non-mutating smoke is executed\n(`integration and not live_mutation`). To also verify\n`like/favorite/comment/post/delete`, opt in explicitly:\n\n```bash\nXHS_SMOKE_MUTATION=1 ./scripts/smoke_local.sh\n```\n\nOptional environment variables:\n\n```bash\nXHS_SMOKE_COMMENT_TEXT=\"smoke test comment\"\nXHS_SMOKE_POST_IMAGES=\"/abs/a.jpg,/abs/b.jpg\"\nXHS_SMOKE_POST_TITLE=\"smoke title\"\nXHS_SMOKE_POST_CONTENT=\"smoke content\"\n```\n\n## Usage\n\n### Login\n\n```bash\n# Auto-extract cookies from Chrome (recommended)\nxhs login\n\n# Force QR code login (useful for troubleshooting auth)\nxhs login --qrcode\n\n# Or provide cookie string manually (must include a1 and web_session)\nxhs login --cookie \"a1=xxx; web_session=yyy\"\n\n# Quick check for saved login session\n# (no browser needed, no browser-cookie extraction)\nxhs status\n\n# Show profile info\nxhs whoami\nxhs whoami --json\n\n# Logout\nxhs logout\n```\n\n### Search\n\n```bash\nxhs search \"咖啡\"\nxhs search \"咖啡\" --json\n```\n\n### Read Note\n\n```bash\n# View note (xsec_token auto-resolved from cache)\nxhs read <note_id>\n\n# Include comments\nxhs read <note_id> --comments\n\n# Provide xsec_token manually if needed\nxhs read <note_id> --xsec-token <token>\n```\n\n### User\n\n```bash\n# View user profile (uses internal user_id, not Red ID)\nxhs user <user_id>\n\n# List user's published notes\nxhs user-posts <user_id>\n\n# Followers / following\nxhs followers <user_id>\nxhs following <user_id>\n```\n\n### Feed & Topics\n\n```bash\nxhs feed\nxhs topics \"travel\"\n```\n\n### Interactions\n\n```bash\n# Like / Unlike (xsec_token auto-resolved)\nxhs like <note_id>\nxhs like <note_id> --undo\n\n# Favorite / Unfavorite\nxhs favorite <note_id>\nxhs favorite <note_id> --undo\n\n# Comment\nxhs comment <note_id> \"nice post!\"\n\n# Delete your own note\nxhs delete <note_id>\n\n# List your favorites\nxhs favorites\nxhs favorites --max 10\n```\n\n### Post\n\n```bash\nxhs post \"Title\" --image photo1.jpg --image photo2.jpg --content \"Body text\"\nxhs post \"Title\" --image photo1.jpg --content \"Body text\" --json\n```\n\n### Other\n\n```bash\nxhs --version\nxhs -v search \"咖啡\"   # debug logging\nxhs --help\n```\n\n## Architecture\n\n```\nCLI (click) → XhsClient (camoufox browser)\n                  ↓ navigate to real pages\n              window.__INITIAL_STATE__ → extract structured data\n```\n\nUses [camoufox](https://github.com/daijro/camoufox) (anti-fingerprint Firefox) to browse Xiaohongshu like a real user. Data is extracted from `window.__INITIAL_STATE__` — completely indistinguishable from normal browsing.\n\n## How It Works\n\n1. **Authentication** — First reads `~/.xhs-cli/cookies.json`; if missing, extracts cookies from local Chrome via browser-cookie3. Falls back to QR code login if extraction fails (terminal half-block rendering with `▀ ▄ █`).\n2. **Session Validation** — After login, the CLI verifies that the session is non-guest and probes feed/search usability. If probe fails, it asks for re-login.\n3. **Browsing** — Each operation navigates to real pages using camoufox, making all traffic look like normal user browsing.\n4. **Data Extraction** — Structured data is pulled from `window.__INITIAL_STATE__`.\n5. **Token Caching** — After search/feed, `xsec_token` is auto-cached to `~/.xhs-cli/token_cache.json`.\n6. **Interactions** — Like, favorite, and comment work by clicking actual DOM buttons.\n\n## Use as AI Agent Skill\n\nxhs-cli ships with a [`SKILL.md`](./SKILL.md) that teaches AI agents how to use it.\n\n### Claude Code / Antigravity\n\n```bash\n# Clone into your project's skills directory\nmkdir -p .agents/skills\ngit clone git@github.com:jackwener/xhs-cli.git .agents/skills/xhs-cli\n\n# Or just copy the SKILL.md\ncurl -o .agents/skills/xhs-cli/SKILL.md \\\n  https://raw.githubusercontent.com/jackwener/xhs-cli/main/SKILL.md\n```\n\nOnce added, AI agents that support the `.agents/skills/` convention will automatically discover and use xhs-cli commands.\n\n### OpenClaw / ClawHub\n\nOfficially supports [OpenClaw](https://openclaw.ai) and [ClawHub](https://docs.openclaw.ai/tools/clawhub). Install via ClawHub:\n\n```bash\nclawhub install xiaohongshu-cli\n```\n\nAll xhs-cli commands are available in OpenClaw after installation.\n\n## Notes\n\n- Cookies are stored in `~/.xhs-cli/cookies.json` with `0600` permissions.\n- `xhs status` checks saved local cookies only and never triggers browser extraction.\n- `xhs login --cookie` requires at least `a1` and `web_session`.\n- Login runs a usability probe; guest/risk-limited sessions are treated as invalid and require re-login.\n- `xhs post` may require an extra creator-platform login at `https://creator.xiaohongshu.com`.\n- Uses headless Firefox via camoufox — no browser window is shown.\n- First run requires downloading the camoufox browser (`python -m camoufox fetch`).\n- User profile lookup requires the internal user_id (hex format), not the Red ID.\n\n## License\n\nApache License 2.0\n\nFile v0.1.3:pyproject.toml\n\n[build-system]\nrequires = [\"hatchling\"]\nbuild-backend = \"hatchling.build\"\n\n[project]\nname = \"xhs-cli\"\nversion = \"0.1.3\"\ndescription = \"A CLI for Xiaohongshu (小红书) — search, read notes, view profiles\"\nreadme = \"README.md\"\nlicense = { file = \"LICENSE\" }\nrequires-python = \">=3.8\"\nauthors = [{ name = \"jackwener\", email = \"jakevingoo@gmail.com\" }]\nkeywords = [\"xiaohongshu\", \"xhs\", \"cli\", \"redbook\", \"小红书\"]\nclassifiers = [\n    \"Development Status :: 3 - Alpha\",\n    \"Environment :: Console\",\n    \"Intended Audience :: Developers\",\n    \"License :: OSI Approved :: Apache Software License\",\n    \"Programming Language :: Python :: 3\",\n    \"Programming Language :: Python :: 3.8\",\n    \"Programming Language :: Python :: 3.9\",\n    \"Programming Language :: Python :: 3.10\",\n    \"Programming Language :: Python :: 3.11\",\n    \"Programming Language :: Python :: 3.12\",\n    \"Programming Language :: Python :: 3.13\",\n    \"Topic :: Utilities\",\n]\ndependencies = [\n    \"camoufox[geoip]>=0.4\",\n    \"playwright>=1.40\",\n    \"browser-cookie3>=0.19\",\n    \"qrcode>=7.4\",\n    \"click>=8.0\",\n    \"rich>=13.0\",\n]\n\n[project.urls]\nHomepage = \"https://github.com/jackwener/xhs-cli\"\nRepository = \"https://github.com/jackwener/xhs-cli\"\nIssues = \"https://github.com/jackwener/xhs-cli/issues\"\n\n[project.scripts]\nxhs = \"xhs_cli.cli:cli\"\n\n[dependency-groups]\ndev = [\n    \"pytest>=8.3.5\",\n    \"ruff>=0.11.0\",\n]\n\n[tool.pytest.ini_options]\nmarkers = [\n    \"integration: requires valid login session (deselect with '-m \\\"not integration\\\"')\",\n    \"live_mutation: integration tests that may mutate account state (like/favorite/comment/post)\",\n]\naddopts = \"-m 'not integration'\"\n\n[tool.ruff]\nline-length = 100\ntarget-version = \"py38\"\n\n[tool.ruff.lint]\nselect = [\"E\", \"F\", \"I\", \"B\", \"UP\"]\n\nArchive v0.1.2: 16 files, 44961 bytes\n\nFiles: pyproject.toml (1760b), README_EN.md (7298b), README.md (7103b), scripts/smoke_local.sh (891b), SKILL.md (3745b), tests/conftest.py (940b), tests/test_auth.py (6677b), tests/test_cli.py (10245b), tests/test_client.py (3932b), tests/test_integration.py (10138b), xhs_cli/__init__.py (72b), xhs_cli/auth.py (24773b), xhs_cli/cli.py (37959b), xhs_cli/client.py (52227b), xhs_cli/exceptions.py (315b), _meta.json (134b)\n\nFile v0.1.2:SKILL.md\n\n---\nname: xhs-cli\ndescription: Xiaohongshu (小红书) CLI — search, read, like, favorite, comment from the terminal\n---\n\n# xhs-cli Skill\n\nA CLI tool for interacting with Xiaohongshu (小红书). Use it to search notes, read details, browse user profiles, and perform interactions like liking, favoriting, and commenting.\n\n## Prerequisites\n\n```bash\n# Install (requires Python 3.8+)\nuv tool install xhs-cli\n# Or: pipx install xhs-cli\n```\n\n## Authentication\n\nAll commands require valid cookies to function.\n\n```bash\nxhs status                     # Check saved login session (no browser extraction)\nxhs login                      # Auto-extract Chrome cookies\nxhs login --cookie \"a1=...\"    # Or provide cookies manually\n```\n\nAuthentication first uses saved local cookies. If unavailable, it auto-detects local Chrome cookies via browser-cookie3. If extraction fails, QR code login is available.\n\n## Command Reference\n\n### Search\n\n```bash\nxhs search \"咖啡\"              # Search notes (rich table output)\nxhs search \"咖啡\" --json       # Raw JSON output\n```\n\n### Read Note\n\n```bash\n# View note (xsec_token auto-resolved from search cache)\nxhs read <note_id>\nxhs read <note_id> --comments  # Include comments\nxhs read <note_id> --xsec-token <token>  # Manual token\nxhs read <note_id> --json\n```\n\n### User\n\n```bash\n# Look up user profile (by internal user_id, hex format)\nxhs user <user_id>\nxhs user <user_id> --json\n\n# List user's published notes\nxhs user-posts <user_id>\nxhs user-posts <user_id> --json\n\n# Followers / Following\nxhs followers <user_id>\nxhs following <user_id>\n```\n\n### Discovery\n\n```bash\nxhs feed                       # Explore page recommended feed\nxhs feed --json\nxhs topics \"旅行\"              # Search topics/hashtags\nxhs topics \"旅行\" --json\n```\n\n### Interactions (require login)\n\n```bash\n# Like / Unlike (xsec_token auto-resolved)\nxhs like <note_id>\nxhs like <note_id> --undo\n\n# Favorite / Unfavorite\nxhs favorite <note_id>\nxhs favorite <note_id> --undo\n\n# Comment\nxhs comment <note_id> \"好棒！\"\n\n# Delete your own note\nxhs delete <note_id>\n```\n\n### Favorites\n\n```bash\nxhs favorites                  # List your favorites\nxhs favorites --max 10         # Limit count\nxhs favorites --json\n```\n\n### Post\n\n```bash\nxhs post \"标题\" --image photo1.jpg --image photo2.jpg --content \"正文\"\nxhs post \"标题\" --image photo1.jpg --content \"正文\" --json\n```\n\n### Account\n\n```bash\nxhs status                     # Quick saved-session check\nxhs whoami                     # Full profile info\nxhs whoami --json\nxhs login                      # Login\nxhs logout                     # Clear cookies\n```\n\n## JSON Output\n\nMajor query commands support `--json` for machine-readable output:\n\n```bash\nxhs search \"咖啡\" --json | jq '.[0].id'           # First note ID\nxhs whoami --json | jq '.userInfo.userId'          # Your user ID\nxhs favorites --json | jq '.[0].displayTitle'      # First favorite title\n```\n\n## Common Patterns for AI Agents\n\n```bash\n# Get your user ID for further queries\nxhs whoami --json | python3 -c \"import sys,json; d=json.load(sys.stdin); print(d.get('userInfo',{}).get('userId',''))\"\n\n# Search and get note IDs (xsec_token auto-cached for later use)\nxhs search \"topic\" --json | python3 -c \"import sys,json; [print(n['id']) for n in json.load(sys.stdin)[:3]]\"\n\n# Check login before performing actions\nxhs status && xhs like <note_id>\n\n# Read a note with comments for summarization\nxhs read <note_id> --comments --json\n```\n\n## Error Handling\n\n- Commands exit with code 0 on success, non-zero on failure\n- Error messages are prefixed with ❌\n- Login-required commands show clear instruction to run `xhs login`\n- `xsec_token` is auto-resolved from cache; manual `--xsec-token` available as fallback\n\nFile v0.1.2:README.md\n\n# xhs-cli\n\n**中文** | [English](README_EN.md)\n\n[![PyPI](https://img.shields.io/pypi/v/xhs-cli)](https://pypi.org/project/xhs-cli/)\n[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)\n\n小红书命令行工具 — 在终端中搜索笔记、查看主页、点赞、收藏、评论。\n\n## 推荐项目\n\n- [twitter-cli](https://github.com/jackwener/twitter-cli) - 在终端中操作 X/Twitter 的 CLI 工具\n- [bilibili-cli](https://github.com/jackwener/bilibili-cli) - 哔哩哔哩 CLI 工具\n\n## 功能\n\n- **搜索** — 按关键词搜索笔记，Rich 表格展示\n- **阅读** — 查看笔记内容、数据、评论\n- **用户资料** — 查看用户信息、笔记、粉丝、关注\n- **推荐 Feed** — 获取探索页推荐内容\n- **话题** — 搜索话题标签\n- **互动** — 点赞/取消、收藏/取消、评论、删除笔记\n- **发布** — 发布图文笔记\n- **认证** — 自动提取 Chrome cookie，或扫码登录（终端二维码渲染）\n- **JSON 输出** — 所有数据命令支持 `--json`\n- **Token 自动缓存** — `xsec_token` 搜索后自动缓存，后续命令免手动传\n\n## 命令一览\n\n| 分类 | 命令 | 说明 |\n|------|------|------|\n| Auth | `login`, `logout`, `status`, `whoami` | 登录、退出、状态检查、查看个人资料 |\n| Read | `search`, `read`, `feed`, `topics` | 搜索笔记、阅读详情、推荐 Feed、搜索话题 |\n| Users | `user`, `user-posts`, `followers`, `following` | 查看资料、列出笔记/粉丝/关注 |\n| Engage | `like`, `unlike`, `comment`, `delete` | 点赞、取消点赞、评论、删除笔记 |\n| Favorites | `favorite`, `unfavorite`, `favorites` | 收藏、取消收藏、查看收藏列表 |\n| Post | `post` | 发布图文笔记 |\n\n> 所有数据命令支持 `--json` 输出。`xsec_token` 自动缓存，无需手动传递。\n\n## 安装\n\n需要 Python 3.8+。\n\n```bash\n# 推荐：使用 uv\nuv tool install xhs-cli\n\n# 或使用 pipx\npipx install xhs-cli\n```\n\n<details>\n<summary>从源码安装（开发用）</summary>\n\n```bash\ngit clone git@github.com:jackwener/xhs-cli.git\ncd xhs-cli\nuv sync\n```\n\n</details>\n\n## 本地一键冒烟测试\n\n在本地已登录（有 `~/.xhs-cli/cookies.json`）的情况下，直接运行：\n\n```bash\n./scripts/smoke_local.sh\n```\n\n可选地传递 pytest 参数（例如只跑某个用例）：\n\n```bash\n./scripts/smoke_local.sh -k whoami\n```\n\n默认只跑无副作用命令（`integration and not live_mutation`）。如需额外验证\n`like/favorite/comment/post/delete`，显式开启：\n\n```bash\nXHS_SMOKE_MUTATION=1 ./scripts/smoke_local.sh\n```\n\n可选环境变量：\n\n```bash\nXHS_SMOKE_COMMENT_TEXT=\"smoke test comment\"\nXHS_SMOKE_POST_IMAGES=\"/abs/a.jpg,/abs/b.jpg\"\nXHS_SMOKE_POST_TITLE=\"smoke title\"\nXHS_SMOKE_POST_CONTENT=\"smoke content\"\n```\n\n## 使用\n\n### 登录\n\n```bash\n# 自动从 Chrome 提取 cookie（推荐）\nxhs login\n\n# 强制使用二维码登录（用于排查登录问题）\nxhs login --qrcode\n\n# 手动提供 cookie 字符串（至少包含 a1 和 web_session）\nxhs login --cookie \"a1=xxx; web_session=yyy\"\n\n# 快速检查已保存的登录状态（不启动浏览器，不读取浏览器 cookie）\nxhs status\n\n# 查看个人资料\nxhs whoami\nxhs whoami --json\n\n# 退出登录\nxhs logout\n```\n\n### 搜索\n\n```bash\nxhs search \"咖啡\"\nxhs search \"咖啡\" --json\n```\n\n### 阅读笔记\n\n```bash\n# 查看笔记（xsec_token 从缓存自动解析）\nxhs read <note_id>\n\n# 包含评论\nxhs read <note_id> --comments\n\n# 手动指定 xsec_token\nxhs read <note_id> --xsec-token <token>\n```\n\n### 用户\n\n```bash\n# 查看用户资料（使用内部 user_id，非小红书号）\nxhs user <user_id>\n\n# 列出用户笔记\nxhs user-posts <user_id>\n\n# 粉丝 / 关注\nxhs followers <user_id>\nxhs following <user_id>\n```\n\n### 推荐 & 话题\n\n```bash\nxhs feed\nxhs topics \"旅行\"\n```\n\n### 互动\n\n```bash\n# 点赞 / 取消（xsec_token 自动解析）\nxhs like <note_id>\nxhs like <note_id> --undo\n\n# 收藏 / 取消\nxhs favorite <note_id>\nxhs favorite <note_id> --undo\n\n# 评论\nxhs comment <note_id> \"好棒！\"\n\n# 删除自己的笔记\nxhs delete <note_id>\n\n# 查看收藏列表\nxhs favorites\nxhs favorites --max 10\n```\n\n### 发布笔记\n\n```bash\nxhs post \"标题\" --image photo1.jpg --image photo2.jpg --content \"正文内容\"\nxhs post \"标题\" --image photo1.jpg --content \"正文内容\" --json\n```\n\n### 其他\n\n```bash\nxhs --version\nxhs -v search \"咖啡\"   # 调试日志\nxhs --help\n```\n\n## 架构\n\n```\nCLI (click) → XhsClient (camoufox 浏览器)\n                  ↓ 导航到真实页面\n              window.__INITIAL_STATE__ → 提取结构化数据\n```\n\n使用 [camoufox](https://github.com/daijro/camoufox)（反指纹 Firefox）像真实用户一样浏览小红书。数据从页面的 `window.__INITIAL_STATE__` 中提取，与正常浏览完全一致。\n\n## 工作原理\n\n1. **认证** — 优先读取 `~/.xhs-cli/cookies.json`；未命中时通过 browser-cookie3 从本地 Chrome 提取 cookie，失败则 fallback 到扫码登录（终端半块字符二维码，`▀ ▄ █`）。\n2. **登录态校验** — 登录后会校验会话是否为有效非 guest 会话，并做 feed/search 可用性探活；探活失败会提示重新登录。\n3. **浏览** — 使用 camoufox 导航到真实页面，所有流量与正常用户浏览一致。\n4. **数据提取** — 从 `window.__INITIAL_STATE__` 提取结构化数据。\n5. **Token 缓存** — 搜索/Feed 后 `xsec_token` 自动缓存到 `~/.xhs-cli/token_cache.json`。\n6. **互动操作** — 点赞、收藏、评论通过点击真实 DOM 按钮实现。\n\n## 作为 AI Agent Skill 使用\n\nxhs-cli 自带 [`SKILL.md`](./SKILL.md)，让 AI Agent 能自动学习并使用本工具。\n\n### Claude Code / Antigravity\n\n```bash\n# 克隆到项目的 skills 目录\nmkdir -p .agents/skills\ngit clone git@github.com:jackwener/xhs-cli.git .agents/skills/xhs-cli\n\n# 或者只复制 SKILL.md\ncurl -o .agents/skills/xhs-cli/SKILL.md \\\n  https://raw.githubusercontent.com/jackwener/xhs-cli/main/SKILL.md\n```\n\n添加后，支持 `.agents/skills/` 的 AI Agent 会自动发现并使用 xhs-cli 命令。\n\n### OpenClaw / ClawHub\n\n官方支持 [OpenClaw](https://openclaw.ai) 和 [ClawHub](https://docs.openclaw.ai/tools/clawhub) 生态。通过 ClawHub 安装：\n\n```bash\nclawhub install xiaohongshu-cli\n```\n\n安装后即可在 OpenClaw 中直接使用所有 xhs-cli 命令。\n\n## 注意事项\n\n- Cookie 存储在 `~/.xhs-cli/cookies.json`，权限 `0600`。\n- `xhs status` 只检查本地已保存 cookie，不会触发浏览器 cookie 提取。\n- `xhs login --cookie` 要求 cookie 至少包含 `a1` 和 `web_session`。\n- 登录后会自动做可用性探活；若会话仍为 guest/风控受限，会提示重新登录。\n- `xhs post` 可能要求额外登录创作平台（`https://creator.xiaohongshu.com`）。\n- 使用 headless Firefox，不会弹出浏览器窗口。\n- 首次运行需下载 camoufox 浏览器（`python -m camoufox fetch`）。\n- 用户资料查询需要内部 user_id（十六进制），不是小红书号。\n\n## License\n\nApache License 2.0\n\nFile v0.1.2:_meta.json\n\n{\n  \"ownerId\": \"kn757vsv03fbpevrxybjc424wh828377\",\n  \"slug\": \"xiaohongshu-cli\",\n  \"version\": \"0.1.2\",\n  \"publishedAt\": 1772731692110\n}\n\nFile v0.1.2:README_EN.md\n\n# xhs-cli\n\n[中文](README.md) | **English**\n\n[![PyPI](https://img.shields.io/pypi/v/xhs-cli)](https://pypi.org/project/xhs-cli/)\n[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)\n\nA command-line tool for [Xiaohongshu (小红书)](https://www.xiaohongshu.com) — search notes, view profiles, like, favorite, and comment, all from your terminal.\n\n## Recommended Projects\n\n- [twitter-cli](https://github.com/jackwener/twitter-cli) - A CLI tool for X/Twitter workflows\n- [bilibili-cli](https://github.com/jackwener/bilibili-cli) - A CLI tool for Bilibili workflows\n\n## Features\n\n- **Search** — search notes by keyword with rich table output\n- **Read** — view note content, stats, and comments\n- **User Profile** — view user info, posts, followers, following\n- **Feed** — get recommended content from explore page\n- **Topics** — search for topics and hashtags\n- **Engage** — like/unlike, favorite/unfavorite, comment, delete\n- **Post** — publish image notes\n- **Auth** — auto-extract cookies from Chrome, or login via QR code (terminal-rendered)\n- **JSON output** — `--json` flag for all data commands\n- **Auto token** — `xsec_token` is cached and auto-resolved\n\n## Commands\n\n| Category | Commands | Description |\n|----------|----------|-------------|\n| Auth | `login`, `logout`, `status`, `whoami` | Login, logout, check status, view profile |\n| Read | `search`, `read`, `feed`, `topics` | Search notes, read details, explore feed, find topics |\n| Users | `user`, `user-posts`, `followers`, `following` | View profile, list posts/followers/following |\n| Engage | `like`, `unlike`, `comment`, `delete` | Like, unlike, comment, delete notes |\n| Favorites | `favorite`, `unfavorite`, `favorites` | Favorite, unfavorite, list all favorites |\n| Post | `post` | Publish a new image note |\n\n> All data commands support `--json` for raw JSON output. `xsec_token` is auto-cached and auto-resolved.\n\n## Installation\n\nRequires Python 3.8+.\n\n```bash\n# Recommended: using uv\nuv tool install xhs-cli\n\n# Or using pipx\npipx install xhs-cli\n```\n\n<details>\n<summary>Install from source (for development)</summary>\n\n```bash\ngit clone git@github.com:jackwener/xhs-cli.git\ncd xhs-cli\nuv sync\n```\n\n</details>\n\n## One-Command Local Smoke Test\n\nWith a valid saved session (`~/.xhs-cli/cookies.json`), run:\n\n```bash\n./scripts/smoke_local.sh\n```\n\nYou can pass extra pytest arguments, for example:\n\n```bash\n./scripts/smoke_local.sh -k whoami\n```\n\nBy default, only non-mutating smoke is executed\n(`integration and not live_mutation`). To also verify\n`like/favorite/comment/post/delete`, opt in explicitly:\n\n```bash\nXHS_SMOKE_MUTATION=1 ./scripts/smoke_local.sh\n```\n\nOptional environment variables:\n\n```bash\nXHS_SMOKE_COMMENT_TEXT=\"smoke test comment\"\nXHS_SMOKE_POST_IMAGES=\"/abs/a.jpg,/abs/b.jpg\"\nXHS_SMOKE_POST_TITLE=\"smoke title\"\nXHS_SMOKE_POST_CONTENT=\"smoke content\"\n```\n\n## Usage\n\n### Login\n\n```bash\n# Auto-extract cookies from Chrome (recommended)\nxhs login\n\n# Force QR code login (useful for troubleshooting auth)\nxhs login --qrcode\n\n# Or provide cookie string manually (must include a1 and web_session)\nxhs login --cookie \"a1=xxx; web_session=yyy\"\n\n# Quick check for saved login session\n# (no browser needed, no browser-cookie extraction)\nxhs status\n\n# Show profile info\nxhs whoami\nxhs whoami --json\n\n# Logout\nxhs logout\n```\n\n### Search\n\n```bash\nxhs search \"咖啡\"\nxhs search \"咖啡\" --json\n```\n\n### Read Note\n\n```bash\n# View note (xsec_token auto-resolved from cache)\nxhs read <note_id>\n\n# Include comments\nxhs read <note_id> --comments\n\n# Provide xsec_token manually if needed\nxhs read <note_id> --xsec-token <token>\n```\n\n### User\n\n```bash\n# View user profile (uses internal user_id, not Red ID)\nxhs user <user_id>\n\n# List user's published notes\nxhs user-posts <user_id>\n\n# Followers / following\nxhs followers <user_id>\nxhs following <user_id>\n```\n\n### Feed & Topics\n\n```bash\nxhs feed\nxhs topics \"travel\"\n```\n\n### Interactions\n\n```bash\n# Like / Unlike (xsec_token auto-resolved)\nxhs like <note_id>\nxhs like <note_id> --undo\n\n# Favorite / Unfavorite\nxhs favorite <note_id>\nxhs favorite <note_id> --undo\n\n# Comment\nxhs comment <note_id> \"nice post!\"\n\n# Delete your own note\nxhs delete <note_id>\n\n# List your favorites\nxhs favorites\nxhs favorites --max 10\n```\n\n### Post\n\n```bash\nxhs post \"Title\" --image photo1.jpg --image photo2.jpg --content \"Body text\"\nxhs post \"Title\" --image photo1.jpg --content \"Body text\" --json\n```\n\n### Other\n\n```bash\nxhs --version\nxhs -v search \"咖啡\"   # debug logging\nxhs --help\n```\n\n## Architecture\n\n```\nCLI (click) → XhsClient (camoufox browser)\n                  ↓ navigate to real pages\n              window.__INITIAL_STATE__ → extract structured data\n```\n\nUses [camoufox](https://github.com/daijro/camoufox) (anti-fingerprint Firefox) to browse Xiaohongshu like a real user. Data is extracted from `window.__INITIAL_STATE__` — completely indistinguishable from normal browsing.\n\n## How It Works\n\n1. **Authentication** — First reads `~/.xhs-cli/cookies.json`; if missing, extracts cookies from local Chrome via browser-cookie3. Falls back to QR code login if extraction fails (terminal half-block rendering with `▀ ▄ █`).\n2. **Session Validation** — After login, the CLI verifies that the session is non-guest and probes feed/search usability. If probe fails, it asks for re-login.\n3. **Browsing** — Each operation navigates to real pages using camoufox, making all traffic look like normal user browsing.\n4. **Data Extraction** — Structured data is pulled from `window.__INITIAL_STATE__`.\n5. **Token Caching** — After search/feed, `xsec_token` is auto-cached to `~/.xhs-cli/token_cache.json`.\n6. **Interactions** — Like, favorite, and comment work by clicking actual DOM buttons.\n\n## Use as AI Agent Skill\n\nxhs-cli ships with a [`SKILL.md`](./SKILL.md) that teaches AI agents how to use it.\n\n### Claude Code / Antigravity\n\n```bash\n# Clone into your project's skills directory\nmkdir -p .agents/skills\ngit clone git@github.com:jackwener/xhs-cli.git .agents/skills/xhs-cli\n\n# Or just copy the SKILL.md\ncurl -o .agents/skills/xhs-cli/SKILL.md \\\n  https://raw.githubusercontent.com/jackwener/xhs-cli/main/SKILL.md\n```\n\nOnce added, AI agents that support the `.agents/skills/` convention will automatically discover and use xhs-cli commands.\n\n### OpenClaw / ClawHub\n\nOfficially supports [OpenClaw](https://openclaw.ai) and [ClawHub](https://docs.openclaw.ai/tools/clawhub). Install via ClawHub:\n\n```bash\nclawhub install xiaohongshu-cli\n```\n\nAll xhs-cli commands are available in OpenClaw after installation.\n\n## Notes\n\n- Cookies are stored in `~/.xhs-cli/cookies.json` with `0600` permissions.\n- `xhs status` checks saved local cookies only and never triggers browser extraction.\n- `xhs login --cookie` requires at least `a1` and `web_session`.\n- Login runs a usability probe; guest/risk-limited sessions are treated as invalid and require re-login.\n- `xhs post` may require an extra creator-platform login at `https://creator.xiaohongshu.com`.\n- Uses headless Firefox via camoufox — no browser window is shown.\n- First run requires downloading the camoufox browser (`python -m camoufox fetch`).\n- User profile lookup requires the internal user_id (hex format), not the Red ID.\n\n## License\n\nApache License 2.0\n\nFile v0.1.2:pyproject.toml\n\n[build-system]\nrequires = [\"hatchling\"]\nbuild-backend = \"hatchling.build\"\n\n[project]\nname = \"xhs-cli\"\nversion = \"0.1.2\"\ndescription = \"A CLI for Xiaohongshu (小红书) — search, read notes, view profiles\"\nreadme = \"README.md\"\nlicense = { file = \"LICENSE\" }\nrequires-python = \">=3.8\"\nauthors = [{ name = \"jackwener\", email = \"jakevingoo@gmail.com\" }]\nkeywords = [\"xiaohongshu\", \"xhs\", \"cli\", \"redbook\", \"小红书\"]\nclassifiers = [\n    \"Development Status :: 3 - Alpha\",\n    \"Environment :: Console\",\n    \"Intended Audience :: Developers\",\n    \"License :: OSI Approved :: Apache Software License\",\n    \"Programming Language :: Python :: 3\",\n    \"Programming Language :: Python :: 3.8\",\n    \"Programming Language :: Python :: 3.9\",\n    \"Programming Language :: Python :: 3.10\",\n    \"Programming Language :: Python :: 3.11\",\n    \"Programming Language :: Python :: 3.12\",\n    \"Programming Language :: Python :: 3.13\",\n    \"Topic :: Utilities\",\n]\ndependencies = [\n    \"camoufox[geoip]>=0.4\",\n    \"playwright>=1.40\",\n    \"browser-cookie3>=0.19\",\n    \"qrcode>=7.4\",\n    \"click>=8.0\",\n    \"rich>=13.0\",\n]\n\n[project.urls]\nHomepage = \"https://github.com/jackwener/xhs-cli\"\nRepository = \"https://github.com/jackwener/xhs-cli\"\nIssues = \"https://github.com/jackwener/xhs-cli/issues\"\n\n[project.scripts]\nxhs = \"xhs_cli.cli:cli\"\n\n[dependency-groups]\ndev = [\n    \"pytest>=8.3.5\",\n    \"ruff>=0.11.0\",\n]\n\n[tool.pytest.ini_options]\nmarkers = [\n    \"integration: requires valid login session (deselect with '-m \\\"not integration\\\"')\",\n    \"live_mutation: integration tests that may mutate account state (like/favorite/comment/post)\",\n]\naddopts = \"-m 'not integration'\"\n\n[tool.ruff]\nline-length = 100\ntarget-version = \"py38\"\n\n[tool.ruff.lint]\nselect = [\"E\", \"F\", \"I\", \"B\", \"UP\"]\n\nArchive v0.1.1: 16 files, 39183 bytes\n\nFiles: pyproject.toml (1741b), README_EN.md (6785b), README.md (6572b), scripts/smoke_local.sh (891b), SKILL.md (3745b), tests/conftest.py (940b), tests/test_auth.py (5044b), tests/test_cli.py (5219b), tests/test_client.py (3670b), tests/test_integration.py (10138b), xhs_cli/__init__.py (72b), xhs_cli/auth.py (13702b), xhs_cli/cli.py (35587b), xhs_cli/client.py (47412b), xhs_cli/exceptions.py (315b), _meta.json (134b)\n\nFile v0.1.1:SKILL.md\n\n---\nname: xhs-cli\ndescription: Xiaohongshu (小红书) CLI — search, read, like, favorite, comment from the terminal\n---\n\n# xhs-cli Skill\n\nA CLI tool for interacting with Xiaohongshu (小红书). Use it to search notes, read details, browse user profiles, and perform interactions like liking, favoriting, and commenting.\n\n## Prerequisites\n\n```bash\n# Install (requires Python 3.8+)\nuv tool install xhs-cli\n# Or: pipx install xhs-cli\n```\n\n## Authentication\n\nAll commands require valid cookies to function.\n\n```bash\nxhs status                     # Check saved login session (no browser extraction)\nxhs login                      # Auto-extract Chrome cookies\nxhs login --cookie \"a1=...\"    # Or provide cookies manually\n```\n\nAuthentication first uses saved local cookies. If unavailable, it auto-detects local Chrome cookies via browser-cookie3. If extraction fails, QR code login is available.\n\n## Command Reference\n\n### Search\n\n```bash\nxhs search \"咖啡\"              # Search notes (rich table output)\nxhs search \"咖啡\" --json       # Raw JSON output\n```\n\n### Read Note\n\n```bash\n# View note (xsec_token auto-resolved from search cache)\nxhs read <note_id>\nxhs read <note_id> --comments  # Include comments\nxhs read <note_id> --xsec-token <token>  # Manual token\nxhs read <note_id> --json\n```\n\n### User\n\n```bash\n# Look up user profile (by internal user_id, hex format)\nxhs user <user_id>\nxhs user <user_id> --json\n\n# List user's published notes\nxhs user-posts <user_id>\nxhs user-posts <user_id> --json\n\n# Followers / Following\nxhs followers <user_id>\nxhs following <user_id>\n```\n\n### Discovery\n\n```bash\nxhs feed                       # Explore page recommended feed\nxhs feed --json\nxhs topics \"旅行\"              # Search topics/hashtags\nxhs topics \"旅行\" --json\n```\n\n### Interactions (require login)\n\n```bash\n# Like / Unlike (xsec_token auto-resolved)\nxhs like <note_id>\nxhs like <note_id> --undo\n\n# Favorite / Unfavorite\nxhs favorite <note_id>\nxhs favorite <note_id> --undo\n\n# Comment\nxhs comment <note_id> \"好棒！\"\n\n# Delete your own note\nxhs delete <note_id>\n```\n\n### Favorites\n\n```bash\nxhs favorites                  # List your favorites\nxhs favorites --max 10         # Limit count\nxhs favorites --json\n```\n\n### Post\n\n```bash\nxhs post \"标题\" --image photo1.jpg --image photo2.jpg --content \"正文\"\nxhs post \"标题\" --image photo1.jpg --content \"正文\" --json\n```\n\n### Account\n\n```bash\nxhs status                     # Quick saved-session check\nxhs whoami                     # Full profile info\nxhs whoami --json\nxhs login                      # Login\nxhs logout                     # Clear cookies\n```\n\n## JSON Output\n\nMajor query commands support `--json` for machine-readable output:\n\n```bash\nxhs search \"咖啡\" --json | jq '.[0].id'           # First note ID\nxhs whoami --json | jq '.userInfo.userId'          # Your user ID\nxhs favorites --json | jq '.[0].displayTitle'      # First favorite title\n```\n\n## Common Patterns for AI Agents\n\n```bash\n# Get your user ID for further queries\nxhs whoami --json | python3 -c \"import sys,json; d=json.load(sys.stdin); print(d.get('userInfo',{}).get('userId',''))\"\n\n# Search and get note IDs (xsec_token auto-cached for later use)\nxhs search \"topic\" --json | python3 -c \"import sys,json; [print(n['id']) for n in json.load(sys.stdin)[:3]]\"\n\n# Check login before performing actions\nxhs status && xhs like <note_id>\n\n# Read a note with comments for summarization\nxhs read <note_id> --comments --json\n```\n\n## Error Handling\n\n- Commands exit with code 0 on success, non-zero on failure\n- Error messages are prefixed with ❌\n- Login-required commands show clear instruction to run `xhs login`\n- `xsec_token` is auto-resolved from cache; manual `--xsec-token` available as fallback\n\nFile v0.1.1:README.md\n\n# xhs-cli\n\n**中文** | [English](README_EN.md)\n\n[![PyPI](https://img.shields.io/pypi/v/xhs-cli)](https://pypi.org/project/xhs-cli/)\n[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)\n\n小红书命令行工具 — 在终端中搜索笔记、查看主页、点赞、收藏、评论。\n\n## 推荐项目\n\n- [twitter-cli](https://github.com/jackwener/twitter-cli) - 在终端中操作 X/Twitter 的 CLI 工具\n- [bilibili-cli](https://github.com/jackwener/bilibili-cli) - 哔哩哔哩 CLI 工具\n\n## 功能\n\n- **搜索** — 按关键词搜索笔记，Rich 表格展示\n- **阅读** — 查看笔记内容、数据、评论\n- **用户资料** — 查看用户信息、笔记、粉丝、关注\n- **推荐 Feed** — 获取探索页推荐内容\n- **话题** — 搜索话题标签\n- **互动** — 点赞/取消、收藏/取消、评论、删除笔记\n- **发布** — 发布图文笔记\n- **认证** — 自动提取 Chrome cookie，或扫码登录\n- **JSON 输出** — 所有数据命令支持 `--json`\n- **Token 自动缓存** — `xsec_token` 搜索后自动缓存，后续命令免手动传\n\n## 命令一览\n\n| 分类 | 命令 | 说明 |\n|------|------|------|\n| Auth | `login`, `logout`, `status`, `whoami` | 登录、退出、状态检查、查看个人资料 |\n| Read | `search`, `read`, `feed`, `topics` | 搜索笔记、阅读详情、推荐 Feed、搜索话题 |\n| Users | `user`, `user-posts`, `followers`, `following` | 查看资料、列出笔记/粉丝/关注 |\n| Engage | `like`, `unlike`, `comment`, `delete` | 点赞、取消点赞、评论、删除笔记 |\n| Favorites | `favorite`, `unfavorite`, `favorites` | 收藏、取消收藏、查看收藏列表 |\n| Post | `post` | 发布图文笔记 |\n\n> 所有数据命令支持 `--json` 输出。`xsec_token` 自动缓存，无需手动传递。\n\n## 安装\n\n需要 Python 3.8+。\n\n```bash\n# 推荐：使用 uv\nuv tool install xhs-cli\n\n# 或使用 pipx\npipx install xhs-cli\n```\n\n<details>\n<summary>从源码安装（开发用）</summary>\n\n```bash\ngit clone git@github.com:jackwener/xhs-cli.git\ncd xhs-cli\nuv sync\n```\n\n</details>\n\n## 本地一键冒烟测试\n\n在本地已登录（有 `~/.xhs-cli/cookies.json`）的情况下，直接运行：\n\n```bash\n./scripts/smoke_local.sh\n```\n\n可选地传递 pytest 参数（例如只跑某个用例）：\n\n```bash\n./scripts/smoke_local.sh -k whoami\n```\n\n默认只跑无副作用命令（`integration and not live_mutation`）。如需额外验证\n`like/favorite/comment/post/delete`，显式开启：\n\n```bash\nXHS_SMOKE_MUTATION=1 ./scripts/smoke_local.sh\n```\n\n可选环境变量：\n\n```bash\nXHS_SMOKE_COMMENT_TEXT=\"smoke test comment\"\nXHS_SMOKE_POST_IMAGES=\"/abs/a.jpg,/abs/b.jpg\"\nXHS_SMOKE_POST_TITLE=\"smoke title\"\nXHS_SMOKE_POST_CONTENT=\"smoke content\"\n```\n\n## 使用\n\n### 登录\n\n```bash\n# 自动从 Chrome 提取 cookie（推荐）\nxhs login\n\n# 手动提供 cookie 字符串\nxhs login --cookie \"a1=xxx; web_session=yyy\"\n\n# 快速检查已保存的登录状态（不启动浏览器，不读取浏览器 cookie）\nxhs status\n\n# 查看个人资料\nxhs whoami\nxhs whoami --json\n\n# 退出登录\nxhs logout\n```\n\n### 搜索\n\n```bash\nxhs search \"咖啡\"\nxhs search \"咖啡\" --json\n```\n\n### 阅读笔记\n\n```bash\n# 查看笔记（xsec_token 从缓存自动解析）\nxhs read <note_id>\n\n# 包含评论\nxhs read <note_id> --comments\n\n# 手动指定 xsec_token\nxhs read <note_id> --xsec-token <token>\n```\n\n### 用户\n\n```bash\n# 查看用户资料（使用内部 user_id，非小红书号）\nxhs user <user_id>\n\n# 列出用户笔记\nxhs user-posts <user_id>\n\n# 粉丝 / 关注\nxhs followers <user_id>\nxhs following <user_id>\n```\n\n### 推荐 & 话题\n\n```bash\nxhs feed\nxhs topics \"旅行\"\n```\n\n### 互动\n\n```bash\n# 点赞 / 取消（xsec_token 自动解析）\nxhs like <note_id>\nxhs like <note_id> --undo\n\n# 收藏 / 取消\nxhs favorite <note_id>\nxhs favorite <note_id> --undo\n\n# 评论\nxhs comment <note_id> \"好棒！\"\n\n# 删除自己的笔记\nxhs delete <note_id>\n\n# 查看收藏列表\nxhs favorites\nxhs favorites --max 10\n```\n\n### 发布笔记\n\n```bash\nxhs post \"标题\" --image photo1.jpg --image photo2.jpg --content \"正文内容\"\nxhs post \"标题\" --image photo1.jpg --content \"正文内容\" --json\n```\n\n### 其他\n\n```bash\nxhs --version\nxhs -v search \"咖啡\"   # 调试日志\nxhs --help\n```\n\n## 架构\n\n```\nCLI (click) → XhsClient (camoufox 浏览器)\n                  ↓ 导航到真实页面\n              window.__INITIAL_STATE__ → 提取结构化数据\n```\n\n使用 [camoufox](https://github.com/daijro/camoufox)（反指纹 Firefox）像真实用户一样浏览小红书。数据从页面的 `window.__INITIAL_STATE__` 中提取，与正常浏览完全一致。\n\n## 工作原理\n\n1. **认证** — 优先读取 `~/.xhs-cli/cookies.json`；未命中时通过 browser-cookie3 从本地 Chrome 提取 cookie，失败则 fallback 到扫码登录。\n2. **浏览** — 使用 camoufox 导航到真实页面，所有流量与正常用户浏览一致。\n3. **数据提取** — 从 `window.__INITIAL_STATE__` 提取结构化数据。\n4. **Token 缓存** — 搜索/Feed 后 `xsec_token` 自动缓存到 `~/.xhs-cli/token_cache.json`。\n5. **互动操作** — 点赞、收藏、评论通过点击真实 DOM 按钮实现。\n\n## 作为 AI Agent Skill 使用\n\nxhs-cli 自带 [`SKILL.md`](./SKILL.md)，让 AI Agent 能自动学习并使用本工具。\n\n### Claude Code / Antigravity\n\n```bash\n# 克隆到项目的 skills 目录\nmkdir -p .agents/skills\ngit clone git@github.com:jackwener/xhs-cli.git .agents/skills/xhs-cli\n\n# 或者只复制 SKILL.md\ncurl -o .agents/skills/xhs-cli/SKILL.md \\\n  https://raw.githubusercontent.com/jackwener/xhs-cli/main/SKILL.md\n```\n\n添加后，支持 `.agents/skills/` 的 AI Agent 会自动发现并使用 xhs-cli 命令。\n\n### OpenClaw / ClawHub\n\n官方支持 [OpenClaw](https://openclaw.ai) 和 [ClawHub](https://docs.openclaw.ai/tools/clawhub) 生态。通过 ClawHub 安装：\n\n```bash\nclawhub install xiaohongshu-cli\n```\n\n安装后即可在 OpenClaw 中直接使用所有 xhs-cli 命令。\n\n## 注意事项\n\n- Cookie 存储在 `~/.xhs-cli/cookies.json`，权限 `0600`。\n- `xhs status` 只检查本地已保存 cookie，不会触发浏览器 cookie 提取。\n- `xhs post` 可能要求额外登录创作平台（`https://creator.xiaohongshu.com`）。\n- 使用 headless Firefox，不会弹出浏览器窗口。\n- 首次运行需下载 camoufox 浏览器（`python -m camoufox fetch`）。\n- 用户资料查询需要内部 user_id（十六进制），不是小红书号。\n\n## License\n\nApache License 2.0\n\nFile v0.1.1:_meta.json\n\n{\n  \"ownerId\": \"kn757vsv03fbpevrxybjc424wh828377\",\n  \"slug\": \"xiaohongshu-cli\",\n  \"version\": \"0.1.1\",\n  \"publishedAt\": 1772726557063\n}\n\nFile v0.1.1:README_EN.md\n\n# xhs-cli\n\n[中文](README.md) | **English**\n\n[![PyPI](https://img.shields.io/pypi/v/xhs-cli)](https://pypi.org/project/xhs-cli/)\n[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)\n\nA command-line tool for [Xiaohongshu (小红书)](https://www.xiaohongshu.com) — search notes, view profiles, like, favorite, and comment, all from your terminal.\n\n## Recommended Projects\n\n- [twitter-cli](https://github.com/jackwener/twitter-cli) - A CLI tool for X/Twitter workflows\n- [bilibili-cli](https://github.com/jackwener/bilibili-cli) - A CLI tool for Bilibili workflows\n\n## Features\n\n- **Search** — search notes by keyword with rich table output\n- **Read** — view note content, stats, and comments\n- **User Profile** — view user info, posts, followers, following\n- **Feed** — get recommended content from explore page\n- **Topics** — search for topics and hashtags\n- **Engage** — like/unlike, favorite/unfavorite, comment, delete\n- **Post** — publish image notes\n- **Auth** — auto-extract cookies from Chrome, or login via QR code\n- **JSON output** — `--json` flag for all data commands\n- **Auto token** — `xsec_token` is cached and auto-resolved\n\n## Commands\n\n| Category | Commands | Description |\n|----------|----------|-------------|\n| Auth | `login`, `logout`, `status`, `whoami` | Login, logout, check status, view profile |\n| Read | `search`, `read`, `feed`, `topics` | Search notes, read details, explore feed, find topics |\n| Users | `user`, `user-posts`, `followers`, `following` | View profile, list posts/followers/following |\n| Engage | `like`, `unlike`, `comment`, `delete` | Like, unlike, comment, delete notes |\n| Favorites | `favorite`, `unfavorite`, `favorites` | Favorite, unfavorite, list all favorites |\n| Post | `post` | Publish a new image note |\n\n> All data commands support `--json` for raw JSON output. `xsec_token` is auto-cached and auto-resolved.\n\n## Installation\n\nRequires Python 3.8+.\n\n```bash\n# Recommended: using uv\nuv tool install xhs-cli\n\n# Or using pipx\npipx install xhs-cli\n```\n\n<details>\n<summary>Install from source (for development)</summary>\n\n```bash\ngit clone git@github.com:jackwener/xhs-cli.git\ncd xhs-cli\nuv sync\n```\n\n</details>\n\n## One-Command Local Smoke Test\n\nWith a valid saved session (`~/.xhs-cli/cookies.json`), run:\n\n```bash\n./scripts/smoke_local.sh\n```\n\nYou can pass extra pytest arguments, for example:\n\n```bash\n./scripts/smoke_local.sh -k whoami\n```\n\nBy default, only non-mutating smoke is executed\n(`integration and not live_mutation`). To also verify\n`like/favorite/comment/post/delete`, opt in explicitly:\n\n```bash\nXHS_SMOKE_MUTATION=1 ./scripts/smoke_local.sh\n```\n\nOptional environment variables:\n\n```bash\nXHS_SMOKE_COMMENT_TEXT=\"smoke test comment\"\nXHS_SMOKE_POST_IMAGES=\"/abs/a.jpg,/abs/b.jpg\"\nXHS_SMOKE_POST_TITLE=\"smoke title\"\nXHS_SMOKE_POST_CONTENT=\"smoke content\"\n```\n\n## Usage\n\n### Login\n\n```bash\n# Auto-extract cookies from Chrome (recommended)\nxhs login\n\n# Or provide cookie string manually\nxhs login --cookie \"a1=xxx; web_session=yyy\"\n\n# Quick check for saved login session\n# (no browser needed, no browser-cookie extraction)\nxhs status\n\n# Show profile info\nxhs whoami\nxhs whoami --json\n\n# Logout\nxhs logout\n```\n\n### Search\n\n```bash\nxhs search \"咖啡\"\nxhs search \"咖啡\" --json\n```\n\n### Read Note\n\n```bash\n# View note (xsec_token auto-resolved from cache)\nxhs read <note_id>\n\n# Include comments\nxhs read <note_id> --comments\n\n# Provide xsec_token manually if needed\nxhs read <note_id> --xsec-token <token>\n```\n\n### User\n\n```bash\n# View user profile (uses internal user_id, not Red ID)\nxhs user <user_id>\n\n# List user's published notes\nxhs user-posts <user_id>\n\n# Followers / following\nxhs followers <user_id>\nxhs following <user_id>\n```\n\n### Feed & Topics\n\n```bash\nxhs feed\nxhs topics \"travel\"\n```\n\n### Interactions\n\n```bash\n# Like / Unlike (xsec_token auto-resolved)\nxhs like <note_id>\nxhs like <note_id> --undo\n\n# Favorite / Unfavorite\nxhs favorite <note_id>\nxhs favorite <note_id> --undo\n\n# Comment\nxhs comment <note_id> \"nice post!\"\n\n# Delete your own note\nxhs delete <note_id>\n\n# List your favorites\nxhs favorites\nxhs favorites --max 10\n```\n\n### Post\n\n```bash\nxhs post \"Title\" --image photo1.jpg --image photo2.jpg --content \"Body text\"\nxhs post \"Title\" --image photo1.jpg --content \"Body text\" --json\n```\n\n### Other\n\n```bash\nxhs --version\nxhs -v search \"咖啡\"   # debug logging\nxhs --help\n```\n\n## Architecture\n\n```\nCLI (click) → XhsClient (camoufox browser)\n                  ↓ navigate to real pages\n              window.__INITIAL_STATE__ → extract structured data\n```\n\nUses [camoufox](https://github.com/daijro/camoufox) (anti-fingerprint Firefox) to browse Xiaohongshu like a real user. Data is extracted from `window.__INITIAL_STATE__` — completely indistinguishable from normal browsing.\n\n## How It Works\n\n1. **Authentication** — First reads `~/.xhs-cli/cookies.json`; if missing, extracts cookies from local Chrome via browser-cookie3. Falls back to QR code login if extraction fails.\n2. **Browsing** — Each operation navigates to real pages using camoufox, making all traffic look like normal user browsing.\n3. **Data Extraction** — Structured data is pulled from `window.__INITIAL_STATE__`.\n4. **Token Caching** — After search/feed, `xsec_token` is auto-cached to `~/.xhs-cli/token_cache.json`.\n5. **Interactions** — Like, favorite, and comment work by clicking actual DOM buttons.\n\n## Use as AI Agent Skill\n\nxhs-cli ships with a [`SKILL.md`](./SKILL.md) that teaches AI agents how to use it.\n\n### Claude Code / Antigravity\n\n```bash\n# Clone into your project's skills directory\nmkdir -p .agents/skills\ngit clone git@github.com:jackwener/xhs-cli.git .agents/skills/xhs-cli\n\n# Or just copy the SKILL.md\ncurl -o .agents/skills/xhs-cli/SKILL.md \\\n  https://raw.githubusercontent.com/jackwener/xhs-cli/main/SKILL.md\n```\n\nOnce added, AI agents that support the `.agents/skills/` convention will automatically discover and use xhs-cli commands.\n\n### OpenClaw / ClawHub\n\nOfficially supports [OpenClaw](https://openclaw.ai) and [ClawHub](https://docs.openclaw.ai/tools/clawhub). Install via ClawHub:\n\n```bash\nclawhub install xiaohongshu-cli\n```\n\nAll xhs-cli commands are available in OpenClaw after installation.\n\n## Notes\n\n- Cookies are stored in `~/.xhs-cli/cookies.json` with `0600` permissions.\n- `xhs status` checks saved local cookies only and never triggers browser extraction.\n- `xhs post` may require an extra creator-platform login at `https://creator.xiaohongshu.com`.\n- Uses headless Firefox via camoufox — no browser window is shown.\n- First run requires downloading the camoufox browser (`python -m camoufox fetch`).\n- User profile lookup requires the internal user_id (hex format), not the Red ID.\n\n## License\n\nApache License 2.0\n\nFile v0.1.1:pyproject.toml\n\n[build-system]\nrequires = [\"hatchling\"]\nbuild-backend = \"hatchling.build\"\n\n[project]\nname = \"xhs-cli\"\nversion = \"0.1.1\"\ndescription = \"A CLI for Xiaohongshu (小红书) — search, read notes, view profiles\"\nreadme = \"README.md\"\nlicense = { file = \"LICENSE\" }\nrequires-python = \">=3.8\"\nauthors = [{ name = \"jackwener\", email = \"jakevingoo@gmail.com\" }]\nkeywords = [\"xiaohongshu\", \"xhs\", \"cli\", \"redbook\", \"小红书\"]\nclassifiers = [\n    \"Development Status :: 3 - Alpha\",\n    \"Environment :: Console\",\n    \"Intended Audience :: Developers\",\n    \"License :: OSI Approved :: Apache Software License\",\n    \"Programming Language :: Python :: 3\",\n    \"Programming Language :: Python :: 3.8\",\n    \"Programming Language :: Python :: 3.9\",\n    \"Programming Language :: Python :: 3.10\",\n    \"Programming Language :: Python :: 3.11\",\n    \"Programming Language :: Python :: 3.12\",\n    \"Programming Language :: Python :: 3.13\",\n    \"Topic :: Utilities\",\n]\ndependencies = [\n    \"camoufox[geoip]>=0.4\",\n    \"playwright>=1.40\",\n    \"browser-cookie3>=0.19\",\n    \"click>=8.0\",\n    \"rich>=13.0\",\n]\n\n[project.urls]\nHomepage = \"https://github.com/jackwener/xhs-cli\"\nRepository = \"https://github.com/jackwener/xhs-cli\"\nIssues = \"https://github.com/jackwener/xhs-cli/issues\"\n\n[project.scripts]\nxhs = \"xhs_cli.cli:cli\"\n\n[dependency-groups]\ndev = [\n    \"pytest>=8.3.5\",\n    \"ruff>=0.11.0\",\n]\n\n[tool.pytest.ini_options]\nmarkers = [\n    \"integration: requires valid login session (deselect with '-m \\\"not integration\\\"')\",\n    \"live_mutation: integration tests that may mutate account state (like/favorite/comment/post)\",\n]\naddopts = \"-m 'not integration'\"\n\n[tool.ruff]\nline-length = 100\ntarget-version = \"py38\"\n\n[tool.ruff.lint]\nselect = [\"E\", \"F\", \"I\", \"B\", \"UP\"]\n\nArchive v0.1.0: 14 files, 32297 bytes\n\nFiles: pyproject.toml (1634b), README_EN.md (5494b), README.md (5256b), SKILL.md (3547b), tests/conftest.py (940b), tests/test_auth.py (4734b), tests/test_cli.py (3304b), tests/test_integration.py (4942b), xhs_cli/__init__.py (72b), xhs_cli/auth.py (13477b), xhs_cli/cli.py (33275b), xhs_cli/client.py (36759b), xhs_cli/exceptions.py (315b), _meta.json (134b)\n\nFile v0.1.0:SKILL.md\n\n---\nname: xhs-cli\ndescription: Xiaohongshu (小红书) CLI — search, read, like, favorite, comment from the terminal\n---\n\n# xhs-cli Skill\n\nA CLI tool for interacting with Xiaohongshu (小红书). Use it to search notes, read details, browse user profiles, and perform interactions like liking, favoriting, and commenting.\n\n## Prerequisites\n\n```bash\n# Install (requires Python 3.8+)\nuv tool install xhs-cli\n# Or: pipx install xhs-cli\n```\n\n## Authentication\n\nAll commands require valid cookies to function.\n\n```bash\nxhs status                     # Check if logged in\nxhs login                      # Auto-extract Chrome cookies\nxhs login --cookie \"a1=...\"    # Or provide cookies manually\n```\n\nAuthentication auto-detects local Chrome cookies via browser-cookie3. If extraction fails, QR code login is available.\n\n## Command Reference\n\n### Search\n\n```bash\nxhs search \"咖啡\"              # Search notes (rich table output)\nxhs search \"咖啡\" --json       # Raw JSON output\n```\n\n### Read Note\n\n```bash\n# View note (xsec_token auto-resolved from search cache)\nxhs read <note_id>\nxhs read <note_id> --comments  # Include comments\nxhs read <note_id> --xsec-token <token>  # Manual token\nxhs read <note_id> --json\n```\n\n### User\n\n```bash\n# Look up user profile (by internal user_id, hex format)\nxhs user <user_id>\nxhs user <user_id> --json\n\n# List user's published notes\nxhs user-posts <user_id>\nxhs user-posts <user_id> --json\n\n# Followers / Following\nxhs followers <user_id>\nxhs following <user_id>\n```\n\n### Discovery\n\n```bash\nxhs feed                       # Explore page recommended feed\nxhs feed --json\nxhs topics \"旅行\"              # Search topics/hashtags\nxhs topics \"旅行\" --json\n```\n\n### Interactions (require login)\n\n```bash\n# Like / Unlike (xsec_token auto-resolved)\nxhs like <note_id>\nxhs like <note_id> --undo\n\n# Favorite / Unfavorite\nxhs favorite <note_id>\nxhs favorite <note_id> --undo\n\n# Comment\nxhs comment <note_id> \"好棒！\"\n```\n\n### Favorites\n\n```bash\nxhs favorites                  # List your favorites\nxhs favorites --max 10         # Limit count\nxhs favorites --json\n```\n\n### Post\n\n```bash\nxhs post \"标题\" --image photo1.jpg --image photo2.jpg --content \"正文\"\n```\n\n### Account\n\n```bash\nxhs status                     # Quick login check\nxhs whoami                     # Full profile info\nxhs whoami --json\nxhs login                      # Login\nxhs logout                     # Clear cookies\n```\n\n## JSON Output\n\nMajor query commands support `--json` for machine-readable output:\n\n```bash\nxhs search \"咖啡\" --json | jq '.[0].id'           # First note ID\nxhs whoami --json | jq '.userInfo.userId'          # Your user ID\nxhs favorites --json | jq '.[0].displayTitle'      # First favorite title\n```\n\n## Common Patterns for AI Agents\n\n```bash\n# Get your user ID for further queries\nxhs whoami --json | python3 -c \"import sys,json; d=json.load(sys.stdin); print(d.get('userInfo',{}).get('userId',''))\"\n\n# Search and get note IDs (xsec_token auto-cached for later use)\nxhs search \"topic\" --json | python3 -c \"import sys,json; [print(n['id']) for n in json.load(sys.stdin)[:3]]\"\n\n# Check login before performing actions\nxhs status && xhs like <note_id>\n\n# Read a note with comments for summarization\nxhs read <note_id> --comments --json\n```\n\n## Error Handling\n\n- Commands exit with code 0 on success, non-zero on failure\n- Error messages are prefixed with ❌\n- Login-required commands show clear instruction to run `xhs login`\n- `xsec_token` is auto-resolved from cache; manual `--xsec-token` available as fallback\n\nFile v0.1.0:README.md\n\n# xhs-cli\n\n**中文** | [English](README_EN.md)\n\n[![PyPI](https://img.shields.io/pypi/v/xhs-cli)](https://pypi.org/project/xhs-cli/)\n[![License](https://img.shields.io/github/license/jackwener/xhs-cli)](LICENSE)\n\n小红书命令行工具 — 在终端中搜索笔记、查看主页、点赞、收藏、评论。\n\n## 功能\n\n- **搜索** — 按关键词搜索笔记，Rich 表格展示\n- **阅读** — 查看笔记内容、数据、评论\n- **用户资料** — 查看用户信息、笔记、粉丝、关注\n- **推荐 Feed** — 获取探索页推荐内容\n- **话题** — 搜索话题标签\n- **互动** — 点赞/取消、收藏/取消、评论\n- **发布** — 发布图文笔记\n- **认证** — 自动提取 Chrome cookie，或扫码登录\n- **JSON 输出** — 所有数据命令支持 `--json`\n- **Token 自动缓存** — `xsec_token` 搜索后自动缓存，后续命令免手动传\n\n## 命令一览\n\n| 分类 | 命令 | 说明 |\n|------|------|------|\n| Auth | `login`, `logout`, `status`, `whoami` | 登录、退出、状态检查、查看个人资料 |\n| Read | `search`, `read`, `feed`, `topics` | 搜索笔记、阅读详情、推荐 Feed、搜索话题 |\n| Users | `user`, `user-posts`, `followers`, `following` | 查看资料、列出笔记/粉丝/关注 |\n| Engage | `like`, `unlike`, `comment` | 点赞、取消点赞、评论 |\n| Favorites | `favorite`, `unfavorite`, `favorites` | 收藏、取消收藏、查看收藏列表 |\n| Post | `post` | 发布图文笔记 |\n\n> 所有数据命令支持 `--json` 输出。`xsec_token` 自动缓存，无需手动传递。\n\n## 安装\n\n需要 Python 3.8+。\n\n```bash\n# 推荐：使用 uv\nuv tool install xhs-cli\n\n# 或使用 pipx\npipx install xhs-cli\n```\n\n<details>\n<summary>从源码安装（开发用）</summary>\n\n```bash\ngit clone git@github.com:jackwener/xhs-cli.git\ncd xhs-cli\nuv sync\n```\n\n</details>\n\n## 使用\n\n### 登录\n\n```bash\n# 自动从 Chrome 提取 cookie（推荐）\nxhs login\n\n# 手动提供 cookie 字符串\nxhs login --cookie \"a1=xxx; web_session=yyy\"\n\n# 快速检查登录状态（不启动浏览器）\nxhs status\n\n# 查看个人资料\nxhs whoami\nxhs whoami --json\n\n# 退出登录\nxhs logout\n```\n\n### 搜索\n\n```bash\nxhs search \"咖啡\"\nxhs search \"咖啡\" --json\n```\n\n### 阅读笔记\n\n```bash\n# 查看笔记（xsec_token 从缓存自动解析）\nxhs read <note_id>\n\n# 包含评论\nxhs read <note_id> --comments\n\n# 手动指定 xsec_token\nxhs read <note_id> --xsec-token <token>\n```\n\n### 用户\n\n```bash\n# 查看用户资料（使用内部 user_id，非小红书号）\nxhs user <user_id>\n\n# 列出用户笔记\nxhs user-posts <user_id>\n\n# 粉丝 / 关注\nxhs followers <user_id>\nxhs following <user_id>\n```\n\n### 推荐 & 话题\n\n```bash\nxhs feed\nxhs topics \"旅行\"\n```\n\n### 互动\n\n```bash\n# 点赞 / 取消（xsec_token 自动解析）\nxhs like <note_id>\nxhs like <note_id> --undo\n\n# 收藏 / 取消\nxhs favorite <note_id>\nxhs favorite <note_id> --undo\n\n# 评论\nxhs comment <note_id> \"好棒！\"\n\n# 查看收藏列表\nxhs favorites\nxhs favorites --max 10\n```\n\n### 发布笔记\n\n```bash\nxhs post \"标题\" --image photo1.jpg --image photo2.jpg --content \"正文内容\"\n```\n\n### 其他\n\n```bash\nxhs --version\nxhs -v search \"咖啡\"   # 调试日志\nxhs --help\n```\n\n## 架构\n\n```\nCLI (click) → XhsClient (camoufox 浏览器)\n                  ↓ 导航到真实页面\n              window.__INITIAL_STATE__ → 提取结构化数据\n```\n\n使用 [camoufox](https://github.com/daijro/camoufox)（反指纹 Firefox）像真实用户一样浏览小红书。数据从页面的 `window.__INITIAL_STATE__` 中提取，与正常浏览完全一致。\n\n## 工作原理\n\n1. **认证** — 通过 browser-cookie3 从本地 Chrome 提取 cookie，失败则 fallback 到扫码登录。\n2. **浏览** — 使用 camoufox 导航到真实页面，所有流量与正常用户浏览一致。\n3. **数据提取** — 从 `window.__INITIAL_STATE__` 提取结构化数据。\n4. **Token 缓存** — 搜索/Feed 后 `xsec_token` 自动缓存到 `~/.xhs-cli/token_cache.json`。\n5. **互动操作** — 点赞、收藏、评论通过点击真实 DOM 按钮实现。\n\n## 作为 AI Agent Skill 使用\n\nxhs-cli 自带 [`SKILL.md`](./SKILL.md)，让 AI Agent 能自动学习并使用本工具。\n\n### Claude Code / Antigravity\n\n```bash\n# 克隆到项目的 skills 目录\nmkdir -p .agents/skills\ngit clone git@github.com:jackwener/xhs-cli.git .agents/skills/xhs-cli\n\n# 或者只复制 SKILL.md\ncurl -o .agents/skills/xhs-cli/SKILL.md \\\n  https://raw.githubusercontent.com/jackwener/xhs-cli/main/SKILL.md\n```\n\n添加后，支持 `.agents/skills/` 的 AI Agent 会自动发现并使用 xhs-cli 命令。\n\n### OpenClaw / ClawHub\n\n官方支持 [OpenClaw](https://openclaw.ai) 和 [ClawHub](https://docs.openclaw.ai/tools/clawhub) 生态。通过 ClawHub 安装：\n\n```bash\nclawhub install xhs-cli\n```\n\n安装后即可在 OpenClaw 中直接使用所有 xhs-cli 命令。\n\n## 注意事项\n\n- Cookie 存储在 `~/.xhs-cli/cookies.json`，权限 `0600`。\n- 使用 headless Firefox，不会弹出浏览器窗口。\n- 首次运行需下载 camoufox 浏览器（`python -m camoufox fetch`）。\n- 用户资料查询需要内部 user_id（十六进制），不是小红书号。\n\n## License\n\nApache License 2.0\n\nFile v0.1.0:_meta.json\n\n{\n  \"ownerId\": \"kn757vsv03fbpevrxybjc424wh828377\",\n  \"slug\": \"xiaohongshu-cli\",\n  \"version\": \"0.1.0\",\n  \"publishedAt\": 1772701154436\n}\n\nFile v0.1.0:README_EN.md\n\n# xhs-cli\n\n[中文](README.md) | **English**\n\n[![PyPI](https://img.shields.io/pypi/v/xhs-cli)](https://pypi.org/project/xhs-cli/)\n[![License](https://img.shields.io/github/license/jackwener/xhs-cli)](LICENSE)\n\nA command-line tool for [Xiaohongshu (小红书)](https://www.xiaohongshu.com) — search notes, view profiles, like, favorite, and comment, all from your terminal.\n\n## Features\n\n- **Search** — search notes by keyword with rich table output\n- **Read** — view note content, stats, and comments\n- **User Profile** — view user info, posts, followers, following\n- **Feed** — get recommended content from explore page\n- **Topics** — search for topics and hashtags\n- **Engage** — like/unlike, favorite/unfavorite, comment\n- **Post** — publish image notes\n- **Auth** — auto-extract cookies from Chrome, or login via QR code\n- **JSON output** — `--json` flag for all data commands\n- **Auto token** — `xsec_token` is cached and auto-resolved\n\n## Commands\n\n| Category | Commands | Description |\n|----------|----------|-------------|\n| Auth | `login`, `logout`, `status`, `whoami` | Login, logout, check status, view profile |\n| Read | `search`, `read`, `feed`, `topics` | Search notes, read details, explore feed, find topics |\n| Users | `user`, `user-posts`, `followers`, `following` | View profile, list posts/followers/following |\n| Engage | `like`, `unlike`, `comment` | Like, unlike, comment on notes |\n| Favorites | `favorite`, `unfavorite`, `favorites` | Favorite, unfavorite, list all favorites |\n| Post | `post` | Publish a new image note |\n\n> All data commands support `--json` for raw JSON output. `xsec_token` is auto-cached and auto-resolved.\n\n## Installation\n\nRequires Python 3.8+.\n\n```bash\n# Recommended: using uv\nuv tool install xhs-cli\n\n# Or using pipx\npipx install xhs-cli\n```\n\n<details>\n<summary>Install from source (for development)</summary>\n\n```bash\ngit clone git@github.com:jackwener/xhs-cli.git\ncd xhs-cli\nuv sync\n```\n\n</details>\n\n## Usage\n\n### Login\n\n```bash\n# Auto-extract cookies from Chrome (recommended)\nxhs login\n\n# Or provide cookie string manually\nxhs login --cookie \"a1=xxx; web_session=yyy\"\n\n# Quick login check (no browser needed)\nxhs status\n\n# Show profile info\nxhs whoami\nxhs whoami --json\n\n# Logout\nxhs logout\n```\n\n### Search\n\n```bash\nxhs search \"咖啡\"\nxhs search \"咖啡\" --json\n```\n\n### Read Note\n\n```bash\n# View note (xsec_token auto-resolved from cache)\nxhs read <note_id>\n\n# Include comments\nxhs read <note_id> --comments\n\n# Provide xsec_token manually if needed\nxhs read <note_id> --xsec-token <token>\n```\n\n### User\n\n```bash\n# View user profile (uses internal user_id, not Red ID)\nxhs user <user_id>\n\n# List user's published notes\nxhs user-posts <user_id>\n\n# Followers / following\nxhs followers <user_id>\nxhs following <user_id>\n```\n\n### Feed & Topics\n\n```bash\nxhs feed\nxhs topics \"travel\"\n```\n\n### Interactions\n\n```bash\n# Like / Unlike (xsec_token auto-resolved)\nxhs like <note_id>\nxhs like <note_id> --undo\n\n# Favorite / Unfavorite\nxhs favorite <note_id>\nxhs favorite <note_id> --undo\n\n# Comment\nxhs comment <note_id> \"nice post!\"\n\n# List your favorites\nxhs favorites\nxhs favorites --max 10\n```\n\n### Post\n\n```bash\nxhs post \"Title\" --image photo1.jpg --image photo2.jpg --content \"Body text\"\n```\n\n### Other\n\n```bash\nxhs --version\nxhs -v search \"咖啡\"   # debug logging\nxhs --help\n```\n\n## Architecture\n\n```\nCLI (click) → XhsClient (camoufox browser)\n                  ↓ navigate to real pages\n              window.__INITIAL_STATE__ → extract structured data\n```\n\nUses [camoufox](https://github.com/daijro/camoufox) (anti-fingerprint Firefox) to browse Xiaohongshu like a real user. Data is extracted from `window.__INITIAL_STATE__` — completely indistinguishable from normal browsing.\n\n## How It Works\n\n1. **Authentication** — Cookies are extracted from your local Chrome via browser-cookie3. Falls back to QR code login if extraction fails.\n2. **Browsing** — Each operation navigates to real pages using camoufox, making all traffic look like normal user browsing.\n3. **Data Extraction** — Structured data is pulled from `window.__INITIAL_STATE__`.\n4. **Token Caching** — After search/feed, `xsec_token` is auto-cached to `~/.xhs-cli/token_cache.json`.\n5. **Interactions** — Like, favorite, and comment work by clicking actual DOM buttons.\n\n## Use as AI Agent Skill\n\nxhs-cli ships with a [`SKILL.md`](./SKILL.md) that teaches AI agents how to use it.\n\n### Claude Code / Antigravity\n\n```bash\n# Clone into your project's skills directory\nmkdir -p .agents/skills\ngit clone git@github.com:jackwener/xhs-cli.git .agents/skills/xhs-cli\n\n# Or just copy the SKILL.md\ncurl -o .agents/skills/xhs-cli/SKILL.md \\\n  https://raw.githubusercontent.com/jackwener/xhs-cli/main/SKILL.md\n```\n\nOnce added, AI agents that support the `.agents/skills/` convention will automatically discover and use xhs-cli commands.\n\n### OpenClaw / ClawHub\n\nOfficially supports [OpenClaw](https://openclaw.ai) and [ClawHub](https://docs.openclaw.ai/tools/clawhub). Install via ClawHub:\n\n```bash\nclawhub install xhs-cli\n```\n\nAll xhs-cli commands are available in OpenClaw after installation.\n\n## Notes\n\n- Cookies are stored in `~/.xhs-cli/cookies.json` with `0600` permissions.\n- Uses headless Firefox via camoufox — no browser window is shown.\n- First run requires downloading the camoufox browser (`python -m camoufox fetch`).\n- User profile lookup requires the internal user_id (hex format), not the Red ID.\n\n## License\n\nApache License 2.0\n\nFile v0.1.0:pyproject.toml\n\n[build-system]\nrequires = [\"hatchling\"]\nbuild-backend = \"hatchling.build\"\n\n[project]\nname = \"xhs-cli\"\nversion = \"0.1.0\"\ndescription = \"A CLI for Xiaohongshu (小红书) — search, read notes, view profiles\"\nreadme = \"README.md\"\nlicense = \"Apache-2.0\"\nrequires-python = \">=3.8\"\nauthors = [{ name = \"jackwener\", email = \"jakevingoo@gmail.com\" }]\nkeywords = [\"xiaohongshu\", \"xhs\", \"cli\", \"redbook\", \"小红书\"]\nclassifiers = [\n    \"Development Status :: 3 - Alpha\",\n    \"Environment :: Console\",\n    \"Intended Audience :: Developers\",\n    \"License :: OSI Approved :: Apache Software License\",\n    \"Programming Language :: Python :: 3\",\n    \"Programming Language :: Python :: 3.8\",\n    \"Programming Language :: Python :: 3.9\",\n    \"Programming Language :: Python :: 3.10\",\n    \"Programming Language :: Python :: 3.11\",\n    \"Programming Language :: Python :: 3.12\",\n    \"Programming Language :: Python :: 3.13\",\n    \"Topic :: Utilities\",\n]\ndependencies = [\n    \"camoufox[geoip]>=0.4\",\n    \"playwright>=1.40\",\n    \"browser-cookie3>=0.19\",\n    \"click>=8.0\",\n    \"rich>=13.0\",\n]\n\n[project.urls]\nHomepage = \"https://github.com/jackwener/xhs-cli\"\nRepository = \"https://github.com/jackwener/xhs-cli\"\nIssues = \"https://github.com/jackwener/xhs-cli/issues\"\n\n[project.scripts]\nxhs = \"xhs_cli.cli:cli\"\n\n[dependency-groups]\ndev = [\n    \"pytest>=8.3.5\",\n    \"ruff>=0.11.0\",\n]\n\n[tool.pytest.ini_options]\nmarkers = [\n    \"integration: requires valid login session (deselect with '-m \\\"not integration\\\"')\",\n]\naddopts = \"-m 'not integration'\"\n\n[tool.ruff]\nline-length = 100\ntarget-version = \"py38\"\n\n[tool.ruff.lint]\nselect = [\"E\", \"F\", \"I\", \"B\", \"UP\"]","readmeExcerpt":"Skill: xiaohongshu-cli Owner: jackwener Summary: Use xiaohongshu-cli for ALL Xiaohongshu (Little Red Book, 小红书) operations — searching notes, reading content, browsing users, liking, collecting, commenting,... Tags: latest:0.2.1 Version history: v0.2.1 | 2026-03-10T17:15:55.955Z | user Release 0.2.1 v0.1.4 | 2026-03-08T18:16:50.706Z | user Sync SKILL.md: add 小红书 tag, safety notes v0.1.3 | 2026-03-05T17:59:13.818Z | u","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"# Install (requires Python 3.10+)\nuv tool install xiaohongshu-cli\n# Or: pipx install xiaohongshu-cli"},{"language":"bash","snippet":"xhs status --yaml >/dev/null && echo \"AUTH_OK\" || echo \"AUTH_NEEDED\""},{"language":"bash","snippet":"xhs login                              # auto-extract cookies\nxhs login --cookie-source firefox      # specify browser"},{"language":"bash","snippet":"xhs status\nxhs whoami"},{"language":"bash","snippet":"NOTE_ID=$(xhs search \"美食推荐\" --json | jq -r '.data.items[0].id')\nxhs read \"$NOTE_ID\" --json | jq '.data'\nxhs like \"$NOTE_ID\""},{"language":"bash","snippet":"xhs hot -c food --json | jq '.data.items[:5] | .[].note_card | {title, likes: .interact_info.liked_count}'"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: xiaohongshu-cli\ndescription: 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.\nauthor: jackwener\nversion: \"1.0.0\"\ntags:\n  - xiaohongshu\n  - xhs\n  - redbook\n  - 小红书\n  - social-media\n  - cli\n---\n\n# xiaohongshu-cli — Xiaohongshu CLI Tool\n\n**Binary:** `xhs`\n**Credentials:** browser cookies (auto-extracted via `--cookie-source`)\n\n## Setup\n\n```bash\n# Install (requires Python 3.10+)\nuv tool install xiaohongshu-cli\n# Or: pipx install xiaohongshu-cli\n```\n\n## Authentication\n\n**IMPORTANT FOR AGENTS**: Before executing ANY xhs command, check if credentials exist first. Do NOT assume cookies are configured.\n\n### Step 0: Check if already authenticated\n\n```bash\nxhs status --yaml >/dev/null && echo \"AUTH_OK\" || echo \"AUTH_NEEDED\"\n```\n\nIf `AUTH_OK`, skip to [Command Reference](#command-reference).\nIf `AUTH_NEEDED`, proceed to Step 1.\n\n### Step 1: Guide user to authenticate\n\nEnsure user is logged into xiaohongshu.com in one of: Chrome, Edge, Firefox, Safari, Brave. Then:\n\n```bash\nxhs login                              # auto-extract cookies\nxhs login --cookie-source firefox      # specify browser\n```\n\nVerify with:\n\n```bash\nxhs status\nxhs whoami\n```\n\n### Step 2: Handle common auth issues\n\n| Symptom | Agent action |\n|---------|-------------|\n| `NoCookieError: No 'a1' cookie found` | Guide user to login to xiaohongshu.com in browser |\n| `NeedVerifyError: Captcha required` | Ask user to open browser, complete captcha, then retry |\n| `IpBlockedError: IP blocked` | Suggest switching network (hotspot/VPN) |\n| `SessionExpiredError` | Run `xhs login` to refresh cookies |\n\n## Agent Defaults\n\nAll machine-readable output uses the envelope documented in [SCHEMA.md](./SCHEMA.md).\nPayloads live under `.data`.\n\n- Non-TTY stdout → auto YAML\n- `--json` / `--yaml` → explicit format\n- `OUTPUT=json` env → global override\n- `OUTPUT=rich` env → force human output\n\n## Command Reference\n\n### Reading\n\n| Command | Description | Example |\n|---------|-------------|---------|\n| `xhs search <keyword>` | Search notes | `xhs search \"美食\" --sort popular --type video` |\n| `xhs read <id_or_url>` | Read a note (URL auto-extracts xsec_token) | `xhs read \"https://...?xsec_token=xxx\"` |\n| `xhs comments <id_or_url>` | Get comments (xsec_token required — paste URL) | `xhs comments \"https://...?xsec_token=...\"` |\n| `xhs comments <id_or_url> --all` | Get ALL comments (auto-paginate) | `xhs comments \"<url>\" --all --json` |\n| `xhs sub-comments <note_id> <comment_id>` | Get replies to comment | `xhs sub-comments abc 123` |\n| `xhs user <user_id>` | View user profile | `xhs user 5f2e123` |\n| `xhs user-posts <user_id>` | List user's notes | `xhs user-posts 5f2e123 --cursor \"\"` |\n| `xhs feed` | Browse recommendation feed | `xhs feed --yaml` |\n| `xhs hot` | Browse trending notes | `xhs hot -c food` |\n| `xhs topics "},{"path":"README.md","content":"# xiaohongshu-cli\n\n[![CI](https://github.com/jackwener/xiaohongshu-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/jackwener/xiaohongshu-cli/actions/workflows/ci.yml)\n[![Python](https://img.shields.io/badge/python-%3E%3D3.10-blue.svg)](https://pypi.org/project/xiaohongshu-cli/)\n\nA CLI for Xiaohongshu (小红书) — search, read, interact, and post via reverse-engineered API 📕\n\n[English](#features) | [中文](#功能特性)\n\n## More Tools\n\n- [bilibili-cli](https://github.com/jackwener/bilibili-cli) — Bilibili CLI for videos, users, search, and feeds\n- [twitter-cli](https://github.com/jackwener/twitter-cli) — Twitter/X CLI for timelines, bookmarks, and posting\n- [discord-cli](https://github.com/jackwener/discord-cli) — Discord CLI for local-first sync, search, and export\n- [tg-cli](https://github.com/jackwener/tg-cli) — Telegram CLI for local-first sync, search, and export\n\n## Features\n\n- 🔐 **Auth** — auto-extract browser cookies, status check, whoami\n- 🔍 **Search** — notes by keyword, user search, topic search\n- 📖 **Reading** — note detail, comments, sub-comments, user profiles\n- 📰 **Feed** — recommendation feed, hot/trending by category\n- 👥 **Social** — follow/unfollow, favorites\n- 👍 **Interactions** — like, favorite, comment, reply, delete\n- ✍️ **Creator** — post image notes, my-notes list, delete\n- 🔔 **Notifications** — unread count, mentions, likes, new followers\n- 🛡️ **Anti-detection** — consistent macOS Chrome fingerprint, `sec-ch-ua` alignment, session-stable browser identity, Gaussian jitter, captcha cooldown, exponential backoff\n- 📊 **Structured output** — commands support `--yaml` and `--json`; non-TTY stdout defaults to YAML\n- 📦 **Stable envelope** — see [SCHEMA.md](./SCHEMA.md) for `ok/schema_version/data/error`\n\n> **AI Agent Tip:** Prefer `--yaml` for structured output unless strict JSON is required. Non-TTY stdout defaults to YAML automatically.\n\n## Installation\n\n```bash\n# Recommended: uv tool (fast, isolated)\nuv tool install xiaohongshu-cli\n\n# Or: pipx\npipx install xiaohongshu-cli\n```\n\nFrom source:\n\n```bash\ngit clone git@github.com:jackwener/xiaohongshu-cli.git\ncd xiaohongshu-cli\nuv sync\n```\n\n## Usage\n\n```bash\n# ─── Auth ─────────────────────────────────────────\nxhs login                             # Extract cookies from browser\nxhs status                            # Check login status\nxhs whoami                            # Detailed profile (fans, likes, etc)\nxhs whoami --json                     # Structured JSON envelope\nxhs logout                            # Clear saved cookies\n\n# ─── Search ───────────────────────────────────────\nxhs search \"美食\"                      # Search notes\nxhs search \"旅行\" --sort popular       # Sort: general, popular, latest\nxhs search \"穿搭\" --type video         # Filter: all, video, image\nxhs search \"AI\" --page 2              # Pagination\nxhs search-user \"用户名\"               # Search users\nxhs topics \"美食\"                      # Search hashtags/topics\n\n# ─── Reading ────────────────────────────────"},{"path":"_meta.json","content":"{\n  \"ownerId\": \"kn757vsv03fbpevrxybjc424wh828377\",\n  \"slug\": \"xiaohongshu-cli\",\n  \"version\": \"0.2.1\",\n  \"publishedAt\": 1773162955955\n}"},{"path":"SCHEMA.md","content":"# Structured Output Schema\n\n`xiaohongshu-cli` uses a shared agent-friendly envelope for machine-readable output.\n\n## Success\n\n```yaml\nok: true\nschema_version: \"1\"\ndata: ...\n```\n\n## Error\n\n```yaml\nok: false\nschema_version: \"1\"\nerror:\n  code: not_authenticated\n  message: need login\n```\n\n## Notes\n\n- `--yaml` and `--json` both use this envelope\n- non-TTY stdout defaults to YAML\n- reading and search commands return their payload under `data`\n- `status` returns `data.authenticated` plus `data.user`\n- `whoami` returns `data.user`\n- common `error.code` values include `not_authenticated`, `verification_required`, `ip_blocked`, `signature_error`, `unsupported_operation`, and `api_error`"},{"path":"skill-card.md","content":"## Description:\n\nUse xiaohongshu-cli for Xiaohongshu operations including searching notes, reading content, browsing users, liking, collecting, commenting, following, and posting.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[jackwener](https://clawhub.ai/user/jackwener)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nExternal users and developers use this skill to let an agent operate the xiaohongshu-cli tool for Xiaohongshu reading, discovery, account interaction, and creator workflows. It is intended for authenticated CLI use with local browser cookies and structured YAML or JSON output.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill can use local browser-session cookies and perform authenticated Xiaohongshu actions.\n\nMitigation: Use a dedicated browser profile or test account, avoid sharing raw cookie values, and clear cached cookies with xhs logout when finished.\n\nRisk: Mutating commands can like, collect, comment, follow, post, or delete account content.\n\nMitigation: Review every mutating command before execution and require explicit user confirmation for account-changing actions.\n\nRisk: Aggressive or parallel requests may trigger captcha, rate limits, or IP blocks.\n\nMitigation: Do not parallelize requests; respect built-in delays and pause for browser captcha completion when verification is required.\n\nRisk: Integration tests and real API workflows may contact Xiaohongshu with live credentials.\n\nMitigation: Do not run integration tests casually; run only in an intentional test environment with credentials suitable for that purpose.\n\n## Reference(s):\n\n- [ClawHub skill page](https://clawhub.ai/jackwener/skills/xiaohongshu-cli)\n- [README](README.md)\n- [Structured Output Schema](SCHEMA.md)\n- [PyPI package](https://pypi.org/project/xiaohongshu-cli/)\n\n## Skill Output:\n\n**Output Type(s):** [Text, Markdown, Shell commands, Configuration, Guidance]\n\n**Output Format:** [Markdown guidance with inline shell commands; CLI results are YAML or JSON envelopes.]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Uses local browser-cookie authentication and may trigger authenticated account actions.]\n\n## Skill Version(s):\n\n0.2.1 (source: ClawHub release metadata and pyproject.toml)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment."}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"Use xiaohongshu-cli for ALL Xiaohongshu (Little Red Book, 小红书) operations — searching notes, reading content, browsing users, liking, collecting, commenting,... Skill: xiaohongshu-cli Owner: jackwener Summary: Use xiaohongshu-cli for ALL Xiaohongshu (Little Red Book, 小红书) operations — searching notes, reading content, browsing users, liking, collecting, commenting,... Tags: latest:0.2.1 Version history: v0.2.1 | 2026-03-10T17:15:55.955Z | user Release 0.2.1 v0.1.4 | 2026-03-08T18:16:50.706Z | user Sync SKILL.md: add 小红书 tag, safety notes v0.1.3 | 2026-03-05T17:59:13.818Z | u","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":1323,"uniquenessScore":49,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-11T21:12:33.861Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-11T21:12:33.861Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-12T19:57:56.730Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}