wcctl

Use your local WeChat data with AI agents, scripts, search tools, and other software.

wcctl gives you a simple command-line interface for reading contacts, chatrooms, recent conversations, and messages from WeChat 4.x on macOS. Results can be printed as a table for people or as JSON for other programs.

# See your recent conversations.
wcctl sessions

# Get message history as structured data.
wcctl messages -chat wxid_example -limit 100 -json

Your data stays on your Mac. Once setup is complete, all contact, chatroom, session, and message commands are read-only and can run while WeChat is open.

License notice: Schedule A permits licensed use only for interoperability solely for computational data analysis, only with lawfully accessed data, and only while physically outside the United States, Mainland China, and Hong Kong, and it also restricts distribution and secondary licensing.

• Give a local AI agent relevant WeChat context for a task.
• Search, summarize, or analyze your own conversations.
• Export structured data to Python, jq, spreadsheets, or indexing tools.
• Build personal automations without uploading your WeChat database to a new service.
• Work with more than one WeChat account from the same installation.

For example, an agent can first list your recent sessions, choose the relevant contact or group, and then request a limited window of messages. Because every command supports JSON, the agent does not need to understand WeChat's database format.

You need:

• macOS 12 or newer
• WeChat 4.x

If you use Codex or another trusted AI agent that can access the Terminal on your Mac, it can install and verify wcctl for you. Start a new task and paste this message:

Install the latest release of wcctl from https://github.com/XIAZY/wcctl. Use the project's official installation script and its default user-local installation directory. Update my PATH only if necessary, then run wcctl version to verify the installation. Explain any permission request before asking me to approve it. Do not accept the wcctl license on my behalf.

The agent should report an installation path ending in .local/bin/wcctl and a version line beginning with wcctl v. It may ask for permission to download the installer or update your shell configuration. Those are expected; unrelated system changes are not.

Installation does not accept the wcctl license. The first time you use a data command, read the conditions and answer the confirmation questions yourself.

Install the latest release:

curl -fsSL https://raw.githubusercontent.com/XIAZY/wcctl/main/install.sh | sh

The installer detects Apple Silicon or Intel automatically, verifies the downloaded release checksum, and installs wcctl to ~/.local/bin without requiring administrator access. If needed, it adds that directory to PATH in your .zshrc or .bashrc; open a new terminal afterward. To install somewhere else:

curl -fsSL https://raw.githubusercontent.com/XIAZY/wcctl/main/install.sh \
  | sh -s -- --dir "/path/to/bin"

When using a custom directory, make sure it is included in your PATH.

The first time you run wcctl, it will show the license conditions and ask you to confirm that they apply to your use. The complete license is embedded in the executable and can be printed at any time:

wcctl license

To see which release is installed:

wcctl version

WeChat encrypts its local databases. wcctl needs to acquire and verify their keys before it can read them.

This setup requires System Integrity Protection (SIP) to be disabled temporarily. Follow Apple's SIP instructions, then confirm after restarting:

csrutil status

Open WeChat, sign in, and wait for your conversations to load. Then run the following command from your normal macOS account:

wcctl key acquire

Do not add sudo. wcctl will request administrator permission for the part that needs it.

The command guides you through account selection and tells you exactly what it is about to do. WeChat will be closed during acquisition, so save anything unfinished first. When acquisition succeeds, the verified keys are saved in ~/.wcctl/keys.json and the temporary capture is deleted.

After saving the keys, wcctl prominently reminds you to re-enable SIP.

Restart WeChat when you are ready. Re-enable SIP from macOS Recovery with csrutil enable, restart the Mac, and confirm with csrutil status. Normal wcctl queries continue to work with SIP enabled.

List people in your contacts:

wcctl contacts

List group chats:

wcctl chatrooms

See conversations ordered by recent activity:

wcctl sessions

Copy a username from one of those commands and use it to read messages:

wcctl messages -chat wxid_example
wcctl messages -chat 123456789@chatroom -limit 100

That is everything needed for normal use.

Add -json to any listing command:

wcctl contacts -json
wcctl chatrooms -json
wcctl sessions -limit 100 -json
wcctl messages -chat wxid_example -limit 200 -json

