# 命令行使用

## 运行 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`：终端下进入带编辑和历史的交互会话；管道或文件 stdin 则无提示符批处理。`--interactive` / `--repl` 保留为兼容别名，无需再指定。
- `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` 读取 stdin 时为 lazy 会话定义。
- `--limit N`：限制每条语句返回的行数，默认不限；不等同于执行工作量限制。
- `--timing`：向 stderr 输出加载、解析、数据准备、缓存和 SQL 耗时；交互模式逐次输出查询耗时。
- `--trusted-input`：仅适用于输入与缓存均受控的环境。它跳过部分校验，包括 `query-cache` 对源输入的严格新鲜度检查。默认关闭。

`query` 不给 `--sql` 时默认读取 stdin，至少需要一个 `--input`。重复 `--input` 可组合多个 DEX/APK；显式 `--sql` 不读取 DEX/APK 时仍可省略输入，例如 `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"
```

终端会话保留完整数据集，支持方向键编辑与历史、Ctrl-R 搜索。续行提示为 `   ...> `。
Ctrl-C 清空当前未提交的 SQL 而不退出；Ctrl-D 退出且不提交未完成输入。
历史默认保存在 `~/.dexsql_history`，`DEXSQL_HISTORY` 可改路径；设为空字符串则关闭历史。
历史文件无法读写时只警告，不影响查询。管道或重定向模式不访问历史。

```bash
dexsql query --input app.apk
dexsql query --input app.apk < queries.sql
printf 'SELECT count(*) FROM methods;\n' | dexsql query --input app.apk
```

两种 stdin 模式都以行尾 `;` 或空行提交 SQL；批处理 EOF 也提交剩余输入。
没有待提交 SQL 时，点命令按行处理。`.exit`、`.quit`（兼容 `exit`、`quit`）结束会话，
退出命令之后的内容被忽略。错误写入 stderr，后续提交继续执行；只要 SQL 或点命令曾失败，
最终退出码就非零，即使随后使用 `.quit`。

批处理先读完 stdin，再以整组 expected SQL 进行 `PrepareMode::Auto` 按需准备。
`--full` 强制完整数据。含 `--cache`、TEMP TABLE/VIEW 定义、非查询输入或 `.smali` 时保守使用 Full：
当前会话 API 要求完整数据，才能维持 CREATE、重定义和 DROP 之间的 lazy 依赖。
准备阶段 SQL 规划失败也回退 Full，让错误语句不会阻断后面的提交。

终端和批处理的 `CREATE VIEW`、`CREATE TEMP VIEW`、`CREATE TEMP TABLE` 及 `--cache` 定义都跨提交保留。
`CREATE` 校验成功后替换定义，`IF NOT EXISTS` 保留原定义；`DROP VIEW` / `DROP TABLE` 删除定义。
所有定义（包括 TEMP TABLE）都为 lazy，仅查询需要时读取行；会话结束即释放。
显式 `--sql` 的请求级语义保持不变。

### 会话点命令

| 命令 | 行为 |
| --- | --- |
| `.tables [PATTERN]` | 排序列出内置表、VIEW、TEMP 表；可用 SQL LIKE 模式 `%`、`_`，ASCII 大小写不敏感。 |
| `.schema [TABLE]` | 列名和类型；内置表复用 `dexsql tables` 的固定 schema，也包含会话定义。 |
| `.mode table\|csv\|json\|line` | 输出格式；默认 table 与原文本表逐字节一致。 |
| `.headers on\|off` | 开关列名，默认 on；JSON 关闭时省略 columns，line 关闭时省略标签。 |
| `.timer on\|off` | 开关与 `--timing` 相同的单次提交耗时，输出至 stderr。 |
| `.smali DESCRIPTOR` | 当前数据集的方法或类反汇编，格式与 `dexsql decode` 相同；不重新打开数据集，解码器可能重载已释放的源字节。 |
| `.help` | 列出命令。 |
| `.exit`、`.quit` | 退出。 |

lazy 定义的列若依赖运行时值决定类型，会显示 `sqlite_dynamic`。

未知点命令报错并提示 `.help`，不会送入 SQL 执行。点命令只影响 stdin 会话；`--sql` 仍输出原文本表。

CSV 默认含表头；整数保留完整十进制，BLOB 为双引号包裹的小写十六进制，NULL 是不加引号的空字段。
文本总加双引号（含空字符串），内部引号双写、换行保留。CSV 不带运行时类型标签，消费者需避免整数舍入，
并根据 schema 区分十六进制文本与 BLOB。

JSON 每个结果一行对象，含 `columns` 名称数组及 `rows` 行数组，可保留重复列名。
单元格沿用 MCP compact：有符号/无符号整数为 `["i","十进制"]` / `["u","十进制"]`，
BLOB 为 `["b","小写十六进制"]`，NULL 为 `null`，文本为字符串，有限浮点数为数值。
特殊浮点数为 `["f","NaN"]`、`["f","Infinity"]`、`["f","-Infinity"]`。
这避免大整数精度丢失，并区分空 BLOB、空文本和 NULL。
line 模式按 `列名 = 值` 输出，行间空行，值的表示沿用文本表。

命名关系可用于重复 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。本文档采用 [MIT 许可证](../license.md)。
