> ## Documentation Index
> Fetch the complete documentation index at: https://docs.textin.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> 提供可直接复制运行的命令行工具，快速将 xParse 文档解析能力集成到开发环境中

基于 TextIn xParse API 的命令行工具，支持 PDF、图片、Office 文档等 20+ 种格式转换为 Markdown 及结构化数据。

## 一键安装

**Linux / macOS**

```bash theme={null}
source <(curl -fsSL https://dllf.intsig.net/download/2026/Solution/xparse-cli/install.sh)
```

**Windows (PowerShell)**

```powershell theme={null}
irm https://dllf.intsig.net/download/2026/Solution/xparse-cli/install.ps1 | iex
```

## 快速开始

### 1. 零配置解析（免登录, 每日 1000 页）

```bash theme={null}
# 输出 Markdown 到终端
xparse-cli parse report.pdf

# JSON 视图
xparse-cli parse report.pdf --view json

# 保存到目录
xparse-cli parse report.pdf --output ./output/

# 指定页码范围
xparse-cli parse report.pdf --page-range "1-5"

# 加密 PDF
xparse-cli parse secret.pdf --password mypassword
```

### 2. 付费 API（可选，支持更多格式和高级选项）

前往 [TextIn 控制台](https://www.textin.com/user/login?redirect=%252Fconsole%252Fdashboard%252Fsetting\&from=xparse-parse-skill) 获取凭证（`x-ti-app-id` 和 `x-ti-secret-code`），然后运行：

```bash theme={null}
xparse-cli auth
```

按提示输入 App ID 和 Secret Code，凭证将保存至 `~/.xparse-cli/config.yaml`。

也可通过环境变量配置（适合 CI/CD）：

```bash theme={null}
export XPARSE_APP_ID=your_app_id
export XPARSE_SECRET_CODE=your_secret_code
```

```bash theme={null}
# 显式使用付费 API
xparse-cli parse report.pdf --api paid
```

## 命令一览

| 命令                    | 说明                              |
| --------------------- | ------------------------------- |
| `xparse-cli parse`    | 解析文档，输出 Markdown / JSON         |
| `xparse-cli auth`     | 配置 API 凭证（交互式）                  |
| `xparse-cli config`   | 管理配置（show / set / reset / path） |
| `xparse-cli download` | 下载解析结果中 elements 的图片            |
| `xparse-cli update`   | 自更新 CLI 到最新版本                   |
| `xparse-cli version`  | 显示版本信息                          |

## parse 命令参数

| 参数                          | 默认值        | 说明                                    |
| --------------------------- | ---------- | ------------------------------------- |
| `--api`                     | *(auto)*   | API 模式：`free`、`paid`                  |
| `--include-char-details`    | `false`    | 返回字符级详细信息                             |
| `--include-hierarchy`       | `true`     | 返回元素间的层级与关联字段                         |
| `--include-image-data`      | `true`     | 返回图片数据（URL、MIME 类型、Base64）            |
| `--include-inline-objects`  | `true`     | 返回细粒度的行内对象（公式、手写、复选框、内嵌图片）            |
| `--include-pages`           | `true`     | 返回页面元信息列表                             |
| `--include-table-structure` | `true`     | 返回表格的详细结构化信息                          |
| `--include-title-tree`      | `true`     | 返回标题树（目录）                             |
| `--list`                    |            | 从文件读取输入列表（每行一个路径），需配合 `--output`      |
| `--output`                  | *(stdout)* | 输出文件路径或目录；省略则输出到终端                    |
| `--page-range`              |            | 页码范围，例如 `"1-5"` 或 `"1-2,5-10"`        |
| `--password`                |            | 加密文档密码                                |
| `--table-view`              | `html`     | 表格在 Markdown 中的表达格式：`html`、`markdown` |
| `--view`                    | `markdown` | 输出视图：`markdown`、`json`                |

**全局参数（所有命令均支持）：**

| 参数              | 说明                              |
| --------------- | ------------------------------- |
| `--app-id`      | Textin App ID（覆盖环境变量和配置文件）      |
| `--secret-code` | Textin Secret Code（覆盖环境变量和配置文件） |
| `--base-url`    | API 地址（私有化部署时使用）                |
| `--verbose`     | 调试模式，打印 HTTP 请求详情               |

### API capabilities 默认值

CLI 默认开启以下能力，Agent 无需额外配置：

| 能力         | 默认                                  |
| ---------- | ----------------------------------- |
| 标题层级       | 开启                                  |
| 内嵌对象（图片）   | 开启                                  |
| 图片数据       | 开启                                  |
| 表格结构（HTML） | 开启                                  |
| 分页结果       | 开启                                  |
| 目录树        | 开启                                  |
| 字符级详情      | **关闭**（`--include-char-details` 开启） |

## 使用示例

### 管道组合

```bash theme={null}
# 解析并搜索
xparse-cli parse report.pdf | grep "revenue"

# 解析并喂给 LLM
xparse-cli parse paper.pdf | llm "summarize this paper"
```

### 批量处理

```bash theme={null}
# 从文件列表读取
xparse-cli parse --list files.txt --output ./results/
```

### 下载图片

```bash theme={null}
# 从解析结果 JSON 中提取 elements 图片并下载
xparse-cli download --from result.json --output ./images/

# 直接下载图片 URL
xparse-cli download https://web-api.textin.com/ocr_image/external/abc123.jpg --output ./images/
```

## 凭证管理

| 优先级 | 方式    | 说明                                     |
| --- | ----- | -------------------------------------- |
| 1   | 命令行参数 | `--app-id` 和 `--secret-code`           |
| 2   | 环境变量  | `XPARSE_APP_ID` 和 `XPARSE_SECRET_CODE` |
| 3   | 配置文件  | `~/.xparse-cli/config.yaml`            |

## 支持的文件格式

| 类型 | 格式                              |
| -- | ------------------------------- |
| 文档 | PDF, DOC, DOCX, TXT, RTF, OFD   |
| 图片 | PNG, JPG, JPEG, BMP, TIFF, WebP |
| 表格 | XLS, XLSX, CSV                  |
| 演示 | PPT, PPTX                       |
| 网页 | HTML, MHTML                     |

限制：

| 限制项          | 免费 API      | 付费 API                   |
| ------------ | ----------- | ------------------------ |
| 文件大小         | 10MB        | 500MB                    |
| 页数           | 1000 页/日    | —                        |
| XLS/XLSX/CSV | —           | 每 sheet ≤ 2000 行 × 100 列 |
| TXT          | —           | ≤ 100KB                  |
| 图片尺寸         | 20～20000 像素 | 20～20000 像素              |

了解更多：[查看 Github](https://github.com/intsig-textin/xparse-skills/tree/main/cli)