Full-text search skips the contact hiding rules, and key extraction needs SIP off
WeChat macOS database decryption and query tool
At a glance
- What is it?
- A Rust tool that decrypts the WeChat databases on an Apple Silicon Mac, exposes them over REST and SSE, and asks you to disable System Integrity Protection before it can get the key.
- Who is it for?
- wx-cli is aimed at one situation: a Mac with WeChat 4.1.7 or newer, and a reason to treat the local chat database as a queryable data source. Within that scope it is thorough, and the page is candid about its own weak points in a way most tools are not.
- Can I use it commercially?
- Yes. MIT 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?
- Yes. The repository last received commits 88 days ago.
- What is it written in?
- Mainly Rust, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 21, 2026, and from our analysis. They are not legal advice.
Star history
- pandorafuture/wx-cli1,099 ★ · +384
| Repository | 2026-09-18 | 2026-11-21 |
|---|---|---|
| pandorafuture/wx-cli | 715 | 1.1k |
384 Stars in the last 64 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
Key extraction needs SIP disabled, and there is a way around it
The prerequisite is stated in one line and it is the price of admission. Key extraction requires System Integrity Protection to be off, because with SIP enabled the kernel refuses `task_for_pid` even for root. Normally no sudo password is needed for the tool itself.
The LLDB route adds three setup steps on top of that:
sudo DevToolsSecurity -enable
sudo dscl . append /Groups/_developer GroupMembership $USER
xcode-select --installThe last one is what provides `lldb` and `python3`, which the hook needs. A user who hits the timeout should first confirm WeChat has shown its login screen and completed the login, then retry with a longer timeout, and read the log the tool leaves under the temp directory.
There is a documented alternative that skips all of it. If you already have the key, SIP does not need to be disabled at all and you enter it directly with `key set <account> <64-hex-key>`, or set an image key separately with `key set-image <account> <image-key>`. That is the branch to look for first, because a tool that asks you to turn off a system security control should not be your only route.
A `doctor` command checks SIP, DevToolsSecurity, group membership and the presence of the LLDB and Python tooling, one item at a time.
The contact hiding rules are bypassed by full-text search
The tool has a privacy feature for people who share a Mac. Contact hiding works per account: you list contacts or groups to hide, and separately list tags, so anything carrying a given label is hidden as well. The rules live in a TOML file under the application support directory:
[accounts."<account_id>"]
ignore_contacts = ["wxid_xxx", "12345@chatroom"]
ignore_tags = ["同事", "客户"]Once enabled, the rules apply by default to querying, exporting and monitoring, and a local `--show-hidden` flag bypasses them when you want the unfiltered view.
The exception is written plainly: full-text search does not currently apply the hiding configuration. So if you hide a contact because their messages should not surface, a keyword search will still return what they wrote, and only the words they sent, not their name. That is a meaningful difference in practice, because searching for a project name or a phrase is exactly the operation an agent would run most often, and the two operations disagree about who is invisible.
Anyone relying on the feature for privacy rather than for tidiness needs to know that before they connect an agent to the service.
The database key is stored on disk beside the settings
The path table is worth reading closely, because it says both where the secrets live and what you can safely delete. Five locations: configuration under `~/Library/Application Support/wx-cli/config/`, described as holding keys and settings, and marked not deletable; cache under `~/Library/Caches/wx-cli/` holding the decrypted databases, deletable because they can be re-created by decrypting again; state under the application support directory for service runtime metadata; logs under `~/Library/Logs/wx-cli/`; and a temp directory under `$TMPDIR` for key-extraction temporary files, which is also where the LLDB output log lands.
So the raw database key that `key extract` recovers ends up on disk in the configuration directory, in the same place as the hiding rules. A `paths` command prints all of them, and the cache can be cleared by removing the cache directory outright.
Two of the five are marked deletable without consequence, which is unusual and useful: a user who wants to remove the readable copy of the database does not have to uninstall anything, and the tool rebuilds it on the next decrypt.
Two commands appear only in the summary table
The command reference lists twenty entries, two of which the walkthrough never mentions. `wx-cli paths` prints every data path, and `wx-cli info <db>` reports the encryption state of a database. Both are diagnostic, and both are the ones you want when something is not working.
The rest of the surface is a query set: sessions, contacts with a search flag, query by contact, global search by keyword, query filtered by message type, query by group name, export, and a watch command that polls at a configurable interval. Media handling covers image decryption for a single file or a whole directory, voice extraction, which needs ffmpeg on the machine, and video decryption for Channels video with a seed value the example hardcodes.
One behaviour is easy to miss. If a server is already running on this machine, the query commands reuse its REST API automatically, probing `http://127.0.0.1:9100` by default. Two flags change that: `--no-server` forces the local path and `--server-only` forces the remote one. So the same command can quietly change where your query executes depending on whether a background service happens to be up.
Binding the server to a public interface takes a token
The HTTP service binds to `127.0.0.1:9100` by default, and the page shows what changes for remote access:
wx-cli server run --host 0.0.0.0 --token mysecret # 远程访问(必须设 token)A token is required for that case, and the endpoints are a fixed set of eight: health, sessions, contacts, messages, timeline, search, media, and events, the last being server-sent events for live messages. Every query command also takes `--format json` for machine-readable output.
Two details show the service was designed against a real WeChat database rather than an idealised one. Media responses carry an `X-Wechat-Media-Quality` header set to `full` or `thumbnail`, so a client can tell whether it was handed the full image or the small one, and the service prefers a high-quality file already downloaded on the machine. Session and contact records return an optional `avatar_url` when the local database has the field, and older databases without it simply omit the key instead of failing.
The timeline endpoint takes `since` and `until` as unix timestamps and returns every session in one request, which is the call an agent uses to fill in memory rather than iterating conversation by conversation.
PBKDF2 runs 256k rounds and dev builds are told to keep it fast
The manifest explains its one piece of build tuning, and the reason is a performance cliff rather than a preference. PBKDF2 intentionally runs 256,000 rounds, and the workspace turns optimisation on for the crypto path in development and test builds by setting `opt-level = 3` for the decryption crate and for `pbkdf2`, `sha2` and `hmac` individually. Without it, parallel integration tests and local debug binaries would spend seconds per database deriving SQLCipher keys.
That comment also identifies what the data is: the databases are SQLCipher-encrypted, and the key the tool extracts is the input to that key derivation. The 64-character hex string the manual `key set` command expects is the raw key, not the derived one.
The workspace is eight crates under `crates/`: decryption, keychain, the CLI entry point, database queries, media, monitoring, context resolution and platform paths. It is edition 2021 with resolver 2, version 0.7.4, MIT, which matches the newest tag. The root also carries two changelogs, one English and one for Simplified Chinese, plus a skill definition, a security policy and a contributing guide.
Apple Silicon, WeChat 4.1.7 or newer, and a release download that greps the API
Support is narrow and stated up front: macOS on arm64, Apple Silicon, and WeChat 4.1.7 or later. There is no Intel build mentioned and no other platform.
The recommended install is a prebuilt binary, and the command line for it is a pipeline rather than a download link. It asks the GitHub releases API for the latest release, greps out a `browser_download_url` matching `macos-arm64`, takes the fourth field of the quoted string, downloads that, unpacks the tarball, moves the binary into `~/.local/bin`, marks it executable and prints the version. The alternative is `cargo build --release`, which produces `target/release/wx-cli`.
The deployment snippet copies the binary into the same directory and then appends an export line for that directory to `~/.zshrc` and sources it. There is no check for whether the line is already there, so running the snippet twice leaves two identical export lines in the file.
Releases have come every few weeks: v0.7.2 on 2026-06-04, v0.7.3 on 2026-07-10 and v0.7.4 on 2026-07-22, with the repository's last recorded push on 2026-08-26. It is not archived.
Editorial conclusion
wx-cli is aimed at one situation: a Mac with WeChat 4.1.7 or newer, and a reason to treat the local chat database as a queryable data source. Within that scope it is thorough, and the page is candid about its own weak points in a way most tools are not. Four things to weigh before you install it. Disabling System Integrity Protection is a real cost, and there is a documented way around it if you already hold the key, which is the route to prefer. The contact hiding rules are a privacy control with a stated exception, because full-text search does not apply them, so hiding a contact does not hide their words from a keyword search. The service can be bound to a public interface with a token, and since the same process reads the decrypted database and the keys, that exposure is worth scoping carefully. And the tool does not upload anything by default, which is the property that makes it usable at all, but a local service on port 9100 that other local processes can reach is a second-order version of the same question.
Frequently asked questions
What does wx-cli do on macOS?
It reads the local WeChat database on an Apple Silicon Mac, decrypts it, and lets you query, search, export and watch messages by contact, group, time range or type, plus decrypt images, voice notes and Channels video. It also serves the same data over a REST API and a server-sent events endpoint. Support is macOS arm64 with WeChat 4.1.7 or newer.
Why does wx-cli need SIP disabled?
Because key extraction uses task_for_pid, which the kernel refuses while System Integrity Protection is on, even for root. If you already hold the database key you can skip that entirely and enter it with wx-cli key set, and the doctor command reports whether SIP, DevToolsSecurity, the developer group and the LLDB and Python tooling are all in place.
Does wx-cli's contact hiding apply to every command?
No. Query, export and monitor commands apply the hiding rules, and --show-hidden bypasses them, but full-text search does not currently apply the hiding configuration. Hiding a contact therefore does not stop their messages appearing in a keyword search.
Where does wx-cli store the WeChat key and the decrypted database?
The key and the settings sit in the configuration directory under ~/Library/Application Support/wx-cli/config/, which is marked not deletable. The decrypted databases sit in ~/Library/Caches/wx-cli/ and can be deleted, since decrypting again rebuilds them. The paths command prints all five locations, and key-extraction temporary files go under the system temp directory.
Can I use wx-cli without its HTTP server?
Yes, and you may need to. Query commands automatically reuse a running local service, probing http://127.0.0.1:9100, so --no-server forces local execution and --server-only forces the remote path. The server itself binds to 127.0.0.1:9100 unless you pass --host with a token.
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/pandorafuture-wx-cli)Star history chart for your README
[](https://hysenlabs.com/projects/pandorafuture-wx-cli)Was this useful?