### Installation Guide

Source: https://github.com/aeron1-bit/pywxdump/blob/master/doc/UserGuide.md

Instructions for installing PyWxDump, including using pre-built executables, pip, or from source.

```APIDOC
## Installation

### 1. Using Release Executable

Download the latest release `.exe` file from [GitHub Releases](https://github.com/xaoyaoo/PyWxDump/releases).

### 2. Using pip (Stable Version)

```shell
pip install -U pywxdump
```

### 3. From Source (Latest Version)

```shell
# Install latest version
pip install -U git+git://github.com/xaoyaoo/PyWxDump.git

# For web GUI (requires additional steps):
# Clone the web GUI repository
git clone https://github.com/xaoyaoo/wxdump_web.git
cd wxdump_web
npm run build
cd ..

# Copy web GUI files into PyWxDump
cp -r wxdump_web/dist PyWxDump/pywxdump/ui/web

# Install PyWxDump with web GUI support
cd PyWxDump
python -m pip install -U .
```

### 4. Building Executable (from source)

Ensure you have Python, the source code, and `pyinstaller` installed.

```shell
cd tests
python build_exe.py
# Follow the output script for pyinstaller command
pyinstaller --clean --distpath=dist dist/pywxdump.spec
```

Alternatively, download pre-built executables from [GitHub Releases](https://github.com/xaoyaoo/PyWxDump/releases).
```

--------------------------------

### Default Execution (Start UI)

Source: https://context7.com/aeron1-bit/pywxdump/llms.txt

When no parameters are provided, PyWxDump defaults to starting the web UI.

```APIDOC
## GET /aeron1-bit/pywxdump

### Description
When executed without any command-line arguments, PyWxDump defaults to starting the web-based user interface.

### Method
GET

### Endpoint
/aeron1-bit/pywxdump
```

--------------------------------

### Start API Service

Source: https://context7.com/aeron1-bit/pywxdump/llms.txt

Starts an API service without a graphical user interface, useful for backend integrations.

```APIDOC
## GET /aeron1-bit/pywxdump/api

### Description
Starts an API service without a graphical user interface. This is suitable for integrating PyWxDump functionalities into other systems.

### Method
GET

### Endpoint
/aeron1-bit/pywxdump/api

### Query Parameters
- **-p** (integer) - Optional - Port number to run the API service on.
- **--online** - Optional - Flag to enable online mode.
- **--debug** - Optional - Flag to enable debug mode.
```

--------------------------------

### Start Web UI

Source: https://context7.com/aeron1-bit/pywxdump/llms.txt

Launches a web-based user interface for managing WeChat data. Supports local network access.

```APIDOC
## GET /aeron1-bit/pywxdump/ui

### Description
Starts a web-based user interface for managing WeChat data. This UI can be accessed over a local network.

### Method
GET

### Endpoint
/aeron1-bit/pywxdump/ui

### Query Parameters
- **-p** (integer) - Optional - Port number to run the web server on.
- **--online** - Optional - Flag to enable online mode.
- **--debug** - Optional - Flag to enable debug mode.
- **--noOpenBrowser** - Optional - Flag to prevent automatically opening the browser.
```

--------------------------------

### Python API Usage

Source: https://github.com/aeron1-bit/pywxdump/blob/master/doc/UserGuide.md

Examples of using PyWxDump's functions directly within Python scripts.

```APIDOC
## Python API Usage

Import and use functions directly in your Python code.

### Get WeChat Base Address Offsets

```python
from pywxdump import BiasAddr

args = {
    "account": "wechat_account",
    "mobile": "13800138000",
    "name": "wechat_nickname",
    "key": "secret_key", # Optional
    "db_path": "wechat_folder_path", # Optional
    "WX_OFFS_path": "offsets_file_path" # Optional
}

bias_addr = BiasAddr(args["account"], args["mobile"], args["name"], args["key"], args["db_path"])
result = bias_addr.run(True, args["WX_OFFS_path"])
print(result)
```

### Get WeChat Information

```python
from pywxdump import read_info, WX_OFFS

# Assuming WX_OFFS is correctly populated or loaded
wx_info = read_info(WX_OFFS, True)
print(wx_info)
```

### Get WeChat Folder Path

```python
from pywxdump import get_wechat_db

