pdfx: die Kommandozeile von PDF123

Wie installiere ich pdfx?#

Installieren Sie das Paket global, um den Befehl pdfx zu erhalten. Oder führen Sie es einmalig ohne Installation aus.

npm install -g @pdf123/cli
pdfx --version

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 und pnpm add -g @pdf123/cli funktionieren ebenfalls. Weitere Installationen sind nicht nötig.

Wie fange ich an?#

Diese sechs Befehle zeigen die gängigen Muster.

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

Wie führe ich ein beliebiges Werkzeug aus?#

Das erste Argument ist die Werkzeug-ID. Danach folgen die Eingabedateien und die Optionen des Werkzeugs. Jede Option eines Werkzeugs ist ein Flag, geschrieben als API-Feldname (--pageNumbers) oder in Kebab-Case (--page-numbers). Eine negative Zahl kann ihrem Flag nach einem Leerzeichen folgen, etwa bei --rotation -90, oder nach einem Gleichheitszeichen.

pdfx <tool> [files...] [--<field> <value>]...

Mit pdfx list sehen Sie die Werkzeuge. Der Befehl akzeptiert --category oder --group sowie --query mit Suchwörtern. Mit pdfx describe <tool> sehen Sie den Endpunkt, die akzeptierten Eingaben, ob das Werkzeug als Stapel läuft, und jedes Feld mit Standardwert und erlaubten Werten. Bei einer unbekannten Werkzeug-ID erhalten Sie Vorschläge, und eine vertippte ID endet mit Exit-Code 2.

Welcher Befehl gehört zu welcher Werkzeugseite?#

Wie verarbeite ich viele Dateien auf einmal?#

Übergeben Sie einem Einzeldatei-Werkzeug mehrere Dateien, und pdfx führt einen Stapel aus. Verwenden Sie -o mit einem Verzeichnis, das auf einen Schrägstrich endet. Das Werkzeug läuft einmal pro Datei, standardmäßig zwei Dateien gleichzeitig. Ändern Sie das mit --concurrency.

pdfx compress *.pdf -o compressed/
pdfx protect *.pdf --password secret --concurrency 4 -o locked/

pdfx gibt pro fertiger Datei eine Zeile im Format input -> saved aus. Eine fehlgeschlagene Datei wird auf der Standardfehlerausgabe gemeldet, die übrigen Dateien werden trotzdem fertig verarbeitet. Drücken Sie einmal Strg-C, um die laufende Anfrage abzubrechen; bereits gespeicherte Dateien bleiben erhalten. Ein zweites Strg-C beendet sofort mit Code 130. Mit --idempotency-key k sendet jede Datei k:<index>, und eine Wiederholung derselben Anfrage liefert 24 Stunden lang das erste Ergebnis erneut.

Ein Stapel mit einem Werkzeug, das einen Bericht liefert, etwa get-info, schreibt ohne -o keine Dateien. Er gibt die Berichte aus, nach Eingabedatei geordnet.

Wie verkette ich Werkzeuge in einer Anfrage?#

pdfx pipeline führt mehrere Werkzeuge in einer Anfrage aus. Wiederholen Sie --step für jedes Werkzeug. Um Optionen zu setzen, übergeben Sie mit --steps ein JSON-Array.

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

Schritte können keine Werkzeuge verwenden, die eine zweite Datei brauchen.

Wie öffne ich passwortgeschützte PDFs?#

--input-password öffnet zuerst jede verschlüsselte Eingabe. --password-for <file>=<password> legt das Passwort einer einzelnen Datei fest. Die Option lässt sich wiederholen, und * als Dateiname gilt für alle übrigen. Das eignet sich für einen Stapel aus gesperrten und offenen Dateien. Bei merge und images-to-pdf wird jede genannte Datei einzeln entsperrt, bevor das Werkzeug läuft.

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

Dieselben Optionen funktionieren in einer Pipeline. Um den Schutz dauerhaft zu entfernen, nutzen Sie das Werkzeug Entsperren mit seiner eigenen Option --password.

Wie funktionieren Ein- und Ausgabe?#

• Die Eingabe - liest die Standardeingabe, einmal pro Aufruf. -o - schreibt das Ergebnis auf die Standardausgabe.
• -o file.pdf schreibt diese Datei. -o dir/ schreibt in ein Verzeichnis. Ein Verzeichnis, das noch nicht existiert, braucht den abschließenden Schrägstrich, denn ein Name ohne ihn wird als Datei geschrieben.
• Ohne -o landen die Ergebnisse unter dem Dateinamen des Servers im aktuellen Verzeichnis.
• In ein Verzeichnis ersetzt pdfx nie eine vorhandene Datei, sondern wählt einen neuen Namen. Ein ausdrückliches -o file.pdf ersetzt diese Datei.
• Ein Dateiname für -o, dessen Endung dem Ergebnis widerspricht, etwa ein ZIP von split, das als .pdf gespeichert werden soll, wird mit Exit-Code 2 und code: output_mismatch abgelehnt. Es wird nichts geschrieben.
• Eine Ausgabe, die nicht geschrieben werden kann, ist ein Aufruffehler, der erkannt wird, bevor etwas hochgeladen wird.

