pdfx: บรรทัดคำสั่งของ PDF123

จะติดตั้ง pdfx ได้อย่างไร#

ติดตั้งแพ็กเกจแบบ global เพื่อให้ได้คำสั่ง pdfx หรือจะรันครั้งเดียวโดยไม่ติดตั้งก็ได้

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 และ pnpm add -g @pdf123/cli ใช้ได้เช่นกัน ไม่ต้องติดตั้งอย่างอื่นเพิ่ม

จะเริ่มใช้งานได้อย่างไร#

หกคำสั่งนี้แสดงรูปแบบการใช้งานทั่วไป

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

จะรันเครื่องมือใดก็ได้อย่างไร#

อาร์กิวเมนต์แรกคือรหัสเครื่องมือ ตามด้วยไฟล์อินพุตและตัวเลือกของเครื่องมือ ทุกตัวเลือกของเครื่องมือเป็นแฟลก เขียนเป็นชื่อฟิลด์ของ API (--pageNumbers) หรือแบบ kebab case (--page-numbers) ตัวเลขติดลบวางตามหลังแฟลกโดยเว้นวรรคได้ เช่น --rotation -90 หรือวางตามหลังเครื่องหมายเท่ากับ

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

ใช้ pdfx list เพื่อดูเครื่องมือ รับ --category หรือ --group และ --query พร้อมคำค้น ใช้ pdfx describe <tool> เพื่อดูปลายทาง อินพุตที่รองรับ ว่าเครื่องมือทำงานเป็นชุดงานหรือไม่ และทุกฟิลด์พร้อมค่าเริ่มต้นและค่าที่อนุญาต หากไม่รู้จักรหัสเครื่องมือ จะมีคำแนะนำให้ และหากพิมพ์ผิดจะออกด้วยรหัส 2

คำสั่งใดตรงกับหน้าเครื่องมือใด#

จะประมวลผลหลายไฟล์พร้อมกันได้อย่างไร#

ส่งหลายไฟล์ให้เครื่องมือแบบไฟล์เดียว แล้ว pdfx จะรันเป็นชุดงาน ใช้ -o กับไดเรกทอรีที่ลงท้ายด้วยเครื่องหมายสแลช เครื่องมือรันหนึ่งครั้งต่อไฟล์ โดยค่าเริ่มต้นรันครั้งละสองไฟล์ เปลี่ยนได้ด้วย --concurrency

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

pdfx พิมพ์หนึ่งบรรทัด คือ input -> saved เมื่อแต่ละไฟล์เสร็จ ไฟล์ที่ล้มเหลวจะรายงานทาง standard error และไฟล์อื่นยังทำต่อจนเสร็จ กด Ctrl-C หนึ่งครั้งเพื่อยกเลิกคำขอที่กำลังทำงาน ไฟล์ที่บันทึกไปแล้วจะยังอยู่ กด Ctrl-C ครั้งที่สองจะออกทันทีด้วยรหัส 130 เมื่อใช้ --idempotency-key k แต่ละไฟล์จะส่ง k:<index> และการส่งคำขอเดิมซ้ำจะได้ผลลัพธ์แรกกลับมาเป็นเวลา 24 ชั่วโมง

ชุดงานของเครื่องมือที่คืนรายงาน เช่น get-info จะไม่เขียนไฟล์หากไม่มี -o แต่จะพิมพ์รายงานโดยจัดกลุ่มตามไฟล์อินพุต

จะเชื่อมเครื่องมือในคำขอเดียวได้อย่างไร#

pdfx pipeline รันหลายเครื่องมือในคำขอเดียว ใส่ --step ซ้ำสำหรับแต่ละเครื่องมือ หากต้องการกำหนดตัวเลือก ให้ส่งอาร์เรย์ JSON ด้วย --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

ขั้นตอนใช้เครื่องมือที่ต้องการไฟล์ที่สองไม่ได้

จะเปิด PDF ที่มีรหัสผ่านได้อย่างไร#

--input-password เปิดทุกอินพุตที่เข้ารหัสก่อน ส่วน --password-for <file>=<password> กำหนดรหัสผ่านของหนึ่งไฟล์ ใช้ซ้ำได้ และใช้ * เป็นชื่อไฟล์เพื่อครอบคลุมไฟล์ที่เหลือ เหมาะกับชุดงานที่มีทั้งไฟล์ที่ล็อกและไม่ล็อก สำหรับ merge และ images-to-pdf ไฟล์ที่ระบุชื่อแต่ละไฟล์จะถูกปลดล็อกแยกกันก่อนรันเครื่องมือ

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

ตัวเลือกเดียวกันใช้ได้ในไปป์ไลน์ หากต้องการถอดการป้องกันถาวร ให้ใช้เครื่องมือถอดรหัสผ่านพร้อมตัวเลือก --password ของเครื่องมือนั้น

อินพุตและเอาต์พุตทำงานอย่างไร#

