pdfx: PDF123 komut satırı

pdfx'i nasıl kurarım?#

pdfx komutunu almak için paketi genel olarak kurun. Ya da kurmadan bir kez çalıştırın.

npm install -g @pdf123/cli
pdfx --version

npx @pdf123/cli merge a.pdf b.pdf -o merged.pdf
bunx @pdf123/cli merge a.pdf b.pdf -o merged.pdf

bun add -g @pdf123/cli ve pnpm add -g @pdf123/cli de çalışır. Başka hiçbir şeyin kurulması gerekmez.

Nasıl başlarım?#

Bu altı komut yaygın kullanım biçimlerini gösterir.

pdfx list                                          # every tool; --category security for one category
pdfx describe watermark                            # a tool's fields and defaults
pdfx merge a.pdf b.pdf -o merged.pdf
pdfx compress *.pdf -o compressed/                 # several files: one result per file
pdfx watermark in.pdf --watermarkText DRAFT
pdfx pipeline a.pdf b.pdf --step merge --step compress -o out.pdf

Herhangi bir aracı nasıl çalıştırırım?#

İlk bağımsız değişken araç kimliğidir. Girdi dosyaları ve aracın seçenekleri onu izler. Bir aracın her seçeneği bir bayraktır; API alan adıyla (--pageNumbers) ya da kebab-case ile (--page-numbers) yazılır. Negatif bir sayı, --rotation -90 gibi bayrağından sonra boşlukla ya da eşittir işaretiyle gelebilir.

pdfx <tool> [files...] [--<field> <value>]...

Araçları görmek için pdfx list kullanın. --category veya --group ile --query ve aranacak sözcükleri kabul eder. Uç noktayı, kabul edilen girdileri, aracın toplu çalışıp çalışmadığını ve her alanı varsayılanı ve izin verilen değerleriyle görmek için pdfx describe <tool> kullanın. Bilinmeyen bir araç kimliği için öneriler gösterilir; yanlış yazılmış bir kimlik 2 koduyla çıkar.

Hangi komut hangi araç sayfasına karşılık gelir?#

Birçok dosyayı aynı anda nasıl işlerim?#

Tek dosyalı bir araca birkaç dosya verirseniz pdfx toplu işlem çalıştırır. -o ile sonu eğik çizgiyle biten bir dizin kullanın. Araç dosya başına bir kez çalışır; varsayılan olarak aynı anda iki dosya işlenir. Bunu --concurrency ile değiştirebilirsiniz.

pdfx compress *.pdf -o compressed/
pdfx protect *.pdf --password secret --concurrency 4 -o locked/

pdfx, her dosya bittiğinde input -> saved biçiminde tek bir satır yazdırır. Başarısız bir dosya standart hataya bildirilir ve diğer dosyalar yine de tamamlanır. Uçuştaki isteği iptal etmek için Ctrl-C tuşlarına bir kez basın; kaydedilmiş dosyalar korunur. İkinci Ctrl-C, 130 koduyla hemen çıkar. --idempotency-key k ile her dosya k:<index> gönderir ve aynı isteğin tekrarı 24 saat boyunca ilk sonucu yeniden verir.

get-info gibi rapor döndüren bir aracın toplu işlemi, -o olmadan hiçbir dosya yazmaz. Raporları girdi dosyasına göre anahtarlanmış olarak yazdırır.

Araçları tek istekte nasıl zincirlerim?#

pdfx pipeline birkaç aracı tek istekte çalıştırır. Her araç için --step bayrağını tekrarlayın. Seçenek vermek için --steps ile bir JSON dizisi geçin.

pdfx pipeline a.pdf b.pdf --step merge --step compress -o out.pdf
pdfx pipeline in.pdf --steps '[{"tool":"watermark","params":{"watermarkText":"DRAFT"}},{"tool":"compress"}]' -o out.pdf

Adımlarda ikinci bir dosya isteyen araçlar kullanılamaz.

Parola korumalı PDF'leri nasıl açarım?#

--input-password şifreli her girdiyi önce açar. --password-for <file>=<password> tek bir dosyanın parolasını belirler. Tekrarlanabilir ve dosya adı yerine * yazmak geri kalanını kapsar. Bu, kilitli ve açık dosyaların karıştığı toplu işlemlere uygundur. merge ve images-to-pdf için adı verilen her dosyanın kilidi, araç çalışmadan önce ayrı ayrı açılır.

pdfx compress locked.pdf --input-password secret -o out.pdf
pdfx compress report.pdf --password-for report.pdf=secret -o out.pdf
pdfx merge a.pdf b.pdf --password-for a.pdf=secret -o merged.pdf

Aynı seçenekler pipeline içinde de çalışır. Korumayı kalıcı olarak kaldırmak için kendi --password seçeneği olan Kilidi aç aracını kullanın.

Girdi ve çıktı nasıl çalışır?#

