wx-cli-wechat-local-data

wx-cli: WeChat Local Data CLI

Skill by 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):

npm install -g @jackwener/wx-cli

macOS / Linux (curl):

curl -fsSL https://raw.githubusercontent.com/jackwener/wx-cli/main/install.sh | bash

Windows (PowerShell as Administrator):

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:

# 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:

codesign --remove-signature "/Applications/WeChat.app/Contents/Frameworks/vlc_plugins/librtp_mpeg4_plugin.dylib"
codesign --force --deep --sign - /Applications/WeChat.app

Linux

sudo wx init

Windows

Run PowerShell as Administrator:

wx init

Verify installation:

wx sessions

If you see recent sessions, setup is complete. The daemon starts automatically on first command.

Core Commands

Messages & Sessions

# 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:

// 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:

{
  "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:

[引用] 当前回复
  ↳ 发送者: 被引用内容

Contacts & Groups

# 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:

{
  "username": "wxid_abc123",
  "display": "李四 (群昵称)",
  "contact_display": "李四",
  "group_nickname": "群昵称",
  "is_owner": false
}

Moments (SNS)

Three separate commands for notifications vs. posts:

# 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:

{
  "type": "like" | "comment",
  "from_nickname": "张三",
  "content": "评论内容",
  "feed_preview": "原帖正文片段",
  "feed_author": "李四",
  "timestamp": 1715832225
}

sns-feed / sns-search output:

{
  "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:

# 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:

{
  "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:

# 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:

{
  "attachment_id": "opaque-id-123",
  "kind": "image",
  "type": 3,
  "local_id": 456,
  "timestamp": 1715832225,
  "time": "2026-05-16 10:23:45",
  "sender": "张三"
}

extract output:

{
  "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

# 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

# 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:

# 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:

# Enable debug logging (not typically needed)
RUST_LOG=debug wx history "张三"

Common Patterns

Monitor new messages in a script

#!/bin/bash
while true; do
  wx new-messages --json | jq -r '.data[] | "\(.time) \(.sender): \(.content)"'
  sleep 60
done

Export all conversations since date

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

wx search "项目" --json | jq -r '.data[] | "\(.time) [\(.sender)] \(.content)"'

Get unread count per conversation

wx unread --json | jq '.[] | "\(.unread_count)\t\(.remark)"'

Extract all images from a date range

# 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

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

macOS: "Operation not permitted"

# Re-sign WeChat
codesign --force --deep --sign - /Applications/WeChat.app

# Reset TCC and reinitialize
for s in ScreenCapture Camera Microphone AppleEvents; do
  tccutil reset "$s" com.tencent.xinWeChat
done
killall WeChat && open /Applications/WeChat.app
sudo wx init --force

macOS: "WeChat 想访问其他 App 的数据" popups

This is a known side effect of re-signing. The popup occurs because macOS treats the re-signed WeChat as a different app accessing its old container. Click "Allow" to proceed. To avoid popups, you'd need to use official WeChat signature (which requires SSH-free local Terminal with Developer Tools TCC access).

Windows: No decryption keys found

# Make sure WeChat is fully logged in
# Run as Administrator
wx init --force

"unknown_shards" in meta output

WeChat may have created new message_N.db shards since initialization:

wx init --force

Daemon not responding

wx stop
wx sessions  # Restarts daemon

Empty results but WeChat has data

# Force refresh all caches
wx init --force

# Check daemon status
wx status

Image extraction fails with "unsupported decoder"

On Linux, V2 image keys are not yet supported. Legacy XOR and V1 AES work. On macOS/Windows, ensure WeChat is running during wx init.

Advanced Usage

Custom limit for large queries

# Default limits are conservative to avoid overwhelming output
wx history "张三" -n 10000
wx search "keyword" -n 5000
wx sns-feed -n 500

Filter messages by type

# Links, files, merged chat records, quoted messages
wx history "AI群" --type link --json

# Images only
wx history "AI群" --type image --json

Include metadata in all outputs

# Human-readable warnings go to stderr
wx history "张三" 2>&1 | grep "WARNING"

# Machine-readable meta in JSON stdout
wx history "张三" --json | jq '.meta'

# Extended meta with per-shard details
wx history "张三" --with-meta --json | jq '.meta.per_shard_latest'

Export with custom time windows

wx export "项目群" -o q1-2026.json --format json \
  --since 2026-01-01 --until 2026-03-31

Integration with AI Agents

wx-cli is designed for AI agent consumption:

1. Install via skills:

   npx skills add jackwener/wx-cli
   

2. Structured output: All query commands return JSON with {data, meta} wrapper

3. Freshness indicators: meta.status tells agents if data may be stale

4. Incremental queries: new-messages returns only messages since last check

5. Error handling: Non-zero exit codes + stderr for errors; JSON always valid on stdout

Example agent prompt:

"Check my WeChat for any messages from 李四 in the last week mentioning '合同'"

Agent execution:

wx search "合同" --in "李四" --since $(date -d '7 days ago' +%Y-%m-%d) --json

Documentation

• GitHub: https://github.com/jackwener/wx-cli
• Installation: See install.sh / install.ps1 in repo
• macOS Permission Guide: docs/macos-permission-guide.md

License

Apache-2.0