pdfx CLI：ローカル優先、必要なときにクラウド

PDF123 は製品名だ。pdfx は同じ操作を扱う短い CLI である。既定の経路はローカルで、ファイルを読み、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 によるファイルで、- は標準出力に書く。

--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 を発行しているチームを担う。エージェントは /mcp の MCP や dist/skills/pdf-toolbox/SKILL.md の skill からも同じ base を呼べる。/llms.txt のような発見用の索引は、コーディングエージェントがエンドポイントを見つける助けになる。Google のランキングシグナルではない。

API に対する変更系 POST を安全に再試行するには Idempotency-Key を送る（Idempotency-Key：PDF ジョブの安全な再試行）。CLI のクラウド経路は呼び出しごとに HTTP リクエスト一つであり、ラッパーが再試行するときにこのヘッダーが効く。

実際にモードを選ぶ

ローカルを使うのは、ファイルを runner に留める必要があるとき、そのマシンに pdfx バイナリとネイティブ依存がすでにあるとき、遅延がアップロードではなく op に支配されているときだ。クラウドを使うのは、重い依存がサーバーにしかないとき、他の API クライアントと同じレート制限と計測を使いたいとき、エージェントがすでに 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 スタックにしたい場合は セルフホスト から始めるとよい。