CLI pdfx: lokal dulu, cloud saat Anda butuh

PDF123 adalah nama produknya. pdfx adalah CLI ringkas yang berbicara ke operasi yang sama. Jalur defaultnya lokal: baca berkas, jalankan operasi lewat pdf-core, tulis hasilnya. Tanpa akun, tanpa API key, tanpa unggahan.

Lokal dulu berarti berkas tidak pernah pergi

Panggilan yang khas berbentuk pdfx merge a.pdf b.pdf -o merged.pdf atau pdfx compress input.pdf. Pemrosesan berjalan di tempat biner itu dijalankan. Pola ini cocok untuk tugas CI di runner privat, skrip yang bekerja di samping tumpukan faktur, dan setiap kasus ketika mengunggah ke pihak ketiga adalah jawaban yang salah.

Mode lokal bukan pembungkus tipis yang diam-diam mengirim byte ke tempat lain. CLI berbagi registry operasi yang sama dengan server (pdf_core::ops::run). Bila Anda memang menginginkan jalur jaringan, Anda memilihnya sendiri dengan --cloud.

Subcommand bawaan mencakup operasi umum: merge, split, compress, rotate, extract, OCR, convert, protect, unlock, watermark, dan pekerjaan terkait. Hasil lokal secara default ditulis ke berkas lewat -o / --output; tanda - menulis ke stdout.

--cloud adalah katalog yang sama lewat HTTP

Ketika Anda membutuhkan API hosted (atau pdfx-server milik Anda sendiri), sertakan --cloud bersama --api-base dan --api-key (atau PDFX_API_KEY). Mode cloud memerlukan curl di baliknya dan gagal bila tidak ada API key. Contoh dari skill yang dipublikasikan:

pdfx --cloud --api-base "$PDFX_API_BASE" --api-key "$PDFX_API_KEY" \
  merge a.pdf b.pdf -o merged.pdf

--api-base secara default bernilai https://pdf123.xyz, yaitu API hosted. Untuk tumpukan Docker Compose lokal, arahkan ke http://127.0.0.1:8080. CLI lalu menjadi klien bagi permukaan REST yang didokumentasikan di Developers; nama operasinya selaras dengan alat di portal dan OpenAPI (/v1/openapi.json).

Mode cloud tidak mengubah arti sebuah operasi. Compress tetap kompresi stream qpdf; OCR tetap mengembalikan teks Markdown dari jalur Rust, bukan lapisan PDF yang bisa dicari. Flag CLI sisa yang memetakan ke parameter OCR era Java yang diabaikan (misalnya field languages) tidak mengubah kontrak itu.

Mengapa ada dua mode

Lokal menjawab kebutuhan kepercayaan offline dan biaya pulang-pergi nol. Cloud menjawab batas laju bersama, keinginan menjalankan operasi di mesin yang hanya terpasang CLI dan curl, serta tim yang sudah menerbitkan API key. Agen juga bisa memanggil base yang sama lewat MCP di /mcp atau skill di dist/skills/pdf-toolbox/SKILL.md. Indeks penemuan seperti /llms.txt membantu agen coding menemukan titik akhir, tetapi bukan sinyal peringkat Google.

Untuk percobaan ulang yang aman pada POST yang mengubah data terhadap API, kirim Idempotency-Key (lihat Idempotency-Key: percobaan ulang yang aman untuk tugas PDF). Jalur cloud CLI tetap satu permintaan HTTP per pemanggilan; gunakan header itu ketika pembungkus Anda mencoba ulang.

Memilih mode dalam praktik

Gunakan mode lokal ketika berkas harus tetap berada di runner, ketika biner pdfx dan dependensi native sudah terpasang di mesin itu, dan ketika latensi lebih banyak ditentukan oleh operasinya daripada oleh unggahan. Gunakan mode cloud ketika dependensi berat hanya ada di server, ketika Anda menginginkan batas laju dan pencatatan yang sama seperti klien API lain, atau ketika agen sudah memegang API key untuk https://pdf123.xyz atau base self-host Anda.

Jangan mencampur ekspektasi: OCR lokal tetap mengikuti kontrak keluaran Markdown dari misc/ocr-pdf; compress cloud tetap stream qpdf, bukan subsetting font. Pergantian mode mengubah di mana operasi berjalan, bukan makna katalognya.

Apa yang bukan CLI ini

pdfx bukan GUI desktop dan bukan pustaka OCR yang bisa Anda tautkan ke aplikasi lain. Ia adalah klien baris perintah untuk operasi PDF: lokal secara default, HTTP saat Anda memintanya. Pekerjaan sekali pakai di browser tetap ada di portal (Compress, OCR, dan sisa katalog). Otomasi yang lebih suka biner bisa tetap memakai pdfx.

Perbandingan operasi yang sama lintas browser, curl, MCP, dan CLI dipaparkan di Operasi yang sama, empat klien. Mulailah dari Developers untuk key dan OpenAPI, atau Self-host bila base API seharusnya menjadi tumpukan Docker Compose Anda sendiri.