CLI pdfx: local primero, cloud cuando lo necesitas
pdfx procesa PDF en tu máquina por defecto. Activa el modo cloud con una base de API y una clave cuando necesites endpoints REST de PDF123, alojados o autoalojados.
PDF123 es el nombre del producto. pdfx es el CLI corto que habla con las mismas operaciones. La ruta predeterminada es local: leer un archivo, ejecutar la op con pdf-core y escribir la salida. Sin cuenta, sin clave de API y sin subida.
Local primero significa que el archivo no sale
Una llamada típica es pdfx merge a.pdf b.pdf -o merged.pdf o pdfx compress input.pdf. El procesamiento se ejecuta donde se ejecute el binario. Eso encaja con trabajos de CI en un runner privado, con scripts junto a un lote de facturas y con cualquier caso en el que subir el archivo a un tercero sea la respuesta equivocada.
El modo local no es una capa fina que envíe los bytes a otro sitio a escondidas. El CLI comparte el mismo registro de operaciones que el servidor (pdf_core::ops::run). Si quieres la vía de red, la habilitas con --cloud.
Los subcomandos incluidos cubren las ops habituales: merge, split, compress, rotate, extract, OCR, convert, protect, unlock, watermark y trabajo relacionado. La salida local va por defecto a un archivo con -o / --output; - escribe en stdout.
--cloud es el mismo catálogo por HTTP
Cuando necesites la API alojada (o tu propio pdfx-server), pasa --cloud junto con --api-base y --api-key (o PDFX_API_KEY). El modo cloud necesita curl por debajo y falla si no hay clave de API. Ejemplo de la skill publicada:
pdfx --cloud --api-base "$PDFX_API_BASE" --api-key "$PDFX_API_KEY" \
merge a.pdf b.pdf -o merged.pdf
--api-base vale https://pdf123.xyz por defecto, la API alojada. Para un stack local de Docker Compose, apúntalo a http://127.0.0.1:8080. El CLI pasa a ser un cliente de la superficie REST documentada en Desarrolladores; los nombres de op coinciden con las herramientas del portal y con OpenAPI (/v1/openapi.json).
El modo cloud no cambia lo que una op significa. Compress sigue siendo compresión de streams con qpdf y el OCR sigue devolviendo texto Markdown desde la ruta de Rust, no una capa PDF buscable. Los flags residuales del CLI que se corresponden con parámetros de OCR ignorados de la era Java (por ejemplo un campo languages) no alteran ese contrato.
Por qué existen dos modos
El modo local cubre la confianza offline y un coste de ida y vuelta nulo. El modo cloud cubre los límites de tasa compartidos, la ejecución en una máquina que solo tiene el CLI y curl instalados, y los equipos que ya emiten claves de API. Los agentes también pueden llamar a la misma base por MCP en /mcp o con la skill de dist/skills/pdf-toolbox/SKILL.md. Los índices de descubrimiento como /llms.txt ayudan a los agentes de código a encontrar endpoints; no son una señal de posicionamiento en Google.
Para reintentar con seguridad los POST que modifican datos contra la API, envía Idempotency-Key (ver Idempotency-Key: reintentos seguros para trabajos PDF). La vía cloud del CLI sigue siendo una petición HTTP por invocación; usa la cabecera cuando tu envoltorio reintente.
Cómo elegir el modo en la práctica
Usa local cuando los archivos deban quedarse en el runner, cuando ya tengas el binario pdfx y las dependencias nativas en esa máquina, y cuando la latencia dependa más de la op que de la subida. Usa cloud cuando las dependencias pesadas vivan solo en el servidor, cuando quieras los mismos límites de tasa y la misma medición que otros clientes de la API, o cuando los agentes ya tengan una clave para https://pdf123.xyz o para tu base autoalojada.
No mezcles expectativas: el OCR local sigue el contrato de salida Markdown de misc/ocr-pdf, y el compress en cloud siguen siendo streams de qpdf, no subsetting de fuentes. Cambiar de modo cambia dónde se ejecuta la op, no la semántica del catálogo.
Qué no es el CLI
pdfx no es una interfaz gráfica de escritorio ni una biblioteca de OCR que puedas enlazar en otra aplicación. Es un cliente de línea de comandos para operaciones con PDF: local por defecto y HTTP cuando lo pides. Las tareas puntuales en el navegador siguen en el portal (Comprimir, OCR y el resto del catálogo). La automatización que prefiera un binario puede quedarse con pdfx.
En La misma operación, cuatro clientes se comparan navegador, curl, MCP y CLI. Empieza por Desarrolladores para las claves y OpenAPI, o por Self-host si la base de API debe ser tu propio stack de Docker Compose.