pdfx CLI：預設本機，需要時再上雲

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 對比，見 同一操作，四種用戶端。金鑰與 OpenAPI 從 開發者 起步；如果 API base 要用你自己的 Docker Compose 堆疊，從 自架 起步。