# CLI 命令行调用

> 通过 EfficiencyToolbox.exe --cli 在脚本中调用效率工具箱的全部工具：命令语法、参数格式、输出协议、退出码约定与多语言调用示例。

- 分类：智能体接入
- 关键词：CLI、命令行、脚本、自动化、批处理、PowerShell、Python、退出码、输出协议
- 在线原文：https://www.xyltools.com/docs/cli-command-reference

---

## 基本语法

CLI 通道通过效率工具箱主程序的 --cli 参数进入，每次调用启动一次、执行完自动退出，适合在 PowerShell、Python、批处理等脚本中集成。

**命令格式**

```text
EfficiencyToolbox.exe --cli <命令> [--参数名 值] [--参数名=值]
```

- 命令名使用中划线风格（kebab-case），例如 pdf-merge、image-resize、search-files。
- 参数支持两种写法：--参数名 值（空格分隔）或 --参数名=值（等号连接），效果相同。
- 不带值的参数（开关型）直接写 --参数名 即可，等价于传入 true。
- 多个文件路径用分号分隔，例如 --input-paths "a.pdf;b.pdf"。
- 含空格或中文的值请用英文双引号包裹。

**快速示例**

```powershell
# 合并两个 PDF
EfficiencyToolbox.exe --cli pdf-merge --input-paths "a.pdf;b.pdf" --output-path "merged.pdf"

# 图片缩放到指定宽度
EfficiencyToolbox.exe --cli image-resize --input-path "photo.jpg" --width 1920

# 按关键词搜索文件
EfficiencyToolbox.exe --cli search-files --keyword "*.pdf" --path "D:\资料"
```

## 查看可用命令

CLI 提供两个不需要登录授权的辅助命令，用于发现能力和查看帮助：

- **--list（或 -l）**：按类别列出全部可用命令及说明，近 400 条
- **--help（或 -h）**：显示语法说明、示例和输出协议

**列出全部命令**

```powershell
EfficiencyToolbox.exe --cli --list
```

> **不确定参数怎么填？**：直接执行命令但不带必需参数，CLI 会返回错误并自动打印该命令的完整参数帮助——包括每个参数是否必需、默认值和可选值列表。这是查看单个命令参数的最快方式。

## 输出协议与退出码

CLI 的标准输出采用固定前缀的行协议（UTF-8 编码），脚本按行前缀解析即可；进程退出码用于快速判断整体结果。

| 输出行前缀 | 含义 | 示例 |
| --- | --- | --- |
| PROGRESS:<0-100>:<消息> | 执行进度报告，可能出现多行 | PROGRESS:50:正在合并第 2 个文件... |
| SUCCESS:<结果> | 执行成功，携带结果或输出文件路径 | SUCCESS:已合并 3 个文件 → merged.pdf |
| ERROR:<错误消息> | 执行失败，携带具体原因 | ERROR:缺少必需参数: --output-path |

| 退出码 | 含义 | 脚本处理建议 |
| --- | --- | --- |
| 0 | 执行成功 | 继续后续流程 |
| 1 | 执行失败（参数错误、未知命令、工具执行出错） | 解析 ERROR: 行获取原因 |
| 2 | 用户取消（Ctrl+C 中断） | 视为主动中止，不必告警 |
| 3 | 未授权（未登录或订阅到期） | 提示先在效率工具箱内登录 / 续费 |

> **授权说明**：除 --list 和 --help 外，所有命令执行前都会校验登录状态与订阅有效期（本地凭据快速校验，毫秒级，不拖慢脚本）。未授权时输出 ERROR: 行并以退出码 3 结束。

## 脚本调用示例

以下示例演示在三种常见环境中调用 CLI 并处理结果，请将 <安装目录> 替换为效率工具箱的实际安装路径。

**PowerShell**

```powershell
$exe = "<安装目录>\EfficiencyToolbox.exe"
& $exe --cli pdf-merge --input-paths "a.pdf;b.pdf" --output-path "merged.pdf" |
  ForEach-Object {
    if ($_ -like "SUCCESS:*") { Write-Host "完成: $($_.Substring(8))" }
    elseif ($_ -like "ERROR:*") { Write-Warning $_.Substring(6) }
  }
if ($LASTEXITCODE -ne 0) { Write-Warning "退出码 $LASTEXITCODE" }
```

**Python**

```python
import subprocess

exe = r"<安装目录>\EfficiencyToolbox.exe"
result = subprocess.run(
    [exe, "--cli", "image-resize", "--input-path", "photo.jpg", "--width", "1920"],
    capture_output=True, text=True, encoding="utf-8",
)
for line in result.stdout.splitlines():
    if line.startswith("SUCCESS:"):
        print("完成:", line[8:])
    elif line.startswith("ERROR:"):
        print("失败:", line[6:])
print("退出码:", result.returncode)
```

**批处理**

```batch
@echo off
"<安装目录>\EfficiencyToolbox.exe" --cli pdf-merge --input-paths "a.pdf;b.pdf" --output-path "merged.pdf"
if %ERRORLEVEL% EQU 0 (
  echo 合并成功
) else (
  echo 执行失败，退出码 %ERRORLEVEL%
)
```

> **长时间任务的进度显示**：批量处理类命令会持续输出 PROGRESS: 行，脚本可实时解析其中的百分比更新自己的进度条；按 Ctrl+C 可优雅取消，进程以退出码 2 结束。

## 相关文章

---

## 相关文章

- [智能体接入概览](https://www.xyltools.com/docs/agent-integration-overview)
- [MCP 服务接入](https://www.xyltools.com/docs/mcp-server-guide)
- [常见问题解答](https://www.xyltools.com/docs/faq)