# 命令行使用

## 运行 CLI

将提供的 `dexsql` 可执行文件（Windows 为 `dexsql.exe`）放到 `PATH` 中的目录，或使用完整路径运行。以下示例使用 `dexsql`：

```bash
dexsql --version
dexsql --help
dexsql query --help
```

每个命令的 `--help` 列出可用参数。全局参数可以放在子命令前后。带 `\` 续行的示例使用 POSIX shell；在 PowerShell 或命令提示符中请合并成一行。

## 命令

- `tables --input app.apk`：显示内置表名、列和 SQL 类型。schema 固定；输入参数仅用于兼容，文件不会被读取。
- `query --input app.apk --sql "..."`：一次性查询，默认只准备 SQL 所需数据；结果与 `--full` 相同。
- `query --input app.apk --interactive`：在同一个内存数据集上连续执行查询的交互会话。
- `prepare-cache --input app.apk --output app.dexsql-cache`：解析输入，在输出目录中写入 `cache.dxc2`，用于重复查询。
- `query-cache --cache-file app.dexsql-cache/cache.dxc2 --sql "..."`：查询持久缓存容器文件。
- `decode --input app.apk --method 'Lcom/example/Foo;->bar(I)V'`：反汇编方法，详见 [Smali 解码](smali.zh.md)。
- `mcp`：通过 stdio 提供 MCP 工具和文档。客户端用 `open_dataset` 打开数据集，详见 [MCP 配置](../mcp/index.md)。
- `extract licenses --output THIRD_PARTY_NOTICES`：导出构建时嵌入此程序的第三方版权及许可声明。省略 `--output` 时输出到 stdout，不覆盖已有文件；无需 APK、网络连接或源码目录。声明包含程序依赖及运行库，不包含构建依赖、过程宏、编译器和链接器。

## 参数

- `--threads N`：工作线程数。`0` 和默认值都使用全部可用逻辑 CPU。
- `--full`（仅 `query`）：准备完整元数据、方法引用和 opcode 数据，而非仅准备 SQL 所需数据；查询结果相同。交互模式始终准备完整数据，因而此参数无效。使用 `prepare-cache` 保存供后续进程使用的缓存。
- `--cache NAME=SQL`：为一个 `SELECT` 定义命名。在 `query --sql` 和 `query-cache` 中限于当前请求，在 `query --interactive` 中为 lazy 会话定义。
- `--limit N`：限制每条语句返回的行数，默认不限；不等同于执行工作量限制。
- `--timing`：向 stderr 输出加载、解析、数据准备、缓存和 SQL 耗时；交互模式逐次输出查询耗时。
- `--trusted-input`：仅适用于输入与缓存均受控的环境。它跳过部分校验，包括 `query-cache` 对源输入的严格新鲜度检查。默认关闭。

`query` 必须选择 `--sql` 或 `--interactive`。重复 `--input` 可组合多个 DEX/APK；不读取 DEX/APK 的 SQL 可以省略输入，例如 `dexsql query --sql "SELECT 1"`。每个 `--sql` 传一条语句；多个 `--sql` 按顺序执行，共享一次加载的数据：

```bash
dexsql query \
  --input app.apk \
  --sql "select count(*) as class_count from classes" \
  --sql "select count(*) as method_count from class_methods"
```

交互模式至少需要一个 `--input`，并在查询之间保留内存中的 DEX/APK 数据。以分号或空行提交查询；`.help` 显示帮助，`.exit`、`.quit` 或 EOF 退出。`--repl` 是 `--interactive` 的别名：

```bash
dexsql query --input app.apk --interactive
```

交互模式下，`CREATE VIEW`、`CREATE TEMP VIEW`、`CREATE TEMP TABLE` 和 `--cache` 定义跨次提交保留。`CREATE` 在校验后替换现有定义；`IF NOT EXISTS` 保留原定义。`DROP VIEW` 或 `DROP TABLE` 删除定义。所有会话定义（包括 TEMP TABLE）都是 lazy 的，仅在查询需要时读取其行；会话关闭后定义消失。

命名关系可用于重复 join：

```bash
dexsql query \
  --input app.apk \
  --cache "refs_per_method=select file_id, method_idx, count(*) ref_count from method_refs group by file_id, method_idx" \
  --sql "select m.descriptor, r.ref_count from methods m join refs_per_method r using (file_id, method_idx) order by r.ref_count desc limit 20"
```

## 输入文件

支持 DEX、APK、JAR、ZIP 路径，重复 `--input` 可组合多个输入。压缩包内的 `classes*.dex` 编号可以不连续；格式错误的 DEX 成员会被跳过，后续可读成员仍然保留。压缩包结构损坏或超过解压预算仍会返回错误，SQL 输入加载至少需要一个可读 DEX。

跨进程重复查询可使用[持久缓存](cache.zh.md)。按需反汇编方法见 [Smali](smali.zh.md)。

## 连接 AI 客户端

使用可执行文件的绝对路径配置本地 stdio MCP 连接：

```json
{
  "mcpServers": {
    "dexsql": {
      "command": "/absolute/path/to/dexsql",
      "args": ["mcp"]
    }
  }
}
```

Windows 路径需遵循 JSON 转义，例如 `"D:\\Tools\\dexsql.exe"`。客户端负责启动进程，输入文件路径必须能被该进程访问。连接后的 AI 可查阅英文 [MCP 参考](../mcp/index.md)。

---

Copyright (c) 2026 LSPosed Developers。本文档采用 [MIT 许可证](../license.md)。