xiaohongshu-cli

xiaohongshu-cli — Xiaohongshu CLI ツール

バイナリ： xhs 認証情報： ブラウザー Cookie（自動抽出）またはブラウザーを利用した QR ログイン（--qrcode）

セットアップ

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

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

認証

エージェント向けの重要事項：xhs コマンドを実行する前に、必ず認証情報が存在するか確認してください。Cookie が設定済みだと思い込まないでください。

ステップ 0：すでに認証済みか確認する

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

AUTH_OK の場合は、コマンドリファレンスに進んでください。 AUTH_NEEDED の場合は、ステップ 1 に進んでください。ブラウザー Cookie の抽出ができないものの、ブラウザーの起動が許容される場合は、--qrcode を優先してください。

ステップ 1：ユーザーに認証を案内する

browser_cookie3 がサポートする任意のブラウザーで、xiaohongshu.com にログインしていることを確認してください。サポートされているブラウザー：Chrome、Arc、Edge、Firefox、Safari、Brave、Chromium、Opera、Opera GX、Vivaldi、LibreWolf、Lynx、w3m。その後、次を実行します。

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

次のコマンドで確認します。

xhs status
xhs whoami

ステップ 2：よくある認証の問題に対処する

症状	エージェントの対応
NoCookieError: No 'a1' cookie found	ブラウザーで xiaohongshu.com にログインするようユーザーに案内します
NeedVerifyError: Captcha required	ブラウザーを開いて CAPTCHA を完了し、再試行するようユーザーに依頼します
IpBlockedError: IP blocked	ネットワーク（ホットスポット／VPN）の切り替えを提案します
SessionExpiredError	xhs login を実行して Cookie を更新します

エージェントのデフォルト設定

機械可読形式の出力はすべて、SCHEMA.md に記載されているエンベロープを使用します。 ペイロードは .data の下に格納されます。

• 非 TTY の標準出力 → YAML を自動選択
• --json / --yaml → 出力形式を明示的に指定
• OUTPUT=json 環境変数 → グローバルな出力形式の上書き
• OUTPUT=rich 環境変数 → 人間向けの出力を強制

コマンドリファレンス

閲覧

コマンド	説明	例
xhs search <keyword>	ノートを検索	xhs search "美食" --sort popular --type video
xhs read <id_or_url_or_index>	ID、URL、または短縮インデックスでノートを読む	xhs read 1 / xhs read "https://...?xsec_token=xxx"
xhs comments <id_or_url_or_index>	ID、URL、または短縮インデックスでコメントを取得	xhs comments 1 / xhs comments "https://...?xsec_token=..."
xhs comments <id_or_url> --all	すべてのコメントを取得（自動ページネーション）	xhs comments "<url>" --all --json
xhs sub-comments <note_id> <comment_id>	コメントへの返信を取得	xhs sub-comments abc 123
xhs user <user_id>	ユーザープロフィールを表示	xhs user 5f2e123
xhs user-posts <user_id>	ユーザーのノート一覧を表示	xhs user-posts 5f2e123 --cursor ""
xhs feed	おすすめフィードを閲覧	xhs feed --yaml
xhs hot	トレンドのノートを閲覧	xhs hot -c food
xhs topics <keyword>	トピック／ハッシュタグを検索	xhs topics "旅行"
xhs search-user <keyword>	ユーザーを検索	xhs search-user "摄影"
xhs my-notes	自分が公開したノートの一覧を表示	xhs my-notes --page 0
xhs notifications	通知を表示	xhs notifications --type likes
xhs unread	未読数を表示	xhs unread --json

インタラクション（書き込み）

コマンド	説明	例
xhs like <id_or_url_or_index>	ノートに「いいね」する	xhs like 1 / xhs like abc123
xhs like <id_or_url_or_index> --undo	ノートの「いいね」を取り消す	xhs like 1 --undo
xhs favorite <id_or_url_or_index>	ノートをブックマークする	xhs favorite 1
xhs unfavorite <id_or_url_or_index>	ブックマークを解除する	xhs unfavorite 1
xhs comment <id_or_url_or_index> -c "text"	コメントを投稿する	xhs comment 1 -c "好看！"
xhs reply <id_or_url_or_index> --comment-id ID -c "text"	コメントに返信する	xhs reply 1 --comment-id 456 -c "谢谢"
xhs delete-comment <note_id> <comment_id>	自分のコメントを削除する	xhs delete-comment abc 123 -y

ソーシャル

コマンド	説明	例
xhs follow <user_id>	ユーザーをフォローします	xhs follow 5f2e123
xhs unfollow <user_id>	ユーザーのフォローを解除します	xhs unfollow 5f2e123
xhs favorites [user_id]	ブックマークしたノートを一覧表示します（省略時は自分）	xhs favorites --json

