La CLI pdfx: local primer, núvol quan cal
La CLI pdfx processa PDF a la vostra màquina per defecte. Activeu el mode núvol amb una URL base i una clau quan calgui REST allotjat o propi.
PDF123 és el nom del producte. pdfx és la CLI curta que parla amb les mateixes operacions. El camí per defecte és local: llegiu un fitxer, executeu l'operació amb pdf-core i escriviu una sortida. Sense compte, sense clau d'API i sense càrrega.
El local primer vol dir que el fitxer no surt mai
Una crida típica és pdfx merge a.pdf b.pdf -o merged.pdf o pdfx compress input.pdf. El processament s'executa allà on s'executa el binari. Això encaixa amb feines de CI en un executor privat, amb scripts al costat d'un lot de factures i amb qualsevol cas en què carregar el fitxer a un tercer és la resposta equivocada.
El mode local no és un embolcall prim que envia bytes en secret a un altre lloc. La CLI comparteix el mateix registre d'operacions que el servidor (pdf_core::ops::run). Si voleu el camí de xarxa, l'activeu amb --cloud.
Els subcomandaments integrats cobreixen les operacions habituals: unir, dividir, comprimir, girar, extreure, OCR, convertir, protegir, desbloquejar, marcar amb aigua i feines relacionades. La sortida local és un fitxer per defecte amb -o / --output; - escriu a stdout.
--cloud és el mateix catàleg per HTTP
Quan necessiteu l'API allotjada (o el vostre propi pdfx-server), passeu --cloud amb --api-base i --api-key (o PDFX_API_KEY). El mode núvol utilitza curl per sota i falla si no hi ha cap clau d'API definida. Exemple tret de l'habilitat publicada:
pdfx --cloud --api-base "$PDFX_API_BASE" --api-key "$PDFX_API_KEY" \
merge a.pdf b.pdf -o merged.pdf
--api-base val https://pdf123.xyz per defecte, l'API allotjada. Per a una pila local de Docker Compose, apunteu-lo a http://127.0.0.1:8080. La CLI es converteix en un client de la superfície REST que es documenta a Desenvolupadors; els noms de les operacions s'alineen amb les eines del portal i amb l'OpenAPI (/v1/openapi.json).
El mode núvol no canvia el que significa una operació. La compressió continua sent compressió de fluxos amb qpdf; l'OCR continua retornant text Markdown des del camí de Rust, no una capa de PDF cercable. Els indicadors residuals de la CLI que es corresponen amb paràmetres d'OCR de l'època de Java que s'ignoren (per exemple un camp languages) no canvien aquest contracte.
Per què hi ha dos modes
El local cobreix la confiança offline i un cost nul d'anada i tornada. El núvol cobreix els límits de taxa compartits, l'execució d'operacions en una màquina que només té la CLI i curl, i els equips que ja emeten claus d'API. Els agents també poden cridar la mateixa base amb MCP a /mcp o amb l'habilitat de dist/skills/pdf-toolbox/SKILL.md. Els índexs de descobriment com /llms.txt ajuden els agents de programació a trobar punts de destinació; no són cap senyal de posicionament a Google.
Per reintentar amb seguretat POST que muten l'estat contra l'API, envieu Idempotency-Key (vegeu Idempotency-Key: reintents segurs per a tasques PDF). El camí núvol de la CLI continua sent una petició HTTP per invocació; feu servir la capçalera quan el vostre embolcall reintenti.
Triar un mode a la pràctica
Feu servir el local quan els fitxers hagin de quedar-se a l'executor, quan ja tingueu el binari pdfx i les dependències natives en aquella màquina i quan la latència la domini l'operació i no la càrrega. Feu servir el núvol quan les dependències pesades només visquin al servidor, quan vulgueu els mateixos límits de taxa i la mateixa facturació que altres clients de l'API, o quan els agents ja tinguin una clau d'API per a https://pdf123.xyz o per a la vostra base autoallotjada.
No barregeu expectatives: l'OCR local continua seguint el contracte de sortida Markdown de misc/ocr-pdf; la compressió al núvol continua sent fluxos de qpdf, no subconjunts de fonts. El canvi de mode canvia on s'executa l'operació, no la semàntica del catàleg.
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: local per defecte i HTTP quan ho demaneu. Les tasques puntuals al navegador continuen al portal (Comprimeix, OCR i la resta del catàleg). L'automatització que prefereix un binari es pot quedar amb pdfx.
Les comparacions de la mateixa operació entre navegador, curl, MCP i CLI es descriuen a La mateixa operació, quatre clients. Comenceu per Desenvolupadors per a les claus i l'OpenAPI, o per Autoallotjament si la base de l'API ha de ser la vostra pròpia pila de Docker Compose.