pdfx: η γραμμή εντολών του PDF123

Πώς εγκαθιστώ το pdfx;#

Εγκαταστήστε το πακέτο καθολικά για να αποκτήσετε την εντολή pdfx. Ή εκτελέστε το μία φορά χωρίς εγκατάσταση.

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

Τα bun add -g @pdf123/cli και pnpm add -g @pdf123/cli λειτουργούν επίσης. Δεν χρειάζεται να εγκαταστήσετε τίποτε άλλο.

Πώς ξεκινώ;#

Αυτές οι έξι εντολές δείχνουν τα συνηθισμένα μοτίβα.

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

Πώς εκτελώ οποιοδήποτε εργαλείο;#

Το πρώτο όρισμα είναι το αναγνωριστικό του εργαλείου. Ακολουθούν τα αρχεία εισόδου και οι επιλογές του εργαλείου. Κάθε επιλογή ενός εργαλείου είναι flag, γραμμένο με το όνομα πεδίου του API (--pageNumbers) ή σε kebab case (--page-numbers). Ένας αρνητικός αριθμός μπορεί να ακολουθεί το flag του μετά από κενό, όπως στο --rotation -90, ή μετά από σύμβολο ίσον.

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

Χρησιμοποιήστε το pdfx list για να δείτε τα εργαλεία. Δέχεται --category ή --group, και --query με λέξεις προς αναζήτηση. Χρησιμοποιήστε το pdfx describe <tool> για να δείτε το endpoint, τις αποδεκτές εισόδους, αν το εργαλείο εκτελείται ως παρτίδα, και κάθε πεδίο με την προεπιλογή και τις επιτρεπόμενες τιμές του. Ένα άγνωστο αναγνωριστικό εργαλείου παίρνει προτάσεις, και ένα με τυπογραφικό λάθος τερματίζει με κωδικό 2.

Ποιες εντολές αντιστοιχούν σε ποιες σελίδες εργαλείων;#

Πώς επεξεργάζομαι πολλά αρχεία ταυτόχρονα;#

Δώστε πολλά αρχεία σε ένα εργαλείο ενός αρχείου και το pdfx εκτελεί παρτίδα. Χρησιμοποιήστε το -o με κατάλογο που τελειώνει σε κάθετο. Το εργαλείο εκτελείται μία φορά ανά αρχείο, δύο αρχεία τη φορά από προεπιλογή. Αλλάξτε το με το --concurrency.

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

Το pdfx τυπώνει μία γραμμή, input -> saved, καθώς ολοκληρώνεται κάθε αρχείο. Ένα αρχείο που απέτυχε αναφέρεται στο τυπικό ρεύμα σφαλμάτων και τα υπόλοιπα αρχεία ολοκληρώνονται κανονικά. Πατήστε Ctrl-C μία φορά για να διακόψετε το αίτημα που βρίσκεται σε εξέλιξη· τα αρχεία που έχουν ήδη αποθηκευτεί διατηρούνται. Ένα δεύτερο Ctrl-C τερματίζει αμέσως με κωδικό 130. Με --idempotency-key k, κάθε αρχείο στέλνει k:<index>, και η επανάληψη του ίδιου αιτήματος επαναλαμβάνει το πρώτο αποτέλεσμα για 24 ώρες.

Μια παρτίδα εργαλείου που επιστρέφει αναφορά, όπως το get-info, δεν γράφει αρχεία χωρίς -o. Τυπώνει τις αναφορές ανά αρχείο εισόδου.

Πώς αλυσοδένω εργαλεία σε ένα αίτημα;#

Το pdfx pipeline εκτελεί πολλά εργαλεία σε ένα αίτημα. Επαναλάβετε το --step για κάθε εργαλείο. Για να ορίσετε επιλογές, περάστε έναν πίνακα JSON με το --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

Τα βήματα δεν μπορούν να χρησιμοποιούν εργαλεία που χρειάζονται δεύτερο αρχείο.

Πώς ανοίγω PDF που προστατεύονται με κωδικό;#

Το --input-password ανοίγει πρώτα κάθε κρυπτογραφημένη είσοδο. Το --password-for <file>=<password> ορίζει τον κωδικό ενός αρχείου. Μπορεί να επαναληφθεί, και το * ως όνομα αρχείου καλύπτει τα υπόλοιπα. Ταιριάζει σε παρτίδα που αναμειγνύει κλειδωμένα και ανοιχτά αρχεία. Για τα merge και images-to-pdf, κάθε αρχείο που κατονομάζεται ξεκλειδώνεται ξεχωριστά πριν εκτελεστεί το εργαλείο.

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

Οι ίδιες επιλογές λειτουργούν σε ένα pipeline. Για να αφαιρέσετε την προστασία μόνιμα, χρησιμοποιήστε το εργαλείο Αφαίρεση κωδικού με τη δική του επιλογή --password.

Πώς λειτουργούν η είσοδος και η έξοδος;#

