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 工作的安全重試)。金鑰、速率限制與錯誤碼在 開發者。