xhs-cli

メモ

代替パッケージの xiaohongshu-cli も利用できます。リバースエンジニアリングされた API を使用するため、より高速に動作します。 このパッケージ（xhs-cli）はヘッドレスブラウザー（camoufox）を使用する方式です。動作は遅めですが、リスク制御による検出への耐性が高くなっています。 ニーズに最適な方をお選びください。

xhs-cli スキル

Xiaohongshu（小红书）を操作するための CLI ツールです。ノートの検索、詳細の閲覧、ユーザープロフィールの確認、いいね、お気に入り登録、コメントなどの操作に使用できます。

前提条件

# Install (requires Python 3.8+)
uv tool install xhs-cli
# Or: pipx install xhs-cli

認証

すべてのコマンドを使用するには、有効な Cookie が必要です。

xhs status                     # Check saved login session (no browser extraction)
xhs login                      # Auto-extract Chrome cookies
xhs login --cookie "a1=..."    # Or provide cookies manually

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

コマンドリファレンス

検索

xhs search "咖啡"              # Search notes (rich table output)
xhs search "咖啡" --json       # Raw JSON output

ノートを読む

# View note (xsec_token auto-resolved from search cache)
xhs read <note_id>
xhs read <note_id> --comments  # Include comments
xhs read <note_id> --xsec-token <token>  # Manual token
xhs read <note_id> --json

ユーザー

# Look up user profile (by internal user_id, hex format)
xhs user <user_id>
xhs user <user_id> --json

# List user's published notes
xhs user-posts <user_id>
xhs user-posts <user_id> --json

# Followers / Following
xhs followers <user_id>
xhs following <user_id>

ディスカバリー

xhs feed                       # Explore page recommended feed
xhs feed --json
xhs topics "旅行"              # Search topics/hashtags
xhs topics "旅行" --json

インタラクション（ログインが必要）

# Like / Unlike (xsec_token auto-resolved)
xhs like <note_id>
xhs like <note_id> --undo

# Favorite / Unfavorite
xhs favorite <note_id>
xhs favorite <note_id> --undo

# Comment
xhs comment <note_id> "好棒！"

# Delete your own note
xhs delete <note_id>

お気に入り

xhs favorites                  # List your favorites
xhs favorites --max 10         # Limit count
xhs favorites --json

投稿

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

アカウント

xhs status                     # Quick saved-session check
xhs whoami                     # Full profile info
xhs whoami --json
xhs login                      # Login
xhs logout                     # Clear cookies

JSON 出力

主要なクエリコマンドでは、機械可読な出力を得るために --json を指定できます。

xhs search "咖啡" --json | jq '.[0].id'           # First note ID
xhs whoami --json | jq '.userInfo.userId'          # Your user ID
xhs favorites --json | jq '.[0].displayTitle'      # First favorite title

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

# Get your user ID for further queries
xhs whoami --json | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('userInfo',{}).get('userId',''))"

# Search and get note IDs (xsec_token auto-cached for later use)
xhs search "topic" --json | python3 -c "import sys,json; [print(n['id']) for n in json.load(sys.stdin)[:3]]"

# Check login before performing actions
xhs status && xhs like <note_id>

# Read a note with comments for summarization
xhs read <note_id> --comments --json

エラー処理

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

安全上の注意

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