wx-cli Explained: Query Local WeChat Chat History from the Command Line

Mon, 18 May 2026 21:02:21 +0800

wx-cli is a local WeChat data command-line tool written in Rust. Its goal is to let you query your own WeChat sessions, chat history, contacts, group members, favorites, Moments, official account articles, attachments, and statistics from the terminal.

It is not a cloud-based WeChat sync service, and it is not a chatbot. It is closer to a local read-only data retrieval layer: WeChat still runs on your machine, the data still stays on your machine, and wx-cli decrypts, caches, and queries local databases on demand before returning YAML or JSON output for humans or agents.

Two points make this project worth watching. First, it turns local WeChat data access into a cross-platform CLI. Second, it explicitly considers AI Agent workflows for tools such as Claude Code, Cursor, and Codex, providing a SKILL.md file and structured output with meta fields.

What wx-cli Can Do

According to the project README, wx-cli covers a fairly complete set of features:

View recent sessions and unread sessions.
Query chat history for a contact or group.
Search keywords across the whole local database.
View newly arrived messages.
Query contacts, group members, and group nicknames.
Query favorites.
Query Moments notifications, timelines, and post bodies.
Query official account article pushes.
List and extract image attachments from chats.
Generate chat statistics.
Export chat history as Markdown or JSON.

These capabilities make it more than a “chat history search” tool. It turns local WeChat data into a searchable, analyzable, and exportable personal knowledge source.

Why It Fits AI Agents

Many CLI tools are designed only for people: their output is just a block of text. wx-cli clearly takes agent consumption into account.

The README notes that commands such as history, search, sessions, unread, new-messages, stats, and attachments include meta information. That metadata contains result status, unknown shards, the latest timestamp in matched data, the latest session timestamp, and similar fields.

This is useful for agents. AI does not only need to know “what was found”; it also needs to know whether the result is fresh, whether messages may be missing, and whether it should run init again. For example:

status can indicate whether the result is ok or possibly_stale.
unknown_shards can indicate whether there are database shards for which the daemon currently has no key.
chat_latest_timestamp tells the agent the latest message time in the matched data.
session_last_timestamp helps determine whether the local session record is clearly newer than the query result.

This kind of metadata reduces AI misjudgment and makes tools such as Claude Code, Cursor, and Codex more reliable when working with WeChat data.

Installation

The project recommends cross-platform installation via npm:

`1`	`npm install -g @jackwener/wx-cli`

It also supports curl installation on macOS / Linux:

`1`	`curl -fsSL https://raw.githubusercontent.com/jackwener/wx-cli/main/install.sh \| bash`

On Windows, run this in an administrator PowerShell:

`1`	`irm https://raw.githubusercontent.com/jackwener/wx-cli/main/install.ps1 \| iex`

If you want to build from source, you can use Rust directly:

1
2

git clone git@github.com:jackwener/wx-cli.git && cd wx-cli
cargo build --release

The build artifact is target/release/wx, or wx.exe on Windows.

Relationship with Agent Skills

wx-cli also provides a Skill for AI Agents. You can install it into Claude Code, Cursor, Codex, and other Skills-compatible environments through the skills CLI:

`1`	`npx skills add jackwener/wx-cli`

Install it globally:

`1`	`npx skills add jackwener/wx-cli -g`

After installation, the agent reads the repository’s SKILL.md and learns how to install, initialize, and call wx-cli.

That means you can ask an agent to help with local information organization tasks such as:

Find keywords discussed in a group chat during a specific period.
Summarize recent unread messages.
Export recent chat history from a specific session.
Search official account article links.
Analyze posting statistics in a group chat.

The premise is unchanged: the data must be your own WeChat data on your own machine.

Basic Usage

Before initialization, keep WeChat running. Requirements differ by platform.

On Linux:

`1`	`sudo wx init`

On Windows, use an administrator PowerShell:

wx init

macOS is more involved. The README explains that, with the default path, you first need to ad-hoc sign WeChat so the tool can scan process memory. After re-signing, you also need to clean old TCC authorization records, otherwise permissions such as screen capture, video calls, and microphone access may look enabled while actually being denied. The project documentation also warns that re-signing may cause macOS to repeatedly prompt for access to other apps’ data.

After initialization, verify the setup with:

`1`	`wx sessions`

If you can see recent sessions, the basic path is working. The daemon starts automatically on the first call.

Common Command Examples

View recent sessions:

`1`	`wx sessions`

View unread sessions:

`1`	`wx unread`

Show only human unread sessions while filtering out official accounts and folded entries:

`1`	`wx unread --filter private,group`

View recent chat history for a session:

`1`	`wx history "张三"`

Fetch more history:

`1`	`wx history "张三" -n 2000`

Query a group chat by time range:

`1`	`wx history "AI群" --since 2026-04-01 --until 2026-04-15`

Search the whole database:

`1`	`wx search "关键词"`

Search for a keyword inside a group:

`1`	`wx search "会议" --in "工作群" --since 2026-01-01`

