WeChat CLI: Query Local WeChat Data from the Terminal

What WeChat CLI Does and Who It Is For

WeChat stores its local database in an encrypted SQLite file protected by SQLCipher. Extracting readable data from that file normally requires knowledge of the encryption key, which changes per installation. WeChat CLI automates the entire process: it scans memory of the running WeChat process to extract the decryption key, opens the database on the fly, and exposes the contents through a set of subcommands.

The primary audience is developers and power users who run AI coding agents. The README calls it AI-first and notes that all commands output structured JSON by default, which is the format LLM agent tool calls expect. A secondary audience is anyone who wants to search or export their own WeChat history from a Mac without relying on WeChat's own limited export functionality.

The tool ships 11 commands: sessions, history, search, contacts, members, stats, export, favorites, unread, new-messages, and init. The init command is always the starting point; the rest query data after init has located the database and stored configuration.

How WeChat CLI Decrypts and Reads Local Data

The init command does three things in sequence. First, it scans the memory of the running WeChat process to find the SQLCipher encryption key. Second, it auto-detects the WeChat data directory on disk. Third, it saves the configuration to ~/.wechat-cli/ so subsequent commands can run without scanning memory again.

All database access happens locally. The README is explicit that data never leaves the machine. The on-the-fly SQLCipher decryption means the tool does not need to write a decrypted copy of the database; it reads directly from the encrypted file using the extracted key.

On macOS, the memory scan requires sudo because reading another process's memory requires elevated privileges. Run init as:

sudo wechat-cli init

On some macOS systems, this fails with a task_for_pid failed error even with sudo, because macOS security policy restricts process memory access. WeChat CLI handles this automatically by re-signing WeChat with the com.apple.security.get-task-allow entitlement. If the automatic re-signing fails, the README provides the manual codesign command:

sudo codesign --force --sign - --entitlements /dev/stdin /Applications/WeChat.app <<'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>com.apple.security.get-task-allow</key>
    <true/>
</dict>
</plist>
EOF

The README notes that re-signing WeChat is safe and does not cause account issues, but may interfere with WeChat's auto-update mechanism. Reinstalling WeChat from the official website restores the original signature without requiring a re-run of init.

Installing WeChat CLI on macOS

The recommended install path is npm, which ships a prebuilt macOS arm64 binary:

npm install -g @canghe_ai/wechat-cli

To update to a newer version:

npm update -g @canghe_ai/wechat-cli

Users on other platforms or on x86 Macs can use pip, which requires Python 3.10 or later:

pip install wechat-cli

To install from source:

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

Before running init, macOS users must grant Full Disk Access to their terminal application. The setting is in System Settings under Privacy and Security. Without it, the init command cannot reach WeChat's data directory and key extraction will fail. The README is explicit that this step must happen before running init, and that the terminal must be restarted after enabling the permission.

After init completes, the basic commands are available immediately:

wechat-cli sessions
wechat-cli history "Alice" --limit 20
wechat-cli search "deadline" --chat "Team"

Using WeChat CLI with AI Agents

The project is built around the assumption that an AI agent will call these commands as tools. All output is structured JSON unless --format text is specified. The README shows a recommended block to add to a project's CLAUDE.md file, listing the most useful commands with brief descriptions of what each returns:

## WeChat CLI

You can use `wechat-cli` to query my local WeChat data.

Common commands:
- `wechat-cli sessions --limit 10` — list recent chats
- `wechat-cli history "NAME" --limit 20 --format text` — read chat history
- `wechat-cli search "KEYWORD" --chat "CHAT_NAME"` — search messages
- `wechat-cli contacts --query "NAME"` — search contacts
- `wechat-cli unread` — show unread sessions
- `wechat-cli new-messages` — get messages since last check
- `wechat-cli members "GROUP"` — list group members
- `wechat-cli stats "CHAT" --format text` — chat statistics

The new-messages command is useful for polling workflows or cron jobs, since it returns only messages received since the last time it was called. The stats command provides analytics including top senders, message type breakdown, and a 24-hour activity chart.

For time-range filtering, the history command accepts --start-time and --end-time flags, and also accepts --type to filter by message type (such as link or file). The search command accepts --chat as a repeatable flag, so a single search can span multiple group chats at once.

Platform Limits and What the Tool Cannot Do

WeChat CLI currently ships a macOS arm64 binary through npm. Users on Intel Macs, Linux, or Windows must use the pip installation path. The README acknowledges this limitation directly and notes that pull requests adding additional platform binaries are welcome, but no Windows or Linux binary is included in the current release.

The tool requires WeChat to be running when init is executed, because the key extraction depends on reading the running process's memory. If WeChat is not running, init cannot extract the encryption key. A subsequent re-run of init after starting WeChat resolves this.

The export command exports conversations to Markdown or plain text, with time range filtering. However, the project has no mechanism for syncing with the WeChat server or retrieving messages from accounts other than the one whose local database is present on the machine. It reads only the local copy.

The pyproject.toml shows the current version is 0.2.4. There are no GitHub releases. The dependencies are click, pycryptodome, and zstandard. The project has no runtime dependencies on WeChat's API or network connectivity once init has captured the key.

Wechaty as an Alternative Approach

Wechaty is a conversational RPA SDK for chat bots that supports WeChat among other messaging platforms. It operates through a puppet layer that maintains a running bot session, giving the application the ability to send and receive messages in real time. This is a fundamentally different model from WeChat CLI.

WeChat CLI is a read-only query tool for local data. It does not maintain a persistent connection to WeChat, cannot send messages, and does not operate as a bot. Wechaty can send messages and react to events, but involves a more complex setup that typically requires a dedicated WeChat account acting as the bot and compliance with platform terms.

For the use case of querying past conversations or feeding message history into an LLM, WeChat CLI is the simpler path. For building an automated assistant that monitors incoming messages and responds, Wechaty is the appropriate tool. The two projects do not overlap in functionality in any meaningful way.

License and Maintenance Status

WeChat CLI is released under the Apache 2.0 license. The source is hosted at github.com/freestylefly/wechat-cli rather than under the huohuoer organization directly, as noted in the pyproject.toml repository URL. The npm package is published as @canghe_ai/wechat-cli.

The last push to the repository was on 2026-04-06. The package version is 0.2.4, and there are no GitHub releases establishing a formal versioning history. The project depends on pycryptodome for the SQLCipher decryption and zstandard for compressed data handling. Neither dependency is pinned to a narrow version range, which reduces the chance of install conflicts but means behavior could shift if a major version of either library introduces breaking changes.

Editorial conclusion

WeChat CLI is the right tool for macOS users who want to give an AI coding agent access to their local WeChat data without writing their own SQLCipher decryption layer. It is not suitable for Windows or Linux users unless they use the pip path and accept that the macOS arm64 binary is unavailable to them. Before using it in any agent workflow, confirm that your terminal application has Full Disk Access enabled in macOS System Settings, since the init step will silently fail without it. The last push to the repository was on 2026-04-06.

Frequently asked questions

Official sources

1. huohuoer/wechat-cli on GitHub
2. Issues
3. License: Apache-2.0
4. Project website
5. README