pdfx: la línia d'ordres de PDF123

Com instal·lo pdfx?#

Instal·la el paquet globalment per obtenir l'ordre pdfx. O executa'l una vegada sense instal·lar-lo.

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 i pnpm add -g @pdf123/cli també funcionen. No cal instal·lar res més.

Com començo?#

Aquestes sis ordres mostren els patrons més habituals.

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

Com executo qualsevol eina?#

El primer argument és l'identificador de l'eina. Els fitxers d'entrada i les opcions de l'eina van a continuació. Cada opció d'una eina és un indicador, escrit com el nom del camp de l'API (--pageNumbers) o en kebab case (--page-numbers). Un nombre negatiu pot anar després del seu indicador amb un espai, com a --rotation -90, o després d'un signe igual.

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

Fes servir pdfx list per veure les eines. Accepta --category o --group, i --query amb paraules per cercar. Fes servir pdfx describe <tool> per veure el punt final, les entrades acceptades, si l'eina s'executa com a lot, i cada camp amb el seu valor per defecte i els valors permesos. Si l'identificador no es coneix, s'ofereixen suggeriments, i si està mal escrit se surt amb el codi 2.

Quina ordre correspon a quina pàgina d'eina?#

Com processo molts fitxers alhora?#

Dona diversos fitxers a una eina d'un sol fitxer i pdfx executa un lot. Fes servir -o amb un directori que acabi amb una barra. L'eina s'executa una vegada per fitxer, dos fitxers alhora per defecte. Canvia-ho amb --concurrency.

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

pdfx imprimeix una línia, input -> saved, a mesura que acaba cada fitxer. Un fitxer que falla es notifica a l'error estàndard i els altres fitxers acaben igualment. Prem Ctrl-C una vegada per avortar la petició en curs; els fitxers ja desats es conserven. Un segon Ctrl-C surt a l'instant amb el codi 130. Amb --idempotency-key k, cada fitxer envia k:<index>, i si es repeteix la mateixa petició es reprodueix el primer resultat durant 24 hores.

Un lot d'una eina que retorna un informe, com get-info, no escriu cap fitxer sense -o. Imprimeix els informes indexats pel fitxer d'entrada.

Com encadeno eines en una sola petició?#

pdfx pipeline executa diverses eines en una sola petició. Repeteix --step per a cada eina. Per definir opcions, passa una matriu JSON amb --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

Els passos no poden fer servir eines que necessiten un segon fitxer.

Com obro PDF protegits amb contrasenya?#

--input-password obre primer totes les entrades xifrades. --password-for <file>=<password> defineix la contrasenya d'un sol fitxer. Es pot repetir, i * com a nom de fitxer cobreix la resta. Va bé per a un lot que barreja fitxers bloquejats i oberts. Per a merge i images-to-pdf, cada fitxer indicat es desbloqueja per separat abans d'executar l'eina.

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

Les mateixes opcions funcionen en un pipeline. Per treure la protecció de manera permanent, fes servir l'eina Desbloqueja amb la seva pròpia opció --password.

Com funcionen l'entrada i la sortida?#

• Una entrada de - llegeix l'entrada estàndard, una vegada per execució. -o - escriu el resultat a la sortida estàndard.
• -o file.pdf escriu aquest fitxer. -o dir/ escriu dins d'un directori. Un directori que encara no existeix necessita la barra final, perquè un nom sense ella s'escriu com a fitxer.
• Sense -o, els resultats van al directori actual amb el nom de fitxer del servidor.
• Dins d'un directori, pdfx mai no substitueix un fitxer existent; tria un nom nou. Un -o file.pdf explícit substitueix aquell fitxer.
• Un nom de fitxer per a -o amb una extensió que contradiu el resultat, com un ZIP de split desat com a .pdf, es rebutja amb el codi de sortida 2 i code: output_mismatch. No s'escriu res.
• Una sortida que no es pot escriure és un error d'ús detectat abans de pujar res.

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

Què imprimeix --json?#

Per a un resultat desat, --json imprimeix la ruta, el tipus de contingut i la mida. Una eina que retorna un informe imprimeix l'informe mateix. Un lot imprimeix un sol informe amb un estat per fitxer.

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

Un fitxer que falla té error i reason en lloc de path i bytes. Una eina de filtre sense coincidència imprimeix { "matched": false }. pdfx list --json imprimeix files amb id, category, group, name, description, returns, files i filter.

Quines opcions s'apliquen a totes les eines?#

Quins són els codis de sortida?#

Els errors imprimeixen les línies reason:, code: i hint: quan el servidor les proporciona, de manera que un script pot bifurcar sense comparar text. Una eina que no troba res per retornar, com pdf-to-csv en un PDF sense taules, surt amb 1 i code: no_content en lloc d'escriure un fitxer buit. Els codis són a Codis d'error.

Com apunto pdfx al meu propi servidor?#

Defineix PDFX_API_BASE, o passa --api-base, amb l'adreça d'un pdfx-server autoallotjat. Afegeix PDFX_API_KEY si el teu servidor necessita una clau. Consulta Autoallotjament.

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

Com executo un punt final que la CLI no coneix?#

pdfx call envia una petició en brut a un identificador d'operació o a una ruta /api/.... Fes servir --field name=value per als camps del formulari i --file field=path per a fitxers addicionals. Envia exactament una petició i no valida res en local, de manera que es rebutgen les contrasenyes i els lots.

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

Pàgines relacionades#

• Visió general per a desenvolupadors amb l'API REST i l'autenticació
• SDK de TypeScript, la biblioteca sobre la qual es construeix la línia d'ordres
• Servidors MCP per a agents d'IA
• L'entrada del blog «pdfx CLI: One Catalog, Called From Your Terminal» al blog de PDF123

FAQ#

Funciona pdfx sense connexió?#

No. pdfx puja cada fitxer a l'API de PDF123 o al teu propi servidor i desa el resultat en local, de manera que la base de l'API ha de ser accessible.

pdfx necessita una clau d'API?#

No. L'ús anònim funciona. Defineix PDFX_API_KEY o passa --api-key si el teu servidor en requereix una. La clau s'envia com a capçalera X-API-KEY.

Quina versió de Node necessita pdfx?#

Node 20.3 o superior, o Bun.

pdfx sobreescriurà els meus fitxers?#

No quan escriu dins d'un directori: un fitxer existent mai no se substitueix. Si indiques tu mateix el fitxer de sortida amb -o file.pdf, aquest fitxer se substitueix, així que tria un nom nou quan vulguis conservar l'original.

Què passa quan una eina de filtre no troba cap coincidència?#

Les eines de filtre, els identificadors de les quals comencen per filter-, deixen passar el fitxer quan es compleix la seva condició. Quan no es compleix, pdfx imprimeix no match i surt amb el codi 0. En un lot, aquest fitxer compta com a sense coincidència, no com a fallit.