クリエイター

コマンド	説明	例
xhs post --title "..." --body "..." --images img.png	ノートを公開します	xhs post --title "Test" --body "Hello"
xhs delete <id_or_url>	自分のノートを削除します	xhs delete abc123 -y

アカウント

コマンド	説明
xhs login	ブラウザーからCookieを抽出します（自動検出）
xhs login --qrcode	ブラウザー支援によるQRログインです。ターミナルにQRコードを表示し、ブラウザーでログインを完了します
xhs status	認証状態を確認します
xhs logout	キャッシュされたCookieを消去します
xhs whoami	現在のユーザープロフィールを表示します

エージェントのワークフロー例

検索 → 読む → いいねのパイプライン

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

人気のグルメノートを閲覧

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

ユーザー情報を取得してからフォロー

xhs user 5f2e123 --json | jq '.data.basic_info | {nickname, user_id}'
xhs follow 5f2e123

通知を確認

xhs unread --json | jq '.data'
xhs notifications --type mentions --json | jq '.data.message_list[:5]'

ノートのコメントをすべて分析

# Fetch ALL comments and analyze themes
xhs comments "$NOTE_URL" --all --json | jq '.data.comments | length'
# Count questions
xhs comments "$NOTE_URL" --all --json | jq '[.data.comments[] | select(.content | test("[\uff1f?]"))] | length'

毎日の読書ワークフロー

# Browse recommendation feed
xhs feed --yaml

# Interactive short-index workflow
xhs search "旅行"
xhs read 1
xhs comments 1
xhs like 1
xhs favorite 1
xhs comment 1 -c "收藏了"

# Browse trending by category
xhs hot -c food --yaml
xhs hot -c travel --yaml

QRコードでログイン

# When browser cookie extraction is not available
xhs login --qrcode
# → Launches a browser-assisted login flow
# → Renders QR in terminal using Unicode half-blocks
# → Scan with Xiaohongshu app → confirm → export cookies

URLからインサイトを取得するパイプライン

# User pastes a URL → read + all comments
xhs read "https://www.xiaohongshu.com/explore/xxx?xsec_token=yyy" --json
xhs comments "https://www.xiaohongshu.com/explore/xxx?xsec_token=yyy" --all --json

人気のカテゴリー

xhs hot -c <category> で利用できます： fashion、food、cosmetics、movie、career、love、home、gaming、travel、fitness

エラーコード

error.code フィールドで返される構造化エラーコード：

• not_authenticated — Cookieの有効期限切れ、または未設定
• verification_required — CAPTCHAまたは認証が必要です
• ip_blocked — IPがレート制限されています
• signature_error — リクエストの署名に失敗しました
• api_error — 上流APIエラー
• unsupported_operation — この操作は利用できません

制限事項

• 動画のダウンロード不可 — ノートの画像や動画をダウンロードできません
• DM不可 — プライベートメッセージにアクセスできません
• ライブ配信不可 — ライブ機能はサポートされていません
• フォロー中・フォロワーの一覧表示不可 — XHSのWeb APIではこれらのエンドポイントが公開されていません
• 単一アカウント — 一度に使用できるCookieのセットは1つです
• レート制限あり — リクエスト間にガウス分布に基づくジッター遅延（約1～1.5秒）が組み込まれています。過度な使用はCAPTCHAやIPブロックを招く可能性があります

エージェント向けの検出回避に関する注意

• リクエストを並列化しないでください — 組み込みのレート制限遅延はアカウントの安全を守るためのものです
• CAPTCHAからの復旧：NeedVerifyError が発生した場合、クライアントは遅延時間を段階的に増やして自動的にクールダウンします（5秒→10秒→20秒→30秒）。再試行する前に、ブラウザーでCAPTCHAを完了するようユーザーに依頼してください
• バッチ処理：大量の処理（例：多数のノートを読む）を行う場合は、CLIの呼び出し間に time.sleep() を追加してください
• セッションの安定性：1つのセッション内のすべてのリクエストで、一貫したブラウザーフィンガープリントが共有されます。CLIを再起動すると、新しいフィンガープリントのセッションが作成されます

安全上の注意

• チャットログでCookieの生の値を共有するようユーザーに求めないでください。
• 手動で秘密情報をコピー＆ペーストするより、ローカルブラウザーからCookieを抽出する方法を優先してください。
• 認証に失敗した場合は、xhs login で再ログインするようユーザーに依頼してください。
• エージェントはCookieの値を秘密情報として扱ってください（不要に標準出力へ出力しないでください）。
• 組み込みのレート制限遅延はアカウントを保護します。これを回避しないでください。