CLI pdfx: спершу локально, хмара — коли потрібна
pdfx обробляє PDF на вашій машині типово. Хмарний режим вмикається базовою адресою API й ключем, коли потрібні хмарні або власні кінцеві точки REST від PDF123.
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.
Вбудовані підкоманди покривають поширені операції: об’єднання, розділення, стиснення, обертання, витягування, OCR, конвертацію, захист, розблокування, водяні знаки та споріднену роботу. Локальний результат типово пишеться у файл через -o / --output; - виводить у стандартний потік.
--cloud — це той самий каталог через HTTP
Коли потрібен хмарний API (або ваш власний pdfx-server), додайте --cloud разом із --api-base і --api-key (або PDFX_API_KEY). Хмарний режим під капотом потребує curl і завершується помилкою, якщо ключ API не задано. Приклад із опублікованої навички:
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).
Хмарний режим не змінює того, що означає операція. Стиснення й далі є стисненням потоків qpdf; OCR і далі повертає текст Markdown із Rust-шляху, а не шар пошуку в PDF. Залишкові прапорці CLI, які відповідають проігнорованим параметрам OCR доби Java (наприклад, поле languages), цього контракту не змінюють.
Чому існують два режими
Локальний покриває довіру в офлайні та нульову вартість зворотного шляху. Хмарний покриває спільні обмеження швидкості, запуск операцій на машині, де встановлено лише CLI та curl, і команди, які вже видають ключі API. Агенти також можуть звертатися до тієї самої базової адреси через MCP на /mcp або через навичку в dist/skills/pdf-toolbox/SKILL.md. Покажчики виявлення на кшталт /llms.txt допомагають агентам-програмістам знаходити кінцеві точки; сигналом позицій у Google вони не є.
Для безпечних повторних спроб операцій POST, що змінюють стан, надсилайте Idempotency-Key (див. Idempotency-Key: безпечні повторні спроби для завдань PDF). Хмарний шлях CLI — це й далі один HTTP-запит на виклик; використовуйте заголовок, коли ваша обгортка повторює спробу.
Як вибрати режим на практиці
Обирайте локальний, коли файли мусять лишатися на раннері, коли на тій машині вже є бінарник pdfx і рідні залежності та коли затримку визначає сама операція, а не завантаження. Обирайте хмарний, коли важкі залежності є лише на сервері, коли потрібні ті самі обмеження швидкості й облік, що й в інших клієнтів API, або коли агенти вже мають ключ API для https://pdf123.xyz чи вашої базової адреси на власному хостингу.
Не змішуйте очікувань: локальний OCR і далі дотримується контракту виводу Markdown від misc/ocr-pdf; хмарне стиснення — це й далі потоки qpdf, а не субсетування шрифтів. Перемикання режиму змінює місце виконання операції, а не семантику каталогу.
Чим CLI не є
pdfx — не настільний графічний інтерфейс і не OCR-бібліотека, яку вбудовують у інший застосунок. Це клієнт командного рядка для операцій із PDF: локальний типово, HTTP — коли попросите. Разові задачі у браузері й далі живуть на порталі (Стиснути, OCR та решта каталогу). Автоматизація, якій зручніше мати бінарник, може лишатися на pdfx.
Порівняння тієї самої операції у браузері, curl, MCP і CLI окреслено в статті Та сама операція, чотири клієнти. Почніть із Розробникам для ключів і OpenAPI або зі сторінки Власний хостинг, якщо базовою адресою API має бути ваш власний стек Docker Compose.