args = {
    "require_list": "all",  # Optional
    "wx_files": "WeChat Files",  # Optional
    "wxid": "wxid_",  # Optional
}
user_dirs = get_wechat_db(args["require_list"], args["wx_files"], args["wxid"], True)
print(user_dirs)
```

### Decrypt WeChat Database

```python
from pywxdump import batch_decrypt

args = {
    "key": "secret_key",
    "db_path": "/path/to/wechat/databases",
    "out_path": "/path/to/output"
}
result = batch_decrypt(args["key"], args["db_path"], args["out_path"], True)
print(result)
```
```

--------------------------------

### Get WeChat Database Path

Source: https://context7.com/aeron1-bit/pywxdump/llms.txt

Retrieves the path to the WeChat database files.

```APIDOC
## GET /aeron1-bit/pywxdump/wx_path

### Description
Retrieves the path to the WeChat database files, optionally filtering by message types or specifying WeChat Files directory.

### Method
GET

### Endpoint
/aeron1-bit/pywxdump/wx_path

### Query Parameters
- **-r** (string) - Optional - Filter by message types (e.g., MSG;MicroMsg;MediaMSG).
- **-wf** (string) - Optional - Specify the path to the "WeChat Files" directory.
- **-id** (string) - Optional - Specify the WeChat ID (wxid_xxx).
```

--------------------------------

### GET /info

Source: https://context7.com/aeron1-bit/pywxdump/llms.txt

Retrieves WeChat account information including nickname, account ID, mobile, email, and the database key from the running process memory.

```APIDOC
## GET /info

### Description
Retrieves account details from the active WeChat process memory.

### Method
GET

### Endpoint
/info

### Parameters
#### Query Parameters
- **save_path** (string) - Optional - Path to save the JSON output.

### Response
#### Success Response (200)
- **pid** (integer) - Process ID
- **version** (string) - WeChat version
- **account** (string) - WeChat account ID
- **mobile** (string) - Linked mobile number
- **nickname** (string) - User nickname
- **key** (string) - 64-character hex database key

#### Response Example
{
  "account": "user123",
  "nickname": "John Doe",
  "key": "64_char_hex_string"
}
```

--------------------------------

### Get WeChat Database Paths (Python)

Source: https://context7.com/aeron1-bit/pywxdump/llms.txt

Locates all database files within a specified WeChat user directory. It supports filtering by database type (e.g., MSG, MicroMsg) and wxid. The function returns a list of dictionaries, each containing the wxid, database type, full path to the database file, and the user's directory.

```python
from pywxdump import get_wx_db

# Get all WeChat database paths
db_list = get_wx_db(
    msg_dir="C:\\Users\\xxx\\Documents\\WeChat Files",  # WeChat Files directory
    db_types=["MSG", "MicroMsg", "MediaMSG"],  # Optional: Specify database types
    wxids=["wxid_xxxxxxxxxx"]  # Optional: Specify wxid
)

# Example return value:
# [
#     {
#         "wxid": "wxid_xxxxxxxxxx",
#         "db_type": "MSG",
#         "db_path": "C:\\...\\Msg\\MSG0.db",
#         "wxid_dir": "C:\\...\\wxid_xxxxxxxxxx"
#     },
#     {
#         "wxid": "wxid_xxxxxxxxxx",
#         "db_type": "MicroMsg",
#         "db_path": "C:\\...\\Msg\\MicroMsg.db",
#         "wxid_dir": "C:\\...\\wxid_xxxxxxxxxx"
#     }
# ]

# Command-line usage:
# wxdump wx_path [-r MSG;MicroMsg] [-wf "WeChat Files path"] [-id wxid_xxx]
```

--------------------------------

### Get WeChat Account Information (Python)

Source: https://context7.com/aeron1-bit/pywxdump/llms.txt

Retrieves account details such as nickname, account, phone number, email, wxid, database key, and WeChat folder path from running WeChat processes. It reads memory and uses version-specific offsets. The output can be printed or saved to a JSON file.

