pdfx: PDF123:s kommandorad

Hur installerar jag pdfx?#

Installera paketet globalt för att få kommandot pdfx. Eller kör det en gång utan installation.

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 och pnpm add -g @pdf123/cli fungerar också. Inget annat behöver installeras.

Hur kommer jag igång?#

Dessa sex kommandon visar de vanligaste mönstren.

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

Hur kör jag ett valfritt verktyg?#

Det första argumentet är verktygets id. Indatafilerna och verktygets alternativ följer efter. Varje alternativ för ett verktyg är en flagga, skriven som API-fältets namn (--pageNumbers) eller i kebab-skiftläge (--page-numbers). Ett negativt tal kan följa efter sin flagga med ett mellanslag, som i --rotation -90, eller efter ett likhetstecken.

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

Använd pdfx list för att se verktygen. Kommandot godtar --category eller --group, samt --query med sökord. Använd pdfx describe <tool> för att se slutpunkten, de godtagna indata, om verktyget körs som batch, och varje fält med standardvärde och tillåtna värden. Ett okänt verktygs-id ger förslag, och ett felstavat id avslutas med kod 2.

Vilka kommandon motsvarar vilka verktygssidor?#

Hur bearbetar jag många filer samtidigt?#

Ge flera filer till ett enfilsverktyg så kör pdfx en batch. Använd -o med en katalog som slutar med snedstreck. Verktyget körs en gång per fil, som standard två filer åt gången. Ändra det med --concurrency.

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

pdfx skriver ut en rad, input -> saved, när varje fil är klar. En misslyckad fil rapporteras på standardfelutdata och de andra filerna blir ändå klara. Tryck på Ctrl-C en gång för att avbryta den pågående begäran; filer som redan sparats finns kvar. Ett andra Ctrl-C avslutar direkt med kod 130. Med --idempotency-key k skickar varje fil k:<index>, och en upprepning av samma begäran spelar upp det första resultatet i 24 timmar.

En batch med ett verktyg som returnerar en rapport, till exempel get-info, skriver inga filer utan -o. Den skriver ut rapporterna ordnade efter indatafil.

Hur kedjar jag verktyg i en och samma begäran?#

pdfx pipeline kör flera verktyg i en och samma begäran. Upprepa --step för varje verktyg. Om du vill ange alternativ skickar du en JSON-array med --steps.

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

Steg kan inte använda verktyg som behöver en andra fil.

Hur öppnar jag lösenordsskyddade PDF:er?#

--input-password öppnar först alla krypterade indatafiler. --password-for <file>=<password> anger lösenordet för en fil. Den kan upprepas, och * som filnamn gäller resten. Det passar en batch som blandar låsta och öppna filer. För merge och images-to-pdf låses varje namngiven fil upp separat innan verktyget körs.

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

Samma alternativ fungerar i en pipeline. Om du vill ta bort skyddet permanent använder du verktyget Ta bort lösenord med dess eget alternativ --password.

Hur fungerar indata och utdata?#

• Indata - läser standardindata, en gång per körning. -o - skriver resultatet till standardutdata.
• -o file.pdf skriver den filen. -o dir/ skriver i en katalog. En katalog som inte finns än kräver det avslutande snedstrecket, eftersom ett namn utan det skrivs som en fil.
• Utan -o hamnar resultaten i den aktuella katalogen under serverns filnamn.
• I en katalog ersätter pdfx aldrig en befintlig fil, utan väljer ett nytt namn. Ett uttryckligt -o file.pdf ersätter den filen.
• Ett filnamn i -o vars ändelse motsäger resultatet, till exempel en ZIP-fil från split som sparas som .pdf, avvisas med slutkod 2 och code: output_mismatch. Ingenting skrivs.
• Utdata som inte kan skrivas är ett användningsfel som upptäcks innan något laddas upp.

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

Vad skriver --json ut?#

För ett sparat resultat skriver --json ut sökvägen, innehållstypen och storleken. Ett verktyg som returnerar en rapport skriver ut själva rapporten. En batch skriver ut en rapport med en status per fil.

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

En misslyckad fil har error och reason i stället för path och bytes. Ett filterverktyg utan träff skriver ut { "matched": false }. pdfx list --json skriver ut rader med id, category, group, name, description, returns, files och filter.

Vilka alternativ gäller för alla verktyg?#

Vilka slutkoder finns?#

Fel skriver ut raderna reason:, code: och hint: när servern lämnar dem, så ett skript kan förgrena utan att matcha text. Ett verktyg som inte hittar något att returnera, till exempel pdf-to-csv på en PDF utan tabeller, avslutas med 1 och code: no_content i stället för att skriva en tom fil. Koderna finns listade under Felkoder.

Hur pekar jag pdfx mot min egen server?#

Ange PDFX_API_BASE, eller skicka --api-base, med adressen till en egen pdfx-server. Lägg till PDFX_API_KEY om din server kräver en nyckel. Se Self-host.

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

Hur kör jag en slutpunkt som CLI:t inte känner till?#

pdfx call skickar en rå begäran till ett operations-id eller en /api/...-sökväg. Använd --field name=value för formulärfält och --file field=path för extra filer. Den skickar exakt en begäran och validerar ingenting lokalt, så lösenord och batchar avvisas.

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

Relaterade sidor#

• Översikt för utvecklare med REST API och autentisering
• TypeScript-SDK, biblioteket som kommandoraden bygger på
• MCP-servrar för AI-agenter
• Blogginlägget "pdfx CLI: en katalog, anropad från din terminal" på PDF123-bloggen

Vanliga frågor#

Fungerar pdfx offline?#

Nej. pdfx laddar upp varje fil till PDF123 API eller till din egen server och sparar resultatet lokalt, så API-basen måste vara nåbar.

Behöver pdfx en API-nyckel?#

Nej. Anonym användning fungerar. Ange PDFX_API_KEY eller skicka --api-key om din server kräver en. Nyckeln skickas som rubriken X-API-KEY.

Vilken Node-version kräver pdfx?#

Node 20.3 eller senare, eller Bun.

Skriver pdfx över mina filer?#

Inte när det skriver till en katalog: en befintlig fil ersätts aldrig. Om du själv anger utdatafilen med -o file.pdf ersätts den filen, så välj ett nytt namn när du vill behålla originalet.

Vad händer när ett filterverktyg inte hittar någon träff?#

Filterverktyg, vars id:n börjar med filter-, släpper igenom filen när deras villkor uppfylls. När det inte gör det skriver pdfx ut no match och avslutas med kod 0. I en batch räknas en sådan fil som utan träff, inte som misslyckad.