メインコンテンツへスキップ
PPDF123

pdfx: PDF123のコマンドライン

pdfxはPDF123のコマンドラインツールで、npmに @pdf123/cli として公開されています。結合、分割、圧縮、OCRなど95種類のPDFツールを、ディスク上のファイルに対して実行します。ファイルをPDF123 APIまたは自分のサーバーに送り、結果をローカルに保存します。

@pdf123/cliNode 20.3以降、またはBun

インストール

npm install -g @pdf123/cli
このページの内容

pdfxをインストールするには？

パッケージをグローバルにインストールすると、pdfx コマンドが使えます。インストールせずに1回だけ実行することもできます。

インストールbash
npm install -g @pdf123/cli
pdfx --version
インストールせずに実行bash
npx @pdf123/cli merge a.pdf b.pdf -o merged.pdf
bunx @pdf123/cli merge a.pdf b.pdf -o merged.pdf

bun add -g @pdf123/cli や pnpm add -g @pdf123/cli でも同様にインストールできます。ほかにインストールするものはありません。

使い始めるには？

次の6つのコマンドで、よく使うパターンがわかります。

クイックスタートbash
pdfx list                                          # every tool; --category security for one category
pdfx describe watermark                            # a tool's fields and defaults
pdfx merge a.pdf b.pdf -o merged.pdf
pdfx compress *.pdf -o compressed/                 # several files: one result per file
pdfx watermark in.pdf --watermarkText DRAFT
pdfx pipeline a.pdf b.pdf --step merge --step compress -o out.pdf

任意のツールを実行するには？

最初の引数はツールIDです。その後に入力ファイルとツールのオプションを続けます。ツールのオプションはすべてフラグで、APIのフィールド名（--pageNumbers）またはケバブケース（--page-numbers）で書きます。負の数は、--rotation -90 のようにフラグの後ろに空白を挟んで続けるか、等号の後ろに書きます。

構文text
pdfx <tool> [files...] [--<field> <value>]...

ツールの一覧は pdfx list で確認します。--category または --group と、検索語を指定する --query を使えます。pdfx describe <tool> では、エンドポイント、受け付ける入力、バッチとして実行されるかどうか、各フィールドの既定値と許可される値が表示されます。不明なツールIDには候補が示され、入力ミスは終了コード2で終了します。

どのコマンドがどのツールページに対応しますか？

コマンドツールページ機能
pdfx merge a.pdf b.pdf -o merged.pdf結合複数のPDFを1つにまとめる
pdfx split report.pdf --pageNumbers 3,7 -o parts.zip分割PDFを複数のファイルに分ける
pdfx compress in.pdf -o out/圧縮PDFのストリームを再圧縮してサイズを減らす
pdfx watermark in.pdf --watermarkText DRAFT透かしテキストまたは画像の透かしを追加する
pdfx protect in.pdf --password secret -o locked.pdf保護パスワードでPDFを暗号化する
pdfx unlock locked.pdf --password secret解除パスワード保護を取り除く
pdfx get-info in.pdf文書情報メタデータ、権限、構造をJSONで出力する
pdfx ocr scan.pdf -o out/OCRスキャンしたPDFを読み取り、Markdownを保存する
pdfx pdf-to-markdown in.pdf -o out/PDFからMarkdownPDFをMarkdownに変換する
pdfx rotate in.pdf --angle 90回転ページの向きを90度、180度、270度のいずれかで変える
pdfx repair broken.pdf修復破損したPDFの構造を再構築する

多数のファイルを一度に処理するには？

単一ファイル用のツールに複数のファイルを渡すと、pdfx はバッチとして実行します。-o には、末尾がスラッシュのディレクトリを指定します。ツールはファイルごとに1回ずつ、既定では2ファイルずつ並行して実行されます。これは --concurrency で変更できます。

バッチbash
pdfx compress *.pdf -o compressed/
pdfx protect *.pdf --password secret --concurrency 4 -o locked/

pdfx は、各ファイルが終わるたびに input -> saved という1行を表示します。失敗したファイルは標準エラー出力に報告され、ほかのファイルは最後まで処理されます。Ctrl-Cを1回押すと、実行中のリクエストを中止します。すでに保存されたファイルは残ります。2回目のCtrl-Cでは、コード130ですぐに終了します。--idempotency-key k を付けると、各ファイルが k:<index> を送り、同じリクエストを繰り返したときは24時間のあいだ最初の結果が再生されます。

get-info のようにレポートを返すツールのバッチは、-o がなければファイルを書き出しません。代わりに、入力ファイルをキーにしたレポートを表示します。

1回のリクエストで複数のツールをつなぐには？

pdfx pipeline は、複数のツールを1回のリクエストで実行します。ツールごとに --step を繰り返し指定します。オプションを設定するには、--steps でJSON配列を渡します。

パイプラインbash
pdfx pipeline a.pdf b.pdf --step merge --step compress -o out.pdf
pdfx pipeline in.pdf --steps '[{"tool":"watermark","params":{"watermarkText":"DRAFT"}},{"tool":"compress"}]' -o out.pdf

ステップには、2つ目のファイルを必要とするツールは使えません。

パスワード付きのPDFを開くには？

--input-password は、暗号化されたすべての入力を先に開きます。--password-for <file>=<password> は、1つのファイルのパスワードを設定します。繰り返し指定でき、ファイル名に * を指定すると残りのすべてが対象になります。ロックされたファイルとそうでないファイルが混在するバッチに向いています。merge と images-to-pdf では、名前を指定した各ファイルが、ツールの実行前に個別にロック解除されます。

パスワードbash
pdfx compress locked.pdf --input-password secret -o out.pdf
pdfx compress report.pdf --password-for report.pdf=secret -o out.pdf
pdfx merge a.pdf b.pdf --password-for a.pdf=secret -o merged.pdf

