pdfx: dòng lệnh của PDF123

Làm sao cài pdfx?#

Cài gói ở chế độ toàn cục để có lệnh pdfx. Hoặc chạy một lần mà không cần cài.

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 và pnpm add -g @pdf123/cli cũng dùng được. Không cần cài thêm gì khác.

Làm sao bắt đầu?#

Sáu lệnh này cho thấy các mẫu dùng phổ biến.

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

Làm sao chạy một công cụ bất kỳ?#

Đối số đầu tiên là id công cụ. Tiếp theo là các tệp đầu vào và tùy chọn của công cụ. Mỗi tùy chọn của công cụ là một cờ, viết theo tên trường API (--pageNumbers) hoặc kiểu kebab (--page-numbers). Số âm có thể đặt sau cờ cách một khoảng trắng, như --rotation -90, hoặc sau dấu bằng.

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

Dùng pdfx list để xem các công cụ. Lệnh nhận --category hoặc --group, và --query kèm từ khóa để tìm kiếm. Dùng pdfx describe <tool> để xem endpoint, các đầu vào được chấp nhận, công cụ có chạy theo lô hay không, và từng trường cùng giá trị mặc định và giá trị cho phép. Id công cụ không tồn tại sẽ nhận gợi ý, còn id gõ sai sẽ thoát với mã 2.

Lệnh nào tương ứng với trang công cụ nào?#

Làm sao xử lý nhiều tệp cùng lúc?#

Đưa nhiều tệp cho một công cụ một tệp thì pdfx sẽ chạy theo lô. Hãy dùng -o với một thư mục kết thúc bằng dấu gạch chéo. Công cụ chạy một lần cho mỗi tệp, mặc định hai tệp cùng lúc. Đổi số này bằng --concurrency.

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

pdfx in một dòng input -> saved khi mỗi tệp xong. Tệp bị lỗi được báo trên đầu ra lỗi chuẩn và các tệp khác vẫn hoàn tất. Nhấn Ctrl-C một lần để hủy yêu cầu đang chạy; các tệp đã lưu được giữ lại. Nhấn Ctrl-C lần thứ hai sẽ thoát ngay với mã 130. Với --idempotency-key k, mỗi tệp gửi k:<index>, và việc lặp lại cùng yêu cầu sẽ phát lại kết quả đầu tiên trong 24 giờ.

Một lô của công cụ trả về báo cáo, như get-info, không ghi tệp nào nếu thiếu -o. Lệnh in các báo cáo theo từng tệp đầu vào.

Làm sao nối các công cụ trong một yêu cầu?#

pdfx pipeline chạy nhiều công cụ trong một yêu cầu. Lặp lại --step cho mỗi công cụ. Để đặt tùy chọn, hãy truyền một mảng JSON bằng --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

Các bước không thể dùng những công cụ cần tệp thứ hai.

Làm sao mở PDF có mật khẩu?#

--input-password mở trước mọi đầu vào đã mã hóa. --password-for <file>=<password> đặt mật khẩu cho một tệp. Có thể lặp lại, và * làm tên tệp sẽ áp dụng cho phần còn lại. Cách này hợp với lô trộn lẫn tệp có khóa và tệp không khóa. Với merge và images-to-pdf, mỗi tệp được nêu tên sẽ được mở khóa riêng trước khi công cụ chạy.

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

Các tùy chọn này cũng dùng được trong pipeline. Để gỡ bảo vệ vĩnh viễn, hãy dùng công cụ Mở khóa với tùy chọn --password riêng của nó.

Đầu vào và đầu ra hoạt động thế nào?#

