CLI pdfx: сначала локально, облако — когда нужно

PDF123 — это имя продукта. pdfx — короткий CLI, который обращается к тем же операциям. Путь по умолчанию локальный: прочитать файл, выполнить операцию через pdf-core, записать результат. Ни аккаунта, ни API-ключа, ни загрузки.

Сначала локально — значит, файл никуда не уходит

Типичный вызов выглядит как pdfx merge a.pdf b.pdf -o merged.pdf или pdfx compress input.pdf. Обработка идёт там, где запущен бинарник. Это подходит для задач CI на приватном раннере, скриптов рядом с пачкой счетов и любого случая, когда загрузка к третьей стороне — неправильный ответ.

Локальный режим — не тонкая обёртка, которая втайне отправляет байты куда-то ещё. CLI использует тот же реестр операций, что и сервер (pdf_core::ops::run). Если нужен сетевой путь, вы включаете его явно через --cloud.

Встроенные подкоманды покрывают обычные операции: merge, split, compress, rotate, extract, OCR, convert, protect, unlock, watermark и родственные. Локальный вывод по умолчанию пишется в файл через -o / --output; - пишет в stdout.

--cloud — тот же каталог по HTTP

Когда нужен хостинговый API (или ваш собственный pdfx-server), передайте --cloud с --api-base и --api-key (или PDFX_API_KEY). Облачный режим требует curl внутри и падает, если API-ключ не задан. Пример из опубликованного skill:

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

--api-base по умолчанию равен https://pdf123.xyz, то есть хостинговому API. Для локального стека Docker Compose укажите http://127.0.0.1:8080. CLI становится клиентом REST-поверхности, описанной в разделе Разработчикам; имена операций совпадают с инструментами портала и OpenAPI (/v1/openapi.json).

Облачный режим не меняет того, что операция означает. Compress — по-прежнему потоковое сжатие qpdf; OCR по-прежнему возвращает текст Markdown из Rust-пути, а не слой поиска в PDF. Оставшиеся флаги CLI, которые отображаются на игнорируемые параметры OCR эпохи Java (например, поле languages), этот контракт не меняют.

Зачем нужны два режима

Локальный покрывает доверие в офлайне и отсутствие затрат на сетевой круг. Облачный покрывает общие ограничения частоты, запуск операций на машине, где установлены только CLI и curl, и команды, которые уже выдают API-ключи. Агенты также могут обращаться к тому же базовому URL через MCP на /mcp или через skill dist/skills/pdf-toolbox/SKILL.md. Индексы обнаружения вроде /llms.txt помогают агентам-программистам находить эндпоинты; они не сигнал ранжирования в Google.

Для безопасных повторных попыток изменяющих POST-запросов к API отправляйте Idempotency-Key (см. Idempotency-Key: безопасные повторные попытки для PDF-задач). Облачный путь CLI — по-прежнему один HTTP-запрос на вызов; используйте заголовок, когда ваша обёртка повторяет попытку.

Как выбрать режим на практике

Используйте локальный, когда файлы должны оставаться на раннере, когда на этой машине уже есть бинарник pdfx и нативные зависимости и когда задержку определяет операция, а не загрузка. Используйте облачный, когда тяжёлые зависимости есть только на сервере, когда нужны те же ограничения частоты и учёт, что у других клиентов API, или когда у агентов уже есть API-ключ для https://pdf123.xyz или вашего собственного базового URL.

Не смешивайте ожидания: локальный OCR по-прежнему следует контракту вывода Markdown из misc/ocr-pdf; облачный compress — по-прежнему потоки qpdf, а не подрезание шрифтов. Переключатель режима меняет то, где выполняется операция, а не смысл каталога.

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

pdfx — не настольный графический интерфейс и не встраиваемая библиотека OCR, которую можно слинковать с другим приложением. Это клиент командной строки для операций с PDF: локальный по умолчанию, HTTP по запросу. Разовые задачи в браузере по-прежнему живут на портале (Сжатие, OCR и остальной каталог). Автоматизация, предпочитающая бинарник, может оставаться на pdfx.

Сравнения одной операции между браузером, curl, MCP и CLI набросаны в статье Одна операция, четыре клиента. Начните с Разработчикам ради ключей и OpenAPI или с Self-host, если базовым URL API должен быть ваш собственный стек Docker Compose.