Product4 min di lettura

CLI pdfx: un solo catalogo, chiamato dal tuo terminale

La CLI pdfx invia le stesse richieste multipart di curl all’API PDF123 o al tuo pdfx-server, e aggiunge esecuzioni in batch, password per file e codici di uscita su cui uno script può diramarsi.

By the PDF123 team · Updated 2026-09-29
CLI pdfx: un solo catalogo, chiamato dal tuo terminale

PDF123 è il nome del prodotto. pdfx è lo stesso catalogo di operazioni avvolto per una shell: costruisce la richiesta multipart che avrebbe costruito curl, la invia alla base API che scegli e scrive il risultato accanto ai tuoi file. Unisci, Comprimi, OCR e il resto del catalogo si chiamano così.

Cosa invia davvero una chiamata

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

--api-base vale https://pdf123.xyz per impostazione predefinita, e --api-key (o la variabile d’ambiente PDFX_API_KEY) è facoltativa, quindi il catalogo anonimo funziona anche senza. Punta la base su http://127.0.0.1:8080 per uno stack docker-compose tuo. Sotto non c’è un secondo protocollo: la CLI è un client della superficie REST documentata su Developers, e i suoi nomi di operazione coincidono con gli strumenti del portale e con il documento OpenAPI su /v1/openapi.json.

Il catalogo si scopre senza lasciare il terminale. pdfx list stampa ogni strumento e pdfx describe add-stamp stampa i campi e i valori predefiniti di uno strumento, cioè la stessa definizione che il portale rende come modulo.

Esecuzioni in batch e le opzioni che curl ti costringe a scrivere

Dai più input a uno strumento a file singolo e li esegue come batch nella directory -o, stampando una riga input -> saved per file. I fallimenti vanno su stderr e i file restanti arrivano comunque a termine, così un PDF corrotto in una cartella di fatture non interrompe l’esecuzione. --concurrency <n> stabilisce quanti file sono in lavorazione insieme (predefinito 2).

-o accetta un file o una directory e non sovrascrive mai un file esistente: dentro la directory usa il nome fornito dal server. È importante quando il server nomina il risultato dall’input: senza questo, un’esecuzione cancellerebbe il PDF appena caricato.

Gli input cifrati vengono aperti prima della richiesta, non dallo strumento: --input-password copre ogni file dell’esecuzione, e --password-for report.pdf=secret imposta la password di un singolo file e può essere ripetuto, con * al posto degli altri. Un batch che mescola file protetti e aperti non richiede quindi alcuna selezione manuale. --json stampa { path, contentType, bytes } per risultato, oppure [{ input, ok, path | error, reason }] per un batch, così un wrapper può analizzare l’esito invece di estrarre le righe leggibili.

Codici di uscita su cui uno script può diramarsi

0 significa successo, 1 che una richiesta è fallita (in un batch: almeno un file), 2 è un errore d’uso in cui non è stato caricato nulla, e 130 che hai interrotto il comando e la richiesta in corso è stata annullata. I fallimenti stampano righe reason:, code: e hint: sotto il messaggio quando sono disponibili, ed è su quelle che uno script dovrebbe confrontarsi, non sulla prosa.

Un codice di uscita è facile da leggere male. Uno strumento che non trova nulla da restituire esce con un codice diverso da zero e code: no_content invece di scrivere un file vuoto: pdf-to-csv su un PDF senza tabelle è quindi un fallimento, non un CSV da zero byte.

Dove finiscono i byte

I file vengono caricati sulla base API, elaborati lì ed eliminati non appena la risposta è inviata. È lo stesso contratto del modulo nel browser: la CLI cambia il client, non la destinazione. Per i documenti che non devono uscire dalla tua rete, esegui tu un pdfx-server e punta --api-base su di esso, cosa trattata in Self-host.

Non esiste una modalità offline su cui ripiegare: se la base non è raggiungibile, il comando fallisce. pdfx è un client di rete che si trova a essere comodo in una shell, non un motore PDF locale.

Cosa non è la CLI

pdfx non è una GUI desktop né una libreria OCR incorporabile da collegare a un’altra applicazione. È un client da riga di comando per operazioni PDF, quindi un’attività umana una tantum è ancora meglio servita dal portale (Comprimi, OCR e il resto del catalogo), e qualsiasi cosa che richieda un proprio albero di interfacce ricreerebbe il problema di divergenza descritto in La stessa operazione, quattro client.

Gli agenti ottengono le stesse forme dalla skill pubblicata su /skills/pdf123.md, che documenta per intero le richieste di merge e pipeline. Per ripetere in sicurezza POST che modificano lo stato, invia Idempotency-Key; la CLI fa comunque una richiesta per invocazione, quindi l’intestazione spetta a ciò che la ritenta (Idempotency-Key: nuovi tentativi sicuri per le attività PDF). Chiavi, limiti di frequenza e codici di errore sono su Developers.

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