pdfx CLI: önce yerel, gerektiğinde bulut
pdfx PDF’leri varsayılan olarak makinenizde işler. Barındırılan veya kendi PDF123 REST uç noktaları için API tabanı ve anahtarıyla bulut kipine geçin.
Ürünün adı PDF123’tür. pdfx, aynı işlemlerle konuşan kısa CLI’dır. Varsayılan yol yereldir: bir dosya okuyun, işlemi pdf-core üzerinden çalıştırın, bir çıktı yazın. Hesap yok, API anahtarı yok, yükleme yok.
Önce yerel: dosya makineden hiç çıkmaz
Tipik bir çağrı pdfx merge a.pdf b.pdf -o merged.pdf ya da pdfx compress input.pdf gibi görünür. İşleme, ikili dosyanın çalıştığı yerde gerçekleşir. Bu; özel bir çalıştırıcıdaki CI işlerine, bir fatura yığınının yanındaki betiklere ve üçüncü bir tarafa yüklemenin yanlış cevap olduğu her duruma uyar.
Yerel kip, baytları gizlice başka bir yere gönderen ince bir sarmalayıcı değildir. CLI, sunucuyla aynı işlem kayıt defterini paylaşır (pdf_core::ops::run). Ağ yolunu istiyorsanız --cloud ile açıkça geçersiniz.
Yerleşik alt komutlar yaygın işlemleri kapsar: merge, split, compress, rotate, extract, OCR, convert, protect, unlock, watermark ve ilgili işler. Yerel çıktı varsayılan olarak -o / --output ile bir dosyaya yazılır; - standart çıktıya yazar.
--cloud aynı kataloğu HTTP üzerinden açar
Barındırılan API’ye veya kendi pdfx-server’ınıza ihtiyaç duyduğunuzda --api-base ve --api-key (ya da PDFX_API_KEY) ile --cloud geçin. Bulut kipi arka planda curl gerektirir ve API anahtarı ayarlı değilse başarısız olur. Yayımlanan beceriden bir örnek:
pdfx --cloud --api-base "$PDFX_API_BASE" --api-key "$PDFX_API_KEY" \
merge a.pdf b.pdf -o merged.pdf
--api-base ayarlanmadığında https://pdf123.xyz, yani barındırılan API varsayılanına düşer. Yerel bir Docker Compose yığını için bunun yerine http://127.0.0.1:8080 adresini gösterin. CLI, Geliştiriciler sayfasında belgelenen REST yüzeyinin bir istemcisi hâline gelir; işlem adları portal araçlarıyla ve OpenAPI (/v1/openapi.json) ile hizalanır.
Bulut kipi bir işlemin anlamını değiştirmez. Compress yine qpdf akış sıkıştırmasıdır; OCR yine Rust yolu üzerinden aranabilir bir PDF katmanı değil Markdown metni döner. Java döneminden kalan ve yok sayılan OCR parametrelerine eşlenen artık CLI bayrakları (örneğin bir languages alanı) bu sözleşmeyi değiştirmez.
İki kip neden var
Yerel kip çevrimdışı güveni ve sıfır gidiş-dönüş maliyetini karşılar. Bulut kip ise paylaşılan hız sınırlarını, yalnızca CLI ve curl kurulu bir makinede işlem çalıştırmayı ve zaten API anahtarı veren ekipleri karşılar. Ajanlar aynı tabana /mcp adresindeki MCP ya da dist/skills/pdf-toolbox/SKILL.md adresindeki beceri üzerinden de erişebilir. /llms.txt gibi keşif dizinleri kodlama ajanlarının uç noktaları bulmasına yardım eder; bunlar bir Google sıralama sinyali değildir.
API’ye karşı değiştirici POST’ların güvenli yeniden denemeleri için Idempotency-Key gönderin (Idempotency-Key: PDF işleri için güvenli yeniden denemeler yazısına bakın). CLI’nın bulut yolu her çağrıda hâlâ tek bir HTTP isteğidir; sarmalayıcınız yeniden deniyorsa bu başlığı kullanın.
Pratikte kip seçmek
Dosyaların çalıştırıcıda kalması gerektiğinde, pdfx ikilisi ve yerel bağımlılıkları o makinede zaten bulunduğunda ve gecikmeye yükleme değil işlem hâkim olduğunda yerel kipi kullanın. Ağır bağımlılıklar yalnızca sunucuda yaşadığında, diğer API istemcileriyle aynı hız sınırlarını ve ölçümü istediğinizde ya da ajanlar https://pdf123.xyz veya kendi barındırdığınız taban için zaten bir API anahtarı taşıdığında bulut kipini kullanın.
Beklentileri karıştırmayın: yerel OCR yine misc/ocr-pdf işleminin Markdown çıktı sözleşmesine uyar; bulut compress yine qpdf akışlarıdır, yazı tipi alt kümeleme değil. Kip değişikliği işlemin nerede çalıştığını değiştirir, kataloğun anlamını değil.
CLI ne değildir
pdfx bir masaüstü GUI’si ve başka bir uygulamaya bağlayacağınız gömülebilir bir OCR kitaplığı değildir. PDF işlemleri için bir komut satırı istemcisidir: varsayılan olarak yerel, istediğinizde HTTP. Tarayıcıdan tek seferlik işler yine portalda yaşar (Compress, OCR ve kataloğun geri kalanı). İkili dosya tercih eden otomasyon pdfx üzerinde kalabilir.
Tarayıcı, curl, MCP ve CLI arasındaki aynı-işlem karşılaştırmaları Aynı işlem, dört istemci yazısında çizilir. Anahtarlar ve OpenAPI için Geliştiriciler sayfasından, API tabanının kendi Docker Compose yığınınız olması gerekiyorsa Self-host sayfasından başlayın.