```python
from pywxdump import get_wx_info, WX_OFFS

# Get all information for the currently logged-in WeChat
# WX_OFFS contains memory offsets for different WeChat versions
result = get_wx_info(WX_OFFS, is_print=True, save_path="wx_info.json")

# Example return value:
# [
#     {
#         "pid": 12345,
#         "version": "3.9.12.51",
#         "account": "your_account",
#         "mobile": "138****8000",
#         "nickname": "微信昵称",
#         "mail": "email@example.com",
#         "wxid": "wxid_xxxxxxxxxx",
#         "key": "64-bit hexadecimal key string",
#         "wx_dir": "C:\\Users\\xxx\\Documents\\WeChat Files\\wxid_xxx"
#     }
# ]

# Command-line usage:
# wxdump info [-s save_path]
```

--------------------------------

### Get Base Offset

Source: https://context7.com/aeron1-bit/pywxdump/llms.txt

Obtains base offset information, useful for supporting newer versions of WeChat.

```APIDOC
## GET /aeron1-bit/pywxdump/bias

### Description
Retrieves base offset information, which is necessary for supporting newer versions of WeChat.

### Method
GET

### Endpoint
/aeron1-bit/pywxdump/bias

### Query Parameters
- **--mobile** (string) - Required - Mobile number associated with the WeChat account.
- **--name** (string) - Required - Nickname of the WeChat account.
- **--account** (string) - Required - WeChat account identifier.
- **--key** (string) - Optional - Encryption key.
```

--------------------------------

### Command-Line Usage

Source: https://github.com/aeron1-bit/pywxdump/blob/master/doc/UserGuide.md

How to use the `wxdump` command-line tool for various operations.

```APIDOC
## Command-Line Usage

Run `wxdump -h` for detailed help.

### Modes:

- `bias`: Get WeChat base address offsets.
- `info`: Get WeChat information.
- `wx_path`: Get WeChat folder path.
- `decrypt`: Decrypt WeChat databases.
- `merge`: Merge WeChat databases (experimental).
- `all`: (Deprecated) Get info, decrypt DB, view chat records.
- `ui`: Start the web graphical interface.
- `api`: Start the API service (default port 5000).

### Examples:

#### Get WeChat Base Address Offsets

```bash
wxdump bias --mobile <phone_number> --name <wechat_nickname> --account <wechat_account> [--key <secret_key>] [--db_path <wechat_folder_path>] [--WX_OFFS_path <offsets_file_path>]
```

#### Get WeChat Information

```bash
wxdump info [--WX_OFFS_path <offsets_file_path>]
```

#### Get WeChat Folder Path

```bash
wxdump wx_path [-r <database_name>] [-wf <WeChat Files_path>] [-id <wxid_>]
```

#### Decrypt WeChat Database

```bash
wxdump decrypt -k <secret_key> -i <database_path> [-o <output_path>]
```

#### Start Web GUI

```bash
wxdump ui
```

#### Start API Service

```bash
wxdump api
```
```

--------------------------------

### 打包可执行文件

Source: https://github.com/aeron1-bit/pywxdump/blob/master/doc/UserGuide.md

使用 PyInstaller 将 PyWxDump 源码打包为独立的可执行文件。

```shell
cd tests
python build_exe.py
pyinstaller --clean --distpath=dist dist/pywxdump.spec
```

--------------------------------

### 命令行操作示例

Source: https://github.com/aeron1-bit/pywxdump/blob/master/doc/UserGuide.md

展示如何通过命令行调用 PyWxDump 的不同功能模式，如获取基址、解密数据库及启动 API 服务。

```bash
wxdump bias --mobile <手机号> --name <微信昵称> --account <微信账号>
wxdump info
wxdump decrypt -k <密钥> -i <数据库路径> -o <输出路径>
wxdump api
```

--------------------------------

### 安装 PyWxDump

Source: https://github.com/aeron1-bit/pywxdump/blob/master/doc/UserGuide.md

提供通过 PyPI 安装稳定版以及从源码构建包含 Web 图形界面的最新版的方法。

```shell
pip install -U pywxdump
```

```shell
git clone https://github.com/xaoyaoo/wxdump_web.git
cd wxdump_web
npm run build
cd ..
git clone https://github.com/xaoyaoo/PyWxDump.git
cp -r wxdump_web/dist PyWxDump/pywxdump/ui/web
cd PyWxDump
python -m pip install -U .
```

--------------------------------

### Python API 调用

