wechat-cli

A command-line tool for reading WeChat chat records from the local macOS database.

Features

• Auto-detect WeChat data paths (supports both new and old WeChat formats)
• Extract database encryption keys directly from WeChat process memory
• List contacts, groups, and recent chats
• Read message history for any contact or group
• Single binary — no external scripts or tools needed for key extraction

Prerequisites

• macOS (Apple Silicon or Intel)
• Go 1.25+ (for building)
• Xcode Command Line Tools (xcode-select --install)
• sqlcipher (for database queries): brew install sqlcipher
• SIP disabled (required for process memory access, see below)

Build

./scripts/build.sh

Or manually:

CGO_ENABLED=1 go build -o wechat-cli .

Quick Start

1. Disable SIP (one-time setup)

The key extraction requires reading WeChat's process memory via task_for_pid, which needs SIP disabled:

1. Restart Mac and hold Power button (Apple Silicon) or Cmd+R (Intel) to enter Recovery Mode
2. Open Terminal from the menu bar
3. Run: csrutil disable
4. Restart

2. Initialize

Make sure WeChat is running and logged in, then:

wechat-cli init

Use -d (or --default) to skip all interactive prompts and auto-select the recommended data path + auto-extract keys:

wechat-cli init -d

This will:

1. Auto-detect your WeChat data directory
2. Scan WeChat's process memory for encryption keys (requires sudo)
3. Verify keys using HMAC-SHA512 against each database file
4. Save the configuration to ~/.config/wechat-cli/config.json

3. Use

# List all contacts
wechat-cli contacts

# Search contacts
wechat-cli contacts "name"

# List all groups
wechat-cli groups

# List recent chats
wechat-cli chats

# Read messages (last 50 by default)
wechat-cli messages <username>

# Read last 100 messages
wechat-cli messages -n 100 <username>

# Read most recent messages (tail mode)
wechat-cli messages -t <username>

How It Works

Key Extraction

WeChat uses WCDB (based on SQLCipher 4) to encrypt all local databases. The encryption keys are cached in process memory in the format:

x'<64-char hex key><32-char hex salt>'

wechat-cli init performs the following steps:

1. Find WeChat PID via pgrep
2. Attach to process using macOS Mach kernel API (task_for_pid)
3. Enumerate memory regions (mach_vm_region) — only scans readable+writable, non-executable regions
4. Pattern scan for x'<96 hex chars>' in 2MB chunks with overlap
5. Salt matching — compares the 32-char salt portion against the first 16 bytes of each .db file
6. HMAC-SHA512 verification — validates the key using SQLCipher 4's page HMAC:
   • mac_salt = db_salt XOR 0x3A
   • mac_key = PBKDF2_HMAC_SHA512(key, mac_salt, iterations=2, dklen=32)
   • Verify HMAC of page content matches stored HMAC
7. Cross-verification — tries verified keys against all databases (same key often encrypts multiple DBs)

Database Access

WeChat uses WCDB (SQLCipher 4 based) with per-database independent keys. We bypass Go's mattn/go-sqlite3 driver (which runs PRAGMAs before PRAGMA key, breaking SQLCipher) by calling the sqlcipher CLI directly via os/exec with JSON output mode.

WCDB also compresses some message content with zstd (WCDB_CT_message_content=4), which is transparently decompressed.

Data Paths

• New format: ~/Library/Containers/com.tencent.xinWeChat/Data/Documents/xwechat_files/<account>/db_storage/
• Old format: ~/Library/Containers/com.tencent.xinWeChat/Data/Library/Application Support/com.tencent.xinWeChat/<ver>/<hash>/

Architecture

wechat-cli (single Go binary)
├── cmd/           CLI commands (init, contacts, groups, messages, chats)
├── internal/
│   ├── config/    Configuration (~/.config/wechat-cli/config.json)
│   ├── db/        Database queries via sqlcipher CLI + zstd decompression
│   └── wechat/
│       ├── path.go              WeChat data path detection (new + old format)
│       └── memscan_darwin.go    Memory scanner (CGo + Mach APIs)

The memory scanner uses CGo to call macOS Mach kernel APIs (task_for_pid, mach_vm_region, mach_vm_read). Cryptographic verification (PBKDF2, HMAC-SHA512) is implemented in pure Go.

Troubleshooting

"task_for_pid failed"

• Make sure you run with sudo (the init command will prompt for it)
• Make sure SIP is disabled: csrutil status

"WeChat process not found"

• Start WeChat and make sure it's running (not just in the Dock)

"No keys found"

• Make sure you are logged in to WeChat (not just at the login screen)
• WeChat must have opened its databases at least once after login

"sqlcipher not found"

• Install sqlcipher: brew install sqlcipher

Re-initialization

If you log out and back in to WeChat, or if keys change after a WeChat update, re-run:

wechat-cli init

Disclaimer / 免责声明

This tool is intended solely for accessing your own WeChat data on your own device. You are responsible for ensuring your use complies with all applicable laws and regulations, including but not limited to:

• Do not use this tool to access, decrypt, or read other people's chat records
• Do not use this tool for any illegal purpose, including unauthorized data collection, surveillance, or privacy violations
• This tool is provided for personal data backup and research purposes only

The author assumes no liability for any misuse of this tool. By using this software, you agree that you bear full responsibility for your actions.

本工具仅供用户在自己的设备上访问自己的微信数据。使用者须自行确保符合所有适用的法律法规，包括但不限于：

• 禁止使用本工具访问、解密或读取他人的聊天记录
• 禁止将本工具用于任何非法目的，包括未经授权的数据采集、监控或侵犯隐私
• 本工具仅供个人数据备份与技术研究使用

作者不对本工具的任何滥用行为承担责任。使用本软件即表示您同意对自身行为承担全部责任。

References

• ylytdeng/wechat-decrypt — Memory scanning approach, message type parsing
• Thearas/wechat-db-decrypt-macos — HMAC-SHA512 verification algorithm, new format schema

License

MIT