pdfx: la línea de comandos de PDF123

¿Cómo instalo pdfx?#

Instala el paquete de forma global para obtener el comando pdfx. También puedes ejecutarlo una vez sin instalarlo.

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 y pnpm add -g @pdf123/cli también funcionan. No hace falta instalar nada más.

¿Cómo empiezo?#

Estos seis comandos muestran los patrones habituales.

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

¿Cómo ejecuto cualquier herramienta?#

El primer argumento es el id de la herramienta. Después van los archivos de entrada y las opciones de la herramienta. Cada opción de una herramienta es un indicador (flag), escrito con el nombre del campo de la API (--pageNumbers) o en kebab case (--page-numbers). Un número negativo puede ir tras su flag separado por un espacio, como en --rotation -90, o tras un signo igual.

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

Usa pdfx list para ver las herramientas. Acepta --category o --group, y --query con palabras para buscar. Usa pdfx describe <tool> para ver el endpoint, las entradas aceptadas, si la herramienta se ejecuta como lote y cada campo con su valor por defecto y sus valores permitidos. Un id de herramienta desconocido recibe sugerencias, y uno mal escrito termina con el código 2.

¿Qué comandos corresponden a cada página de herramienta?#

¿Cómo proceso muchos archivos a la vez?#

Si das varios archivos a una herramienta de un solo archivo, pdfx ejecuta un lote. Usa -o con un directorio que termine en barra. La herramienta se ejecuta una vez por archivo, de dos en dos por defecto. Cámbialo con --concurrency.

pdfx compress *.pdf -o compressed/
pdfx protect *.pdf --password secret --concurrency 4 -o locked/

pdfx imprime una línea, input -> saved, a medida que termina cada archivo. Un archivo que falla se notifica por la salida de error estándar y los demás se terminan igualmente. Pulsa Ctrl-C una vez para abortar la solicitud en curso; los archivos ya guardados se conservan. Un segundo Ctrl-C sale de inmediato con el código 130. Con --idempotency-key k, cada archivo envía k:<index>, y repetir la misma solicitud reproduce el primer resultado durante 24 horas.

Un lote de una herramienta que devuelve un informe, como get-info, no escribe archivos sin -o. Imprime los informes indexados por archivo de entrada.

¿Cómo encadeno herramientas en una sola solicitud?#

pdfx pipeline ejecuta varias herramientas en una sola solicitud. Repite --step para cada herramienta. Para definir opciones, pasa un array JSON con --steps.

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

Los pasos no pueden usar herramientas que necesiten un segundo archivo.

¿Cómo abro PDF protegidos con contraseña?#

--input-password abre primero todas las entradas cifradas. --password-for <file>=<password> define la contraseña de un archivo concreto. Se puede repetir, y * como nombre de archivo cubre el resto. Es útil para un lote que mezcla archivos bloqueados y abiertos. Con merge y images-to-pdf, cada archivo nombrado se desbloquea por separado antes de ejecutar la herramienta.

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

Las mismas opciones funcionan en un pipeline. Para quitar la protección de forma permanente, usa la herramienta Desbloquear con su propia opción --password.

¿Cómo funcionan la entrada y la salida?#

• Una entrada - lee la entrada estándar, una vez por ejecución. -o - escribe el resultado en la salida estándar.
• -o file.pdf escribe ese archivo. -o dir/ escribe dentro de un directorio. Un directorio que aún no existe necesita la barra final, porque un nombre sin ella se escribe como archivo.
• Sin -o, los resultados van al directorio actual con el nombre de archivo que da el servidor.
• Dentro de un directorio, pdfx nunca reemplaza un archivo existente; elige un nombre nuevo. Un -o file.pdf explícito sí reemplaza ese archivo.
• Un nombre de archivo de -o cuya extensión contradice el resultado, como un ZIP de split guardado como .pdf, se rechaza con el código de salida 2 y code: output_mismatch. No se escribe nada.
• Una salida que no se puede escribir es un error de uso detectado antes de subir nada.

cat in.pdf | pdfx compress - -o - > out.pdf

¿Qué imprime --json?#

Para un resultado guardado, --json imprime la ruta, el tipo de contenido y el tamaño. Una herramienta que devuelve un informe imprime el informe en sí. Un lote imprime un único informe con un estado por archivo.

{ "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 }
  ]
}

Un archivo fallido tiene error y reason en lugar de path y bytes. Una herramienta de filtro sin coincidencia imprime { "matched": false }. pdfx list --json imprime filas con id, category, group, name, description, returns, files y filter.

¿Qué opciones se aplican a todas las herramientas?#

¿Cuáles son los códigos de salida?#

Los fallos imprimen líneas reason:, code: y hint: cuando el servidor las proporciona, de modo que un script puede ramificar sin comparar texto. Una herramienta que no encuentra nada que devolver, como pdf-to-csv con un PDF sin tablas, termina con 1 y code: no_content en lugar de escribir un archivo vacío. Los códigos figuran en Códigos de error.

¿Cómo apunto pdfx a mi propio servidor?#

Define PDFX_API_BASE, o pasa --api-base, con la dirección de un pdfx-server autohospedado. Añade PDFX_API_KEY si tu servidor exige una clave. Consulta Autohospedaje.

export PDFX_API_BASE=http://localhost:8080
export PDFX_API_KEY=<your-key>
pdfx compress in.pdf

¿Cómo ejecuto un endpoint que la CLI no conoce?#

pdfx call envía una solicitud sin procesar a un id de operación o a una ruta /api/.... Usa --field name=value para los campos del formulario y --file field=path para archivos adicionales. Envía exactamente una solicitud y no valida nada en local, por lo que rechaza las contraseñas y los lotes.

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

Páginas relacionadas#

• Resumen para desarrolladores, con la API REST y la autenticación
• SDK de TypeScript, la biblioteca sobre la que se construye la línea de comandos
• Servidores MCP para agentes de IA
• La entrada «pdfx CLI: One Catalog, Called From Your Terminal» del blog de PDF123

Preguntas frecuentes#

¿pdfx funciona sin conexión?#

No. pdfx sube cada archivo a la API de PDF123 o a tu propio servidor y guarda el resultado en local, así que la base de la API debe ser accesible.

¿pdfx necesita una clave de API?#

No. Funciona de forma anónima. Define PDFX_API_KEY o pasa --api-key si tu servidor exige una. La clave se envía en la cabecera X-API-KEY.

¿Qué versión de Node necesita pdfx?#

Node 20.3 o superior, o Bun.

¿pdfx sobrescribirá mis archivos?#

No cuando escribe dentro de un directorio: un archivo existente nunca se reemplaza. Si nombras tú el archivo de salida con -o file.pdf, ese archivo sí se reemplaza, así que elige un nombre nuevo si quieres conservar el original.

¿Qué pasa cuando una herramienta de filtro no encuentra coincidencia?#

Las herramientas de filtro, cuyos ids empiezan por filter-, dejan pasar el archivo cuando se cumple su condición. Cuando no se cumple, pdfx imprime no match y termina con el código 0. En un lote, ese archivo cuenta como sin coincidencia, no como fallido.