Source: https://github.com/aeron1-bit/pywxdump/blob/master/doc/UserGuide.md

通过导入 pywxdump 模块在 Python 代码中直接调用核心功能，包括基址获取、信息读取及数据库解密。

```python
from pywxdump import *

# 获取微信基址偏移
bias_addr = BiasAddr("account", "mobile", "name", "key", "db_path")
result = bias_addr.run(True, "WX_OFFS_path")

# 获取微信信息
wx_info = read_info(WX_OFFS, True)

# 解密微信数据库
result = batch_decrypt("key", "db_path", "/path/to/decrypted", True)
```

--------------------------------

### Real-time Merge Encrypted Databases (Python)

Source: https://context7.com/aeron1-bit/pywxdump/llms.txt

Merges encrypted WeChat databases in real-time while WeChat is running, without needing to decrypt them first. This feature is only supported on 64-bit systems. It requires the decryption key and paths to the databases to be merged. An optional path for a custom real-time executable can be provided.

```python
from pywxdump import merge_real_time_db, all_merge_real_time_db

# Method 1: Merge specified databases
db_paths = [
    {
        'wxid': 'wxid_xxx',
        'db_type': 'MSG',
        'db_path': 'C:\\...\\wxid_xxx\\Msg\\MSG0.db',
        'wxid_dir': 'C:\\...\\wxid_xxx'
    }
]

success, result = merge_real_time_db(
    key="your_64_char_hex_key",
    merge_path="C:\\output\\merge_realtime.db",
    db_paths=db_paths,
    real_time_exe_path=None  # Optional: Custom tool path
)

# Method 2: Merge all databases for all logged-in users (example)
# success, result = all_merge_real_time_db(
#     key="your_64_char_hex_key",
#     merge_path="C:\\output\\all_merge_realtime.db",
#     real_time_exe_path=None
# )

if success:
    print(f"Real-time merge successful: {result}")
else:
    print(f"Real-time merge failed: {result}")
```

--------------------------------

### POST /merge

Source: https://context7.com/aeron1-bit/pywxdump/llms.txt

Merges multiple decrypted WeChat database files into a single master database.

```APIDOC
## POST /merge

### Description
Combines multiple decrypted database files into one, handling duplicate records.

### Method
POST

### Endpoint
/merge

### Parameters
#### Request Body
- **db_paths** (array) - Required - List of objects containing db_path and de_path
- **save_path** (string) - Required - Output path for the merged database

### Response
#### Success Response (200)
- **merged_path** (string) - Path to the resulting merged database

#### Response Example
{
  "merged_path": "C:\\output\\merge_all.db"
}
```

--------------------------------

### Programmatic Integration with PyWxDump

Source: https://context7.com/aeron1-bit/pywxdump/llms.txt

Python API usage for integrating WeChat data processing into custom applications. This involves retrieving info, decrypting/merging databases, and generating a FastAPI application for data exposure.

```python
from pywxdump import get_wx_info, decrypt_merge, start_server, gen_fastapi_app

# Retrieve key and path
info = get_wx_info()

# Decrypt and merge databases
success, result = decrypt_merge(info['key'], info['path'])

# Generate a FastAPI app for custom deployment
app = gen_fastapi_app()
```

--------------------------------

### WeChat Database CLI Operations

Source: https://context7.com/aeron1-bit/pywxdump/llms.txt

Common CLI commands for interacting with WeChat data. These include path retrieval, key-based decryption, database merging, and launching the built-in Web UI or API server.

```bash
wxdump wx_path -r MSG;MicroMsg;MediaMSG
wxdump decrypt -k <64位十六进制密钥> -i <数据库路径> -o <输出目录>
wxdump merge -i "db1.db,db2.db" -o <输出路径>
wxdump ui -p 8080
wxdump api -p 8000
```

--------------------------------

### Extract WeChat Database Key with Python

Source: https://github.com/aeron1-bit/pywxdump/blob/master/doc/MAC数据库解密.md

This Python script processes raw key data obtained from lldb to generate the final WeChat database encryption key. It parses a multi-line string, extracts hexadecimal values, and concatenates them into a single key string. Ensure the input `ori_key` is correctly formatted.

