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

Як запустити будь-який інструмент?#

Перший аргумент — ідентифікатор інструмента. Далі йдуть вхідні файли та параметри інструмента. Кожен параметр інструмента — це прапорець, який записують як назву поля API (--pageNumbers) або в kebab case (--page-numbers). Від’ємне число може йти після свого прапорця через пробіл, як-от --rotation -90, або після знака рівності.

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

Щоб побачити інструменти, виконайте pdfx list. Команда приймає --category або --group, а також --query зі словами для пошуку. Щоб побачити кінцеву точку, допустимі вхідні дані, чи працює інструмент пакетно, і кожне поле з типовим значенням та допустимими значеннями, виконайте pdfx describe <tool>. Для невідомого ідентифікатора інструмента показуються підказки, а помилково введений завершується з кодом 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

Ті самі параметри працюють і в конвеєрі. Щоб зняти захист назавжди, скористайтеся інструментом Зняти пароль з його власним параметром --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 }
  ]
}

У невдалого файла замість path і bytes є error і reason. Інструмент-фільтр без збігу виводить { "matched": false }. pdfx list --json виводить рядки з полями id, category, group, name, description, returns, files і filter.

Які параметри діють для кожного інструмента?#

Які є коди виходу?#

Збої виводять рядки reason:, code: і hint:, якщо їх надає сервер, тож скрипт може розгалужуватися, не порівнюючи текст. Інструмент, якому нічого повертати, наприклад pdf-to-csv для PDF без таблиць, завершується з кодом 1 і code: no_content замість запису порожнього файла. Коди перелічено на сторінці Коди помилок.

Як спрямувати pdfx на власний сервер?#

Задайте PDFX_API_BASE або передайте --api-base з адресою власного pdfx-server. Додайте PDFX_API_KEY, якщо ваш сервер вимагає ключ. Див. Self-host.

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

Як викликати кінцеву точку, якої 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 й автентифікацією
• TypeScript SDK — бібліотека, на якій побудовано командний рядок
• MCP-сервери для ШІ-агентів
• Допис «pdfx CLI: One Catalog, Called From Your Terminal» у блозі PDF123

FAQ#

Чи працює 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. У пакеті такий файл рахується як незбіглий, а не як невдалий.