cat in.pdf | pdfx compress - -o - > out.pdf

Was gibt --json aus?#

Für ein gespeichertes Ergebnis gibt --json den Pfad, den Content-Type und die Größe aus. Ein Werkzeug, das einen Bericht liefert, gibt den Bericht selbst aus. Ein Stapel gibt einen Bericht mit einem Status pro Datei aus.

{ "path": "one.pdf", "contentType": "application/pdf", "bytes": 1040 }

{
  "processed": 2,
  "unmatched": 0,
  "failed": 0,
  "files": [
    { "input": "/abs/a.pdf", "ok": true, "path": "comp/a.pdf", "contentType": "application/pdf", "bytes": 1040 }
  ]
}

Eine fehlgeschlagene Datei hat error und reason statt path und bytes. Ein Filter-Werkzeug ohne Treffer gibt { "matched": false } aus. pdfx list --json gibt Zeilen mit id, category, group, name, description, returns, files und filter aus.

Welche Optionen gelten für jedes Werkzeug?#

Welche Exit-Codes gibt es?#

Fehlschläge geben die Zeilen reason:, code: und hint: aus, sofern der Server sie liefert, sodass ein Skript verzweigen kann, ohne Text zu vergleichen. Ein Werkzeug, das nichts zurückzugeben hat, etwa pdf-to-csv bei einer PDF ohne Tabellen, endet mit Code 1 und code: no_content, statt eine leere Datei zu schreiben. Die Codes stehen unter Fehlercodes.

Wie richte ich pdfx auf meinen eigenen Server?#

Setzen Sie PDFX_API_BASE oder übergeben Sie --api-base mit der Adresse eines selbst gehosteten pdfx-server. Ergänzen Sie PDFX_API_KEY, wenn Ihr Server einen Schlüssel verlangt. Siehe Self-Host.

export PDFX_API_BASE=http://localhost:8080
export PDFX_API_KEY=<your-key>
pdfx compress in.pdf

Wie rufe ich einen Endpunkt auf, den die CLI nicht kennt?#

pdfx call sendet eine Rohanfrage an eine Operations-ID oder einen /api/...-Pfad. Verwenden Sie --field name=value für Formularfelder und --file field=path für zusätzliche Dateien. Es sendet genau eine Anfrage und validiert lokal nichts, daher werden Passwörter und Stapel abgelehnt.

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

Weiterführende Seiten#

• Entwicklerübersicht mit REST-API und Authentifizierung
• TypeScript-SDK, die Bibliothek, auf der die Kommandozeile aufbaut
• MCP-Server für KI-Agenten
• Der Blogbeitrag „pdfx CLI: One Catalog, Called From Your Terminal“ im PDF123-Blog

FAQ#

Funktioniert pdfx offline?#

Nein. pdfx lädt jede Datei zur PDF123-API oder zu Ihrem eigenen Server hoch und speichert das Ergebnis lokal. Die API-Basis muss daher erreichbar sein.

Braucht pdfx einen API-Schlüssel?#

Nein. Anonyme Nutzung funktioniert. Setzen Sie PDFX_API_KEY oder übergeben Sie --api-key, wenn Ihr Server einen verlangt. Der Schlüssel wird als Header X-API-KEY gesendet.

Welche Node-Version braucht pdfx?#

Node 20.3 oder neuer, oder Bun.

Überschreibt pdfx meine Dateien?#

Nicht, wenn es in ein Verzeichnis schreibt: Eine vorhandene Datei wird nie ersetzt. Wenn Sie die Ausgabedatei selbst mit -o file.pdf benennen, wird diese Datei ersetzt. Wählen Sie also einen neuen Namen, wenn das Original erhalten bleiben soll.

Was passiert, wenn ein Filter-Werkzeug keinen Treffer findet?#

Filter-Werkzeuge, deren IDs mit filter- beginnen, reichen die Datei durch, wenn ihre Bedingung zutrifft. Trifft sie nicht zu, gibt pdfx no match aus und endet mit Code 0. In einem Stapel zählt eine solche Datei als ohne Treffer, nicht als fehlgeschlagen.