pdfx: de PDF123-opdrachtregel

Hoe installeer ik pdfx?#

Installeer het pakket globaal om de opdracht pdfx te krijgen. Of voer het eenmalig uit zonder te installeren.

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 en pnpm add -g @pdf123/cli werken ook. Verder hoeft er niets te worden geïnstalleerd.

Hoe begin ik?#

Deze zes opdrachten laten de gangbare patronen zien.

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

Hoe voer ik een willekeurige tool uit?#

Het eerste argument is de tool-id. Daarna volgen de invoerbestanden en de opties van de tool. Elke optie van een tool is een vlag, geschreven als de veldnaam uit de API (--pageNumbers) of in kebab-case (--page-numbers). Een negatief getal kan na een spatie op zijn vlag volgen, zoals in --rotation -90, of na een gelijkteken.

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

Gebruik pdfx list om de tools te zien. Het accepteert --category of --group, en --query met zoekwoorden. Gebruik pdfx describe <tool> om het eindpunt, de geaccepteerde invoer, of de tool als batch draait en elk veld met standaardwaarde en toegestane waarden te zien. Bij een onbekende tool-id krijg je suggesties, en een typefout sluit af met code 2.

Welke opdrachten horen bij welke toolpagina?#

Hoe verwerk ik veel bestanden tegelijk?#

Geef meerdere bestanden aan een tool voor één bestand en pdfx draait een batch. Gebruik -o met een map die op een schuine streep eindigt. De tool draait één keer per bestand, standaard twee bestanden tegelijk. Wijzig dat met --concurrency.

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

pdfx toont één regel, input -> saved, zodra een bestand klaar is. Een mislukt bestand wordt op standaardfout gemeld en de overige bestanden worden gewoon afgemaakt. Druk één keer op Ctrl-C om het lopende verzoek af te breken; bestanden die al zijn opgeslagen blijven behouden. Een tweede Ctrl-C stopt meteen met code 130. Met --idempotency-key k verstuurt elk bestand k:<index>, en een herhaling van hetzelfde verzoek geeft 24 uur lang het eerste resultaat terug.

Een batch van een tool die een rapport teruggeeft, zoals get-info, schrijft zonder -o geen bestanden. De rapporten worden getoond, gesorteerd op invoerbestand.

Hoe koppel ik tools in één verzoek?#

pdfx pipeline voert meerdere tools uit in één verzoek. Herhaal --step voor elke tool. Om opties in te stellen geef je met --steps een JSON-array mee.

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

Stappen kunnen geen tools gebruiken die een tweede bestand nodig hebben.

Hoe open ik PDF's met een wachtwoord?#

--input-password opent eerst elke versleutelde invoer. --password-for <file>=<password> stelt het wachtwoord van één bestand in. Dit kan herhaald worden, en * als bestandsnaam geldt voor de rest. Dat is handig voor een batch met een mix van beveiligde en open bestanden. Bij merge en images-to-pdf wordt elk genoemd bestand apart ontgrendeld voordat de tool draait.

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

Dezelfde opties werken in een pipeline. Gebruik de tool Ontgrendelen met zijn eigen optie --password om de beveiliging blijvend te verwijderen.

Hoe werken invoer en uitvoer?#

• Een invoer van - leest standaardinvoer, één keer per uitvoering. -o - schrijft het resultaat naar standaarduitvoer.
• -o file.pdf schrijft dat bestand. -o dir/ schrijft in een map. Een map die nog niet bestaat, vereist de afsluitende schuine streep, want een naam zonder wordt als bestand geschreven.
• Zonder -o komen resultaten in de huidige map terecht, onder de bestandsnaam van de server.
• In een map vervangt pdfx nooit een bestaand bestand; er wordt een nieuwe naam gekozen. Een expliciete -o file.pdf vervangt dat bestand wel.
• Een -o-bestandsnaam waarvan de extensie niet bij het resultaat past, zoals een ZIP van split die als .pdf wordt opgeslagen, wordt geweigerd met exitcode 2 en code: output_mismatch. Er wordt niets geschreven.
• Een uitvoer die niet kan worden geschreven, is een gebruiksfout die wordt vastgesteld voordat er iets wordt geüpload.

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

Wat toont --json?#

Voor een opgeslagen resultaat toont --json het pad, het contenttype en de grootte. Een tool die een rapport teruggeeft, toont het rapport zelf. Een batch toont één rapport met een status per bestand.

{ "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 }
  ]
}

Een mislukt bestand heeft error en reason in plaats van path en bytes. Een filtertool zonder overeenkomst toont { "matched": false }. pdfx list --json toont rijen met id, category, group, name, description, returns, files en filter.

Welke opties gelden voor elke tool?#

Wat zijn de exitcodes?#

Fouten tonen regels met reason:, code: en hint: wanneer de server die levert, zodat een script kan vertakken zonder tekst te vergelijken. Een tool die niets heeft om terug te geven, zoals pdf-to-csv bij een PDF zonder tabellen, sluit af met 1 en code: no_content in plaats van een leeg bestand te schrijven. De codes staan op Foutcodes.

Hoe richt ik pdfx op mijn eigen server?#

Stel PDFX_API_BASE in, of geef --api-base mee, op het adres van een zelfgehoste pdfx-server. Voeg PDFX_API_KEY toe als je server een sleutel vereist. Zie Self-host.

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

Hoe roep ik een eindpunt aan dat de CLI niet kent?#

pdfx call stuurt een ruw verzoek naar een bewerkings-id of een /api/...-pad. Gebruik --field name=value voor formuliervelden en --file field=path voor extra bestanden. Er wordt precies één verzoek verstuurd en lokaal wordt niets gevalideerd, dus wachtwoorden en batches worden geweigerd.

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

Gerelateerde pagina's#

• Overzicht voor ontwikkelaars met de REST API en authenticatie
• TypeScript-SDK, de bibliotheek waarop de opdrachtregel is gebouwd
• MCP-servers voor AI-agents
• De blogpost "pdfx CLI: One Catalog, Called From Your Terminal" op de PDF123-blog

FAQ#

Werkt pdfx offline?#

Nee. pdfx uploadt elk bestand naar de PDF123-API of naar je eigen server en slaat het resultaat lokaal op, dus de API-basis moet bereikbaar zijn.

Heeft pdfx een API-sleutel nodig?#

Nee. Anoniem gebruik werkt. Stel PDFX_API_KEY in of geef --api-key mee als je server een sleutel vereist. De sleutel wordt verstuurd als de header X-API-KEY.

Welke Node-versie heeft pdfx nodig?#

Node 20.3 of nieuwer, of Bun.

Overschrijft pdfx mijn bestanden?#

Niet als het in een map schrijft: een bestaand bestand wordt nooit vervangen. Als je zelf de uitvoerbestandsnaam opgeeft met -o file.pdf, wordt dat bestand wel vervangen, kies dus een nieuwe naam als je het origineel wilt bewaren.

Wat gebeurt er als een filtertool geen overeenkomst vindt?#

Filtertools, waarvan de id's met filter- beginnen, laten het bestand door als hun voorwaarde geldt. Als dat niet zo is, toont pdfx no match en sluit af met code 0. In een batch telt zo'n bestand als niet overeenkomend, niet als mislukt.