wx-cli: reading WeChat's macOS databases from the command line

What wx-cli is for, and who actually needs it

The README frames the project as turning WeChat into a data source an agent can read, search and subscribe to. That framing matters more than the feature list. The tool does not send messages and does not automate the WeChat UI. It reads the local data WeChat has already written to disk on a Mac and makes it queryable: history by contact, by group, by time range and by message type, plus a global keyword search across every conversation. The intended user is someone building a personal assistant, a memory store, an archive job or a small internal CRM on top of their own chat history. The documentation is explicit that data stays on the machine and that no chat database is uploaded, which is the whole reason a local decrypt step exists rather than a cloud export. If you just want a one-off dump of a conversation to a text file, the export command covers it, but you are paying for a lot of machinery you will not use.

Key extraction, SQLCipher decryption and the rest of the pipeline

The workspace is split into eight crates and the split follows the data flow. wx-keychain handles extraction: the README describes key extract as an LLDB hook that captures the PBKDF2 call and obtains the raw key, covering all databases, and notes that it restarts WeChat. wx-decrypt is the core library, described in the repository layout as handling the KDF, per-page decryption and whole-database decryption. The Cargo.toml carries a deliberate choice worth noticing: PBKDF2 runs 256k rounds, and the profile overrides force wx-decrypt, pbkdf2, sha2 and hmac to opt-level 3 even in dev and test builds, with a comment explaining that otherwise debug binaries spend seconds per database deriving SQLCipher keys. That is a real cost being managed, not a micro-optimisation. From there wx-db answers contact, message, session and group queries, wx-media handles images, voice and video, wx-monitor does live listening and incremental monitoring, wx-context resolves accounts, the decryption cache and contacts, and wx-paths owns platform paths. The CLI is a thin entry point over that. Decrypted databases land in a cache directory, and decrypt --incremental only processes files that changed, which is the mode you want for a long-running setup.

Installing wx-cli on macOS arm64 and running a first query

The README recommends the prebuilt release binary for macOS arm64. The download snippet resolves the latest release asset through the GitHub API, unpacks it and puts the binary on your PATH. After this, wx-cli --version should print the version.

curl -fSL "$(curl -fsSL https://api.github.com/repos/pandorafuture/wx-cli/releases/latest \
  | grep -o '"browser_download_url": "[^"]*macos-arm64[^"]*"' \
  | cut -d'"' -f4)" -o wx-cli.tar.gz
tar xzf wx-cli.tar.gz
mkdir -p ~/.local/bin
mv wx-cli ~/.local/bin/
chmod +x ~/.local/bin/wx-cli
wx-cli --version

Building from source needs a Rust toolchain; cargo build --release produces target/release/wx-cli. Before extracting anything, check the environment and the account state. doctor checks SIP, DevToolsSecurity, the _developer group and lldb/python3, and status shows whether WeChat is running and what key and cache state each account is in.

wx-cli doctor
wx-cli status

Then extract the key and decrypt. The README notes this restarts WeChat and usually does not need sudo.

wx-cli key extract --timeout 120
wx-cli key list
wx-cli decrypt --incremental

Once the cache exists, the query commands work without touching WeChat again. A first useful pass is listing recent sessions, then searching everything for a keyword, then pulling one conversation as JSON.

wx-cli sessions --limit 10
wx-cli search 周末 --limit 20
wx-cli query 张三 --limit 20 --format json

If server run is active, the query commands reuse the REST API at http://127.0.0.1:9100 automatically; --no-server forces a local query and --server-only forces the remote path. For an agent-driven workflow, the project ships an Agent Skill installed with npx skills add pandorafuture/wx-cli, and the README states Claude Code, Codex and Cursor understand the commands after that.

The SIP requirement is the real adoption barrier

This is the part to decide on before anything else. The README states that key extraction requires SIP to be disabled, because with SIP enabled the kernel rejects task_for_pid even for root, and that disabling SIP means rebooting into recovery mode and running csrutil disable. The LLDB path additionally needs sudo DevToolsSecurity -enable, membership of the _developer group and xcode-select --install for lldb and python3. That is a machine-level security change, not a package install. The escape hatch is manual entry: if you already hold a key, key set <account> <64-hex-key> and key set-image <account> <image-key> bypass the SIP requirement entirely. The documentation does not say how to obtain that key by other means, so the escape hatch only helps people who already have one. A second limitation is scope: platform support is macOS arm64 only, and WeChat 4.1.7 or later. A third is documented rather than hidden, which is to the project's credit: the Contact Hiding section states that search does not currently apply the hidden-contact configuration, so ignore_contacts and ignore_tags filter queries, exports and monitoring but not global keyword search. If hiding is part of your privacy model, search is a hole in it.

