[!NOTE] リバースエンジニアリングされたAPIを使用する代替パッケージ xiaohongshu-cli も利用可能です。こちらはより高速です。 このパッケージ (xhs-cli) はヘッドレスブラウザ (camoufox) を使用しています — 低速ですがリスク制御検知への耐性が高いです。 必要に応じてどちらかを選択してください。

xhs-cli スキル

Xiaohongshu (小红书) と連携するCLIツールです。ノート検索、詳細閲覧、ユーザープロフィール参照、いいね、お気に入り、コメントなどのインタラクション操作に使用できます。

前提条件

# インストール (Python 3.8以上が必要)
uv tool install xhs-cli
# または: pipx install xhs-cli

認証

すべてのコマンドは有効なCookieが必要です。

xhs status                     # 保存済みログインセッションを確認 (ブラウザ抽出なし)
xhs login                      # Chrome Cookieを自動抽出
xhs login --cookie "a1=..."    # またはCookieを手動で入力

認証は最初に保存済みのローカルCookieを使用します。利用できない場合、browser-cookie3を介してローカルChromeのCookieを自動検出します。抽出に失敗した場合、QRコードログインが利用可能です。

コマンドリファレンス

検索

xhs search "咖啡"              # ノート検索 (リッチテーブル出力)
xhs search "咖啡" --json       # JSON形式の出力

ノート閲覧

# ノート表示 (xsec_tokenは検索キャッシュから自動解決)
xhs read <note_id>
xhs read <note_id> --comments  # コメントを含める
xhs read <note_id> --xsec-token <token>  # トークンを手動指定
xhs read <note_id> --json

ユーザー

# ユーザープロフィール検索 (内部user_id、16進数形式)
xhs user <user_id>
xhs user <user_id> --json

# ユーザーが公開したノート一覧
xhs user-posts <user_id>
xhs user-posts <user_id> --json

# フォロワー / フォロー中
xhs followers <user_id>
xhs following <user_id>

ディスカバリー

xhs feed                       # 発見ページのおすすめフィード
xhs feed --json
xhs topics "旅行"              # トピック/ハッシュタグ検索
xhs topics "旅行" --json

インタラクション (ログインが必要)

# いいね / いいね解除 (xsec_tokenは自動解決)
xhs like <note_id>
xhs like <note_id> --undo

# お気に入り / お気に入り解除
xhs favorite <note_id>
xhs favorite <note_id> --undo

# コメント
xhs comment <note_id> "好棒！"

# 自分のノートを削除
xhs delete <note_id>

お気に入り

xhs favorites                  # お気に入り一覧表示
xhs favorites --max 10         # 件数を制限
xhs favorites --json

投稿

xhs post "标题" --image photo1.jpg --image photo2.jpg --content "正文"
xhs post "标题" --image photo1.jpg --content "正文" --json

アカウント

xhs status                     # 保存済みセッションの簡易確認
xhs whoami                     # 完全なプロフィール情報
xhs whoami --json
xhs login                      # ログイン
xhs logout                     # Cookieをクリア

JSON出力

主なクエリコマンドは --json オプションでマシンが読み取れる形式で出力できます。

xhs search "咖啡" --json | jq '.[0].id'           # 最初のノートID
xhs whoami --json | jq '.userInfo.userId'          # 自分のユーザーID
xhs favorites --json | jq '.[0].displayTitle'      # 最初のお気に入りタイトル

AIエージェント向けの一般的なパターン

# 今後のクエリに使用するユーザーIDを取得
xhs whoami --json | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('userInfo',{}).get('userId',''))"

# ノートを検索してIDを取得 (xsec_tokenは自動的にキャッシュされて後で使用可能)
xhs search "topic" --json | python3 -c "import sys,json; [print(n['id']) for n in json.load(sys.stdin)[:3]]"

# アクション実行前にログイン状態を確認
xhs status && xhs like <note_id>

# 要約用にコメント付きでノートを読む
xhs read <note_id> --comments --json

エラーハンドリング

• コマンドは成功時に終了コード0、失敗時に0以外で終了します
• エラーメッセージの先頭に ❌ が付きます
• ログイン必須のコマンドでは xhs login 実行を促す明確な指示が表示されます
• xsec_token はキャッシュから自動解決され、フォールバック用に手動指定の --xsec-token を使用できます

セーフティに関する注意事項

• ユーザーにチャットログで生のCookie値を共有するよう促さないでください
• 手動によるCookie入力よりも xhs login での自動抽出を優先してください
• 認証に失敗した場合、ユーザーに xhs login でのログイン再実行を案内してください