f51e89ce12
- Add npm package structure (@canghe_ai/wechat-cli) with platform-specific optionalDependencies - Add JS wrapper (bin/wechat-cli.js) and postinstall script - Add PyInstaller entry point and build script - Update scanner_macos.py for PyInstaller compatibility (sys._MEIPASS) - Update README with npm install instructions (macOS arm64) - Fix repo URLs to freestylefly/wechat-cli
245 lines
6.9 KiB
Markdown
245 lines
6.9 KiB
Markdown
# WeChat CLI
|
|
|
|
[中文文档](README_CN.md)
|
|
|
|
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):**
|
|
|
|
```bash
|
|
pip install wechat-cli
|
|
```
|
|
|
|
**Via npm (standalone binary, no Python needed):**
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
git clone https://github.com/freestylefly/wechat-cli.git
|
|
cd wechat-cli
|
|
pip install -e .
|
|
```
|
|
|
|
### Initialize
|
|
|
|
Make sure WeChat is running, then:
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
wechat-cli sessions # Last 20 sessions (JSON)
|
|
wechat-cli sessions --limit 10 # Last 10
|
|
wechat-cli sessions --format text # Human-readable
|
|
```
|
|
|
|
### history — Chat Messages
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
wechat-cli unread # All unread sessions
|
|
wechat-cli unread --limit 10 --format text
|
|
```
|
|
|
|
### new-messages — Incremental New Messages
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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](LICENSE)
|