• Μια είσοδος - διαβάζει την τυπική είσοδο, μία φορά ανά εκτέλεση. Το -o - γράφει το αποτέλεσμα στην τυπική έξοδο.
• Το -o file.pdf γράφει αυτό το αρχείο. Το -o dir/ γράφει μέσα σε κατάλογο. Ένας κατάλογος που δεν υπάρχει ακόμη χρειάζεται την τελική κάθετο, γιατί ένα όνομα χωρίς αυτήν γράφεται ως αρχείο.
• Χωρίς -o, τα αποτελέσματα πηγαίνουν στον τρέχοντα κατάλογο με το όνομα αρχείου του διακομιστή.
• Μέσα σε κατάλογο, το pdfx δεν αντικαθιστά ποτέ υπάρχον αρχείο· επιλέγει νέο όνομα. Ένα ρητό -o file.pdf αντικαθιστά αυτό το αρχείο.
• Ένα όνομα αρχείου -o με επέκταση που έρχεται σε αντίφαση με το αποτέλεσμα, όπως ένα ZIP από το split που αποθηκεύεται ως .pdf, απορρίπτεται με κωδικό εξόδου 2 και code: output_mismatch. Τίποτα δεν γράφεται.
• Μια έξοδος που δεν μπορεί να γραφτεί είναι σφάλμα χρήσης που εντοπίζεται πριν ανέβει οτιδήποτε.

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

Τι τυπώνει το --json;#

Για ένα αποθηκευμένο αποτέλεσμα, το --json τυπώνει τη διαδρομή, τον τύπο περιεχομένου και το μέγεθος. Ένα εργαλείο που επιστρέφει αναφορά τυπώνει την ίδια την αναφορά. Μια παρτίδα τυπώνει μία αναφορά με κατάσταση ανά αρχείο.

{ "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 }
  ]
}

Ένα αρχείο που απέτυχε έχει error και reason στη θέση των path και bytes. Ένα εργαλείο φίλτρου χωρίς αντιστοίχιση τυπώνει { "matched": false }. Το pdfx list --json τυπώνει γραμμές με id, category, group, name, description, returns, files και filter.

Ποιες επιλογές ισχύουν για κάθε εργαλείο;#

Ποιοι είναι οι κωδικοί εξόδου;#

Οι αποτυχίες τυπώνουν γραμμές reason:, code: και hint: όταν τις παρέχει ο διακομιστής, ώστε ένα script να διακλαδώνεται χωρίς να συγκρίνει κείμενο. Ένα εργαλείο που δεν βρίσκει τίποτα να επιστρέψει, όπως το pdf-to-csv σε PDF χωρίς πίνακες, τερματίζει με 1 και code: no_content αντί να γράψει κενό αρχείο. Οι κωδικοί παρατίθενται στους Κωδικούς σφαλμάτων.

Πώς κατευθύνω το pdfx στον δικό μου διακομιστή;#

Ορίστε το PDFX_API_BASE, ή περάστε το --api-base, στη διεύθυνση ενός pdfx-server που φιλοξενείτε μόνοι σας. Προσθέστε το PDFX_API_KEY αν ο διακομιστής σας απαιτεί κλειδί. Δείτε την Αυτοφιλοξενία.

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

Πώς εκτελώ ένα endpoint που το CLI δεν γνωρίζει;#

Το pdfx call στέλνει ανεπεξέργαστο αίτημα σε αναγνωριστικό λειτουργίας ή διαδρομή /api/.... Χρησιμοποιήστε το --field name=value για πεδία φόρμας και το --file field=path για πρόσθετα αρχεία. Στέλνει ακριβώς ένα αίτημα και δεν επικυρώνει τίποτα τοπικά, οπότε οι κωδικοί και οι παρτίδες απορρίπτονται.

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

Σχετικές σελίδες#

• Επισκόπηση για προγραμματιστές, με το REST API και την ταυτοποίηση
• SDK TypeScript, η βιβλιοθήκη πάνω στην οποία είναι χτισμένη η γραμμή εντολών
• Διακομιστές MCP για πράκτορες AI
• Το άρθρο «pdfx CLI: One Catalog, Called From Your Terminal» στο ιστολόγιο του PDF123

Συχνές ερωτήσεις#

Λειτουργεί το pdfx εκτός σύνδεσης;#

Όχι. Το pdfx ανεβάζει κάθε αρχείο στο API του PDF123 ή στον δικό σας διακομιστή και αποθηκεύει το αποτέλεσμα τοπικά, οπότε η βάση του API πρέπει να είναι προσβάσιμη.

Χρειάζεται το pdfx κλειδί API;#

Όχι. Λειτουργεί ανώνυμα. Ορίστε το PDFX_API_KEY ή περάστε το --api-key αν ο διακομιστής σας απαιτεί κλειδί. Το κλειδί στέλνεται ως κεφαλίδα X-API-KEY.

Ποια έκδοση του Node χρειάζεται το pdfx;#

Node 20.3 ή νεότερο, ή Bun.

Θα αντικαταστήσει το pdfx τα αρχεία μου;#

Όχι όταν γράφει μέσα σε κατάλογο: ένα υπάρχον αρχείο δεν αντικαθίσταται ποτέ. Αν ονομάσετε εσείς το αρχείο εξόδου με -o file.pdf, το αρχείο αυτό αντικαθίσταται, οπότε επιλέξτε νέο όνομα όταν θέλετε να κρατήσετε το πρωτότυπο.

Τι συμβαίνει όταν ένα εργαλείο φίλτρου δεν βρίσκει αντιστοίχιση;#

Τα εργαλεία φίλτρου, με αναγνωριστικά που αρχίζουν με filter-, προωθούν το αρχείο όταν ισχύει η συνθήκη τους. Όταν δεν ισχύει, το pdfx τυπώνει no match και τερματίζει με κωδικό 0. Σε παρτίδα, ένα τέτοιο αρχείο μετρά ως χωρίς αντιστοίχιση, όχι ως αποτυχημένο.