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

아무 도구나 실행하려면?#

첫 번째 인수는 도구 ID입니다. 그 뒤에 입력 파일과 도구의 옵션이 옵니다. 도구의 모든 옵션은 플래그이며, API 필드 이름(--pageNumbers) 또는 케밥 케이스(--page-numbers)로 씁니다. 음수는 --rotation -90처럼 플래그 뒤에 공백을 두고 쓰거나 등호 뒤에 씁니다.

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

도구 목록은 pdfx list로 확인합니다. --category 또는 --group, 그리고 검색어를 받는 --query를 쓸 수 있습니다. pdfx describe <tool>은 엔드포인트, 허용되는 입력, 일괄 처리로 실행되는지 여부, 그리고 각 필드의 기본값과 허용 값을 보여 줍니다. 알 수 없는 도구 ID에는 후보가 제시되고, 잘못 입력하면 종료 코드 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을 반복해서 지정하세요. 옵션을 설정하려면 --steps로 JSON 배열을 전달합니다.

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 파일 이름(예: split이 반환한 ZIP을 .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 }
  ]
}

실패한 파일에는 path와 bytes 대신 error와 reason이 들어갑니다. 일치하는 것이 없는 필터 도구는 { "matched": false }를 출력합니다. pdfx list --json은 id, category, group, name, description, returns, files, filter를 가진 행을 출력합니다.

모든 도구에 공통으로 적용되는 옵션은?#

종료 코드는 무엇을 뜻하나요?#

서버가 제공하면 실패 시 reason:, code:, hint: 줄이 출력되므로, 스크립트가 문구를 비교하지 않고도 분기할 수 있습니다. 표가 없는 PDF에 pdf-to-csv를 실행하는 경우처럼 반환할 것이 없는 도구는 빈 파일을 쓰는 대신 종료 코드 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은 작업 ID 또는 /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 에이전트용
• PDF123 블로그의 글 "pdfx CLI: One Catalog, Called From Your Terminal"

FAQ#

pdfx는 오프라인에서 동작하나요?#

아니요. pdfx는 각 파일을 PDF123 API 또는 자체 서버에 업로드하고 결과를 로컬에 저장하므로, API 기본 주소에 접속할 수 있어야 합니다.

pdfx에 API 키가 필요한가요?#

아니요. 익명으로도 사용할 수 있습니다. 서버에 키가 필요하면 PDFX_API_KEY를 설정하거나 --api-key를 전달하세요. 키는 X-API-KEY 헤더로 전송됩니다.

pdfx에는 어떤 Node 버전이 필요한가요?#

Node 20.3 이상 또는 Bun입니다.

pdfx가 내 파일을 덮어쓰나요?#

디렉터리에 쓸 때는 덮어쓰지 않습니다. 기존 파일은 절대 교체되지 않습니다. -o file.pdf처럼 출력 파일 이름을 직접 지정하면 그 파일이 교체되므로, 원본을 남기고 싶다면 새 이름을 고르세요.

필터 도구에서 일치하는 것이 없으면 어떻게 되나요?#

필터 도구(ID가 filter-로 시작하는 도구)는 조건이 맞으면 파일을 그대로 통과시킵니다. 맞지 않으면 pdfx가 no match를 출력하고 종료 코드 0으로 끝납니다. 일괄 처리에서는 이런 파일이 실패가 아니라 불일치로 집계됩니다.