pdfx CLI: lokalt först, molnet när du behöver det
pdfx bearbetar PDF:er på din egen maskin som standard. Välj molnläge med basadress och nyckel när du behöver hostade eller självhostade REST-slutpunkter.
PDF123 är produktnamnet. pdfx är det korta kommandoradsverktyget som talar med samma operationer. Standardvägen är lokal: läs en fil, kör operationen via pdf-core och skriv ett resultat. Inget konto, ingen API-nyckel, ingen uppladdning.
Lokalt först betyder att filen aldrig lämnar datorn
Ett typiskt anrop ser ut så här: pdfx merge a.pdf b.pdf -o merged.pdf eller pdfx compress input.pdf. Bearbetningen körs där programmet körs. Det passar CI-jobb på en privat runner, skript som ligger bredvid en hög fakturor och varje fall där uppladdning till en tredje part är fel svar.
Det lokala läget är inte ett tunt skal som i hemlighet skickar byten någon annanstans. Kommandoradsverktyget delar samma operationsregister som servern (pdf_core::ops::run). Vill du använda nätverksvägen väljer du den uttryckligen med --cloud.
Inbyggda underkommandon täcker vanliga operationer: slå ihop, dela, komprimera, rotera, extrahera, OCR, konvertera, skydda, låsa upp, vattenstämpla och liknande. Lokal utdata blir en fil via -o / --output; - skriver till standardutdata.
--cloud är samma katalog över HTTP
När du behöver det hostade API:et (eller din egen pdfx-server) skickar du --cloud tillsammans med --api-base och --api-key (eller PDFX_API_KEY). Molnläget kräver curl i bakgrunden och misslyckas om ingen API-nyckel är satt. Exempel från den publicerade skillen:
pdfx --cloud --api-base "$PDFX_API_BASE" --api-key "$PDFX_API_KEY" \
merge a.pdf b.pdf -o merged.pdf
--api-base har standardvärdet https://pdf123.xyz, den hostade API:n. För en lokal Docker Compose-stack pekar du den i stället mot http://127.0.0.1:8080. Kommandoradsverktyget blir en klient mot REST-ytan som beskrivs på Utvecklare; operationsnamnen följer portalens verktyg och OpenAPI (/v1/openapi.json).
Molnläget ändrar inte vad en operation betyder. Komprimering är fortfarande qpdf:s strömkomprimering, och OCR returnerar fortfarande Markdown-text via Rust-vägen, inte ett sökbart textlager i en PDF. Kvarvarande flaggor som motsvarar ignorerade OCR-parametrar från Java-tiden (till exempel ett fält languages) ändrar inte det kontraktet.
Varför det finns två lägen
Det lokala läget täcker förtroende offline och noll fördröjning per anrop. Molnläget täcker delade hastighetsgränser, körning på en maskin där bara kommandoradsverktyget och curl är installerade, och team som redan utfärdar API-nycklar. Agenter kan också nå samma bas via MCP på /mcp eller via skillen på dist/skills/pdf-toolbox/SKILL.md. Upptäcktsindex som /llms.txt hjälper kodagenter att hitta slutpunkterna; de är ingen rankningssignal för Google.
För säkra återförsök av förändrande POST-anrop mot API:et skickar du Idempotency-Key (se Idempotency-Key: säkra återförsök för PDF-jobb). I molnläget är varje körning fortfarande en HTTP-begäran; använd huvudet när din omslutning gör om anropet.
Att välja läge i praktiken
Använd det lokala läget när filerna måste stanna på runner-maskinen, när du redan har pdfx och de nativa beroendena där, och när svarstiden främst bestäms av operationen snarare än av uppladdningen. Använd molnläget när de tunga beroendena bara finns på servern, när du vill ha samma hastighetsgränser och mätning som andra API-klienter, eller när agenter redan har en API-nyckel för https://pdf123.xyz eller din egen bas.
Blir inte förväntningarna blandade: lokal OCR följer fortfarande kontraktet med Markdown från misc/ocr-pdf, och molnkomprimering är fortfarande qpdf-strömmar, inte teckensnittssubsetting. Att byta läge ändrar var operationen körs, inte vad den gör.
Vad kommandoradsverktyget inte är
pdfx är varken ett grafiskt skrivbordsprogram eller ett inbäddningsbart OCR-bibliotek som du länkar in i en annan app. Det är en kommandoradsbaserad klient för PDF-operationer: lokal som standard, HTTP när du begär det. Engångsjobb i webbläsaren finns fortfarande i portalen (Komprimera PDF, OCR och resten av katalogen). Automatisering som föredrar ett program kan stanna vid pdfx.
Jämförelser av samma operation mellan webbläsare, curl, MCP och kommandoradsverktyget finns i Samma operation, fyra klienter. Börja på Utvecklare för nycklar och OpenAPI, eller Kör själv om API-basen ska vara din egen Docker Compose-stack.