pdfx CLI: Zuerst lokal, Cloud nur wenn nötig
pdfx verarbeitet PDFs standardmäßig lokal. In den Cloud-Modus wechselst du mit API-Basis und Schlüssel, wenn du gehostete oder eigene PDF123-REST-Endpunkte brauchst.
PDF123 ist der Produktname. pdfx ist das kurze CLI, das dieselben Operationen anspricht. Der Standardweg ist lokal: Datei lesen, die Operation über pdf-core ausführen, Ergebnis schreiben. Kein Konto, kein API-Schlüssel, kein Upload.
Lokal zuerst heißt, die Datei verlässt den Rechner nicht
Ein typischer Aufruf sieht so aus: pdfx merge a.pdf b.pdf -o merged.pdf oder pdfx compress input.pdf. Die Verarbeitung läuft dort, wo die Binärdatei läuft. Das passt zu CI-Aufgaben auf einem eigenen Runner, zu Skripten neben einem Stapel Rechnungen und zu jedem Fall, in dem ein Upload zu einem Dritten die falsche Antwort ist.
Der lokale Modus ist kein dünner Wrapper, der Bytes heimlich woandershin sendet. Das CLI nutzt dieselbe Registry von Operationen wie der Server (pdf_core::ops::run). Wer den Weg über das Netzwerk will, entscheidet sich mit --cloud dafür.
Die eingebauten Unterbefehle decken gängige Operationen ab: merge, split, compress, rotate, extract, OCR, convert, protect, unlock, watermark und Verwandtes. Die lokale Ausgabe geht standardmäßig über -o / --output in eine Datei; - schreibt nach stdout.
--cloud ist derselbe Katalog über HTTP
Wenn du die gehostete API brauchst (oder deinen eigenen pdfx-server), übergib --cloud zusammen mit --api-base und --api-key (oder PDFX_API_KEY). Der Cloud-Modus setzt curl im Hintergrund voraus und schlägt fehl, wenn kein API-Schlüssel gesetzt ist. Ein Beispiel aus dem veröffentlichten Skill:
pdfx --cloud --api-base "$PDFX_API_BASE" --api-key "$PDFX_API_KEY" \
merge a.pdf b.pdf -o merged.pdf
Ohne Angabe steht --api-base auf https://pdf123.xyz, der gehosteten API. Für einen lokalen Aufbau mit Docker Compose verweisen Sie damit stattdessen auf http://127.0.0.1:8080. Das CLI wird damit zum Client der REST-Oberfläche, die unter Entwickler dokumentiert ist; die Namen der Operationen stimmen mit den Werkzeugen im Portal und mit OpenAPI überein (/v1/openapi.json).
Der Cloud-Modus ändert nicht, was eine Operation bedeutet. Komprimieren bleibt die Kompression von qpdf-Streams; OCR liefert weiterhin Markdown-Text aus dem Rust-Pfad und keine durchsuchbare Ebene in einer PDF. Übrig gebliebene Schalter des CLI, die auf ignorierte OCR-Parameter aus der Java-Zeit verweisen (zum Beispiel ein Feld languages), ändern diesen Vertrag nicht.
Warum es zwei Modi gibt
Der lokale Modus deckt Vertrauen ohne Netz und Kosten ohne Umweg ab. Der Cloud-Modus deckt gemeinsame Ratenbegrenzungen ab, den Betrieb auf einer Maschine, auf der nur das CLI und curl installiert sind, und Teams, die bereits API-Schlüssel ausgeben. Agenten können dieselbe Basis auch über MCP unter /mcp oder über den Skill unter dist/skills/pdf-toolbox/SKILL.md ansprechen. Verzeichnisse zur Auffindbarkeit wie /llms.txt helfen Coding-Agenten, Endpunkte zu finden; sie sind kein Signal für Google-Rankings.
Für sichere Wiederholungen verändernder POST-Anfragen gegen die API sende Idempotency-Key (siehe Idempotency-Key: sichere Wiederholungen für PDF-Aufgaben). Der Cloud-Weg des CLI bleibt ein HTTP-Aufruf pro Start; nutze den Header, wenn dein Wrapper wiederholt.
Die Wahl des Modus in der Praxis
Nutze den lokalen Modus, wenn die Dateien auf dem Runner bleiben müssen, wenn die Binärdatei pdfx und die nativen Abhängigkeiten auf dieser Maschine bereits vorhanden sind und wenn die Laufzeit von der Operation und nicht vom Upload bestimmt wird. Nutze den Cloud-Modus, wenn die schweren Abhängigkeiten nur auf dem Server liegen, wenn du dieselben Ratenbegrenzungen und dieselbe Abrechnung wie andere API-Clients willst oder wenn Agenten bereits einen API-Schlüssel für https://pdf123.xyz oder deine selbst gehostete Basis besitzen.
Vermische die Erwartungen nicht: lokales OCR folgt weiterhin dem Vertrag für die Markdown-Ausgabe von misc/ocr-pdf, und Cloud-Komprimierung bleibt die Kompression von qpdf-Streams und kein Font-Subsetting. Der Wechsel des Modus ändert, wo die Operation läuft, nicht die Bedeutung des Katalogs.
Was das CLI nicht ist
pdfx ist keine Desktopoberfläche und keine OCR-Bibliothek, die du in eine andere Anwendung einbindest. Es ist ein Kommandozeilenclient für PDF-Operationen: standardmäßig lokal, über HTTP wenn du es verlangst. Einmalige Aufgaben im Browser laufen weiterhin im Portal (Komprimieren, OCR und der übrige Katalog). Automatisierung, die eine Binärdatei bevorzugt, kann bei pdfx bleiben.
Vergleiche derselben Operation über Browser, curl, MCP und CLI skizziert Dieselbe Operation, vier Clients. Beginne bei Entwickler für Schlüssel und OpenAPI oder bei Selbst hosten, wenn die API-Basis dein eigener Aufbau mit Docker Compose sein soll.