Product4 min de lectura

La CLI pdfx: un sol catàleg, cridat des del vostre terminal

La CLI pdfx envia les mateixes peticions multipart que curl a l'API de PDF123 o al vostre pdfx-server, i afegeix execucions per lots, contrasenyes per fitxer i codis de sortida sobre els quals un script pot bifurcar.

By the PDF123 team · Updated 2026-09-29
La CLI pdfx: un sol catàleg, cridat des del vostre terminal

PDF123 és el nom del producte. pdfx és el mateix catàleg d'operacions embolcallat per a un intèrpret d'ordres: construeix la petició multipart que curl hauria construït, l'envia a la base de l'API que trieu i escriu el resultat al costat dels vostres fitxers. Uneix, Comprimeix, OCR i la resta del catàleg es poden cridar d'aquesta manera.

Què envia realment una crida

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

--api-base val https://pdf123.xyz per defecte, i --api-key (o la variable d'entorn PDFX_API_KEY) és opcional, així que el catàleg anònim funciona sense cap clau. Apunteu la base a http://127.0.0.1:8080 per a una pila de docker-compose pròpia. No hi ha cap segon protocol a sota: la CLI és un client de la superfície REST que es documenta a Desenvolupadors, i els noms de les operacions coincideixen amb les eines del portal i amb el document OpenAPI de /v1/openapi.json.

El catàleg es pot descobrir sense sortir del terminal. pdfx list imprimeix cada eina i pdfx describe add-stamp imprimeix els camps i els valors per defecte d'una eina, que és la mateixa definició que el portal renderitza com a formulari.

Execucions per lots i els indicadors que curl us fa escriure a mà

Doneu diverses entrades a una eina d'un sol fitxer i les executa com un lot dins del directori -o, imprimint una línia input -> saved per fitxer. Els errors van a stderr i la resta de fitxers s'acaben igualment, així que un PDF dolent en una carpeta de factures no avorta l'execució. --concurrency <n> fixa quants fitxers hi ha en vol alhora (per defecte, 2).

-o accepta un fitxer o un directori i no sobreescriu mai un fitxer existent, sinó que fa servir el nom que el servidor dona al resultat dins del directori. Això importa quan el servidor anomena el resultat a partir de l'entrada: sense això, una execució trepitjaria el PDF que acabeu de pujar.

Les entrades xifrades s'obren abans de la petició, no per l'eina: --input-password cobreix tots els fitxers de l'execució, i --password-for report.pdf=secret fixa la contrasenya d'un fitxer i es pot repetir, amb * en lloc de la resta. Un lot que barreja fitxers bloquejats i oberts no necessita, doncs, cap ordenació manual. --json imprimeix { path, contentType, bytes } per resultat, o [{ input, ok, path | error, reason }] per a un lot, de manera que un embolcall pot analitzar el resultat en lloc de raspar les línies llegibles per a persones.

Codis de sortida sobre els quals un script pot bifurcar

0 vol dir èxit, 1 vol dir que una petició ha fallat (en un lot: almenys un fitxer), 2 és un error d'ús en què no s'ha pujat res, i 130 vol dir que l'heu interromput i la petició en curs s'ha avortat. Els errors imprimeixen línies reason:, code: i hint: sota el missatge sempre que estiguin disponibles, i és això el que un script ha de fer coincidir, no la prosa.

Hi ha una sortida que és fàcil de malinterpretar. Una eina que no troba res a retornar surt amb un codi diferent de zero i code: no_content en lloc d'escriure un fitxer buit, així que pdf-to-csv sobre un PDF sense taules és un error, no un CSV de zero bytes.

On van els bytes

Els fitxers es pugen a la base de l'API, s'hi processen i s'esborren quan s'ha enviat la resposta. És el mateix contracte que el formulari del navegador: la CLI canvia el client, no la destinació. Per a documents que no poden sortir de la vostra xarxa, executeu un pdfx-server propi i apunteu-hi --api-base, cosa que es tracta a Autoallotjament.

No hi ha cap mode fora de línia on recular: si la base no és accessible, l'ordre falla. pdfx és un client de xarxa que resulta agradable en un intèrpret d'ordres, no un motor de PDF local.

Què no és la CLI

pdfx no és una interfície gràfica d'escriptori ni una biblioteca d'OCR que pugueu enllaçar dins d'una altra aplicació. És un client de línia de comandes per a operacions amb PDF, així que una tasca humana puntual continua tenint millor servei al portal (Comprimeix, OCR i la resta del catàleg), i qualsevol cosa que necessiti un arbre d'interfície propi recrearia el problema de la divergència descrit a La mateixa operació, quatre clients.

Els agents obtenen les mateixes formes de l'habilitat publicada a /skills/pdf123.md, que documenta del tot les peticions d'unió i de pipeline. Per reintentar amb seguretat POST que muten l'estat, envieu Idempotency-Key; la CLI continua fent una petició per invocació, així que la capçalera pertoca a allò que reintenti (reintents segurs per a tasques PDF). Les claus, els límits de taxa i els codis d'error són a Desenvolupadors.

Open tool
Process in the browser — no watermark, files removed after the job.
Open tool