pdfx CLI: 기본은 로컬, 필요할 때 클라우드
pdfx는 기본적으로 사용자 머신에서 PDF를 처리하며 파일을 업로드하지 않습니다. 호스팅 또는 자체 호스팅 PDF123 REST 엔드포인트가 필요할 때 API base와 키로 클라우드 모드를 켭니다.
PDF123은 제품 이름입니다. pdfx는 같은 연산에 연결하는 짧은 CLI입니다. 기본 경로는 로컬입니다. 파일을 읽고, pdf-core로 op를 돌리고, 출력을 씁니다. 계정도 API 키도 업로드도 없습니다.
기본이 로컬이라는 것은 파일이 떠나지 않는다는 뜻
전형적인 호출은 pdfx merge a.pdf b.pdf -o merged.pdf나 pdfx compress input.pdf입니다. 처리는 바이너리가 실행되는 곳에서 돌아갑니다. 사설 러너의 CI 작업, 청구서 묶음 옆에 놓인 스크립트, 제3자에게 업로드하는 것이 애초에 틀린 답인 경우에 맞습니다.
로컬 모드는 바이트를 몰래 다른 곳에 POST하는 얇은 껍데기가 아닙니다. CLI는 서버와 같은 연산 레지스트리(pdf_core::ops::run)를 공유합니다. 네트워크 경로를 원하면 --cloud로 직접 켭니다.
내장 하위 명령이 흔한 op를 다룹니다. merge, split, compress, rotate, extract, OCR, convert, protect, unlock, watermark 등입니다. 로컬 출력은 기본적으로 -o / --output으로 파일에 쓰고, -는 stdout입니다.
--cloud는 HTTP로 같은 카탈로그
호스팅 API(또는 직접 돌리는 pdfx-server)가 필요하면 --cloud와 함께 --api-base, --api-key(또는 PDFX_API_KEY)를 넘깁니다. 클라우드 모드는 내부적으로 curl을 쓰며 API 키가 없으면 실패합니다. 공개된 skill의 예입니다.
pdfx --cloud --api-base "$PDFX_API_BASE" --api-key "$PDFX_API_KEY" \
merge a.pdf b.pdf -o merged.pdf
--api-base를 지정하지 않으면 기본값은 https://pdf123.xyz, 즉 호스팅 API입니다. 로컬 Docker Compose 스택에서는 http://127.0.0.1:8080을 가리키면 됩니다. CLI는 개발자에 문서화된 REST 표면의 클라이언트가 되고, op 이름은 포털 도구 및 OpenAPI(/v1/openapi.json)와 맞춰집니다.
클라우드 모드가 op의 의미를 바꾸지는 않습니다. 압축은 여전히 qpdf 스트림 압축이고, OCR은 검색 가능한 PDF 레이어가 아니라 Rust 경로에서 Markdown 텍스트를 반환합니다. 무시되는 Java 시대 OCR 매개변수(예: languages 필드)에 대응하는 남은 CLI 플래그가 이 계약을 바꾸지 않습니다.
두 모드가 있는 이유
로컬은 오프라인 신뢰와 왕복 비용 제로를 담당합니다. 클라우드는 공유 요청 제한, CLI와 curl만 설치된 머신에서의 op 실행, 이미 API 키를 발급하는 팀을 담당합니다. 에이전트는 /mcp의 MCP나 dist/skills/pdf-toolbox/SKILL.md의 skill로 같은 base를 호출할 수도 있습니다. /llms.txt 같은 발견 색인은 코딩 에이전트가 엔드포인트를 찾도록 돕습니다. Google 순위 신호는 아닙니다.
API의 변경형 POST를 안전하게 재시도하려면 Idempotency-Key를 보냅니다(Idempotency-Key: PDF 작업의 안전한 재시도). CLI 클라우드 경로는 호출당 HTTP 요청 하나입니다. 래퍼가 재시도할 때 이 헤더를 쓰세요.
실무에서 모드 고르기
파일이 러너에 남아야 하고, 그 머신에 pdfx 바이너리와 네이티브 의존성이 이미 있고, 지연 시간이 업로드보다 op에 좌우될 때 로컬을 씁니다. 무거운 의존성이 서버에만 있거나, 다른 API 클라이언트와 같은 요청 제한과 계량을 원하거나, 에이전트가 이미 https://pdf123.xyz 또는 자체 호스팅 base의 API 키를 들고 있을 때 클라우드를 씁니다.
기대를 섞지는 마세요. 로컬 OCR도 misc/ocr-pdf의 Markdown 출력 계약을 따르고, 클라우드 압축도 폰트 서브셋팅이 아니라 qpdf 스트림입니다. 모드 전환이 바꾸는 것은 op가 어디서 도는지이지 카탈로그의 의미가 아닙니다.
CLI가 아닌 것
pdfx는 데스크톱 GUI가 아니고, 다른 앱에 링크하는 임베디드 OCR 라이브러리도 아닙니다. PDF 연산을 위한 명령줄 클라이언트이며, 기본은 로컬이고 요청할 때만 HTTP를 씁니다. 브라우저에서 한 번 쓰는 작업은 포털에 남습니다(PDF 압축, OCR 그리고 카탈로그의 나머지). 바이너리를 선호하는 자동화는 pdfx에 머물 수 있습니다.
브라우저, curl, MCP, CLI 사이의 같은 op 비교는 같은 연산, 네 개의 클라이언트에 정리돼 있습니다. 키와 OpenAPI는 개발자에서, API base를 직접 돌리는 Docker Compose 스택으로 두려면 자체 호스팅에서 시작하세요.