pdfx CLI: Ein Katalog, vom Terminal aus aufgerufen
Das pdfx CLI sendet dieselben Multipart-Anfragen wie curl an die PDF123-API oder deinen eigenen pdfx-server und ergänzt Stapelläufe, Passwörter pro Datei und Exit-Codes, auf die ein Skript verzweigen kann.

PDF123 ist der Produktname. pdfx ist derselbe Katalog von Operationen, für eine Shell verpackt: Es baut die Multipart-Anfrage, die curl gebaut hätte, sendet sie an die API-Basis deiner Wahl und schreibt das Ergebnis neben deine Dateien. Zusammenführen, Komprimieren, OCR und der Rest des Katalogs lassen sich so aufrufen.
Was ein Aufruf tatsächlich sendet
pdfx --api-base "$API_BASE" --api-key "$PDFX_API_KEY" \
merge a.pdf b.pdf -o merged.pdf
--api-base steht standardmäßig auf https://pdf123.xyz, und --api-key (oder die Umgebungsvariable PDFX_API_KEY) ist optional, sodass der anonyme Katalog auch ohne Schlüssel funktioniert. Richte die Basis für einen eigenen docker-compose-Aufbau auf http://127.0.0.1:8080. Darunter liegt kein zweites Protokoll: Das CLI ist ein Client der REST-Oberfläche, die unter Entwickler dokumentiert ist, und seine Operationsnamen stimmen mit den Portal-Werkzeugen und dem OpenAPI-Dokument unter /v1/openapi.json überein.
Der Katalog ist auffindbar, ohne das Terminal zu verlassen. pdfx list gibt jedes Werkzeug aus, und pdfx describe add-stamp gibt die Felder und Standardwerte eines Werkzeugs aus, also dieselbe Definition, die das Portal als Formular rendert.
Stapelläufe und die Flags, die curl dich selbst schreiben lässt
Gib einem Werkzeug für einzelne Dateien mehrere Eingaben, und es führt sie als Stapel in das Verzeichnis -o aus und gibt pro Datei eine Zeile input -> saved aus. Fehler gehen nach stderr, und die übrigen Dateien laufen trotzdem durch, sodass eine defekte PDF in einem Ordner voller Rechnungen den Lauf nicht abbricht. --concurrency <n> legt fest, wie viele Dateien gleichzeitig unterwegs sind (Standard 2).
-o nimmt eine Datei oder ein Verzeichnis und überschreibt niemals eine vorhandene Datei, sondern verwendet den Dateinamen des Servers innerhalb des Verzeichnisses. Das zählt, wenn der Server das Ergebnis nach der Eingabe benennt: ohne diese Regel würde ein Lauf die gerade hochgeladene PDF überschreiben.
Verschlüsselte Eingaben werden vor der Anfrage geöffnet, nicht vom Werkzeug: --input-password deckt jede Datei im Lauf ab, und --password-for report.pdf=secret setzt das Passwort einer Datei und lässt sich wiederholen, wobei * für den Rest steht. Ein Stapel, der gesperrte und offene Dateien mischt, braucht also keine manuelle Sortierung. --json gibt pro Ergebnis { path, contentType, bytes } aus, oder [{ input, ok, path | error, reason }] für einen Stapel, damit ein Wrapper das Ergebnis parsen kann, statt die menschenlesbaren Zeilen zu schaben.
Exit-Codes, auf die ein Skript verzweigen kann
0 bedeutet Erfolg, 1 bedeutet, dass eine Anfrage fehlgeschlagen ist (im Stapel: mindestens eine Datei), 2 ist ein Nutzungsfehler, bei dem nichts hochgeladen wurde, und 130 bedeutet, dass du abgebrochen hast und die laufende Anfrage beendet wurde. Fehler geben reason:, code: und hint: unter der Meldung aus, wann immer sie verfügbar sind, und darauf sollte ein Skript passen statt auf Prosa.
Ein Exit ist leicht misszuverstehen. Ein Werkzeug, das nichts zurückzugeben findet, endet mit einem von null verschiedenen Code und code: no_content, statt eine leere Datei zu schreiben, sodass pdf-to-csv auf einer PDF ohne Tabellen ein Fehler ist und keine CSV mit null Bytes.
Wohin die Bytes gehen
Die Dateien werden an die API-Basis hochgeladen, dort verarbeitet und gelöscht, sobald die Antwort gesendet ist. Das ist derselbe Vertrag wie beim Browserformular; das CLI ändert den Client, nicht das Ziel. Für Dokumente, die dein Netz nicht verlassen dürfen, betreibe selbst einen pdfx-server und richte --api-base darauf, was unter Selbst hosten behandelt wird.
Es gibt keinen Offline-Modus als Rückfall: Ist die Basis nicht erreichbar, schlägt der Befehl fehl. pdfx ist ein Netzwerkclient, der sich zufällig in einer Shell wohlfühlt, keine lokale PDF-Engine.
Was das CLI nicht ist
pdfx ist keine Desktopoberfläche und keine einbettbare OCR-Bibliothek, die du in eine andere Anwendung einbindest. Es ist ein Kommandozeilenclient für PDF-Operationen, sodass eine einmalige menschliche Aufgabe weiterhin besser im Portal aufgehoben ist (Komprimieren, OCR und der übrige Katalog), und alles, was einen eigenen UI-Baum braucht, das in Dieselbe Operation, vier Clients beschriebene Driftproblem neu erschaffen würde.
Agenten bekommen dieselben Formen vom veröffentlichten Skill unter /skills/pdf123.md, der die Merge- und Pipeline-Anfragen vollständig dokumentiert. Für sichere Wiederholungen verändernder POST-Anfragen sende Idempotency-Key; das CLI macht weiterhin einen Aufruf pro Start, also gehört der Header in das, was es wiederholt (Idempotency-Key: sichere Wiederholungen für PDF-Aufgaben). Schlüssel, Ratenbegrenzungen und Fehlercodes stehen unter Entwickler.