pdfx: wiersz poleceń PDF123

Jak zainstalować pdfx?#

Zainstaluj pakiet globalnie, aby dostać polecenie pdfx. Możesz też uruchomić je jednorazowo bez instalacji.

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 i pnpm add -g @pdf123/cli również działają. Nie trzeba instalować niczego więcej.

Jak zacząć?#

Tych sześć poleceń pokazuje typowe wzorce użycia.

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

Jak uruchomić dowolne narzędzie?#

Pierwszy argument to identyfikator narzędzia. Dalej podajesz pliki wejściowe i opcje narzędzia. Każda opcja narzędzia jest flagą zapisaną jako nazwa pola API (--pageNumbers) lub w notacji kebab-case (--page-numbers). Liczba ujemna może następować po fladze po spacji, jak w --rotation -90, lub po znaku równości.

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

Narzędzia wyświetlisz poleceniem pdfx list. Przyjmuje ono --category lub --group oraz --query ze słowami do wyszukania. Poleceniem pdfx describe <tool> zobaczysz endpoint, akceptowane wejścia, informację, czy narzędzie działa jako partia, oraz każde pole z wartością domyślną i dozwolonymi wartościami. Dla nieznanego identyfikatora narzędzia wyświetlane są podpowiedzi, a literówka kończy działanie kodem 2.

Które polecenia odpowiadają którym stronom narzędzi?#

Jak przetworzyć wiele plików naraz?#

Podaj kilka plików narzędziu jednoplikowemu, a pdfx uruchomi partię. Użyj -o z katalogiem zakończonym ukośnikiem. Narzędzie działa raz na plik, domyślnie po dwa pliki naraz. Zmienisz to opcją --concurrency.

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

pdfx wypisuje jedną linię, input -> saved, gdy tylko skończy każdy plik. Plik, który się nie powiódł, jest zgłaszany na standardowym wyjściu błędów, a pozostałe pliki nadal są dokańczane. Naciśnij Ctrl-C raz, aby przerwać żądanie w toku; już zapisane pliki zostają. Drugie Ctrl-C kończy działanie natychmiast kodem 130. Z --idempotency-key k każdy plik wysyła k:<index>, a powtórzenie tego samego żądania przez 24 godziny zwraca pierwszy wynik.

Partia narzędzia zwracającego raport, takiego jak get-info, bez -o nie zapisuje żadnych plików. Wypisuje raporty pogrupowane według pliku wejściowego.

Jak połączyć narzędzia w jednym żądaniu?#

pdfx pipeline uruchamia kilka narzędzi w jednym żądaniu. Powtórz --step dla każdego narzędzia. Aby ustawić opcje, przekaż tablicę JSON w --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

Kroki nie mogą używać narzędzi, które wymagają drugiego pliku.

Jak otworzyć pliki PDF chronione hasłem?#

--input-password najpierw otwiera każde zaszyfrowane wejście. --password-for <file>=<password> ustawia hasło jednego pliku. Można go powtarzać, a * w miejscu nazwy pliku obejmuje pozostałe. To dobre rozwiązanie dla partii mieszającej pliki zablokowane i otwarte. Dla merge i images-to-pdf każdy wskazany plik jest odblokowywany osobno przed uruchomieniem narzędzia.

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

Te same opcje działają w potoku. Aby trwale usunąć ochronę, użyj narzędzia Odblokuj z jego własną opcją --password.

Jak działają wejście i wyjście?#

• Wejście - czyta standardowe wejście, raz na uruchomienie. -o - zapisuje wynik na standardowe wyjście.
• -o file.pdf zapisuje ten plik. -o dir/ zapisuje do katalogu. Katalog, który jeszcze nie istnieje, wymaga końcowego ukośnika, bo nazwa bez niego jest zapisywana jako plik.
• Bez -o wyniki trafiają do bieżącego katalogu pod nazwą pliku nadaną przez serwer.
• W katalogu pdfx nigdy nie zastępuje istniejącego pliku; wybiera nową nazwę. Jawne -o file.pdf zastępuje ten plik.
• Nazwa pliku w -o, której rozszerzenie przeczy wynikowi, na przykład ZIP z split zapisany jako .pdf, jest odrzucana z kodem wyjścia 2 i code: output_mismatch. Nic nie zostaje zapisane.
• Wynik, którego nie da się zapisać, to błąd użycia wykrywany przed wysłaniem czegokolwiek.

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

Co wypisuje --json?#

Dla zapisanego wyniku --json wypisuje ścieżkę, typ zawartości i rozmiar. Narzędzie zwracające raport wypisuje sam raport. Partia wypisuje jeden raport ze statusem dla każdego pliku.

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

Plik, który się nie powiódł, ma error i reason zamiast path i bytes. Narzędzie filtrujące bez dopasowania wypisuje { "matched": false }. pdfx list --json wypisuje wiersze z polami id, category, group, name, description, returns, files i filter.

Które opcje dotyczą każdego narzędzia?#

Jakie są kody wyjścia?#

Przy błędach wypisywane są linie reason:, code: i hint:, jeśli serwer je poda, więc skrypt może rozgałęziać logikę bez dopasowywania tekstu. Narzędzie, które nie ma nic do zwrócenia, na przykład pdf-to-csv dla PDF-a bez tabel, kończy się kodem 1 z code: no_content zamiast zapisywać pusty plik. Kody wymieniono na stronie Kody błędów.

Jak skierować pdfx na własny serwer?#

Ustaw PDFX_API_BASE lub przekaż --api-base z adresem samodzielnie hostowanego pdfx-server. Jeśli Twój serwer wymaga klucza, dodaj PDFX_API_KEY. Zobacz Self-host.

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

Jak wywołać endpoint, którego CLI nie zna?#

pdfx call wysyła surowe żądanie do identyfikatora operacji lub ścieżki /api/.... Użyj --field name=value dla pól formularza i --file field=path dla dodatkowych plików. Wysyła dokładnie jedno żądanie i niczego nie waliduje lokalnie, więc hasła i partie są odrzucane.

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

Powiązane strony#

• Przegląd dla deweloperów z API REST i uwierzytelnianiem
• SDK TypeScript, biblioteka, na której zbudowano wiersz poleceń
• Serwery MCP dla agentów AI
• Wpis „pdfx CLI: One Catalog, Called From Your Terminal” na blogu PDF123

FAQ#

Czy pdfx działa offline?#

Nie. pdfx wysyła każdy plik do API PDF123 lub na Twój własny serwer i zapisuje wynik lokalnie, więc adres bazowy API musi być osiągalny.

Czy pdfx wymaga klucza API?#

Nie. Użycie anonimowe działa. Ustaw PDFX_API_KEY lub przekaż --api-key, jeśli Twój serwer tego wymaga. Klucz jest wysyłany w nagłówku X-API-KEY.

Jakiej wersji Node wymaga pdfx?#

Node 20.3 lub nowszego albo Bun.

Czy pdfx nadpisze moje pliki?#

Nie, gdy zapisuje do katalogu: istniejący plik nigdy nie jest zastępowany. Jeśli sam nazwiesz plik wyjściowy przez -o file.pdf, ten plik zostanie zastąpiony, więc wybierz nową nazwę, gdy chcesz zachować oryginał.

Co się dzieje, gdy narzędzie filtrujące nie znajdzie dopasowania?#

Narzędzia filtrujące, których identyfikatory zaczynają się od filter-, przepuszczają plik, gdy ich warunek jest spełniony. Gdy nie jest, pdfx wypisuje no match i kończy działanie kodem 0. W partii taki plik liczy się jako niedopasowany, a nie jako nieudany.