Export chat history:

1
2

wx export "张三" --format markdown -o chat.md
wx export "AI群" --since 2026-01-01 --format json

These commands are well suited for scripts or agents, especially when combined with --json.

Moments and Official Account Articles

wx-cli does not only query chats.

Moments-related commands are split into notifications and posts:

1
2
3

wx sns-notifications
wx sns-feed
wx sns-search "关键词"

Note that Moments data only covers content that has appeared locally. The WeChat client downloads data on demand; if something has never appeared locally, the tool cannot retrieve it out of thin air.

Official account articles are queried through separate commands:

wx biz-articles
wx biz-articles --account "返朴"
wx biz-articles --since 2026-05-01 --until 2026-05-10
wx biz-articles --json | jq '.[].url'

It returns fields such as account name, title, URL, summary, cover image, and timestamp. This is useful for people who organize references, collect articles, or build local knowledge bases.

Attachment Extraction

Image attachments in WeChat chats are usually not ordinary readable image files. They are often .dat files under xwechat_files/<wxid>/msg/attach/....

wx-cli provides a two-step flow:

1
2

wx attachments "张三"
wx attachments "AI群" --kind image -n 100

After getting an attachment_id, extract it:

`1`	`wx extract <attachment_id> -o ~/Desktop/photo.jpg`

The output report includes fields such as md5, dat_path, dat_size, output, format, and decoder. The README says it supports decoding modes such as legacy XOR, V1 fixed-AES, and V2 AES + XOR, while image key extraction differs across platforms.

This capability is powerful, but it requires extra care: only process your own data, and do not use it for unauthorized data access.

Why the Daemon Architecture Matters

The performance story of wx-cli comes from its daemon.

The README describes the structure roughly as:

wx (CLI) ──Unix socket──▶ wx-daemon (background process)
                              │
                    ┌─────────┴──────────┐
               DBCache               contact cache
           (mtime-aware reuse)

After the first decryption, the daemon persists database and mtime information under ~/.wx-cli/cache/. If the database file mtime has not changed, later calls can reuse the cache without decrypting everything again.

This is important for command-line queries and agent loops. An agent may query several sessions, search multiple keywords, then run statistics and exports. If every call had to rescan and decrypt everything, the experience would be poor. The daemon cache makes it feel closer to a local query service.

A Brief Look at the Principle

The project README explains the principle directly: WeChat 4.x encrypts local databases with SQLCipher 4, and WCDB caches the derived raw key in process memory.

wx-cli uses platform-specific methods to scan WeChat process memory, match key patterns, extract the key, and then let the daemon decrypt and cache databases on demand.

The underlying mechanism differs by platform:

macOS uses the Mach VM API.
Linux uses /proc/<pid>/mem.
Windows uses VirtualQueryEx and ReadProcessMemory.

These details explain why initialization usually requires elevated permissions, and why macOS involves signing and privacy authorization.

Boundaries and Risks

Tools like this must start with boundaries.

The wx-cli README disclaimer is clear: the tool is only for learning and research, for decrypting your own WeChat data, and it requires users to comply with applicable laws and regulations. It must not be used for unauthorized data access.

In practice, it is also wise to keep these points in mind:

Use it only on your own computer and your own WeChat account.
Do not casually upload exported chat history to cloud models.
When using an agent to analyze chat history, first confirm the API provider and cross-border data risks.
After exporting Markdown / JSON, pay attention to file permissions and backup locations.
On company or shared devices, confirm compliance and authorization first.

A local tool does not mean there is no privacy risk. It reduces the default path for data to leave your machine, but if you hand the output to a cloud model, cloud drive, or third-party script, the risk comes back.

Who It Is For

wx-cli fits these scenarios:

Quickly search your own historical WeChat messages locally.
Export a session as Markdown or JSON.
Analyze posting activity in a group chat over a time range.
Let Claude Code, Cursor, Codex, and similar agents organize local WeChat material.
Collect official account article links into a local knowledge base.
Study WeChat’s local database structure and decryption flow.

It is less suitable for these scenarios:

You want cloud-based WeChat sync.
You want to bypass someone else’s device or account permissions.
You want a point-and-click GUI and do not want to touch the command line.
You do not want to deal with macOS permissions, Windows administrator rights, or Linux sudo.

Summary

The value of wx-cli is not merely “searching WeChat chat history from the command line.” More precisely, it turns local WeChat data into a local data source that can be queried, exported, and consumed by agents.

Its daemon architecture solves repeated decryption and query performance issues; the meta wrapper helps AI Agents judge whether results are fresh; and SKILL.md lets tools such as Claude Code, Cursor, and Codex understand how to install and use it.

If you often need to find information in WeChat, organize group chats, export records, or build a personal knowledge base, wx-cli is worth watching. But one bottom line should always remain clear: only process your own data, and manage exported results carefully.

References

jackwener/wx-cli GitHub repository

CLI Tools on KnightLi Blog