CLI pdfx: un solo catálogo, invocado desde tu terminal
El CLI pdfx envía las mismas peticiones multipart que curl a la API de PDF123 o a tu propio pdfx-server, y añade ejecuciones por lotes, contraseñas por archivo y códigos de salida sobre los que un script puede ramificar.

PDF123 es el nombre del producto. pdfx es ese mismo catálogo de operaciones envuelto para un shell: construye la petición multipart que habría construido curl, la envía a la base de API que elijas y escribe el resultado junto a tus archivos. Combinar, Comprimir, OCR y el resto del catálogo se pueden llamar así.
Qué envía realmente una llamada
pdfx --api-base "$API_BASE" --api-key "$PDFX_API_KEY" \
merge a.pdf b.pdf -o merged.pdf
--api-base vale https://pdf123.xyz por defecto, y --api-key (o la variable de entorno PDFX_API_KEY) es opcional, así que el catálogo anónimo funciona sin ella. Apunta la base a http://127.0.0.1:8080 para un stack de docker-compose propio. Debajo no hay un segundo protocolo: el CLI es un cliente de la superficie REST documentada en Desarrolladores, y los nombres de sus operaciones coinciden con las herramientas del portal y con el documento OpenAPI en /v1/openapi.json.
El catálogo se puede descubrir sin salir de la terminal. pdfx list imprime todas las herramientas y pdfx describe add-stamp imprime los campos y los valores por defecto de una, que es la misma definición que el portal renderiza como formulario.
Ejecuciones por lotes y los flags que curl te obliga a escribir
Da varios archivos de entrada a una herramienta de un solo archivo y los ejecuta como un lote dentro del directorio -o, imprimiendo una línea input -> saved por archivo. Los fallos van a stderr y los archivos restantes terminan igualmente, así que un PDF defectuoso en una carpeta de facturas no aborta la ejecución. --concurrency <n> fija cuántos archivos están en vuelo a la vez (por defecto 2).
-o acepta un archivo o un directorio y nunca sobrescribe un archivo existente: dentro del directorio usa el nombre que da el servidor. Eso importa cuando el servidor nombra el resultado a partir de la entrada; sin ello, una ejecución machacaría el PDF que acabas de subir.
Las entradas cifradas se abren antes de la petición, no por la herramienta: --input-password cubre todos los archivos de la ejecución, y --password-for report.pdf=secret fija la contraseña de un archivo y puede repetirse, con * en lugar del resto. Un lote que mezcla archivos bloqueados y abiertos no necesita ordenarse a mano. --json imprime { path, contentType, bytes } por resultado, o [{ input, ok, path | error, reason }] para un lote, de modo que un envoltorio puede parsear el desenlace en lugar de raspar las líneas legibles.
Códigos de salida sobre los que un script puede ramificar
0 significa éxito, 1 significa que falló una petición (en un lote: al menos un archivo), 2 es un error de uso en el que no se subió nada, y 130 significa que lo interrumpiste y la petición en vuelo se abortó. Los fallos imprimen líneas reason:, code: y hint: bajo el mensaje siempre que estén disponibles, y eso es lo que un script debería comparar, no la prosa.
Un código de salida se malinterpreta con facilidad. Una herramienta que no encuentra nada que devolver sale con un código distinto de cero y code: no_content en lugar de escribir un archivo vacío, así que pdf-to-csv sobre un PDF sin tablas es un fallo, no un CSV de cero bytes.
A dónde van los bytes
Los archivos se suben a la base de API, se procesan allí y se eliminan en cuanto se envía la respuesta. Es el mismo contrato que el formulario del navegador; el CLI cambia el cliente, no el destino. Para documentos que no deben salir de tu red, ejecuta tú un pdfx-server y apunta --api-base a él, algo que se cubre en Self-host.
No hay un modo offline al que recurrir: si la base no está accesible, el comando falla. pdfx es un cliente de red que resulta agradable en un shell, no un motor PDF local.
Qué no es el CLI
pdfx no es una interfaz gráfica de escritorio ni una biblioteca de OCR embebible que enlazar en otra aplicación. Es un cliente de línea de comandos para operaciones con PDF, así que una tarea humana puntual sigue estando mejor servida por el portal (Comprimir, OCR y el resto del catálogo), y cualquier cosa que necesite un árbol de interfaz propio recrearía el problema de deriva que se describe en La misma operación, cuatro clientes.
Los agentes obtienen las mismas formas de la skill publicada en /skills/pdf123.md, que documenta por completo las peticiones de combinación y de pipeline. Para reintentar con seguridad POST que modifican datos, envía Idempotency-Key; el CLI sigue haciendo una petición por invocación, así que la cabecera corresponde a quien lo reintente (Idempotency-Key: reintentos seguros para trabajos PDF). Las claves, los límites de tasa y los códigos de error están en Desarrolladores.