# Wechat CLI Install

> Install, update, verify, and initialize the huohuoer/freestylefly WeChat CLI tool for querying local WeChat data. Use proactively when the user mentions analyzing WeChat chat records, 微信聊天记录分析, 微信好友聊天分析, exporting/searching local WeChat history, unread/new WeChat messages, contacts, sessions, favorites, or any task that needs local WeChat data and `wechat-cli` is not already confirmed installed and initialized.

- Skill: `shawn222/wechat-cli-install` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add shawn222/wechat-cli-install`
- Raw SKILL.md: https://api.skillmd.com/api/skills/shawn222/wechat-cli-install/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: Shawn222 (https://skillmd.com/u/shawn222)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/shawn222/wechat-cli-install

---


# WeChat CLI Install

## Core Rule

Before any local WeChat chat-record analysis, verify `wechat-cli` is available and initialized. If either check fails, install and initialize it before continuing with the user's actual analysis task.

Use the project named in the upstream README. On Windows, prefer the pip installation because the npm package may leave a broken launcher that looks for a missing Windows binary package.

## Workflow

1. Check the environment:

```powershell
node --version
npm --version
wechat-cli --help
```

2. Install or update.

On Windows, use pip:

```powershell
python --version
pip install -U wechat-cli
where.exe wechat-cli
```

If `where.exe wechat-cli` does not find the command, search common Python environments and call the executable by full path:

```powershell
Get-ChildItem -Path C:\Users\$env:USERNAME\AppData\Local\Programs\Python,C:\Users\$env:USERNAME\AppData\Roaming\Python,%USERPROFILE%\miniconda3 -Recurse -Filter wechat-cli* -ErrorAction SilentlyContinue
```

If a previous npm install left a broken launcher such as `Cannot find module '@canghe_ai/wechat-cli-win32-x64/package.json'`, remove the npm package and use the pip executable:

```powershell
npm uninstall -g @canghe_ai/wechat-cli @canghe_ai/wechat-cli-win32-x64
```

On macOS arm64, npm is acceptable:

```powershell
npm install -g @canghe_ai/wechat-cli
npm update -g @canghe_ai/wechat-cli
```

If a pip-installed launcher imports from a local checkout but reports missing modules, install the missing dependency into the same Python environment, e.g. `<python-for-that-env> -m pip install click`.

3. Ask the user to make sure WeChat is open and logged in, then initialize:

```powershell
wechat-cli init
```

On macOS/Linux, use `sudo wechat-cli init` when the command reports permission or process-memory access errors. On Windows, run from a terminal with sufficient privileges.

4. Confirm the tool works:

```powershell
wechat-cli sessions --limit 5
```

Prefer JSON output for agent processing. Use `--format text` only when the user wants a readable excerpt or when JSON parsing is not needed.

## Common Commands

Use `references/wechat-cli-commands.md` when you need command options or examples.

Frequent commands:

```powershell
wechat-cli sessions --limit 10
wechat-cli history "好友名" --limit 50
wechat-cli history "好友名" --limit 100 --start-time "2026-01-01" --end-time "2026-01-31"
wechat-cli search "关键词" --chat "好友名" --limit 20
wechat-cli contacts --query "好友名"
wechat-cli stats "好友名" --format text
wechat-cli export "好友名" --format markdown --limit 1000
```

## Privacy And Safety

- Treat all WeChat data as private local data.
- Do not upload chat records to external services.
- Only read/query/export data needed for the user's request.
- Explain that `wechat-cli` is read-only and works against local WeChat data.
- If initialization fails because WeChat is not running or the account is ambiguous, ask the user to open/login WeChat or choose the active account.