CLI pdfx: prima in locale, cloud quando serve
pdfx elabora i PDF sulla tua macchina per impostazione predefinita. Passa alla modalità cloud con base e chiave API quando ti servono gli endpoint REST di PDF123.
PDF123 è il nome del prodotto. pdfx è la CLI breve che parla con le stesse operazioni. Il percorso predefinito è locale: legge un file, esegue l'operazione con pdf-core, scrive un output. Nessun account, nessuna API key, nessun caricamento.
Locale prima di tutto: il file non esce mai
Una chiamata tipica è pdfx merge a.pdf b.pdf -o merged.pdf oppure pdfx compress input.pdf. L'elaborazione avviene dove viene eseguito il binario. È la scelta giusta per attività CI su un runner privato, per script che lavorano su una cartella di fatture e per ogni caso in cui caricare i dati presso terzi è la risposta sbagliata.
La modalità locale non è un wrapper sottile che invia i byte altrove di nascosto. La CLI condivide lo stesso registro di operazioni del server (pdf_core::ops::run). Se vuoi il percorso di rete, lo attivi con --cloud.
I sottocomandi integrati coprono le operazioni più comuni: merge, split, compress, rotate, extract, OCR, convert, protect, unlock, watermark e attività correlate. In locale l'output predefinito è un file tramite -o / --output; - scrive su stdout.
--cloud è lo stesso catalogo su HTTP
Quando ti serve l'API ospitata (o il tuo pdfx-server), passa --cloud con --api-base e --api-key (oppure PDFX_API_KEY). La modalità cloud richiede curl sotto il cofano e fallisce se non è impostata alcuna API key. Esempio dalla skill pubblicata:
pdfx --cloud --api-base "$PDFX_API_BASE" --api-key "$PDFX_API_KEY" \
merge a.pdf b.pdf -o merged.pdf
Se non viene impostato, --api-base vale https://pdf123.xyz, l'API ospitata. Per uno stack Docker Compose locale, puntatelo invece su http://127.0.0.1:8080. La CLI diventa così un client dell'API REST documentata su Developers; i nomi delle operazioni coincidono con gli strumenti del portale e con OpenAPI (/v1/openapi.json).
La modalità cloud non cambia cosa significa un'operazione. Comprimi resta la compressione degli stream con qpdf; l'OCR restituisce comunque testo Markdown dal percorso Rust, non uno strato PDF ricercabile. I flag residui della CLI che corrispondono a parametri OCR ignorati dell'era Java (per esempio il campo languages) non cambiano quel contratto.
Perché esistono due modalità
La modalità locale copre la fiducia offline e l'assenza di costi di andata e ritorno. Quella cloud copre limiti di frequenza condivisi, l'esecuzione di operazioni su una macchina che ha installati solo la CLI e curl, e i team che emettono già API key. Gli agenti possono anche chiamare la stessa base via MCP su /mcp o tramite la skill in dist/skills/pdf-toolbox/SKILL.md. Gli indici di scoperta come /llms.txt aiutano gli agenti di programmazione a trovare gli endpoint; non sono un segnale di posizionamento per Google.
Per ripetere in sicurezza le POST che modificano lo stato tramite l'API, invia Idempotency-Key (vedi Idempotency-Key: nuovi tentativi sicuri per le attività PDF). Il percorso cloud della CLI resta una richiesta HTTP per invocazione; usa l'intestazione quando il tuo wrapper ritenta.
Scegliere una modalità nella pratica
Usa la modalità locale quando i file devono restare sul runner, quando hai già il binario pdfx e le dipendenze native su quella macchina e quando la latenza è dominata dall'operazione più che dal caricamento. Usa quella cloud quando le dipendenze pesanti vivono solo sul server, quando vuoi gli stessi limiti di frequenza e la stessa misurazione degli altri client API, o quando gli agenti hanno già una API key per https://pdf123.xyz o per la tua base self-hosted.
Non mescolare le aspettative: l'OCR locale segue ancora il contratto di output Markdown di misc/ocr-pdf; la compressione cloud resta stream qpdf, non subsetting dei font. Il cambio di modalità modifica dove gira l'operazione, non la semantica del catalogo.
Cosa non è la CLI
pdfx non è una GUI desktop e non è una libreria OCR da incorporare in un'altra applicazione. È un client da riga di comando per operazioni PDF: locale per impostazione predefinita, HTTP quando lo chiedi. Le attività occasionali nel browser restano sul portale (Comprimi, OCR e il resto del catalogo). L'automazione che preferisce un binario può restare su pdfx.
I confronti della stessa operazione tra browser, curl, MCP e CLI sono tratteggiati in La stessa operazione, quattro client. Parti da Developers per chiavi e OpenAPI, oppure da Self-host se la base API deve essere il tuo stack Docker Compose.