pdfx: командният ред на PDF123

Как да инсталирам pdfx?#

Инсталирайте пакета глобално, за да получите командата 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, щом всеки файл приключи. Неуспешният файл се съобщава в стандартния изход за грешки, а останалите файлове се обработват докрай. Натиснете 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.

Как работят входът и изходът?#

• Вход - чете стандартния вход, веднъж при всяко изпълнение. -o - записва резултата в стандартния изход.
• -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, ако сървърът ви изисква ключ. Вижте Self-host.

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 качва всеки файл в PDF123 API или във ваш собствен сървър и запазва резултата локално, затова базовият адрес на API трябва да е достъпен.

Нужен ли е API ключ на pdfx?#

Не. Анонимната употреба работи. Задайте PDFX_API_KEY или подайте --api-key, ако сървърът ви изисква ключ. Ключът се изпраща в заглавката X-API-KEY.

Коя версия на Node изисква pdfx?#

Node 20.3 или по-нова, или Bun.

Ще презапише ли pdfx файловете ми?#

Не, когато записва в директория: съществуващ файл никога не се заместава. Ако сами зададете изходния файл с -o file.pdf, този файл се заменя, затова изберете ново име, ако искате да запазите оригинала.

Какво става, когато филтриращ инструмент не намери съвпадение?#

Филтриращите инструменти, чиито идентификатори започват с filter-, предават файла нататък, когато условието им е изпълнено. Когато не е, pdfx извежда no match и завършва с код 0. В пакет такъв файл се брои за несъвпаднал, а не за неуспешен.