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-регистре (--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 и аутентификация
• SDK для TypeScript — библиотека, на которой построена командная строка
• MCP-серверы для ИИ-агентов
• Запись «CLI pdfx: один каталог, вызываемый из терминала» в блоге 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. В пакете такой файл считается не совпавшим, а не завершившимся ошибкой.