• - girdisi standart girdiyi okur ve çalıştırma başına bir kez kullanılır. -o - sonucu standart çıktıya yazar.
• -o file.pdf o dosyayı yazar. -o dir/ bir dizinin içine yazar. Henüz var olmayan bir dizin için sondaki eğik çizgi gerekir; çünkü eğik çizgisiz bir ad dosya olarak yazılır.
• -o olmadan sonuçlar, sunucunun verdiği dosya adıyla geçerli dizine gider.
• Bir dizine yazarken pdfx var olan bir dosyanın yerine yazmaz; yeni bir ad seçer. Açıkça verilen -o file.pdf o dosyanın yerine yazar.
• Uzantısı sonuçla çelişen bir -o dosya adı, örneğin split çıktısı olan bir ZIP'in .pdf olarak kaydedilmesi, 2 çıkış koduyla ve code: output_mismatch ile reddedilir. Hiçbir şey yazılmaz.
• Yazılamayan bir çıktı, herhangi bir şey yüklenmeden önce bulunan bir kullanım hatasıdır.

cat in.pdf | pdfx compress - -o - > out.pdf

--json ne yazdırır?#

Kaydedilmiş bir sonuç için --json yolu, içerik türünü ve boyutu yazdırır. Rapor döndüren bir araç raporun kendisini yazdırır. Toplu işlem, dosya başına durum içeren tek bir rapor yazdırır.

{ "path": "one.pdf", "contentType": "application/pdf", "bytes": 1040 }

{
  "processed": 2,
  "unmatched": 0,
  "failed": 0,
  "files": [
    { "input": "/abs/a.pdf", "ok": true, "path": "comp/a.pdf", "contentType": "application/pdf", "bytes": 1040 }
  ]
}

Başarısız bir dosyada path ve bytes yerine error ve reason bulunur. Eşleşmeyen bir filtre aracı { "matched": false } yazdırır. pdfx list --json, id, category, group, name, description, returns, files ve filter alanlı satırlar yazdırır.

Her araç için geçerli seçenekler hangileri?#

Çıkış kodları nelerdir?#

Başarısızlıklar, sunucu sağladığında reason:, code: ve hint: satırlarını yazdırır; böylece bir betik metin eşleştirmeden dallanabilir. Döndürecek bir şey bulamayan bir araç, örneğin tablosu olmayan bir PDF üzerinde pdf-to-csv, boş dosya yazmak yerine 1 koduyla ve code: no_content ile çıkar. Kodlar Hata kodları sayfasında listelenir.

pdfx'i kendi sunucuma nasıl yönlendiririm?#

PDFX_API_BASE değişkenini ya da --api-base seçeneğini, kendi barındırdığınız pdfx-server adresine ayarlayın. Sunucunuz anahtar istiyorsa PDFX_API_KEY ekleyin. Bkz. Self-host.

export PDFX_API_BASE=http://localhost:8080
export PDFX_API_KEY=<your-key>
pdfx compress in.pdf

CLI'nin tanımadığı bir uç noktayı nasıl çalıştırırım?#

pdfx call, bir işlem kimliğine ya da /api/... yoluna ham istek gönderir. Form alanları için --field name=value, ek dosyalar için --file field=path kullanın. Tam olarak bir istek gönderir ve yerelde hiçbir şeyi doğrulamaz; bu yüzden parolalar ve toplu işlemler reddedilir.

pdfx call general/merge-pdfs a.pdf b.pdf -o merged.pdf
pdfx call /api/v1/misc/flatten in.pdf --field flattenOnlyForms=true -o flat.pdf

İlgili sayfalar#

• REST API ve kimlik doğrulamayı anlatan Geliştiriciler genel bakış
• Komut satırının üzerine kurulu olduğu kitaplık, TypeScript SDK
• Yapay zekâ ajanları için MCP sunucuları
• PDF123 blogundaki "pdfx CLI: One Catalog, Called From Your Terminal" yazısı

SSS#

pdfx çevrimdışı çalışır mı?#

Hayır. pdfx her dosyayı PDF123 API'sine ya da kendi sunucunuza yükler ve sonucu yerel olarak kaydeder; bu yüzden API tabanına erişilebilir olmalıdır.

pdfx için API anahtarı gerekir mi?#

Hayır. Anonim kullanım çalışır. Sunucunuz anahtar istiyorsa PDFX_API_KEY değişkenini ayarlayın veya --api-key verin. Anahtar X-API-KEY başlığı olarak gönderilir.

pdfx hangi Node sürümünü gerektirir?#

Node 20.3 veya üstü ya da Bun.

pdfx dosyalarımın üzerine yazar mı?#

Bir dizine yazarken yazmaz: var olan dosyanın yerine hiçbir zaman yazılmaz. Çıktı dosyasını -o file.pdf ile kendiniz adlandırırsanız o dosyanın yerine yazılır; bu yüzden aslını korumak istediğinizde yeni bir ad seçin.

Bir filtre aracı eşleşme bulamazsa ne olur?#

Kimliği filter- ile başlayan filtre araçları, koşulları sağlandığında dosyayı olduğu gibi geçirir. Sağlanmadığında pdfx no match yazdırır ve 0 koduyla çıkar. Toplu işlemde böyle bir dosya başarısız değil, eşleşmeyen sayılır.