wechat-cli: reading local WeChat data from a shell prompt

The gap between a WeChat install and a scriptable query

WeChat stores local data in an encrypted database. There is no supported query interface, no SQL prompt, no export button that gives you a machine-readable dump of one conversation. If you want to answer a question like which links were posted in a group last week, you either scroll the app or you reverse the storage format yourself. wechat-cli exists to close that gap. The README frames it as a way to query chat history, contacts, sessions, favorites and statistics from the command line, and the stated audience is explicit: the tool is designed for LLM integration, with JSON as the default output format. That default is the design decision that matters most. A human-readable CLI would print a table; this one prints structures an agent can parse without a formatting layer.

SQLCipher decryption on the fly, and what init actually does

The mechanism is described in the highlights as on-the-fly SQLCipher decryption, with the claim that data never leaves your machine. The init command is where the pieces come together. According to the README, it auto-detects the WeChat data directory, extracts encryption keys, and writes config to ~/.wechat-cli/. Key extraction on macOS and Linux works by scanning process memory, which is why the documented command is prefixed with sudo. On Windows the README says to run init in a terminal with sufficient privileges but does not specify the mechanism. If more than one WeChat account is logged in locally, init prompts you to choose one, defaulting to the first. The README suggests sorting the data folder by modification date if you are unsure which account is active. After init, each query command reads the stored config, opens the database, and decrypts as it goes rather than maintaining a decrypted copy. The repository does not document the schema, so the mapping from a command like members to the underlying tables is not something you can verify from the material.

Install routes: npm, pip, or source, with one binary caveat

There are three install paths. The recommended one is npm install -g @canghe_ai/wechat-cli, updated with npm update -g @canghe_ai/wechat-cli. The README states plainly that this currently ships a macOS arm64 binary and that other platforms should use pip. That is a real constraint, not a footnote: if you are on Intel macOS, Linux or Windows, the npm route is not the one to take. The pip route is pip install wechat-cli and requires Python 3.10 or higher. The source route is git clone, then pip install -e . inside the repository. The project also documents an install flow aimed at coding agents, where you paste a Chinese-language instruction to configure and install the npm package into a tool such as Claude Code, with a note to make sure Node.js is present first. Nothing in the material says which of the three routes is tested against which platform beyond the arm64 note.

Eleven commands, and the flags that shape their output

The command set is sessions, history, search, contacts, members, stats, export, favorites, unread, new-messages and init. The README shows a working pattern for the main ones. wechat-cli sessions --limit 10 lists recent chats. wechat-cli history "Alice" --limit 100 --offset 50 paginates messages, and history accepts --start-time and --end-time for range filtering plus --type to restrict to a message kind such as link. wechat-cli search "deadline" --chat "Team" scopes a keyword search to one conversation, and search also takes --type and --limit. wechat-cli contacts --query "NAME" searches contacts. wechat-cli members "GROUP" lists group members. wechat-cli stats "CHAT" --format text produces statistics, which the highlights describe as top senders, message type breakdown and a 24-hour activity chart. export supports Markdown or plain text with time range filtering. Every command accepts --format text for human-readable output, which means the JSON default is a switch you can turn off rather than a fixed behaviour. new-messages is documented as returning messages since the last check, which is the piece that makes cron-style polling possible.

Full Disk Access, task_for_pid, and re-signing WeChat

Setup is the part of this tool most likely to stop you. On macOS the README requires Full Disk Access for your terminal app before running init, added under System Settings, Privacy & Security, Full Disk Access, with a terminal restart afterward. Without it, the tool cannot reach the data directory and key extraction fails. A second failure mode is documented: init can fail with task_for_pid failed even under sudo, because macOS restricts process memory access. The README says wechat-cli will attempt to fix this by re-signing WeChat with the com.apple.security.get-task-allow entitlement while preserving the original entitlements, then asks you to quit WeChat completely, reopen it, log in, and rerun sudo wechat-cli init. A manual codesign command is given as a fallback. The project states that re-signing is safe and will not cause account issues or bans, and that it may affect WeChat's auto-update mechanism, in which case reinstalling WeChat from the official site restores it without rerunning init. Treat the safety claim as the project's own assertion, not an independently verified one. The practical consequence is that this tool modifies a third-party application bundle on your machine to read its memory, and that is a decision worth making deliberately.

Where it fits against a general SQLite or logging approach

The obvious alternative is to skip the CLI and work the database directly: locate the WeChat data directory, obtain the key, and query the SQLCipher file with a SQLite client in your own script. That approach gives you the full schema and any join you want. The difference is maintenance. wechat-cli packages key extraction, directory detection and account selection into init, and wraps common questions into named commands, so you trade schema-level control for not having to track WeChat's storage layout yourself. The second alternative is a chat archiving or export tool, which typically produces a static dump you then search. wechat-cli is query-oriented rather than dump-oriented: history, search, stats and new-messages answer questions against the live database, and export exists as one command among eleven rather than the product. If your need is a one-time archive, a dump tool is simpler. If your need is an agent that asks a fresh question each session, the query model is the one that fits.

Maintenance, licensing, and what to check before relying on it

The licence is Apache-2.0, which permits commercial use and modification and requires that you retain the licence and notice files and state significant changes. That is a summary of the licence's general shape, not legal advice; read the LICENSE file in the repository for the terms that bind you. On maintenance, the material offers little to lean on. No releases were retrieved, and the README carries no version history or compatibility matrix, so there is no documented answer to how a WeChat update affects key extraction. The re-signing note is the one place the project acknowledges that its own operation can interfere with another application's update path. The platform table in the badges lists macOS, Windows and Linux, while the npm section states that only a macOS arm64 binary ships, which is a discrepancy worth resolving against your own target before you plan a rollout. If you depend on this in an automated pipeline, the thing to watch is whether init still succeeds after a WeChat upgrade, because every query command sits downstream of the stored key.

Editorial conclusion

Adopt it if you are on macOS arm64, want local-only chat queries, and are wiring WeChat context into an agent that can run shell commands. Skip it if you need a supported Windows or Linux binary today, or if you cannot grant a terminal Full Disk Access and re-sign WeChat. Before trusting it, run sudo wechat-cli init, confirm ~/.wechat-cli/ holds the config, and compare wechat-cli sessions --limit 5 against what WeChat itself shows.

Official sources

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