pdfx CLI: một danh mục, gọi từ terminal của bạn
pdfx CLI gửi đúng những yêu cầu multipart như curl tới API PDF123 hoặc pdfx-server của bạn, đồng thời thêm chạy theo lô, mật khẩu từng tệp và mã thoát để script rẽ nhánh.

PDF123 là tên sản phẩm. pdfx chính là danh mục thao tác đó được gói cho shell: nó dựng yêu cầu multipart mà curl sẽ dựng, gửi tới API base bạn chọn, rồi ghi kết quả ngay cạnh tệp của bạn. Merge, Compress, OCR và phần còn lại của danh mục đều gọi được theo cách này.
Một lệnh gọi thực sự gửi đi những gì
pdfx --api-base "$API_BASE" --api-key "$PDFX_API_KEY" \
merge a.pdf b.pdf -o merged.pdf
--api-base mặc định là https://pdf123.xyz, còn --api-key (hoặc biến môi trường PDFX_API_KEY) là tùy chọn, nên danh mục ẩn danh vẫn dùng được khi không có key. Trỏ base vào http://127.0.0.1:8080 nếu bạn có stack docker-compose của riêng mình. Bên dưới không có giao thức thứ hai: CLI là client của bề mặt REST được ghi tại Nhà phát triển, và tên op của nó khớp với công cụ trên portal cùng tài liệu OpenAPI tại /v1/openapi.json.
Có thể khám phá danh mục mà không cần rời terminal. pdfx list in ra mọi công cụ, còn pdfx describe add-stamp in ra các trường và giá trị mặc định của một công cụ, đúng định nghĩa mà portal render thành form.
Chạy theo lô và những cờ mà curl bắt bạn tự viết
Đưa nhiều đầu vào cho một công cụ đơn tệp, nó chạy chúng thành một lô vào thư mục -o, in một dòng input -> saved cho mỗi tệp. Lỗi đi ra stderr và các tệp còn lại vẫn chạy xong, nên một PDF hỏng trong thư mục hóa đơn không làm hỏng cả lượt chạy. --concurrency <n> đặt số tệp xử lý cùng lúc (mặc định 2).
-o nhận một tệp hoặc một thư mục và không bao giờ ghi đè tệp đã tồn tại: trong thư mục, nó dùng tên tệp do server đặt. Điều này quan trọng khi server đặt tên kết quả theo đầu vào: nếu không, một lượt chạy sẽ đè lên chính PDF bạn vừa tải lên.
Đầu vào được mã hóa sẽ được mở trước khi gửi yêu cầu, không phải do công cụ mở: --input-password áp cho mọi tệp trong lượt chạy, còn --password-for report.pdf=secret đặt mật khẩu cho một tệp và có thể lặp lại, với * đại diện cho phần còn lại. Nhờ vậy một lô trộn tệp khóa và tệp mở không cần phân loại thủ công. --json in { path, contentType, bytes } cho mỗi kết quả, hoặc [{ input, ok, path | error, reason }] cho một lô, để lớp bọc phân tích kết quả thay vì đọc dò từng dòng người đọc được.
Mã thoát để script rẽ nhánh
0 nghĩa là thành công, 1 nghĩa là một yêu cầu thất bại (trong lô: ít nhất một tệp), 2 là lỗi cách dùng khi chưa tải lên gì, còn 130 nghĩa là bạn đã ngắt và yêu cầu đang chạy bị hủy. Khi thất bại, các dòng reason:, code: và hint: được in dưới thông báo nếu có, và đó là thứ script nên khớp thay vì văn xuôi.
Một mã thoát dễ bị đọc nhầm. Một công cụ không tìm thấy gì để trả về sẽ thoát khác 0 với code: no_content thay vì ghi ra tệp rỗng, nên pdf-to-csv trên một PDF không có bảng là thất bại, không phải một CSV 0 byte.
Byte đi đâu
Tệp được tải lên API base, xử lý tại đó, và bị xóa sau khi phản hồi được gửi đi. Đó cũng là hợp đồng của form trình duyệt; CLI thay đổi client chứ không thay đổi đích đến. Với tài liệu không được rời khỏi mạng của bạn, hãy tự chạy một pdfx-server rồi trỏ --api-base vào đó, nội dung này có ở Self-host.
Không có chế độ offline để lui về: nếu base không truy cập được, lệnh sẽ thất bại. pdfx là một client mạng, tình cờ dễ chịu trong shell, chứ không phải một engine PDF cục bộ.
pdfx không phải là gì
pdfx không phải một desktop GUI và không phải thư viện OCR nhúng để liên kết vào ứng dụng khác. Nó là client dòng lệnh cho các thao tác PDF, nên một việc làm một lần của con người vẫn hợp với portal hơn (Compress, OCR và phần còn lại của danh mục), còn bất cứ thứ gì cần cây UI riêng sẽ tái tạo đúng vấn đề lệch hướng mô tả trong Cùng thao tác, bốn client.
Agent nhận cùng những hình dạng đó từ skill đã công bố tại /skills/pdf123.md, nơi ghi đầy đủ các yêu cầu merge và pipeline. Để thử lại an toàn các POST có thay đổi dữ liệu, hãy gửi Idempotency-Key; CLI vẫn chỉ gửi một yêu cầu mỗi lần gọi, nên tiêu đề đó thuộc về bất cứ thứ gì thử lại nó (Idempotency-Key: thử lại an toàn cho tác vụ PDF). Key, hạn mức và mã lỗi nằm ở Nhà phát triển.