Product약 2분

pdfx CLI: 하나의 카탈로그를 터미널에서 호출하기

pdfx CLI는 curl과 같은 multipart 요청을 PDF123 API나 직접 운영하는 pdfx-server로 보내고, 배치 실행, 파일별 비밀번호, 스크립트가 분기할 수 있는 종료 코드를 더한다.

By the PDF123 team · Updated 2026-09-29
pdfx CLI: 하나의 카탈로그를 터미널에서 호출하기

PDF123은 제품 이름입니다. pdfx는 같은 연산 카탈로그를 셸에 맞게 감싼 것으로, curl이 만들 multipart 요청을 대신 만들어 선택한 API base로 보내고 결과를 파일 옆에 씁니다. PDF 병합, PDF 압축, OCR을 비롯한 카탈로그의 나머지도 이렇게 호출할 수 있습니다.

호출 하나가 실제로 보내는 것

pdfx --api-base "$API_BASE" --api-key "$PDFX_API_KEY" \
  merge a.pdf b.pdf -o merged.pdf

--api-base는 기본값이 https://pdf123.xyz이고 --api-key(또는 환경 변수 PDFX_API_KEY)는 선택 사항이라, 익명 카탈로그는 키 없이도 동작합니다. 직접 운영하는 docker-compose 스택에는 base를 http://127.0.0.1:8080으로 지정하세요. 아래에 다른 프로토콜은 없습니다. CLI는 개발자에 문서화된 REST 표면의 클라이언트이고, op 이름은 포털 도구와 /v1/openapi.json의 OpenAPI 문서에 맞춰집니다.

카탈로그는 터미널을 벗어나지 않고도 확인할 수 있습니다. pdfx list는 모든 도구를, pdfx describe add-stamp는 한 도구의 필드와 기본값을 출력합니다. 포털이 폼으로 렌더링하는 것과 같은 정의입니다.

배치 실행과 curl에서는 직접 써야 하는 플래그

단일 파일 도구에 입력을 여러 개 주면 -o 디렉터리로 배치 실행하고 파일마다 input -> saved 줄을 하나씩 출력합니다. 실패는 stderr로 가고 나머지 파일은 계속 끝까지 처리됩니다. 청구서 폴더에서 PDF 하나가 깨져도 실행 전체가 멈추지 않습니다. --concurrency <n>은 동시에 처리할 파일 수를 정합니다(기본값 2).

-o는 파일이나 디렉터리를 받고 기존 파일을 절대 덮어쓰지 않으며, 디렉터리일 때는 서버가 붙인 파일 이름을 그 안에서 씁니다. 서버가 입력을 따라 결과 이름을 정할 때 이 점이 중요합니다. 이것이 없으면 방금 업로드한 PDF를 덮어쓰게 됩니다.

암호화된 입력은 도구가 아니라 요청 전에 열립니다. --input-password는 실행의 모든 파일을 포괄하고, --password-for report.pdf=secret은 한 파일의 비밀번호를 지정하며 반복할 수 있고 *는 나머지 전부를 대신합니다. 잠긴 파일과 열린 파일이 섞인 배치도 수동으로 분류할 필요가 없습니다. --json은 결과마다 { path, contentType, bytes }를, 배치에는 [{ input, ok, path | error, reason }]를 출력하므로 래퍼는 사람이 읽는 줄을 긁어모으는 대신 결과를 파싱할 수 있습니다.

스크립트가 분기할 수 있는 종료 코드

0은 성공, 1은 요청 실패(배치에서는 파일이 하나 이상), 2는 아무것도 업로드되지 않은 사용법 오류, 130은 중단해서 진행 중이던 요청이 취소되었음을 뜻합니다. 실패는 가능할 때 메시지 아래에 reason:, code:, hint: 줄을 출력합니다. 스크립트가 문장이 아니라 이 줄과 대조해야 합니다.

읽기 쉬운 함정이 하나 있습니다. 돌려줄 것이 없는 도구는 빈 파일을 쓰는 대신 code: no_content와 함께 0이 아닌 코드로 끝납니다. 표가 없는 PDF에 pdf-to-csv를 돌리면 실패이지, 0바이트 CSV가 아닙니다.

바이트는 어디로 가는가

파일은 API base로 업로드되어 그곳에서 처리되고, 응답이 전송되면 삭제됩니다. 브라우저 폼과 같은 계약입니다. CLI가 바꾸는 것은 클라이언트이지 목적지가 아닙니다. 네트워크를 벗어나면 안 되는 문서라면 pdfx-server를 직접 띄우고 --api-base를 그곳으로 지정하세요. 자체 호스팅에서 다룹니다.

기댈 오프라인 모드는 없습니다. base에 닿을 수 없으면 명령은 실패합니다. pdfx는 셸에서 쓰기 편할 뿐인 네트워크 클라이언트이지, 로컬 PDF 엔진이 아닙니다.

CLI가 아닌 것

pdfx는 데스크톱 GUI가 아니고 다른 앱에 링크하는 임베디드 OCR 라이브러리도 아닙니다. PDF 연산을 위한 명령줄 클라이언트입니다. 그래서 사람이 한 번 쓰는 작업은 여전히 포털(PDF 압축, OCR, 카탈로그의 나머지)이 낫고, 자체 UI 트리가 필요한 것은 같은 연산, 네 개의 클라이언트에서 설명한 드리프트 문제를 다시 만듭니다.

에이전트는 /skills/pdf123.md의 공개 skill에서 같은 형태를 얻습니다. 이 문서는 merge와 pipeline 요청을 전부 기록합니다. 변경형 POST를 안전하게 재시도하려면 Idempotency-Key를 보내세요. CLI는 호출마다 요청 하나만 보내므로, 이 헤더는 재시도하는 쪽에 속합니다(Idempotency-Key: PDF 작업의 안전한 재시도). 키와 요청 제한, 오류 코드는 개발자에 있습니다.

Open tool
Process in the browser — no watermark, files removed after the job.
Open tool