• อินพุต - อ่านจาก standard input ได้หนึ่งครั้งต่อการรัน -o - เขียนผลลัพธ์ไปที่ standard output
• -o file.pdf เขียนไฟล์นั้น -o dir/ เขียนลงในไดเรกทอรี ไดเรกทอรีที่ยังไม่มีต้องมีเครื่องหมายสแลชท้าย เพราะชื่อที่ไม่มีสแลชจะถูกเขียนเป็นไฟล์
• หากไม่มี -o ผลลัพธ์จะไปที่ไดเรกทอรีปัจจุบันโดยใช้ชื่อไฟล์จากเซิร์ฟเวอร์
• เมื่อเขียนลงไดเรกทอรี pdfx จะไม่เขียนทับไฟล์ที่มีอยู่ แต่จะเลือกชื่อใหม่ ส่วน -o file.pdf ที่ระบุชัดเจนจะเขียนทับไฟล์นั้น
• ชื่อไฟล์ -o ที่นามสกุลขัดกับผลลัพธ์ เช่น ZIP จาก split ที่บันทึกเป็น .pdf จะถูกปฏิเสธด้วยรหัสออก 2 และ code: output_mismatch ไม่มีการเขียนอะไรเลย
• เอาต์พุตที่เขียนไม่ได้เป็นข้อผิดพลาดการใช้งานที่ตรวจพบก่อนอัปโหลดอะไรทั้งสิ้น

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

--json พิมพ์อะไร#

สำหรับผลลัพธ์ที่บันทึกไว้ --json พิมพ์เส้นทาง ประเภทเนื้อหา และขนาด เครื่องมือที่คืนรายงานจะพิมพ์รายงานนั้นเอง ชุดงานพิมพ์รายงานเดียวที่มีสถานะของแต่ละไฟล์

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

ไฟล์ที่ล้มเหลวมี error และ reason แทน path และ bytes เครื่องมือกรองที่ไม่พบรายการตรงเงื่อนไขจะพิมพ์ { "matched": false } ส่วน pdfx list --json พิมพ์แถวที่มี id, category, group, name, description, returns, files และ filter

ตัวเลือกใดใช้กับทุกเครื่องมือ#

รหัสออกมีอะไรบ้าง#

เมื่อล้มเหลวจะพิมพ์บรรทัด reason:, code: และ hint: หากเซิร์ฟเวอร์ให้มา สคริปต์จึงแยกกรณีได้โดยไม่ต้องจับคู่ข้อความ เครื่องมือที่ไม่พบสิ่งที่จะคืน เช่น pdf-to-csv กับ PDF ที่ไม่มีตาราง จะออกด้วย 1 พร้อม code: no_content แทนการเขียนไฟล์ว่าง รหัสทั้งหมดอยู่ในรหัสข้อผิดพลาด

จะชี้ pdfx ไปที่เซิร์ฟเวอร์ของฉันเองได้อย่างไร#

ตั้ง PDFX_API_BASE หรือส่ง --api-base เป็นที่อยู่ของ pdfx-server ที่โฮสต์เอง เพิ่ม PDFX_API_KEY หากเซิร์ฟเวอร์ของคุณต้องใช้คีย์ ดูโฮสต์เอง

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

จะเรียกปลายทางที่ CLI ไม่รู้จักได้อย่างไร#

pdfx call ส่งคำขอดิบไปยังรหัสการทำงานหรือเส้นทาง /api/... ใช้ --field name=value สำหรับฟิลด์ของฟอร์ม และ --file field=path สำหรับไฟล์เพิ่มเติม ส่งคำขอเพียงหนึ่งครั้งและไม่ตรวจสอบอะไรในเครื่อง จึงปฏิเสธรหัสผ่านและชุดงาน

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

หน้าที่เกี่ยวข้อง#

• ภาพรวมสำหรับนักพัฒนา ซึ่งมี REST API และการยืนยันตัวตน
• TypeScript SDK ไลบรารีที่บรรทัดคำสั่งสร้างขึ้นบน
• เซิร์ฟเวอร์ MCP สำหรับเอเจนต์ AI
• บทความบล็อก "pdfx CLI: One Catalog, Called From Your Terminal" ในบล็อก PDF123

คำถามที่พบบ่อย#

pdfx ใช้งานแบบออฟไลน์ได้หรือไม่#

ไม่ได้ pdfx อัปโหลดแต่ละไฟล์ไปยัง API ของ PDF123 หรือเซิร์ฟเวอร์ของคุณเอง แล้วบันทึกผลลัพธ์ในเครื่อง จึงต้องเข้าถึง API base ได้

pdfx ต้องใช้คีย์ API หรือไม่#

ไม่ต้อง ใช้แบบไม่ระบุตัวตนได้ ตั้ง PDFX_API_KEY หรือส่ง --api-key หากเซิร์ฟเวอร์ของคุณต้องใช้ คีย์ถูกส่งเป็นเฮดเดอร์ X-API-KEY

pdfx ต้องใช้ Node เวอร์ชันใด#

Node 20.3 ขึ้นไป หรือ Bun

pdfx จะเขียนทับไฟล์ของฉันหรือไม่#

ไม่เมื่อเขียนลงไดเรกทอรี ไฟล์ที่มีอยู่จะไม่ถูกแทนที่ แต่หากคุณระบุชื่อไฟล์เอาต์พุตเองด้วย -o file.pdf ไฟล์นั้นจะถูกเขียนทับ จึงควรเลือกชื่อใหม่เมื่อต้องการเก็บต้นฉบับไว้

จะเกิดอะไรขึ้นเมื่อเครื่องมือกรองไม่พบรายการที่ตรงเงื่อนไข#

เครื่องมือกรองซึ่งมีรหัสขึ้นต้นด้วย filter- จะส่งไฟล์ผ่านเมื่อเงื่อนไขเป็นจริง เมื่อไม่เป็นจริง pdfx จะพิมพ์ no match และออกด้วยรหัส 0 ในชุดงาน ไฟล์แบบนั้นนับเป็นไม่ตรงเงื่อนไข ไม่ใช่ล้มเหลว