• Đầu vào là - sẽ đọc đầu vào chuẩn, mỗi lần chạy một lần. -o - ghi kết quả ra đầu ra chuẩn.
• -o file.pdf ghi ra tệp đó. -o dir/ ghi vào một thư mục. Thư mục chưa tồn tại cần có dấu gạch chéo ở cuối, vì tên không có dấu này sẽ được ghi thành tệp.
• Không có -o, kết quả được ghi vào thư mục hiện tại với tên tệp do máy chủ đặt.
• Khi ghi vào thư mục, pdfx không bao giờ thay thế tệp đã có; nó chọn một tên mới. -o file.pdf nêu rõ tên thì thay thế tệp đó.
• Tên tệp -o có phần mở rộng mâu thuẫn với kết quả, chẳng hạn ZIP từ split lưu thành .pdf, sẽ bị từ chối với mã thoát 2 và code: output_mismatch. Không có gì được ghi.
• Đầu ra không ghi được là lỗi cách dùng, được phát hiện trước khi có gì được tải lên.

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

--json in ra những gì?#

Với kết quả đã lưu, --json in đường dẫn, loại nội dung và dung lượng. Công cụ trả về báo cáo thì in chính báo cáo đó. Một lô in một báo cáo có trạng thái cho từng tệp.

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

Tệp bị lỗi có error và reason thay cho path và bytes. Công cụ lọc không có kết quả khớp in { "matched": false }. pdfx list --json in các dòng gồm id, category, group, name, description, returns, files và filter.

Những tùy chọn nào áp dụng cho mọi công cụ?#

Các mã thoát là gì?#

Khi thất bại, các dòng reason:, code: và hint: được in ra nếu máy chủ cung cấp, nhờ đó script có thể rẽ nhánh mà không cần so khớp văn bản. Công cụ không tìm thấy gì để trả về, chẳng hạn pdf-to-csv trên PDF không có bảng, thoát với mã 1 và code: no_content thay vì ghi một tệp rỗng. Các mã được liệt kê ở trang Mã lỗi.

Làm sao trỏ pdfx tới máy chủ của riêng tôi?#

Đặt PDFX_API_BASE, hoặc truyền --api-base, là địa chỉ của một pdfx-server tự host. Thêm PDFX_API_KEY nếu máy chủ của bạn cần khóa. Xem Tự host.

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

Làm sao chạy một endpoint mà CLI chưa biết?#

pdfx call gửi một yêu cầu thô tới một id thao tác hoặc đường dẫn /api/.... Dùng --field name=value cho các trường biểu mẫu và --file field=path cho tệp bổ sung. Lệnh chỉ gửi đúng một yêu cầu và không kiểm tra gì ở phía cục bộ, nên mật khẩu và lô bị từ chối.

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

Trang liên quan#

• Tổng quan cho nhà phát triển, gồm REST API và xác thực
• SDK TypeScript, thư viện mà dòng lệnh được xây dựng trên đó
• Máy chủ MCP cho AI agent
• Bài "pdfx CLI: một danh mục, gọi từ terminal của bạn" trên blog PDF123

Câu hỏi thường gặp#

pdfx có hoạt động ngoại tuyến không?#

Không. pdfx tải từng tệp lên API PDF123 hoặc máy chủ riêng của bạn rồi lưu kết quả về máy, nên phải truy cập được API base.

pdfx có cần khóa API không?#

Không. Có thể dùng ẩn danh. Hãy đặt PDFX_API_KEY hoặc truyền --api-key nếu máy chủ của bạn yêu cầu khóa. Khóa được gửi trong header X-API-KEY.

pdfx cần phiên bản Node nào?#

Node 20.3 trở lên, hoặc Bun.

pdfx có ghi đè tệp của tôi không?#

Không khi ghi vào thư mục: tệp đã có không bao giờ bị thay thế. Nếu bạn tự đặt tên tệp đầu ra bằng -o file.pdf thì tệp đó sẽ bị thay thế, nên hãy chọn tên mới khi bạn muốn giữ bản gốc.

Điều gì xảy ra khi công cụ lọc không có kết quả khớp?#

Các công cụ lọc, có id bắt đầu bằng filter-, cho tệp đi qua khi điều kiện thỏa. Khi điều kiện không thỏa, pdfx in no match và thoát với mã 0. Trong một lô, tệp như vậy được tính là không khớp, chứ không phải bị lỗi.