WeChat CLI

中文文档

A command-line tool to query your local WeChat data — chat history, contacts, sessions, favorites, and more. Designed for LLM integration with JSON output by default.

Features

• Self-contained — pip install + wechat-cli init, no external dependencies
• 11 commands — sessions, history, search, contacts, members, stats, export, favorites, unread, new-messages, init
• JSON by default — structured output for programmatic access
• Cross-platform — macOS, Windows, Linux
• On-the-fly decryption — SQLCipher databases decrypted transparently with caching
• Message type filtering — filter by text, image, link, file, video, etc.
• Chat statistics — top senders, type breakdown, hourly activity distribution
• Markdown export — export conversations as markdown or plain text

Quick Start

Install

Via pip (requires Python >= 3.10):

pip install wechat-cli

Via npm (standalone binary, no Python needed):

npm install -g @canghe_ai/wechat-cli

Currently only macOS arm64 binary is available. Other platforms (macOS Intel, Linux, Windows) can use the pip install method. PRs with additional platform binaries are welcome.

Or install from source:

git clone https://github.com/freestylefly/wechat-cli.git
cd wechat-cli
pip install -e .

Initialize

Make sure WeChat is running, then:

# macOS/Linux: may need sudo for memory scanning
sudo wechat-cli init

# Windows: run in a terminal with sufficient privileges
wechat-cli init

This will:

1. Auto-detect your WeChat data directory
2. Extract encryption keys from WeChat process memory
3. Save config and keys to ~/.wechat-cli/

That's it — you're ready to go.

Commands

sessions — Recent Chats

wechat-cli sessions                        # Last 20 sessions (JSON)
wechat-cli sessions --limit 10             # Last 10
wechat-cli sessions --format text          # Human-readable

history — Chat Messages

wechat-cli history "Alice"                 # Last 50 messages
wechat-cli history "Alice" --limit 100 --offset 50
wechat-cli history "Team" --start-time "2026-04-01" --end-time "2026-04-03"
wechat-cli history "Alice" --type link     # Only links/files
wechat-cli history "Alice" --format text

Options: --limit, --offset, --start-time, --end-time, --type, --format

search — Search Messages

wechat-cli search "hello"                  # Global search
wechat-cli search "hello" --chat "Alice"   # In specific chat
wechat-cli search "meeting" --chat "TeamA" --chat "TeamB"  # Multiple chats
wechat-cli search "report" --type file     # Only files
wechat-cli search "hello" --start-time "2026-04-01" --limit 50

Options: --chat (repeatable), --start-time, --end-time, --limit, --offset, --type, --format

contacts — Contact Search & Details

wechat-cli contacts --query "Li"           # Search contacts
wechat-cli contacts --detail "Alice"       # View contact details
wechat-cli contacts --detail "wxid_xxx"    # By WeChat ID

Details include: nickname, remark, WeChat ID (alias), bio, avatar URL, account type.

members — Group Members

wechat-cli members "Team Group"            # List all members (JSON)
wechat-cli members "Team Group" --format text

Shows member list with display names and group owner.

stats — Chat Statistics

wechat-cli stats "Team Group"
wechat-cli stats "Alice" --start-time "2026-04-01" --end-time "2026-04-03"
wechat-cli stats "Team Group" --format text

Returns: total messages, type breakdown, top 10 senders, 24-hour activity distribution.

export — Export Conversations

wechat-cli export "Alice" --format markdown              # To stdout
wechat-cli export "Alice" --format txt --output chat.txt  # To file
wechat-cli export "Team" --start-time "2026-04-01" --limit 1000

Options: --format markdown|txt, --output, --start-time, --end-time, --limit

favorites — WeChat Bookmarks

wechat-cli favorites                       # Recent bookmarks
wechat-cli favorites --type article        # Articles only
wechat-cli favorites --query "machine learning"  # Search

Types: text, image, article, card, video

unread — Unread Sessions

wechat-cli unread                          # All unread sessions
wechat-cli unread --limit 10 --format text

new-messages — Incremental New Messages

wechat-cli new-messages                    # First call: return unread + save state
wechat-cli new-messages                    # Subsequent: only new since last call

State persists at ~/.wechat-cli/last_check.json. Delete it to reset.

Message Type Filter

The --type option (available on history and search) accepts:

Value	Description
text	Text messages
image	Images
voice	Voice messages
video	Videos
sticker	Stickers/emojis
location	Location shares
link	Links and app messages
file	File attachments
call	Voice/video calls
system	System messages

Use Cases

LLM / AI Tool Integration

# For Claude Code, Cursor, or any AI tool that can run shell commands
wechat-cli sessions --limit 5
wechat-cli history "Alice" --limit 20 --format text
wechat-cli search "deadline" --chat "Team" --type text

All commands output JSON by default, making them ideal for AI agent tool calls.

Chat Analysis

# Who talks the most in a group?
wechat-cli stats "Team Group" --format text

# Find all shared links in a conversation
wechat-cli history "Alice" --type link --limit 50

# Search for a specific file
wechat-cli search "report.xlsx" --type file

Data Backup

# Export important conversations
wechat-cli export "Team Group" --format markdown --output team_chat.md
wechat-cli export "Alice" --start-time "2026-01-01" --format txt --output alice_2026.txt

Notification Monitoring

# Cron job to check for new messages every 5 minutes
*/5 * * * * wechat-cli new-messages --format text

Platform Support

Platform	Status	Notes
macOS (Apple Silicon)	Supported	Bundled arm64 binary for key extraction
macOS (Intel)	Supported	x86_64 binary needed
Windows	Supported	Reads Weixin.exe process memory
Linux	Supported	Reads /proc/pid/mem, requires root

How It Works

WeChat stores chat data in SQLCipher-encrypted SQLite databases on your local machine. WeChat CLI:

1. Extracts keys — scans WeChat process memory to find encryption keys (wechat-cli init)
2. Decrypts on-the-fly — transparently decrypts databases with page-level AES-256-CBC + caching
3. Queries locally — all data stays on your machine, no network access required

Requirements

• Python >= 3.10
• WeChat running locally (for init key extraction)

License

Apache License 2.0