Compared with building on WeChat's own export

The obvious alternative is WeChat's built-in chat migration and backup export, which produces an archive you then parse yourself. The difference in approach is where the work happens. The official export gives you a portable file and no key handling, no SIP change and no dependency on a specific client version, but it is a snapshot: you re-export to get new messages, and you write the parsing, indexing and filtering layer yourself. wx-cli inverts that. It reads the live local databases, so decrypt --incremental keeps the cache current without a fresh export, watch --poll --poll-ms 3000 streams new messages, and the REST endpoints plus the SSE stream at /api/v1/events mean several consumers can share one decrypted cache. The price is coupling to the macOS client's on-disk format and to the version support window, plus the SIP change. A second alternative is writing your own SQLCipher reader in Python or Go. That is the same problem wx-decrypt already solves, including the 256k-round PBKDF2 derivation that the Cargo.toml explicitly optimises for, and you would still need the key extraction path. Neither alternative is worse in the abstract; the official export is the safer choice if you need one archive and nothing ongoing.

Maintenance, licence and what an upgrade costs you

The repository is MIT licensed at the workspace level, and the Cargo.toml sets license = "MIT" for the workspace package. MIT places few obligations on reuse, but the code reads and decrypts personal chat data, so the practical constraints are legal and ethical rather than licence terms: whose account is on the machine, and whether you have the right to read it. Nothing here is legal advice, and the SECURITY.md file in the repository root is the place to look for how the maintainers want problems reported. On maintenance, the last push to main was on 2026-08-26, and the most recent release listed is v0.7.4 from 2026-07-22. The repository is not archived. The upgrade cost is mostly environmental: the key extraction path depends on LLDB and on WeChat's internals, and the supported client floor is 4.1.7, so a WeChat update that changes the on-disk format or the PBKDF2 call site is the failure mode to watch. Cache invalidation is cheap by comparison: rm -rf ~/Library/Caches/wx-cli/ and a fresh decrypt rebuilds it. The config directory holds keys and settings and the README warns to back it up rather than delete it.

Running wx-cli as a local service for agents

The server mode is what makes the agent story concrete. wx-cli server run binds 127.0.0.1:9100 by default, and the README lists the endpoints: /api/v1/health, /api/v1/sessions, /api/v1/contacts, /api/v1/messages, /api/v1/timeline, /api/v1/search, /api/v1/media and /api/v1/events for SSE. Two details are worth calling out because they are the kind of thing that usually goes undocumented. The timeline endpoint accepts since and until as Unix timestamps and returns messages from every conversation in that window in one request, which is the correct shape for memory backfill and archiving; the alternative is looping per conversation. And /api/v1/media sets an X-Wechat-Media-Quality header to full or thumbnail so the caller knows whether the machine had the original or only the preview, with the service preferring whatever high-resolution copy is already downloaded locally. For remote access the README is firm that a token is required: server run --host 0.0.0.0 --token mysecret. That is the right default to keep. Exposing an unauthenticated endpoint that returns your chat history is the one configuration mistake this tool makes easy, and the README does not describe what the token protects beyond access itself.

Editorial conclusion

Adopt wx-cli if you are on Apple Silicon, run WeChat 4.1.7 or later, and accept disabling SIP on the machine that holds the account, because key extract depends on it and the README states root does not help while SIP is on. Do not adopt it on Intel Macs, on Windows or Linux, or on a managed laptop where SIP cannot be turned off; in that case the manual key path via key set is the only route and it assumes you already hold a 64-hex key. Verify first that wx-cli doctor reports SIP, DevToolsSecurity, the _developer group membership and lldb/python3 as satisfied, and that wx-cli status can see the account, before you touch key extract. Also read the Contact Hiding section closely: search does not apply the ignore rules, so a hidden contact still surfaces in keyword results.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. pandorafuture/wx-cli on GitHub
4. README
5. Releases