Product4 min read

pdfx CLI: One Catalog, Called From Your Terminal

pdfx sends the same multipart requests as curl to the PDF123 API or your own server, plus batch runs, per-file passwords and exit codes a script can use.

By the PDF123 team Β· Updated 2026-09-29
pdfx CLI: One Catalog, Called From Your Terminal

PDF123 is the product name. pdfx is the same operation catalog wrapped for a shell: it builds the multipart request curl would have built, sends it to the API base you choose, and writes the result next to your files. Merge, Compress, OCR and the rest of the catalog are callable this way.

What a call actually sends

pdfx --api-base "$API_BASE" --api-key "$PDFX_API_KEY" \
  merge a.pdf b.pdf -o merged.pdf

--api-base defaults to https://pdf123.xyz, and --api-key (or the PDFX_API_KEY environment variable) is optional, so the anonymous catalog works without one. Point the base at http://127.0.0.1:8080 for a docker-compose stack of your own. There is no second protocol underneath: the CLI is a client of the REST surface documented on Developers, and its op names line up with the portal tools and the OpenAPI document at /v1/openapi.json.

The catalog is discoverable without leaving the terminal. pdfx list prints every tool and pdfx describe add-stamp prints one tool's fields and defaults, which is the same definition the portal renders as a form.

Batch runs and the flags curl makes you write yourself

Give a single-file tool several inputs and it runs them as a batch into the -o directory, printing one input -> saved line per file. Failures go to stderr and the remaining files still finish, so one bad PDF in a folder of invoices does not abort the run. --concurrency <n> sets how many files are in flight at once (default 2).

-o takes a file or a directory and never overwrites an existing file, using the server's file name inside the directory instead. That matters when the server names the result after the input: without it, a run would clobber the PDF you just uploaded.

Encrypted inputs are opened before the request, not by the tool: --input-password covers every file in the run, and --password-for report.pdf=secret sets one file's password and can be repeated, with * standing in for the rest. A batch that mixes locked and open files thus needs no manual sorting. --json prints { path, contentType, bytes } per result, or [{ input, ok, path | error, reason }] for a batch, so a wrapper can parse the outcome instead of scraping the human-readable lines.

Exit codes a script can branch on

0 means success, 1 means a request failed (in a batch: at least one file), 2 is a usage error where nothing was uploaded, and 130 means you interrupted it and the in-flight request was aborted. Failures print reason:, code: and hint: lines under the message whenever they are available, which is what a script should match on rather than prose.

One exit is easy to misread. A tool that finds nothing to return exits non-zero with code: no_content instead of writing an empty file, so pdf-to-csv on a PDF with no tables is a failure, not a zero-byte CSV.

Where the bytes go

The files are uploaded to the API base, processed there, and deleted once the response is sent. That is the same contract as the browser form; the CLI changes the client, not the destination. For documents that must not leave your network, run a pdfx-server yourself and point --api-base at it, which is covered on Self-host.

There is no offline mode to fall back to: if the base is unreachable, the command fails. pdfx is a network client that happens to be pleasant in a shell, not a local PDF engine.

What the CLI is not

pdfx is not a desktop GUI and not an embeddable OCR library you link into another app. It is a command-line client for PDF operations, so a one-off human job is still better served by the portal (Compress, OCR, and the rest of the catalog), and anything that needs a UI tree of its own would recreate the drift problem described in Same operation, four clients.

Agents get the same shapes from the published skill at /skills/pdf123.md, which documents the merge and pipeline requests in full. For safe retries of mutating POSTs, send Idempotency-Key; the CLI still makes one request per invocation, so the header belongs in whatever retries it (Idempotency-Key: Safe Retries for PDF Jobs). Keys, rate limits and error codes are on Developers.

Open tool
Process in the browser β€” no watermark, files removed after the job.
Open tool