Product3 мин чтения

CLI pdfx: один каталог, вызываемый из терминала

CLI pdfx отправляет те же multipart-запросы, что и curl, к API PDF123 или к вашему собственному pdfx-server, и добавляет пакетные запуски, пароли на файл и коды выхода для скриптов.

By the PDF123 team · Updated 2026-09-29
CLI pdfx: один каталог, вызываемый из терминала

PDF123 — это имя продукта. pdfx — тот же каталог операций, обёрнутый для командной строки: он собирает multipart-запрос, который собрал бы curl, отправляет его на выбранный базовый URL и записывает результат рядом с вашими файлами. Слияние, Сжатие, OCR и остальной каталог вызываются так же.

Что на самом деле отправляет вызов

pdfx --api-base "$API_BASE" --api-key "$PDFX_API_KEY" \
  merge a.pdf b.pdf -o merged.pdf

--api-base по умолчанию равен https://pdf123.xyz, а --api-key (или переменная окружения PDFX_API_KEY) необязателен, поэтому анонимный каталог работает без ключа. Укажите базой http://127.0.0.1:8080, если у вас свой стек docker-compose. Никакого второго протокола под этим нет: CLI — клиент REST-поверхности, описанной в разделе Разработчикам, а имена операций совпадают с инструментами портала и документом OpenAPI по адресу /v1/openapi.json.

Каталог можно изучать, не покидая терминал. pdfx list печатает все инструменты, а pdfx describe add-stamp — поля и значения по умолчанию одного инструмента; это то же определение, которое портал отрисовывает как форму.

Пакетные запуски и флаги, которые curl заставляет писать самому

Дайте инструменту для одного файла несколько входов, и он выполнит их пакетом в каталог -o, печатая по одной строке input -> saved на файл. Ошибки идут в stderr, а остальные файлы всё равно завершаются, поэтому один плохой PDF в папке счетов не прерывает запуск. --concurrency <n> задаёт, сколько файлов обрабатывается одновременно (по умолчанию 2).

-o принимает файл или каталог и никогда не перезаписывает существующий файл, а внутри каталога использует имя, которое дал сервер. Это важно, когда сервер называет результат по входному файлу: без такого правила запуск затёр бы PDF, который вы только что загрузили.

Зашифрованные входные файлы открываются до запроса, а не инструментом: --input-password покрывает все файлы запуска, а --password-for report.pdf=secret задаёт пароль одного файла и может повторяться, при этом * означает остальные. Пакету со смесью закрытых и открытых файлов не нужна ручная сортировка. --json печатает { path, contentType, bytes } на результат или [{ input, ok, path | error, reason }] для пакета, так что обёртка может разобрать исход, а не выскребать человекочитаемые строки.

Коды выхода, по которым скрипт может ветвиться

0 — успех, 1 — запрос не удался (в пакете: хотя бы один файл), 2 — ошибка использования, при которой ничего не загружено, 130 — вы прервали выполнение, и текущий запрос был отменён. Ошибки печатают строки reason:, code: и hint: под сообщением, когда они доступны, и скрипту стоит сопоставлять именно их, а не прозу.

Один код легко прочитать неправильно. Инструмент, которому нечего вернуть, завершается ненулевым кодом с code: no_content, вместо того чтобы записать пустой файл; поэтому pdf-to-csv на PDF без таблиц — это ошибка, а не CSV нулевого размера.

Куда уходят байты

Файлы загружаются на базовый URL, обрабатываются там и удаляются сразу после отправки ответа. Это тот же контракт, что и у формы в браузере: CLI меняет клиента, а не место назначения. Для документов, которые не должны покидать вашу сеть, запустите pdfx-server сами и направьте --api-base на него; это разобрано в разделе Self-host.

Офлайн-режима, на который можно откатиться, нет: если база недоступна, команда падает. pdfx — сетевой клиент, который просто приятен в командной строке, а не локальный движок PDF.

Чем CLI не является

pdfx — не настольный графический интерфейс и не встраиваемая библиотека OCR, которую можно слинковать с другим приложением. Это клиент командной строки для операций с PDF, поэтому разовую человеческую задачу всё ещё лучше решает портал (Сжатие, OCR и остальной каталог), а всё, чему нужна собственная UI-структура, воссоздало бы проблему расхождения, описанную в Одна операция, четыре клиента.

Агенты получают те же формы из опубликованного skill по адресу /skills/pdf123.md, где полностью описаны запросы merge и pipeline. Для безопасных повторов изменяющих POST отправляйте Idempotency-Key; CLI по-прежнему делает один запрос на вызов, поэтому заголовок принадлежит тому, кто повторяет (Idempotency-Key: безопасные повторные попытки для PDF-задач). Ключи, ограничения частоты и коды ошибок — в разделе Разработчикам.

Open tool
Process in the browser — no watermark, files removed after the job.
Open tool