pdfx CLI: lokaal eerst, cloud wanneer u het nodig hebt

PDF123 is de productnaam. pdfx is de korte CLI die met dezelfde bewerkingen praat. Het standaardpad is lokaal: lees een bestand, voer de bewerking uit via pdf-core, schrijf een resultaat weg. Geen account, geen API-sleutel, geen upload.

Lokaal eerst betekent dat het bestand nooit vertrekt

Een typische aanroep ziet eruit als pdfx merge a.pdf b.pdf -o merged.pdf of pdfx compress input.pdf. De verwerking draait waar het programma draait. Dat past bij CI-taken op een privé-runner, scripts naast een reeks facturen, en elk geval waarin uploaden naar een derde partij het verkeerde antwoord is.

De lokale modus is geen dun omhulsel dat stiekem bytes ergens anders naartoe stuurt. De CLI gebruikt dezelfde operatieregistry als de server (pdf_core::ops::run). Wilt u het netwerkpad, dan kiest u daar met --cloud voor.

Ingebouwde subcommando's dekken veelvoorkomende bewerkingen: merge, split, compress, rotate, extract, OCR, convert, protect, unlock, watermark en verwant werk. Lokale uitvoer gaat standaard naar een bestand via -o / --output; - schrijft naar stdout.

--cloud is dezelfde catalogus over HTTP

Hebt u de gehoste API nodig (of uw eigen pdfx-server), geef dan --cloud mee met --api-base en --api-key (of PDFX_API_KEY). De cloudmodus gebruikt onder de motorkap curl en mislukt als er geen API-sleutel is ingesteld. Voorbeeld uit de gepubliceerde skill:

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

--api-base valt terug op https://pdf123.xyz, de gehoste API. Voor een lokale Docker Compose-stack wijst u het in plaats daarvan naar http://127.0.0.1:8080. De CLI wordt dan een client van het REST-oppervlak dat op Developers staat; de namen van bewerkingen komen overeen met de portaltools en met OpenAPI (/v1/openapi.json).

De cloudmodus verandert niet wat een bewerking betekent. Compress is nog steeds qpdf-streamcompressie; OCR levert nog steeds Markdown-tekst uit het Rust-pad, geen doorzoekbare PDF-laag. Overgebleven CLI-opties die naar genegeerde OCR-parameters uit het Java-tijdperk verwijzen (bijvoorbeeld een veld languages) veranderen dat contract niet.

Waarom er twee modi zijn

Lokaal dekt offline vertrouwen en kosten van nul heen-en-weer-verkeer. Cloud dekt gedeelde rate limits, bewerkingen uitvoeren op een machine waar alleen de CLI en curl staan, en teams die al API-sleutels uitgeven. Agents kunnen dezelfde basis ook via MCP op /mcp of via de skill op dist/skills/pdf-toolbox/SKILL.md aanroepen. Ontdekkingsindexen zoals /llms.txt helpen coding agents endpoints te vinden; ze zijn geen signaal voor Google-ranking.

Stuur voor veilige nieuwe pogingen van wijzigende POST's tegen de API een Idempotency-Key mee (zie Idempotency-Key: Safe Retries for PDF Jobs). Het cloudpad van de CLI blijft één HTTP-verzoek per aanroep; gebruik de header wanneer uw omhulsel opnieuw probeert.

Een modus kiezen in de praktijk

Gebruik lokaal wanneer de bestanden op de runner moeten blijven, wanneer u het programma pdfx en de benodigde native afhankelijkheden al op die machine hebt, en wanneer de latentie vooral door de bewerking wordt bepaald en niet door de upload. Gebruik cloud wanneer de zware afhankelijkheden alleen op de server staan, wanneer u dezelfde rate limits en hetzelfde verbruik wilt als andere API-clients, of wanneer agents al een API-sleutel hebben voor https://pdf123.xyz of uw self-hosted basis.

Meng de verwachtingen niet: lokale OCR volgt nog steeds het Markdown-contract van misc/ocr-pdf; cloud-compressie is nog steeds qpdf-streams, geen font-subsetting. De schakelaar verandert waar de bewerking draait, niet de betekenis van de catalogus.

Wat de CLI niet is

pdfx is geen desktop-GUI en geen OCR-bibliotheek die u in een andere app kunt inbedden. Het is een command-lineclient voor PDF-bewerkingen: standaard lokaal, HTTP wanneer u daarom vraagt. Eenmalige taken in de browser blijven op de portal (Compress, OCR en de rest van de catalogus). Automatisering die de voorkeur geeft aan een programma kan bij pdfx blijven.

Vergelijkingen van dezelfde bewerking over browser, curl, MCP en CLI staan in Same operation, four clients. Begin bij Developers voor sleutels en OpenAPI, of bij Self-host als de API-basis uw eigen Docker Compose-stack moet zijn.