Product約1分で読めます

pdfx CLI:一つのカタログをターミナルから呼ぶ

pdfx CLI は curl と同じ multipart リクエストを PDF123 の API または自分の pdfx-server へ送り、バッチ実行、ファイルごとのパスワード、スクリプトが分岐できる終了コードを加える。

By the PDF123 team · Updated 2026-09-29
pdfx CLI:一つのカタログをターミナルから呼ぶ

PDF123 は製品名だ。pdfx は同じ操作カタログをシェル向けに包んだもので、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)は省略可能なので、匿名のカタログはキーなしでも動く。自分の docker-compose スタックなら base を http://127.0.0.1:8080 に向ける。下に別のプロトコルはない。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 は失敗であって、0 バイトの CSV ではない。

バイトはどこへ行くか

ファイルは API base へアップロードされ、そこで処理され、応答が送られ次第削除される。ブラウザのフォームと同じ契約だ。CLI が変えるのはクライアントであって、行き先ではない。ネットワークから出せない文書は、自分で pdfx-server を動かして --api-base をそこへ向ける。セルフホスト で扱っている。

落ち延びるオフラインモードはない。base に到達できなければコマンドは失敗する。pdfx はシェルで快適なだけのネットワーククライアントであり、ローカルの PDF エンジンではない。

CLI ではないもの

pdfx はデスクトップ GUI ではなく、他のアプリに組み込む埋め込み OCR ライブラリでもない。PDF 操作のためのコマンドラインクライアントだ。だから人間の単発作業は依然としてポータル(圧縮、OCR、カタログの残り)が適している。独自の UI ツリーを必要とするものは、同じ操作、四つのクライアント で述べたドリフト問題を再び生む。

エージェントは /skills/pdf123.md の公開 skill から同じ形を得られる。これは結合と pipeline のリクエストを完全に文書化している。変更型 POST を安全に再試行するには Idempotency-Key を送る。CLI は呼び出しごとに一つのリクエストを送るだけなので、このヘッダーは再試行する側に属する(Idempotency-Key:PDF ジョブの安全な再試行)。キー、レート制限、エラーコードは 開発者向け に。

Open tool
Process in the browser — no watermark, files removed after the job.
Open tool