CLI pdfx: najpierw lokalnie, chmura wtedy, gdy jej potrzebujesz
pdfx domyślnie przetwarza PDF-y na twoim komputerze. Tryb chmurowy z adresem bazowym i kluczem API włączasz tylko wtedy, gdy potrzebujesz zdalnych operacji.
PDF123 to nazwa produktu. pdfx to krótkie narzędzie wiersza poleceń, które wykonuje te same operacje. Domyślna ścieżka jest lokalna: odczytuje plik, uruchamia operację przez pdf-core i zapisuje wynik. Bez konta, bez klucza API, bez przesyłania pliku.
Tryb lokalny oznacza, że plik nigdzie nie wyjeżdża
Typowe wywołanie wygląda tak: pdfx merge a.pdf b.pdf -o merged.pdf albo pdfx compress input.pdf. Przetwarzanie odbywa się tam, gdzie działa plik wykonywalny. Pasuje to do zadań CI na prywatnym serwerze runnera, skryptów leżących obok partii faktur i każdej sytuacji, w której wysyłanie pliku osobie trzeciej jest złą odpowiedzią.
Tryb lokalny nie jest cienką nakładką, która po cichu wysyła bajty gdzie indziej. CLI korzysta z tego samego rejestru operacji co serwer (pdf_core::ops::run). Jeśli chcesz ścieżki sieciowej, włączasz ją flagą --cloud.
Wbudowane podpolecenia pokrywają typowe operacje: scalanie, dzielenie, kompresję, obrót, wyodrębnianie, OCR, konwersję, zabezpieczanie hasłem, odblokowanie, znak wodny i pokrewne. Lokalny wynik domyślnie trafia do pliku przez -o / --output; - zapisuje na standardowe wyjście.
--cloud to ten sam katalog przez HTTP
Gdy potrzebujesz hostowanego API (albo własnego pdfx-server), podaj --cloud wraz z --api-base i --api-key (lub PDFX_API_KEY). Tryb chmurowy pod spodem wymaga curl i kończy się błędem, jeśli nie ustawiono klucza API. Przykład z opublikowanego skilla:
pdfx --cloud --api-base "$PDFX_API_BASE" --api-key "$PDFX_API_KEY" \
merge a.pdf b.pdf -o merged.pdf
Gdy --api-base nie zostanie podane, domyślnie przyjmuje https://pdf123.xyz, czyli hostowane API. Przy lokalnym stosie Docker Compose wskaż http://127.0.0.1:8080. CLI staje się klientem interfejsu REST opisanego na stronie Dla programistów; nazwy operacji pokrywają się z narzędziami portalu i OpenAPI (/v1/openapi.json).
Tryb chmurowy nie zmienia tego, co operacja oznacza. Compress to nadal kompresja strumieni przez qpdf; OCR nadal zwraca tekst Markdown ze ścieżki w Rust, a nie przeszukiwalną warstwę PDF. Pozostałe flagi CLI odpowiadające ignorowanym parametrom OCR z epoki Javy (na przykład pole languages) nie zmieniają tego kontraktu.
Dlaczego istnieją dwa tryby
Tryb lokalny odpowiada za zaufanie offline i zerowy koszt rundy przez sieć. Tryb chmurowy obsługuje wspólne limity tempa, uruchamianie operacji na maszynie, na której jest tylko CLI i curl, oraz zespoły, które już wydają klucze API. Agenci mogą też sięgać do tej samej bazy przez MCP pod /mcp albo przez skill w dist/skills/pdf-toolbox/SKILL.md. Indeksy odkrywania, takie jak /llms.txt, pomagają agentom kodującym znaleźć punkty końcowe; nie są sygnałem pozycji w Google.
Bezpieczne ponawianie mutujących żądań POST do API wymaga nagłówka Idempotency-Key (zobacz Idempotency-Key: bezpieczne ponawianie zadań PDF). Ścieżka chmurowa CLI to nadal jedno żądanie HTTP na wywołanie; użyj tego nagłówka, gdy twoja nakładka ponawia próbę.
Wybór trybu w praktyce
Wybierz tryb lokalny, gdy pliki muszą zostać na maszynie runnera, gdy masz już tam plik pdfx i natywne zależności oraz gdy czas odpowiedzi zależy od samej operacji, a nie od przesyłania pliku. Wybierz tryb chmurowy, gdy ciężkie zależności są tylko na serwerze, gdy chcesz takich samych limitów tempa i rozliczania jak inni klienci API albo gdy agenci mają już klucz API do https://pdf123.xyz lub do twojej instalacji self-hosted.
Nie mieszaj oczekiwań: lokalny OCR nadal działa zgodnie z kontraktem wyjścia Markdown z misc/ocr-pdf, a chmurowa kompresja to nadal strumienie qpdf, a nie zawężanie fontów. Przełączenie trybu zmienia to, gdzie operacja się wykonuje, a nie znaczenie katalogu.
Czym CLI nie jest
pdfx to nie graficzna aplikacja desktopowa ani biblioteka OCR, którą można osadzić w innym programie. To klient wiersza poleceń do operacji na PDF: domyślnie lokalny, przez HTTP, gdy o to poprosisz. Jednorazowe zadania w przeglądarce nadal mają miejsce w portalu (Compress, OCR i reszta katalogu). Automatyzacja, która woli plik wykonywalny, może zostać przy pdfx.
Porównanie tej samej operacji w przeglądarce, przez curl, MCP i CLI szkicuje Ta sama operacja, cztery klienty. Klucze i OpenAPI znajdziesz u Dla programistów, a jeśli adresem bazowym API ma być własny stos Docker Compose, zacznij od Self-host.