```python
ori_key = "\n0x60000241e920: 0xc2 0xf9 0x13 0xbe 0xda 0xe8 0x45 0x82\n0x60000241e928: 0x93 0x94 0xsb 0xbf 0x61 0x86 0xd9 0xzf\n0x60000241e930: 0xab 0xd3 0x0e 0xf0 0x39 0xcf 0x4c 0xba\n0x60000241e938: 0x99 0x3a 0x01 0x05 0x2f 0xz5 0x2d 0xcd\n"

key = '0x' + ''.join(i.partition(':')[2].replace('0x', '').replace(' ', '') for i in ori_key.split('\n')[1:5])
print(key)
```

--------------------------------

### Show Database Records

Source: https://context7.com/aeron1-bit/pywxdump/llms.txt

Displays chat records from a specified database, with options for WeChat folder and online status.

```APIDOC
## GET /aeron1-bit/pywxdump/dbshow

### Description
Displays chat records from a specified database. Allows specifying the WeChat folder, your WeChat ID, and online status.

### Method
GET

### Endpoint
/aeron1-bit/pywxdump/dbshow

### Query Parameters
- **-merge** (string) - Required - Path to the merged database file.
- **-wid** (string) - Optional - Path to the WeChat folder.
- **-myid** (string) - Optional - Your WeChat ID.
- **--online** - Optional - Flag to indicate online status.
```

--------------------------------

### Merge Databases

Source: https://context7.com/aeron1-bit/pywxdump/llms.txt

Merges multiple WeChat database files into a single database.

```APIDOC
## POST /aeron1-bit/pywxdump/merge

### Description
Merges multiple WeChat database files into a single, consolidated database.

### Method
POST

### Endpoint
/aeron1-bit/pywxdump/merge

### Query Parameters
- **-i** (string) - Required - Comma-separated list of database file paths to merge (e.g., "db1.db,db2.db").
- **-o** (string) - Optional - Path to save the merged database file.
```

--------------------------------

### Decrypt and Merge WeChat Databases (Python)

Source: https://context7.com/aeron1-bit/pywxdump/llms.txt

Performs decryption and merging of WeChat core databases in a single operation. It takes the WeChat user directory, decryption key, and output paths for temporary decrypted files and the final merged database. Options include merging data, deleting temporary files after merging, and filtering by database type and creation time.

```python
from pywxdump import decrypt_merge

# Decrypt and merge WeChat core databases
success, result = decrypt_merge(
    wx_path="C:\\...\\WeChat Files\\wxid_xxx",  # WeChat user directory
    key="your_64_char_hex_key",
    outpath="C:\\output",  # Output directory
    merge_save_path="C:\\output\\merge_all.db",  # Path for the merged database
    is_merge_data=True,
    is_del_decrypted=True,  # Delete temporary decrypted files after merging
    startCreateTime=0,
    endCreateTime=0,
    db_type=["MSG", "MicroMsg", "MediaMSG"]  # Optional: Specify database types
)

if success:
    print(f"Decryption and merge successful: {result}")
else:
    print(f"Decryption and merge failed: {result}")
```

--------------------------------

### Batch Decrypt WeChat Databases (Python)

Source: https://context7.com/aeron1-bit/pywxdump/llms.txt

Decrypts multiple WeChat database files in batch from a specified directory or list of files. It requires a 64-character hexadecimal key and an output directory for the decrypted files. The function provides feedback on successful and failed decryption attempts.

```python
from pywxdump import batch_decrypt
import os

# Prepare output directory
out_path = "C:\\decrypted_dbs"
os.makedirs(out_path, exist_ok=True)

# Batch decrypt all databases in a directory
key = "your_64_char_hex_key_here_0123456789abcdef0123456789abcdef"
success, results = batch_decrypt(
    key=key,
    db_path="C:\\...\\wxid_xxx\\Msg",  # Can be a directory or a list of files
    out_path=out_path,
    is_print=True  # Print decryption results
)

# Example output:
# ================================
# [+] "...\\MSG0.db" -> "...\\de_MSG0.db"
# [+] "...\\MSG1.db" -> "...\\de_MSG1.db"
# [-] Key Error! (key:'xxx'; db_path:'...')  # Files that failed decryption
# --------------------------------
# [+] Total 10 files, 8 successful, 2 failed
# ================================

# Command-line usage:
# wxdump decrypt -k <key> -i <database_path> [-o <output_path>]
```

