pdfx: la riga di comando di PDF123

Come installo pdfx?#

Installa il pacchetto a livello globale per ottenere il comando pdfx. Oppure eseguilo una volta senza installare nulla.

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

Funzionano anche bun add -g @pdf123/cli e pnpm add -g @pdf123/cli. Non serve installare nient'altro.

Come comincio?#

Questi sei comandi mostrano gli schemi più comuni.

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

Come eseguo uno strumento qualsiasi?#

Il primo argomento è l'id dello strumento. Seguono i file di input e le opzioni dello strumento. Ogni opzione di uno strumento è un flag, scritto con il nome del campo dell'API (--pageNumbers) o in kebab case (--page-numbers). Un numero negativo può seguire il suo flag dopo uno spazio, come in --rotation -90, oppure dopo un segno di uguale.

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

Usa pdfx list per vedere gli strumenti. Accetta --category o --group, e --query con le parole da cercare. Usa pdfx describe <tool> per vedere l'endpoint, gli input accettati, se lo strumento viene eseguito come lotto e ogni campo con il suo valore predefinito e i valori consentiti. Per un id di strumento sconosciuto vengono proposti dei suggerimenti, e se è scritto male il comando termina con il codice 2.

Quale comando corrisponde a quale pagina?#

Come elaboro molti file in una volta?#

Passa più file a uno strumento a file singolo e pdfx esegue un lotto. Usa -o con una cartella che termina con una barra. Lo strumento viene eseguito una volta per file, due file alla volta per impostazione predefinita. Puoi cambiarlo con --concurrency.

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

pdfx stampa una riga, input -> saved, man mano che ogni file termina. Un file che fallisce viene segnalato sullo standard error e gli altri file vengono comunque completati. Premi Ctrl-C una volta per interrompere la richiesta in corso; i file già salvati restano. Un secondo Ctrl-C esce subito con il codice 130. Con --idempotency-key k, ogni file invia k:<index>, e la ripetizione della stessa richiesta restituisce di nuovo il primo risultato per 24 ore.

Un lotto con uno strumento che restituisce un rapporto, come get-info, senza -o non scrive alcun file. Stampa i rapporti indicizzati per file di input.

Come concateno gli strumenti in una sola richiesta?#

pdfx pipeline esegue più strumenti in una sola richiesta. Ripeti --step per ogni strumento. Per impostare le opzioni, passa un array JSON con --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

I passaggi non possono usare strumenti che richiedono un secondo file.

Come apro i PDF protetti da password?#

--input-password apre prima tutti gli input cifrati. --password-for <file>=<password> imposta la password di un singolo file. Si può ripetere, e * come nome di file copre tutti gli altri. È adatto a un lotto che mescola file bloccati e aperti. Per merge e images-to-pdf, ogni file indicato viene sbloccato separatamente prima dell'esecuzione dello strumento.

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

Le stesse opzioni funzionano in una pipeline. Per rimuovere la protezione in modo permanente, usa lo strumento Sblocca con la sua opzione --password.

Come funzionano input e output?#

• Un input - legge lo standard input, una sola volta per esecuzione. -o - scrive il risultato sullo standard output.
• -o file.pdf scrive quel file. -o dir/ scrive in una cartella. Una cartella che non esiste ancora richiede la barra finale, perché un nome senza barra viene scritto come file.
• Senza -o, i risultati vanno nella cartella corrente con il nome di file scelto dal server.
• In una cartella, pdfx non sostituisce mai un file esistente; sceglie un nuovo nome. Un -o file.pdf esplicito sostituisce quel file.
• Un nome di file -o con un'estensione in contrasto con il risultato, per esempio uno ZIP di split salvato come .pdf, viene rifiutato con il codice di uscita 2 e code: output_mismatch. Non viene scritto nulla.
• Un output che non può essere scritto è un errore d'uso rilevato prima di caricare qualsiasi cosa.

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

Che cosa stampa --json?#

Per un risultato salvato, --json stampa il percorso, il tipo di contenuto e la dimensione. Uno strumento che restituisce un rapporto stampa il rapporto stesso. Un lotto stampa un unico rapporto con uno stato per ogni file.

{ "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 file fallito ha error e reason al posto di path e bytes. Uno strumento di filtro senza corrispondenza stampa { "matched": false }. pdfx list --json stampa righe con id, category, group, name, description, returns, files e filter.

Quali opzioni valgono per tutti gli strumenti?#

Quali sono i codici di uscita?#

I fallimenti stampano le righe reason:, code: e hint: quando il server le fornisce, così uno script può ramificare senza confrontare il testo. Uno strumento che non trova nulla da restituire, come pdf-to-csv su un PDF senza tabelle, termina con 1 e code: no_content invece di scrivere un file vuoto. I codici sono elencati in Codici di errore.

Come punto pdfx al mio server?#

Imposta PDFX_API_BASE, oppure passa --api-base, sull'indirizzo di un pdfx-server self-host. Aggiungi PDFX_API_KEY se il tuo server richiede una chiave. Vedi Self-host.

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

Come chiamo un endpoint che la CLI non conosce?#

pdfx call invia una richiesta grezza a un id di operazione o a un percorso /api/.... Usa --field name=value per i campi del modulo e --file field=path per i file aggiuntivi. Invia esattamente una richiesta e non valida nulla in locale, quindi password e lotti vengono rifiutati.

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

Pagine correlate#

• Panoramica per sviluppatori con l'API REST e l'autenticazione
• SDK TypeScript, la libreria su cui è costruita la riga di comando
• Server MCP per agenti IA
• L'articolo del blog "pdfx CLI: One Catalog, Called From Your Terminal" sul blog di PDF123

FAQ#

pdfx funziona offline?#

No. pdfx carica ogni file sull'API di PDF123 o sul tuo server e salva il risultato in locale, quindi la base dell'API deve essere raggiungibile.

pdfx richiede una chiave API?#

No. L'uso anonimo funziona. Imposta PDFX_API_KEY o passa --api-key se il tuo server ne richiede una. La chiave viene inviata nell'header X-API-KEY.

Quale versione di Node richiede pdfx?#

Node 20.3 o successivo, oppure Bun.

pdfx sovrascrive i miei file?#

Non quando scrive in una cartella: un file esistente non viene mai sostituito. Se dai tu il nome al file di output con -o file.pdf, quel file viene sostituito, quindi scegli un nome nuovo quando vuoi conservare l'originale.

Che cosa succede quando uno strumento di filtro non trova corrispondenze?#

Gli strumenti di filtro, i cui id iniziano con filter-, lasciano passare il file quando la loro condizione è soddisfatta. Quando non lo è, pdfx stampa no match e termina con il codice 0. In un lotto, un file del genere conta come non corrispondente, non come fallito.