Wx Cli
Query your local WeChat desktop database for chat history, contacts, group members, and favorites from the terminal.
Overview
wx-cli is an agent skill for the Grow phase that installs and runs wx-cli to query local WeChat desktop chat, contacts, and favorites data.
Install
npx skills add https://github.com/jackwener/wx-cli --skill wx-cliWhat is this skill?
- Global npm or curl installer with wx --version verification
- macOS init flow: codesign WeChat.app, reset TCC entries, then wx init with sudo for key extraction
- Queries messages, contacts, sessions, group nicknames, and favorites from WeChat 4.x local DB
- Triggers on 查微信聊天记录, wechat history, and wx-cli invocation phrases
- Requires WeChat desktop logged in on macOS Apple Silicon/Intel or Linux
- Node.js >= 14 for npm install path
- WeChat desktop 4.x requirement
Adoption & trust: 1.5k installs on skills.sh; 3.3k GitHub stars; 0/3 security scanners passed (skills.sh audits).
What problem does it solve?
You cannot quickly search years of WeChat customer chats, group members, or favorites from your desktop client alone.
Who is it for?
macOS or Linux operators already on WeChat 4.x who own the data and need terminal search for support or personal archive tasks.
Skip if: Cloud multi-tenant analytics, unauthorized access to others’ accounts, or teams without WeChat desktop and acceptable use of local DB access.
When should I use this skill?
User mentions 微信聊天记录, 联系人, 收藏, wechat history/messages/contacts, wx-cli, or 帮我看看微信里.
What do I get? / Deliverables
You run wx-cli commands through the agent to retrieve structured chat and contact results from your local WeChat database after one-time init.
- Installed wx-cli binary
- Queryable local results for messages, contacts, sessions, or favorites
Recommended Skills
Journey fit
Grow covers lifecycle and customer context; many solo sellers support users via WeChat and need searchable history without manual scrolling. Support subphase fits offline lookup of past messages, group rosters, and saved favorites when answering repeat questions.
How it compares
Local-first WeChat DB CLI—not an official Tencent API or a generic chatbot integration.
Common Questions / FAQ
Who is wx-cli for?
Solo builders and small sellers on WeChat desktop who want agent-guided CLI queries over their own message and contact database.
When should I use wx-cli?
In Grow → support when you need 查微信聊天记录, group member lists, favorites, or English wechat history searches during customer follow-up.
Is wx-cli safe to install?
It requires sudo init, app re-signing, and TCC resets on macOS; review the Security Audits panel on this Prism page and treat it as high-trust local data access you initiate yourself.
SKILL.md
READMESKILL.md - Wx Cli
# wx-cli ## Triggers - 查微信聊天记录 - 微信消息历史 - 微信联系人 - 微信群成员 - 微信群昵称 / 群名片 - 微信收藏 - wechat history / messages / contacts - wx-cli - 帮我看看微信里 - 搜索微信消息 ## Prerequisites - macOS（Apple Silicon / Intel）或 Linux - 微信桌面版 4.x 已安装并登录 - Node.js >= 14（npm 安装方式）或 curl（shell 安装方式） - 首次 `wx init` 需要 `sudo`（内存扫描提取密钥） --- ## 安装 ### 方式一：npm（推荐） ```bash npm install -g @jackwener/wx-cli ``` ### 方式二：curl ```bash curl -fsSL https://raw.githubusercontent.com/jackwener/wx-cli/main/install.sh | bash ``` 安装后验证： ```bash wx --version ``` --- ## 初始化（首次使用，只需一次） ### macOS（必须按顺序执行） **第一步：对 WeChat 重新签名**（只需做一次，WeChat 更新后需重做） ```bash codesign --force --deep --sign - /Applications/WeChat.app ``` 如果报错 `signature in use` 或某个 dylib 签名损坏，先修复再签名： ```bash codesign --remove-signature "/Applications/WeChat.app/Contents/Frameworks/vlc_plugins/librtp_mpeg4_plugin.dylib" codesign --force --deep --sign - /Applications/WeChat.app ``` **第二步：清理 WeChat 在 macOS TCC 隐私数据库里的旧授权记录**（重签名后必做） macOS TCC 按 `bundle id + csreq` 联合校验权限；csreq 编码自代码签名。重签名后旧 csreq 和新签名不再匹配，旧授权记录会 silent 失效（System Settings 仍把开关画成"已允许"，运行时实际拒绝）。把 WeChat 在 TCC 里的旧记录抹掉，让 macOS 在下次微信请求权限时按新签名重新生成 csreq： ```bash tccutil reset ScreenCapture com.tencent.xinWeChat # 截图 / 屏幕共享 tccutil reset Camera com.tencent.xinWeChat # 视频通话 / 扫码 tccutil reset Microphone com.tencent.xinWeChat # 语音消息 / 通话 tccutil reset AppleEvents com.tencent.xinWeChat # 自动化 / 输入法 tccutil reset AddressBook com.tencent.xinWeChat # 通讯录 tccutil reset SystemPolicyDocumentsFolder com.tencent.xinWeChat tccutil reset SystemPolicyDownloadsFolder com.tencent.xinWeChat tccutil reset SystemPolicyDesktopFolder com.tencent.xinWeChat ``` `tccutil` 对没有授权过的 service 会报 "No such bundle identifier"，是 no-op，不影响其他 service 的 reset。 **第三步：重启 WeChat** ```bash killall WeChat && open /Applications/WeChat.app # 等待微信完全登录后再继续 ``` 之后微信触发权限请求时按 GUI 提示重新允许即可。在 macOS 26 上，把 WeChat 加进 **隐私与安全 → 录屏与系统录音** 的上半区，**不要**只勾下半区的"仅系统录音"——后者不能授予截图权限。 **第四步：初始化** ```bash sudo wx init ``` ### Linux ```bash sudo wx init ``` `wx init` 会自动： 1. 检测微信数据目录 2. 扫描进程内存，提取所有数据库密钥 3. 写入 `~/.wx-cli/config.json` 初始化完成后，后续所有命令无需 `sudo`，daemon 在首次调用时自动启动。 --- ## 命令速查 所有命令默认输出 YAML，更省 token & 易读；`--json` 可切换为 JSON（方便 `jq` 处理等）。 ### 会话与消息 ```bash # 最近 20 个会话 wx sessions # 有未读消息的会话 wx unread # 只看真人（私聊 + 群聊）的未读，过滤公众号与折叠入口 wx unread --filter private,group # 上次检查后的新消息（增量） wx new-messages wx new-messages --json # JSON 输出，适合 agent 解析 # 聊天记录（支持昵称/备注名） wx history "张三" wx history "张三" -n 2000 wx history "AI群" --since 2026-04-01 --until 2026-04-15 -n 100 # 全库搜索 wx search "关键词" wx search "关键词" -n 500 wx search "会议" --in "工作群" --since 2026-01-01 ``` `history` / `search` / `export` 都支持 `-n` / `--limit` 指定返回条数。默认值只是为了避免一次输出过多，不是硬上限。 `sessions` / `unread` / `history` / `new-messages` / `stats` 的输出都带 `chat_type` 字段，agent 可据此分流： | 取值 | 含义 | username 特征 | |------|------|--------------| | `private` | 真人私聊 | `wxid_*` 或自定义短号 | | `group` | 群聊 | `*@chatroom` | | `official_account` | 公众号 / 订阅号 / 服务号 / 系统通知 | `gh_*`、`biz_*`、`mphelper`、`qqsafe`、`@opencustomerservicemsg` | | `folded` | 折叠入口（订阅号折叠、折叠群聊的聚合条目） | `brandsessionholder`、`@placeholder_foldgroup` | `wx unread --filter` 支持 `private` / `group` / `official` / `folded` / `all`，逗号分隔多选。默认 `all`。 群聊消息里的 `last_sender`、`sender` 和 `stats.top_senders` 会优先显示群昵称（群名片）。如果本地数据库没有群昵称，再回退到联系人备注、微信昵称或 username。 `history` / `search` / `new-messages` / `attachments` 和 `stats.top_senders` 在群上下文里同时输出稳定身份三件套：`sender_username`（稳定 wxid，用来区分同名成员）/ `sender_contact_display`（备注 > 昵称 > wxid 兜底）/ `sender_group_nickname`（群名片，等价于 `sender` 的来源，免去再做字符串解析）。当 wxid 解析不到时，这三字段不会输出，避免空字符串污染下游过滤。 `sessions` / `unread` / `history` / `search` / `new-messages` / `stats` / `attachments` 的 stdout 现在统一是 wrapper： ```json { "messages": [...], "meta": { "status": "ok", "unknown_shards": [], "chat_latest_timestamp":