Any local tool that can run a command and parse JSON can use wcctl. A typical workflow is:

1. Run sessions -json to discover recent conversations.
2. Select a session by its username.
3. Run messages -chat USERNAME -json to retrieve the relevant history.
4. Pass only that result to the agent or analysis step that needs it.

It also works in ordinary shell pipelines:

wcctl sessions -limit 5 -json | jq -r '.[].username'
wcctl messages -chat wxid_example -json > messages.json

wcctl does not upload this data. The tool you connect it to decides what happens to the JSON afterward.

wcctl contacts [-user USER] [-json]

Lists regular contacts and their available profile metadata. Chatrooms, official accounts, deleted contacts, and WeChat's built-in identities are not included.

wcctl chatrooms [-user USER] [-json]

Lists group chats with available details such as their names, owners, member counts, and announcements.

wcctl sessions [-limit N] [-user USER] [-json]

Lists recent conversations, including their usernames, display names, unread state, last activity, and summaries when available. The default limit is 50.

wcctl messages -chat USERNAME \
  [-limit N] [-before TIME] [-user USER] [-json]

Lists messages with a contact or chatroom. wcctl automatically searches all of the local message databases and combines the results in time order. The default limit is 50.

To retrieve older messages, pass the time of the oldest result back through -before. It accepts a Unix timestamp or RFC3339 time:

wcctl messages -chat wxid_example -limit 100 \
  -before 2026-08-01T00:00:00Z -json

Text messages are decoded when possible. Image, video, voice, emoticon, and other attachment metadata may be shown, but exporting the media files themselves is not yet supported.

If keys have been acquired for more than one WeChat account, list them and choose a default:

wcctl user ls
wcctl user use ACCOUNT
wcctl user current

Use -user ACCOUNT when you want to switch for just one command:

wcctl messages -user ACCOUNT -chat wxid_example -json

With only one account, no selection is necessary.

Most people only need:

wcctl key acquire

If auto-detection finds multiple accounts or WeChat processes, choose from the prompt. You can also specify them directly:

wcctl key acquire -account ACCOUNT
wcctl key acquire -pid PID

If acquisition fails after creating a capture, retry key extraction without closing WeChat again:

wcctl key extract -capture /path/to/capture

Advanced options are available for custom database locations, key-store paths, capture locations, and automated confirmation:

wcctl key acquire -data-dir /path/to/xwechat_files
wcctl key acquire -keys /path/to/keys.json
wcctl key acquire -out ./capture
wcctl key acquire -keep-dump
wcctl key acquire -yes

Run wcctl key acquire -h or wcctl key extract -h for the full option list.

• Use wcctl only with accounts and data you are authorized to access and only as permitted by the license.
• Contact, chatroom, session, and message queries never open WeChat's live SQLite databases. Each query uses private, disposable APFS copy-on-write clones of the database and WAL, and rebuilds SHM only beside those clones. A regular private copy is used when APFS cloning is unavailable.
• The database and WAL are cloned individually. A query made while WeChat is actively committing or checkpointing may therefore be slightly stale or, rarely, fail because the two files came from different instants. Retrying the command obtains a fresh copy.
• ~/.wcctl/keys.json contains sensitive database keys. Do not share it.
• A retained memory capture may contain messages, credentials, and other private data. Delete it when it is no longer needed.
• JSON output can contain private contact and message data. Be deliberate about which agents, services, or files receive it.

SIP only needs to be disabled for key acquire. Follow Apple's Recovery instructions, restart, and check csrutil status before trying again.

Open the main WeChat application, sign in, and retry. wcctl intentionally ignores helper and renderer processes.

Choose from the prompt, or pass -account ACCOUNT or -pid PID.

Make sure WeChat was signed in and fully loaded, and that the selected local account matches it. If a capture was retained, retry with wcctl key extract -capture PATH before acquiring again.

wcctl stops immediately if it cannot safely pause WeChat or complete the capture. The retained capture can help diagnose or retry the operation, but it should be treated as sensitive data.

wcctl is distributed under the Data Interoperability Source License 1.0. The license includes purpose, lawful-access, and territory conditions. Read it before using or distributing the software.

Third-party component information is available in THIRD_PARTY_NOTICES.