pdfx CLI：默认本地，需要时才上云
pdfx 默认在本机处理 PDF，不上传文件。需要托管或自托管的 PDF123 REST 端点时，用 API base 和 Key 切到云模式。
PDF123 是产品名，pdfx 是访问同一批操作的短命令行工具。默认路径是本地：读文件、经 pdf-core 跑 op、写出结果。不需要账号，不需要 API Key，也不上传任何东西。
默认本地，文件不出机器
典型调用是 pdfx merge a.pdf b.pdf -o merged.pdf 或 pdfx compress input.pdf。处理发生在二进制运行的地方。这适合私有 runner 上的 CI、和一批发票放在一起的脚本，以及任何“上传给第三方本身就是错误答案”的场景。
本地模式不是那种偷偷把字节 POST 到别处的薄封装。CLI 与服务端共用同一份操作注册表（pdf_core::ops::run）。要走网络路径，得显式加 --cloud。
内置子命令覆盖常见 op：合并、拆分、压缩、旋转、提取、OCR、转换、保护、解锁、水印等。本地输出默认经 -o / --output 写文件，- 表示写到 stdout。
--cloud：用 HTTP 访问同一份目录
需要用托管 API（或你自己的 pdfx-server）时，加 --cloud 并传 --api-base 和 --api-key（或用 PDFX_API_KEY）。云模式底层依赖 curl，没设 API Key 会直接失败。发布 skill 里的示例：
pdfx --cloud --api-base "$PDFX_API_BASE" --api-key "$PDFX_API_KEY" \
merge a.pdf b.pdf -o merged.pdf
未设置时 --api-base 默认为 https://pdf123.xyz，也就是托管 API。要用本地 Docker Compose 栈，就改为指向 http://127.0.0.1:8080。CLI 于是成为开发者文档中那套 REST 表面的客户端，op 名称与门户工具和 OpenAPI（/v1/openapi.json）对齐。
云模式不改变 op 的含义。压缩仍是 qpdf 流压缩；OCR 仍从 Rust 路径返回 Markdown 文本，不是可搜索 PDF 层。那些映射到已忽略的 Java 时代 OCR 参数的遗留 CLI 标志（比如 languages 字段）不会改变这份契约。
为什么要有两种模式
本地模式对应离线信任和零往返开销。云模式对应共享限流、在只装了 CLI 和 curl 的机器上跑 op，以及已经在发放 API Key 的团队。Agent 也可以经 /mcp 的 MCP，或 dist/skills/pdf-toolbox/SKILL.md 的 skill，调用同一个 base。/llms.txt 这类发现索引帮编码 Agent 找到端点，它们不是 Google 排名信号。
对 API 上变更型 POST 做安全重试时，发送 Idempotency-Key（见 Idempotency-Key：PDF 作业的安全重试）。CLI 的云路径每次调用仍是一次 HTTP 请求，重试逻辑在你的包装器里时记得带上这个头。
实践中怎么选
文件必须留在 runner 上、机器上已经装好 pdfx 二进制和原生依赖、延迟主要来自 op 而不是上传，这几种情况用本地。重依赖只存在于服务器、你希望和其他 API 客户端共用同一套限流与计量，或 Agent 已经持有 https://pdf123.xyz 或自托管 base 的 API Key，这些情况用云。
不要把两边的预期搞混：本地 OCR 仍遵守 misc/ocr-pdf 的 Markdown 输出契约；云压缩仍是 qpdf 流，不做字体子集化。模式开关改变的是 op 在哪里 跑，不是目录的语义。
CLI 不是什么
pdfx 不是桌面 GUI，也不是能链进别的应用的可嵌入 OCR 库。它是 PDF 操作的命令行客户端：默认本地，你要它走 HTTP 才走。浏览器里的一次性作业仍在门户（压缩、OCR 以及目录其余工具）。偏好二进制的自动化可以一直用 pdfx。
浏览器、curl、MCP 和 CLI 的同一 op 对比，见同一操作，四种客户端。Key 与 OpenAPI 从开发者起步；如果 API base 应该用你自己的 Docker Compose 栈，从自托管起步。