pdfx: baris perintah PDF123

Bagaimana cara memasang pdfx?#

Pasang paket secara global untuk mendapatkan perintah pdfx. Atau jalankan sekali tanpa memasang.

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 dan pnpm add -g @pdf123/cli juga bisa dipakai. Tidak ada hal lain yang perlu dipasang.

Bagaimana cara memulai?#

Enam perintah ini menunjukkan pola yang umum dipakai.

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

Bagaimana cara menjalankan alat apa pun?#

Argumen pertama adalah id alat. File masukan dan opsi alat menyusul setelahnya. Setiap opsi alat berupa flag, ditulis sebagai nama kolom API (--pageNumbers) atau dalam kebab case (--page-numbers). Angka negatif dapat ditulis setelah flag dengan spasi, seperti --rotation -90, atau setelah tanda sama dengan.

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

Gunakan pdfx list untuk melihat daftar alat. Perintah ini menerima --category atau --group, serta --query dengan kata untuk dicari. Gunakan pdfx describe <tool> untuk melihat endpoint, masukan yang diterima, apakah alat berjalan sebagai batch, dan setiap kolom beserta nilai bawaan dan nilai yang diizinkan. Id alat yang tidak dikenal mendapat saran, dan id yang salah ketik keluar dengan kode 2.

Perintah mana yang sesuai dengan halaman alat mana?#

Bagaimana cara memproses banyak file sekaligus?#

Berikan beberapa file ke alat satu-file dan pdfx menjalankan batch. Gunakan -o dengan direktori yang diakhiri garis miring. Alat dijalankan sekali per file, dua file sekaligus secara bawaan. Ubah dengan --concurrency.

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

pdfx mencetak satu baris, input -> saved, setiap kali sebuah file selesai. File yang gagal dilaporkan ke standard error dan file lainnya tetap diselesaikan. Tekan Ctrl-C sekali untuk membatalkan permintaan yang sedang berjalan; file yang sudah tersimpan tetap ada. Ctrl-C kedua langsung keluar dengan kode 130. Dengan --idempotency-key k, setiap file mengirim k:<index>, dan pengulangan permintaan yang sama memutar ulang hasil pertama selama 24 jam.

Batch dari alat yang mengembalikan laporan, seperti get-info, tidak menulis file jika tanpa -o. Laporannya dicetak dengan file masukan sebagai kunci.

Bagaimana cara merangkai alat dalam satu permintaan?#

pdfx pipeline menjalankan beberapa alat dalam satu permintaan. Ulangi --step untuk setiap alat. Untuk menetapkan opsi, berikan array JSON dengan --steps.

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

Langkah tidak boleh memakai alat yang membutuhkan file kedua.

Bagaimana cara membuka PDF yang dilindungi kata sandi?#

--input-password membuka semua masukan terenkripsi lebih dulu. --password-for <file>=<password> menetapkan kata sandi untuk satu file. Opsi ini dapat diulang, dan * sebagai nama file mencakup sisanya. Ini cocok untuk batch yang mencampur file terkunci dan file terbuka. Untuk merge dan images-to-pdf, setiap file yang disebut dibuka secara terpisah sebelum alat dijalankan.

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

Opsi yang sama berlaku dalam pipeline. Untuk menghapus perlindungan secara permanen, gunakan alat Buka kunci dengan opsi --password miliknya sendiri.

Bagaimana masukan dan keluaran bekerja?#

• Masukan - membaca standard input, satu kali per eksekusi. -o - menulis hasil ke standard output.
• -o file.pdf menulis file tersebut. -o dir/ menulis ke dalam direktori. Direktori yang belum ada memerlukan garis miring di akhir, karena nama tanpa garis miring ditulis sebagai file.
• Tanpa -o, hasil disimpan di direktori saat ini dengan nama file dari server.
• Ke dalam direktori, pdfx tidak pernah menimpa file yang sudah ada; ia memilih nama baru. -o file.pdf yang eksplisit menimpa file tersebut.
• Nama file -o yang ekstensinya bertentangan dengan hasilnya, misalnya ZIP dari split yang disimpan sebagai .pdf, ditolak dengan kode keluar 2 dan code: output_mismatch. Tidak ada yang ditulis.
• Keluaran yang tidak dapat ditulis adalah kesalahan penggunaan yang ditemukan sebelum apa pun diunggah.

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

Apa yang dicetak oleh --json?#

Untuk hasil yang disimpan, --json mencetak jalur, tipe konten, dan ukuran. Alat yang mengembalikan laporan mencetak laporan itu sendiri. Batch mencetak satu laporan dengan status untuk setiap file.

{ "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 }
  ]
}

File yang gagal memiliki error dan reason sebagai pengganti path dan bytes. Alat filter tanpa kecocokan mencetak { "matched": false }. pdfx list --json mencetak baris dengan id, category, group, name, description, returns, files, dan filter.

Opsi mana yang berlaku untuk semua alat?#

Apa saja kode keluarnya?#

Kegagalan mencetak baris reason:, code:, dan hint: jika server menyediakannya, sehingga skrip dapat bercabang tanpa mencocokkan teks. Alat yang tidak menemukan apa pun untuk dikembalikan, seperti pdf-to-csv pada PDF tanpa tabel, keluar dengan 1 dan code: no_content alih-alih menulis file kosong. Kodenya tercantum di Kode galat.

Bagaimana cara mengarahkan pdfx ke server saya sendiri?#

Setel PDFX_API_BASE, atau berikan --api-base, ke alamat pdfx-server self-host. Tambahkan PDFX_API_KEY jika server Anda memerlukan kunci. Lihat Self-host.

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

Bagaimana cara memanggil endpoint yang tidak dikenal CLI?#

pdfx call mengirim permintaan mentah ke id operasi atau jalur /api/.... Gunakan --field name=value untuk kolom formulir dan --file field=path untuk file tambahan. Perintah ini mengirim tepat satu permintaan dan tidak memvalidasi apa pun secara lokal, sehingga kata sandi dan batch ditolak.

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

Halaman terkait#

• Ikhtisar pengembang dengan REST API dan autentikasi
• SDK TypeScript, pustaka yang menjadi dasar baris perintah
• Server MCP untuk agen AI
• Artikel blog "pdfx CLI: One Catalog, Called From Your Terminal" di blog PDF123

FAQ#

Apakah pdfx bisa bekerja offline?#

Tidak. pdfx mengunggah setiap file ke API PDF123 atau ke server Anda sendiri dan menyimpan hasilnya secara lokal, sehingga basis API harus dapat dijangkau.

Apakah pdfx memerlukan kunci API?#

Tidak. Pemakaian anonim berfungsi. Setel PDFX_API_KEY atau berikan --api-key jika server Anda mewajibkannya. Kunci dikirim sebagai header X-API-KEY.

Versi Node berapa yang dibutuhkan pdfx?#

Node 20.3 atau lebih baru, atau Bun.

Apakah pdfx akan menimpa file saya?#

Tidak saat menulis ke dalam direktori: file yang sudah ada tidak pernah diganti. Jika Anda menamai file keluaran sendiri dengan -o file.pdf, file itu akan diganti, jadi pilih nama baru jika Anda ingin menyimpan file aslinya.

Apa yang terjadi jika alat filter tidak menemukan kecocokan?#

Alat filter, yang id-nya diawali filter-, meneruskan file jika kondisinya terpenuhi. Jika tidak, pdfx mencetak no match dan keluar dengan kode 0. Dalam batch, file seperti itu dihitung sebagai tidak cocok, bukan gagal.