wx-cli-wechat-local-data

# wx-cli: WeChat Local Data CLI > Skill by [ara.so](https://ara.so) — Devtools Skills collection. Query and export local WeChat data (messages, contacts, moments, favorites, public account articles) from the command line. Built in Rust with a daemon architecture that caches decrypted databases for millisecond-level responses. ## What it does `wx-cli` provides a command-line interface to your local WeChat data without network calls. It: - Scans WeChat's memory to extract database encryption keys - Maintains a background daemon that caches decrypted databases (reuses cache if mtime unchanged) - Queries messages, contacts, groups, moments (SNS), favorites, and public account articles - Extracts and decodes image attachments (.dat files) - Returns structured JSON with metadata about data freshness **Key features:** - Zero-dependency single binary - Fully local (no data leaves your machine) - AI-friendly JSON output with `meta` wrapper for freshness/source info - Supports incremental queries (`new-messages` returns only messages since last check) ## Installation **npm (recommended, cross-platform):** ```bash npm install -g @jackwener/wx-cli ``` **macOS / Linux (curl):** ```bash curl -fsSL https://raw.githubusercontent.com/jackwener/wx-cli/main/install.sh | bash ``` **Windows (PowerShell as Administrator):** ```powershell irm https://raw.githubusercontent.com/jackwener/wx-cli/main/install.ps1 | iex ``` ## Initial Setup Keep WeChat running, then initialize (one-time): ### macOS Ad-hoc signing is required to scan WeChat's memory: ```bash # 1. Sign WeChat (once per WeChat update) codesign --force --deep --sign - /Applications/WeChat.app # 2. Reset TCC privacy records (required after re-signing) for s in ScreenCapture Camera Microphone AppleEvents AddressBook \ SystemPolicyDocumentsFolder SystemPolicyDownloadsFolder SystemPolicyDesktopFolder; do tccutil reset "$s" com.tencent.xinWeChat done # 3. Restart WeChat and wait for full login killall WeChat && open /Applications/WeChat.app # 4. Initialize wx-cli sudo wx init ``` If `codesign` reports `signature in use`: ```bash codesign --remove-signature "/Applications/WeChat.app/Contents/Frameworks/vlc_plugins/librtp_mpeg4_plugin.dylib" codesign --force --deep --sign - /Applications/WeChat.app ``` ### Linux ```bash sudo wx init ``` ### Windows Run PowerShell as Administrator: ```powershell wx init ``` **Verify installation:** ```bash wx sessions ``` If you see recent sessions, setup is complete. The daemon starts automatically on first command. ## Core Commands ### Messages & Sessions ```bash # Recent sessions (conversations) wx sessions # Unread sessions only wx unread # Filter unread (exclude official accounts and folded entries) wx unread --filter private,group # New messages since last check (incremental) wx new-messages # Chat history with a contact/group wx history "张三" wx history "张三" -n 2000 # More messages wx history "AI群" --since 2026-04-01 --until 2026-04-15 # Search across all messages wx search "关键词" wx search "关键词" -n 500 # More results wx search "会议" --in "工作群" --since 2026-01-01 ``` **JSON output structure:** ```rust // history, search, sessions, new-messages, stats, attachments { "data": [...], "meta": { "status": "ok" | "possibly_stale" | "windowed", "unknown_shards": ["message_3.db"], // If non-empty, run `wx init --force` "chat_latest_timestamp": "2026-05-16T12:34:56+08:00", "chat_latest_db": "message_2.db", "session_last_timestamp": "2026-05-16T14:20:00+08:00" } } ``` **Message fields:** ```json { "time": "2026-05-16 10:23:45", "timestamp": 1715832225, "sender": "张三", "content": "消息内容", "type": "text", "chat_type": "private", "is_self": false } ``` - `chat_type`: `private` | `group` | `official_account` | `folded` - `type`: `text` | `image` | `video` | `file` | `link` | `voice` | `system` | etc. **Quoted messages:** History/search output shows quoted replies with original context: ```text [引用] 当前回复 ↳ 发送者: 被引用内容 ``` ### Contacts & Groups ```bash # List contacts wx contacts wx contacts --query "李" # Search by name # List group members (prioritizes group nicknames) wx members "AI交流群" wx members "AI交流群" --json # JSON with username/display/group_nickname/is_owner ``` **Member JSON structure:** ```json { "username": "wxid_abc123", "display": "李四 (群昵称)", "contact_display": "李四", "group_nickname": "群昵称", "is_owner": false } ``` ### Moments (SNS) Three separate commands for notifications vs. posts: ```bash # Like/comment notifications (unread by default) wx sns-notifications wx sns-notifications --include-read -n 100 # Moments timeline (your feed) wx sns-feed wx sns-feed --user "张三" -n 100 wx sns-feed --since 2026-04-01 # Search moments content wx sns-search "关键词" wx sns-search "婚礼" --user "李四" --since 2023-01-01 ``` **sns-notifications output:** ```json { "type": "like" | "comment", "from_nickname": "张三", "content": "评论内容", "feed_preview": "原帖正文片段", "feed_author": "李四", "timestamp": 1715832225 } ``` **sns-feed / sns-search output:** ```json { "author": "张三", "content": "朋友圈正文", "media": [ { "url": "...", "thumb": "...", "key": "...", "token": "...", "md5": "...", "enc_idx": 0, "size": 123456 } ], "media_count": 1, "location": "北京", "timestamp": 1715832225 } ``` ### Public Account Articles Official/subscription account articles are stored separately: ```bash # Recent articles wx biz-articles wx biz-articles -n 200 # Filter by account name wx biz-articles --account "返朴" # Time range wx biz-articles --since 2026-05-01 --until 2026-05-10 # Unread only (1 latest per account) wx biz-articles --unread # Extract URLs wx biz-articles --json | jq '.[].url' ``` **Output fields:** ```json { "account": "返朴", "account_username": "gh_abc123", "title": "文章标题", "url": "https://mp.weixin.qq.com/...", "digest": "摘要", "cover_url": "...", "time": "2026-05-16 10:00:00", "timestamp": 1715832000, "recv_time_str": "2026-05-16 10:01:23" } ``` ### Attachments (Images) Image attachments are stored as `.dat` files that require decryption: ```bash # 1. List image attachments in a conversation wx attachments "张三" wx attachments "AI群" --kind image -n 100 wx attachments "AI群" --since 2026-04-01 --until 2026-04-15 # 2. Extract a specific attachment by ID wx extract <attachment_id> -o ~/Desktop/photo.jpg wx extract <attachment_id> -o /tmp/x.jpg --overwrite ``` **attachments output:** ```json { "attachment_id": "opaque-id-123", "kind": "image", "type": 3, "local_id": 456, "timestamp": 1715832225, "time": "2026-05-16 10:23:45", "sender": "张三" } ``` **extract output:** ```json { "md5": "abc123...", "dat_path": "/.../msg/attach/.../abc.dat", "dat_size": 123456, "output": "~/Desktop/photo.jpg", "output_size": 120000, "format": "jpg", "decoder": "v2" } ``` Supported decoders: - `legacy_xor`: Early single-byte XOR (no magic header) - `v1_aes`: Fixed AES-128-ECB with hardcoded key - `v2`: AES + XOR with platform-derived keys ### Favorites & Statistics ```bash # All favorites wx favorites wx favorites --type image # Filter by type: text/image/article/card/video wx favorites --since 2026-01-01 # Conversation statistics wx stats "AI群" # Message counts by sender (top 10) wx stats "AI群" --top 20 # More senders ``` ### Export ```bash # Export to text file wx export "张三" -o chat.txt # Export to JSON wx export "AI群" -o chat.json --format json wx export "AI群" -o chat.json --format json --since 2026-04-01 ``` ## Configuration ### Daemon Management The daemon starts automatically on first command. Manual control: ```bash # Check daemon status wx status # Stop daemon wx stop # Restart daemon wx stop && wx sessions # Any query command restarts it # Force re-initialize (re-scan WeChat memory) wx init --force ``` ### Environment Variables wx-cli reads configuration from standard WeChat data paths. No env vars required for normal operation. **Logging:** ```bash # Enable debug logging (not typically needed) RUST_LOG=debug wx history "张三" ``` ## Common Patterns ### Monitor new messages in a script ```bash #!/bin/bash while true; do wx new-messages --json | jq -r '.data[] | "\(.time) \(.sender): \(.content)"' sleep 60 done ``` ### Export all conversations since date ```bash for session in $(wx sessions --json | jq -r '.[].username'); do wx export "$session" -o "backup/${session}.json" --format json --since 2026-01-01 done ``` ### Search for keywords and extract context ```bash wx search "项目" --json | jq -r '.data[] | "\(.time) [\(.sender)] \(.content)"' ``` ### Get unread count per conversation ```bash wx unread --json | jq '.[] | "\(.unread_count)\t\(.remark)"' ``` ### Extract all images from a date range ```bash # 1. Get attachment IDs wx attachments "旅行群" --since 2026-05-01 --json | jq -r '.data[].attachment_id' > ids.txt # 2. Extract each mkdir -p images while read id; do wx extract "$id" -o "images/${id}.jpg" 2>/dev/null done < ids.txt ``` ### Check data freshness in automation ```bash result=$(wx history "张三" --json) status=$(echo "$result" | jq -r '.meta.status') if [ "$status" != "ok" ]; then echo "Warning: Data may be stale. Unknown shards:" echo "$result" | jq '.meta.unknown_shards' echo "Run: wx init --force" fi ``` ## Troubleshooting