wechat-cli: reading local WeChat data from a shell prompt
A CLI tool to query your local WeChat data — chat history, contacts, sessions, favorites, and more. Designed for LLM integration.
At a glance
- What is it?
- A Node and Python CLI that decrypts the local WeChat database, exposes eleven query commands, and returns JSON so an agent can call it as a tool. The catch is that setup is platform-specific and the npm package ships a macOS arm64 binary only.
- Who is it for?
- 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.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Activity is slowing. The repository last received commits 7 months ago.
- What is it written in?
- GitHub does not report a main language for this repository.
Answers come from the project's GitHub data, last synced on November 20, 2026, and from our analysis. They are not legal advice.
Star history
- huohuoer/wechat-cli2,789 ★ · +530
| Repository | 2026-09-10 | 2026-11-20 |
|---|---|---|
| huohuoer/wechat-cli | 2.3k | 2.8k |
530 Stars in the last 71 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
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.
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.
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, there is little to lean on. The repository has no published GitHub releases. 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.
Frequently asked questions
How do I retrieve my chat history in WeChat?
This tool does it locally rather than through an export. It auto-detects the WeChat data directory, extracts the database encryption key from the running client, decrypts the message store on the fly, and then serves queries on chat history, contacts, sessions, favourites and statistics from the command line, with JSON output by default.
Does wechat-cli send my WeChat data anywhere?
The tool is described as fully local, decrypting on the fly with nothing leaving the machine. The same page ships an agent install section that tells you to paste an install prompt into a coding agent, and a project instruction block listing the commands an agent may run against your chats and contacts, so where that data goes next depends on the client you wire it into.
What does wechat-cli change on my computer?
Two documented things. It needs full disk access for your terminal and elevated privileges to read the running client's memory. And where a macOS restriction blocks that read, the page says it will automatically re-sign the WeChat application with an additional entitlement, showing a manual command that replaces the signature with an ad-hoc one. It notes auto-update may be affected and gives a reinstall route.
Which platforms does wechat-cli support?
The JavaScript package ships a macOS arm64 binary only, and the page directs other platforms to the Python method, which needs Python 3.10 or newer. A third route builds from source by cloning the repository and installing in editable mode, using a clone URL under a different account name from the repository itself.
How many commands does wechat-cli have?
Eleven, named in the highlights: sessions, history, search, contacts, members, stats, export, favorites, unread, new-messages and init. The reference section documents options for several of them, including limits, offsets, a time range, a type filter for narrowing to links or files, and a switch between JSON and plain text.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/huohuoer-wechat-cli)Star history chart for your README
[](https://hysenlabs.com/projects/huohuoer-wechat-cli)Was this useful?