wechat-cli

# wechat-cli Native WeChat data CLI. For power agents and humans. macOS / Windows · Local decryption · One-line installation · Stable JSON · Chat history / Search / Images / Files / Voice transcription / Moments / Red packets `wechat-cli` reads the local database of WeChat / 微信 4.x on your computer and outputs structured JSON data, including messages, contacts, groups, media, moments, favorites, transfers, and red packets. Data stays on your machine and is not uploaded to the cloud. It's not a WeChat bot, doesn't control your screen, send messages, or auto-like/comment. It's not an official account or mini-program tool. ## Installation macOS: ```bash curl -fsSL https://raw.githubusercontent.com/r266-tech/wechat-cli/main/scripts/install-release.sh | zsh ~/.local/share/wechat-cli/wxkey bootstrap ~/.local/bin/wechat-cli sessions --limit 5 --pretty ``` Windows: ```powershell powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://raw.githubusercontent.com/r266-tech/wechat-cli/main/scripts/install-release.ps1 | iex" wechat-cli sessions --limit 5 --pretty ``` The third line tests the installation: if it returns `ok: true` and shows recent sessions, it means the CLI, key, and database reading are working. The default installation only includes the CLI, without registering an external protocol adapter or installing a background watcher. The command will be placed in your system's PATH: - macOS: `~/.local/bin/wechat-cli` - Windows: `%LOCALAPPDATA%\Microsoft\WindowsApps\wechat-cli.cmd`, or `%USERPROFILE%\.local\bin\wechat-cli.cmd` if the directory doesn't exist Before reading WeChat data, ensure: - macOS arm64 + WeChat 4.x, or Windows amd64 + Windows WeChat / Weixin 4.x - WeChat is logged in and at least one chat is opened - For macOS 15+, consider adding `~/.local/share/wechat-cli/wechat-cli` and `~/.local/share/wechat-cli/wxkey` to Full Disk Access to reduce system privacy pop-ups On macOS, `wxkey bootstrap` is a one-time key initialization that may require your Mac admin password. The password is only used locally and stored in your Keychain for future key refreshes. `wxkey bootstrap` might temporarily launch a WeChat shadow copy managed by wechat-cli to complete the no-SIP initialization. On WeChat 4.1.10+, `wxkey bootstrap` might print a passive scan with `found=0` and then enter the `PBKDF breakpoint fallback`. This is an expected path, and you should consider it successful if it ends with `[OK] key config written`. The new fallback waits up to 5 minutes and stops any existing WeChat instances before launching a new one for decryption. ## Update If you've installed a release version, run: ```bash wechat-cli update ``` This command downloads the latest release zip from GitHub, checks the sha256, and overwrites the installation using the package's installer. On macOS, it waits for the update to complete and returns JSON; on Windows, it starts a background updater and exits, as Windows can't overwrite a running `.exe` file. The JSON output includes the background update log. ## Quick Start ```bash wechat-cli agent --pretty wechat-cli status --pretty wechat-cli sessions wechat-cli resolve-chat "$CHAT" wechat-cli timeline "$CHAT" --limit 20 wechat-cli context "$CHAT" --local-id 123 --before-count 20 --after-count 20 wechat-cli tail "$CHAT" --since-local-id 123 --jsonl wechat-cli search-context "$KEYWORD" --in "$CHAT" --context-limit 3 wechat-cli history "$CHAT" --view agent --limit 50 wechat-cli search "$KEYWORD" --in "$CHAT" wechat-cli media "$CHAT" --type image --limit 10 ``` All commands are designed for agents, with default compact JSON output. Successful commands return `{"ok":true,"tool":"...","command":"...","data":...}`, while failed commands return `{"ok":false,"error":...}`. Use `--pretty` for human-readable output. ## Common Commands | Command | Purpose | | --- | --- | | `tools` | Lists assistant tools with high signal-to-noise ratio; use `--profile all` for all compatible/maintenance tools | | `agent` | WeChat Read OS entry: coverage matrix, workflow, quality verification, and local readiness | | `status` / `coverage` / `workflows` | Shorter status, coverage, and workflow entries | | `update` | Updates to the latest GitHub release | | `sessions` | Recent sessions, unread counts, and last message summaries | | `resolve-chat` | Resolves nicknames, remarks, or group names to stable talkers | | `timeline` | Primary entry for reading chats, returning `query` / `freshness` / `messages` | | `context` | Expands messages before and after a given `local_id` / `server_id` anchor | | `tail` / `watch` | Read-only incremental event observation, reusing timeline rows for message events | | `history` | Lower-level message reading with filters for time, type, sender, and pagination | | `search` | Full-text search across conversations using WeChat's local FTS | | `search-context` | Searches and automatically expands context around each hit | | `media` | Locates images, videos, files, and other local resources by message | | `members` | Group members, group nicknames, and friend relationships | | `sns-feed` / `sns-search` / `sns-notifications` | Moments timeline, search, and like/comment notifications | | `transfers` / `red-packets` | Transfer and red packet records | | `favorites` | WeChat favorites | | `export` | Explicit local file writing: exports a single conversation to jsonl / markdown / html | | `schema` / `sql` | Read-only database structure and SQL diagnostics | | `cache status` / `cache refresh` | Metadata cache diagnostics and refresh | ## Data and Privacy - `wechat-cli` only reads WeChat's local database. - Chat content is live-read and not cached in full. - Contact and session metadata cache is stored in `~/.wechat-cli/cache/` for name resolution and session sorting. - Key maps are stored in `~/.config/wxcli/config.json`. Do not share this file, WeChat DB, chat exports, screenshots, or logs publicly. - macOS sudo credentials are stored in the local Keychain. Use the installer's `--clear-state` or `--uninstall --purge-state` to clear them. - `wechat-cli` does not send messages, forward messages, like/comment, or modify WeChat data. ## Troubleshooting | Phenomenon | Solution | | --- | --- | | Session not found | First, use `wechat-cli resolve-chat "name"` to check candidates. If necessary, open the corresponding chat in WeChat and try again. | | Key missing prompt | Confirm WeChat is logged in and has opened a chat. For macOS agent, run `~/.local/share/wechat-cli/wxkey bootstrap` or `~/.local/share/wechat-cli/wxkey doctor`. | | `wxkey bootstrap` initially shows `found=0` or `initial passive scan did not capture DB keys before its deadline`, then enters PBKDF fallback | Normal fallback path for WeChat 4.1.10+. Do not interrupt during fallback. If `[OK] key config written` appears and `wechat-cli sessions --limit 5 --pretty` returns `ok: true`, it's successful. | | `PBKDF fallback got partial key coverage (24/26)` | Not an installation failure. Indicates most DB keys are obtained, and core chats are usually readable. Verify with `sessions`. If some pages/media are missing keys, open the corresponding WeChat page and re-run `wxkey bootstrap` or `wxkey doctor`. | | `PBKDF fallback found no keys` | Update to the latest `wechat-cli`. If `pbkdf_calls=0`, ensure the WeChat launched by LLDB triggers DB decryption. Keep the WeChat window logged in, open a normal chat, and re-run. If `pbkdf_calls>0` but `matching_db_salt_calls=0`, use the correct `--root .../xwechat_files/<wxid>` or `WECHAT_CLI_DB_ROOT`. If there are matching salts but still no keys, provide diagnostic logs. | | Initial key scan stuck | New versions timeout with `blocked_by=key_scan_timeout` or `blocked_by=key_not_found`. Keep WeChat open, enter the target chat, and re-run `~/.local/share/wechat-cli/wxkey bootstrap`. For slow machines, use `WXKEY_PBKDF_PROBE_TIMEOUT=5m ~/.local/share/wechat-cli/wxkey bootstrap` to extend the timeout. | | `zsh: killed ~/.local/bin/wechat-cli --help` or `sessions` terminated immediately | Update to the latest version. Old versions may cause signature issues on macOS arm64. | | Frequent privacy authorization prompts on macOS | Grant Full Disk Access to `wechat-cli` and `wxkey`. | | Images only show warnings without paths | WeChat locally only has `.dat` files, and image keys are still unavailable. Open the original image or corresponding chat and try again. | | Windows initialization failure | Confirm Windows WeChat login and `WECHAT_CLI_DB_ROOT` points to the account directory containing `db_storage`. For slow machines, set `WECHAT_CLI_KEY_SCAN_TIMEOUT=5m` and retry. | For more detailed agent operation instructions, see [AGENTS.md](AGENTS.md). Model discovery summaries are in [llms.txt](llms.txt). ## Development ```bash go test ./... go build -trimpath -o wechat-cli ./cmd/wechat-cli ``` Real WeChat read acceptance test: ```bash WECHAT_CLI_BIN=./wechat-cli WECHAT_READ_TEST_CHAT="$CHAT" WECHAT_READ_TEST_KEYWORD="$KEYWORD" ./scripts/wechat-read-regression.sh ``` This test verifies the sequence: `agent/status/coverage/workflows -> resolve-chat -> sessions -> timeline -> context -> timeline anchor paging -> tail -> search -> search-context -> manual search context -> media -> members -> export`, saving each step's JSON to a temporary `0700` directory. Do not upload or share this directory, as it contains local chat data. macOS release package: ```bash WECHAT_CLI_WCDB_DYLIB=/path/to/libWCDB.dylib ./scripts/package.sh 1.6.17 ``` Windows release packages are built using the `Windows Release Package` workflow on GitHub Actions. ## Related Projects - [wxkey](https://github.com/r266-tech/wxkey): macOS WeChat key bootstrap companion, included in release packages. Ordinary users usually don't need to install it separately. - [jackwener/wx-cli](https://github.com/jackwener/wx-cli): Terminal/script-oriented WeChat data CLI. Refer to its command experience. - [joeseesun/wechat-radar](https://github.com/joeseesun/wechat-radar): Local intelligence dashboard based on WeChat data. - [ylytdeng/wechat-decrypt](https://github.com/ylytdeng/wechat-decrypt): WeChat database decryption and export toolset. ## License See [LICENSE](LICENSE). <!-- babata-star-callout-v2 --> ## If this saved you time Starring the repo helps prioritize which integrations stay maintained. This project is part of [babata](https://github.com/r266-tech).