--------------------------------

### Merge WeChat Databases (Python)

Source: https://context7.com/aeron1-bit/pywxdump/llms.txt

Combines multiple decrypted WeChat database files into a single database. It automatically handles duplicate data and table structure differences. The function takes a list of dictionaries, each containing the original and decrypted paths of the databases to merge, and an output path for the merged database. Optional time-based filtering is available.

```python
from pywxdump import merge_db

# Prepare list of databases to merge
db_paths = [
    {"db_path": "C:\\original\\MSG0.db", "de_path": "C:\\decrypted\\de_MSG0.db"},
    {"db_path": "C:\\original\\MSG1.db", "de_path": "C:\\decrypted\\de_MSG1.db"},
    {"db_path": "C:\\original\\MicroMsg.db", "de_path": "C:\\decrypted\\de_MicroMsg.db"},
]

# Merge databases
merged_path = merge_db(
    db_paths=db_paths,
    save_path="C:\\output\\merge_all.db",  # Output file path
    is_merge_data=True,  # Whether to merge data
    startCreateTime=0,  # Optional: Start timestamp filter
    endCreateTime=0  # Optional: End timestamp filter
)

print(f"Merge complete: {merged_path}")

# Command-line usage:
# wxdump merge -i "db1.db,db2.db,db3.db" [-o <output_path>]
```

--------------------------------

### POST /decrypt

Source: https://context7.com/aeron1-bit/pywxdump/llms.txt

Decrypts an encrypted WeChat SQLite database file using the provided 64-character hex key.

```APIDOC
## POST /decrypt

### Description
Decrypts a single WeChat database file using AES-CBC.

### Method
POST

### Endpoint
/decrypt

### Parameters
#### Request Body
- **key** (string) - Required - 64-character hex database key
- **db_path** (string) - Required - Path to the encrypted .db file
- **out_path** (string) - Required - Path to save the decrypted file

### Response
#### Success Response (200)
- **success** (boolean) - Status of the operation
- **result** (array) - List containing original path, output path, and key used

#### Response Example
{
  "success": true,
  "result": ["path/to/db", "path/to/out", "key"]
}
```

--------------------------------

### Define WeChat Version Memory Offsets

Source: https://github.com/aeron1-bit/pywxdump/blob/master/doc/CE获取基址.md

A JSON configuration structure used to define the memory offsets for various WeChat user attributes, including nickname, account, phone, email, and key. These values are typically derived from manual memory analysis using tools like Cheat Engine.

```json
{
	"微信版本号":
	[
		50320784,
		50321712,
		50320640,
		38986104,
		50321676
	]
}
```

--------------------------------

### Decrypt Database

Source: https://context7.com/aeron1-bit/pywxdump/llms.txt

Decrypts WeChat database files using a provided key.

```APIDOC
## POST /aeron1-bit/pywxdump/decrypt

### Description
Decrypts WeChat database files using a provided 64-bit hexadecimal key.

### Method
POST

### Endpoint
/aeron1-bit/pywxdump/decrypt

### Query Parameters
- **-k** (string) - Required - 64-bit hexadecimal decryption key.
- **-i** (string) - Required - Path to the database file to decrypt.
- **-o** (string) - Optional - Directory to save the decrypted database.
```

--------------------------------

### Decrypt Single WeChat Database (Python)

Source: https://context7.com/aeron1-bit/pywxdump/llms.txt

Decrypts a single WeChat database file using a provided 64-character hexadecimal key. WeChat databases are encrypted using AES-CBC with a 256-bit key, and each 4KB page is encrypted independently. The function takes the key, path to the encrypted database, and an output path for the decrypted file.

```python
from pywxdump import decrypt

# Decrypt a single database file
key = "your_64_char_hex_key_here_0123456789abcdef0123456789abcdef"
success, result = decrypt(
    key=key,
    db_path="C:\\...\\Msg\\MicroMsg.db",  # Path to the encrypted database
    out_path="C:\\output\\de_MicroMsg.db"  # Output path for the decrypted file
)

if success:
    print(f"Decryption successful: {result}")
    # result: ['original path', 'output path', 'key']
else:
    print(f"Decryption failed: {result}")
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.