pdfx CLI:一套目录,从终端调用
pdfx 命令行把与 curl 相同的 multipart 请求发往 PDF123 API 或你自己的 pdfx-server,并补上批量运行、逐文件密码,以及脚本可据此分支的退出码。

PDF123 是产品名。pdfx 是同一套操作目录包了一层 shell 外壳:它拼出 curl 本来会拼的多部分(multipart)请求,发到你选定的 API base,再把结果写到你的文件旁边。合并、压缩、OCR 以及目录里其余工具都能这样调用。
一次调用实际发出去什么
pdfx --api-base "$API_BASE" --api-key "$PDFX_API_KEY" \
merge a.pdf b.pdf -o merged.pdf
--api-base 默认是 https://pdf123.xyz,--api-key(或环境变量 PDFX_API_KEY)是可选的,所以匿名目录不带它也能用。把 base 指向 http://127.0.0.1:8080,就走你自己的 docker-compose 栈。底下没有第二套协议:这个 CLI 是开发者页面上那套 REST 表面的客户端,op 名称与门户工具、以及 /v1/openapi.json 上的 OpenAPI 文档一致。
目录不用离开终端也能查。pdfx list 打印每一个工具,pdfx describe add-stamp 打印单个工具的字段与默认值,和门户渲染成表单的是同一份定义。
批量运行,以及 curl 逼你自己写的那些开关
给单文件工具多个输入,它会当成一个批次跑进 -o 目录,每个文件打印一行 input -> saved。失败走 stderr,其余文件照旧跑完,所以一叠发票里有一个坏 PDF 不会中断整轮。--concurrency <n> 设定同时处理几个文件(默认 2)。
-o 收文件或目录,且从不覆盖已存在的文件:在目录里改用服务器给的文件名。服务器按输入命名结果时这一点很关键:不然一轮运行会覆盖你刚上传的那个 PDF。
加密输入在发请求前就被打开,不是由工具去开:--input-password 覆盖本轮每个文件,--password-for report.pdf=secret 设置单个文件的密码、可以重复,用 * 代表其余文件。因此一批混杂着加锁与未加锁文件的工作不需要手工分类。--json 每个结果打印 { path, contentType, bytes },批次则打印 [{ input, ok, path | error, reason }],包装脚本可以直接解析结果,不必去刮人类可读的行。
脚本可以据此分支的退出码
0 表示成功,1 表示有一个请求失败(批次里是至少一个文件),2 是用法错误、什么都没上传,130 表示你打断了它、正在飞的请求被中止。失败时只要有信息,就会在消息下面打印 reason:、code: 与 hint: 行,脚本该匹配的是这些,而不是散文。
有一种退出很容易被误读。工具找不到可返回的内容时,会以 code: no_content 非零退出,而不是写一个空文件,所以对没有表格的 PDF 跑 pdf-to-csv 是失败,不是零字节的 CSV。
字节去了哪里
文件上传到 API base,在那里处理,响应发出后即删除。这与浏览器表单是同一份契约;CLI 换掉的是客户端,不是目的地。必须留在内网里的文档,就自己跑一个 pdfx-server 并把 --api-base 指向它,自托管有说明。
没有可回退的离线模式:base 不可达,命令就失败。pdfx 是一个恰好在 shell 里好用的网络客户端,不是本地 PDF 引擎。
CLI 不是什么
pdfx 不是桌面 GUI,也不是能链进别的应用的可嵌入 OCR 库。它是 PDF 操作的命令行客户端,所以人手的一次性作业仍然更适合门户(压缩、OCR 以及目录里其余工具),而任何需要自己一套 UI 树的东西,都会重新造出同一操作,四种客户端里描述的漂移问题。
Agent 从已发布的 skill /skills/pdf123.md 拿到同样的形状,里面完整记录了 merge 与 pipeline 请求。要对变更型 POST 做安全重试,发送 Idempotency-Key;CLI 每次调用仍只发一个请求,所以这个头属于任何重试它的东西(Idempotency-Key:PDF 作业的安全重试)。Key、限流与错误码在开发者。