pdfx CLI: първо локално, cloud само когато ви трябва

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

„Първо локално“ означава, че файлът не напуска машината

Типичното извикване изглежда така: pdfx merge a.pdf b.pdf -o merged.pdf или pdfx compress input.pdf. Обработката се изпълнява там, където работи изпълнимият файл. Това устройва CI задачи на частен runner, скриптове до пакет фактури и всеки случай, в който качването при трета страна е грешният отговор.

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

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

--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 повърхността, документирана в Developers; имената на операциите съвпадат с инструментите в портала и с OpenAPI (/v1/openapi.json).

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

Защо съществуват два режима

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

За безопасни повторни опити на POST заявки с промяна към API подавайте Idempotency-Key (вижте Idempotency-Key: безопасни повторни опити за PDF задачи). Облачният път на CLI пак прави по една HTTP заявка на извикване; използвайте заглавката, когато вашата обвивка повтаря.

Избор на режим на практика

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

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

Какво CLI не е

pdfx не е настолен графичен интерфейс и не е вграждаща се OCR библиотека, която да свържете в друго приложение. Той е клиент от командния ред за PDF операции: локално по подразбиране, HTTP, когато поискате. Еднократните задачи в браузъра още живеят в портала (Compress, OCR и останалите от каталога). Автоматизацията, която предпочита изпълним файл, може да остане на pdfx.

Сравненията на една и съща операция между браузър, curl, MCP и CLI са скицирани в Една и съща операция, четири клиента. Започнете от Developers за ключове и OpenAPI или от Self-host, ако базовият адрес на API трябва да е вашият собствен Docker Compose стек.