同じオプションはパイプラインでも使えます。保護を恒久的に取り除くには、独自の --password オプションを持つ解除ツールを使ってください。

入力と出力はどのように扱われますか？

  • 入力が - のときは標準入力を読み取ります。これは1回の実行につき1度だけです。-o - は結果を標準出力に書き出します。
  • -o file.pdf はそのファイルに書き込みます。-o dir/ はディレクトリに書き込みます。まだ存在しないディレクトリには末尾のスラッシュが必要です。スラッシュのない名前はファイルとして書き込まれるためです。
  • -o がない場合、結果は、サーバーが付けたファイル名でカレントディレクトリに保存されます。
  • ディレクトリへの書き込みでは、pdfx は既存のファイルを置き換えず、新しい名前を選びます。-o file.pdf のように明示したファイルは置き換えられます。
  • 結果と矛盾する拡張子の -o ファイル名（たとえば split が返したZIPを .pdf として保存しようとした場合）は、終了コード2と code: output_mismatch で拒否されます。何も書き込まれません。
  • 書き込めない出力先は使い方のエラーとして扱われ、何かをアップロードする前に検出されます。
シェルのパイプbash
cat in.pdf | pdfx compress - -o - > out.pdf

--json は何を出力しますか？

保存された結果については、--json はパス、コンテンツタイプ、サイズを出力します。レポートを返すツールでは、レポートそのものを出力します。バッチでは、ファイルごとのステータスを含む1つのレポートを出力します。

単一の結果json
{ "path": "one.pdf", "contentType": "application/pdf", "bytes": 1040 }
バッチのレポートjson
{
  "processed": 2,
  "unmatched": 0,
  "failed": 0,
  "files": [
    { "input": "/abs/a.pdf", "ok": true, "path": "comp/a.pdf", "contentType": "application/pdf", "bytes": 1040 }
  ]
}

失敗したファイルには、path と bytes の代わりに error と reason が入ります。一致しなかったフィルターツールは { "matched": false } を出力します。pdfx list --json は、id、category、group、name、description、returns、files、filter を持つ行を出力します。

すべてのツールに共通するオプションは？

オプション効果
-o, --output <path>書き込むファイル、または書き込み先のディレクトリ。既定はカレントディレクトリ。- は標準出力
--api-base <url>APIのオリジン。環境変数は PDFX_API_BASE、既定値は https://pdf123.xyz
--api-key <key>X-API-KEY として送信。環境変数は PDFX_API_KEY。省略可能
--input-password <pw>パスワードで保護されたすべての入力を先に開く
--password-for <file>=<pw>1つのファイルのパスワード。繰り返し指定可能
--concurrency <n>バッチで同時に処理するファイル数。既定は2
--timeout <ms>各リクエストのタイムアウト。既定は300000
--idempotency-key <k>24時間のあいだ最初の結果を再生する
--json機械可読な出力

終了コードにはどのような意味がありますか？

コード意味
0成功。一致しなかったフィルターツールも0で終了し、no match と表示する
1リクエストが失敗した。バッチでは少なくとも1つのファイルが失敗したが、ほかは最後まで処理される
2使い方のエラー。何もアップロードされていない
130Ctrl-Cで中断された。実行中のリクエストは中止される

失敗時には、サーバーから提供されていれば reason:、code:、hint: の行が表示されるため、スクリプトは文言を照合せずに分岐できます。表のないPDFに対する pdf-to-csv のように、返すものが見つからないツールは、空のファイルを書き出す代わりに、終了コード1と code: no_content で終了します。コードはエラーコードに一覧があります。

pdfxを自分のサーバーに向けるには？

PDFX_API_BASE を設定するか --api-base を渡して、セルフホストした pdfx-server のアドレスを指定します。サーバーがキーを必要とする場合は PDFX_API_KEY も追加してください。セルフホストをご覧ください。

セルフホストしたサーバーbash
export PDFX_API_BASE=http://localhost:8080
export PDFX_API_KEY=<your-key>
pdfx compress in.pdf

CLIが知らないエンドポイントを実行するには？

pdfx call は、操作IDまたは /api/... パスに生のリクエストを送ります。フォームのフィールドには --field name=value、追加のファイルには --file field=path を使います。リクエストはちょうど1回だけ送られ、ローカルでの検証は一切行われないため、パスワードとバッチは拒否されます。

生のリクエストbash
pdfx call general/merge-pdfs a.pdf b.pdf -o merged.pdf
pdfx call /api/v1/misc/flatten in.pdf --field flattenOnlyForms=true -o flat.pdf

FAQ

pdfxはオフラインで動作しますか？

いいえ。pdfx は各ファイルをPDF123 APIまたは自分のサーバーにアップロードし、結果をローカルに保存するため、APIのベースに接続できる必要があります。

pdfxにAPIキーは必要ですか？

いいえ。匿名でも使えます。サーバーがキーを必要とする場合は、PDFX_API_KEY を設定するか --api-key を渡してください。キーは X-API-KEY ヘッダーとして送られます。

pdfxにはどのバージョンのNodeが必要ですか？

Node 20.3以降、またはBunです。

pdfxは自分のファイルを上書きしますか？

ディレクトリに書き込む場合は上書きしません。既存のファイルが置き換えられることはありません。-o file.pdf のように出力ファイルを自分で指定した場合は、そのファイルが置き換えられます。元のファイルを残したいときは、新しい名前を選んでください。

フィルターツールが一致しなかった場合はどうなりますか？

フィルターツール（IDが filter- で始まるもの）は、条件を満たすとファイルをそのまま通します。満たさないときは、pdfx は no match と表示し、終了コード0で終了します。バッチでは、そのようなファイルは失敗ではなく、不一致として数えられます。