Extracción de datos de PDFs desde el terminal: El CLI de DocuTray

Hoy lanzamos el CLI de DocuTray. Está pensado para que tu coding agent agregue capacidades de procesar documentos y extraer datos de PDF en tu aplicación, dándole la posibilidad de interactuar con DocuTray desde el terminal. Todo sin que tengas que leer nuestra documentación (que te recomendamos leer igual: https://docs.docutray.com).

Instala el CLI así:

npm install -g @docutray/cli

(Recomendado) Instala el Skill Si usas Claude Code, Codex, Cursor, u otro agente compatible con agent skills:

npx skills add docutray/docutray-skills

Con esto instalarás dos cosas:

• El CLI de DocuTray: comandos para identificar documentos, extraer datos como JSON estructurado y administrar schemas de extracción desde el terminal.
• El Skill de DocuTray: un paquete de instrucciones que le enseña a tu coding agent (Claude Code, Codex, Cursor, y otros) a usar el CLI por ti. Le pides "extrae los datos de estas facturas" y el agente sabe qué comandos usar.

Con esta herramienta vas a poder identificar el tipo de un documento, convertirlo a JSON, crear tus propios tipos de documento personalizados, e integrar todo esto en scripts Bash o en tu código con los SDKs de Python y Node que ya tenemos.

Te muestro un ejemplo de como usar el CLI en este video:

Configuración inicial

Arriba ya instalaste el CLI y el Skill. Para que funcionen necesitas una API key de DocuTray.

1. Crea una API key. En https://app.docutray.com, ve a Account > Organization Settings > API Keys y crea una nueva.

2. Autentica. La forma recomendada es la variable de entorno, porque funciona igual en tu terminal, en CI/CD, y para los agentes:

export DOCUTRAY_API_KEY="tu_key_aqui"

También puedes usar:

docutray login

para un login interactivo que guarda las credenciales en ~/.config/docutray/config.json.

Verifica la autenticación con:

docutray status

Si el campo authenticated dice true, estás listo. El código del Skill está en https://github.com/docutray/docutray-skills por si quieres ver qué le enseña a tu agente.

¿En qué lo puedo usar?

La idea es simple: le hablas a tu agente en lenguaje natural y él corre los comandos del CLI por ti. Estos son los casos más comunes, con lo que le pides al agente y lo que termina ejecutando por debajo.

Identificar y convertir un documento

docutray identify documento.pdf

{
  "success": true,
  "data": {
    "document_type": "invoice",
    "confidence": 0.95
  }
}

Con confianza sobre 0.9 usa el tipo directo. Después convierte:

docutray convert documento.pdf --type invoice --output resultado.json

{
  "success": true,
  "data": {
    "document_type": "invoice",
    "fields": {
      "invoice_number": "INV-2024-001",
      "date": "2024-03-15",
      "total": 1500.00,
      "vendor": "Acme Corp"
    }
  }
}

Soporta PDF, JPEG, PNG, entre otros, con un máximo de 100MB por documento.

Crear un tipo de documento personalizado

Si tu documento no calza con ningún tipo público (un formato interno de tu empresa, un documento de tu industria), defines uno propio. Acá es donde el Skill más se nota.

Le dices a tu agente: "Crea un tipo de documento para estas liquidaciones de sueldo. Te dejo dos ejemplos. Quiero extraer el RUT, el periodo, y el sueldo líquido."

El agente te hace un par de preguntas (¿hay datos en tabla?, ¿qué formato tienen las fechas?) y arma el schema:

{
  "type": "object",
  "required": ["rut_empleado", "periodo", "sueldo_liquido"],
  "properties": {
    "rut_empleado": {
      "type": ["string", "null"],
      "description": "RUT del empleado, esquina superior del documento"
    },
    "periodo": {
      "type": ["string", "null"],
      "format": "date",
      "description": "Mes de la liquidación"
    },
    "sueldo_liquido": {
      "type": ["number", "null"],
      "description": "Monto líquido a pagar, al final del documento"
    }
  }

Y lo registra:

docutray types create \
  --name "Liquidación de sueldo" \
  --code liquidacion_sueldo \
  --description "Liquidación de sueldo mensual" \
  --schema liquidacion_schema.json \
  --prompt-hints "Montos en pesos sin decimales, con punto como separador de miles."

Dos detalles que el agente cuida y que marcan la diferencia en la calidad de extracción:

• Las descripciones de cada campo son instrucciones para el modelo. Descripciones como "Monto líquido a pagar, al final del documento" funciona mucho mejor para que la conversión sea exitosa. Indica dónde está el valor y cómo desambiguarlo.
• Los prompt hints dan contexto global del documento: formato de fechas, separadores decimales, idioma. Evitan errores sistemáticos como interpretar 1.500 como 1,5.

Desde ahí pruebas el tipo con un documento real, y si algo no sale bien, le pides al agente que ajuste el schema y lo vuelva a probar. Iterar es parte del proceso.

Procesar una carpeta completa

Cuando no es un documento sino cientos, el agente arma el batch.

Le dices: "Convierte todas las facturas de esta carpeta a JSON, un JSON por documento."

for f in documentos/*.pdf; do
  docutray convert "$f" --type invoice --output "${f%.pdf}.json"
done

Como el CLI devuelve JSON por stdout con exit codes claros, el agente puede encadenarlo con otras herramientas (por ejemplo `jq`) o exportar todo a CSV con `--format csv` si el destino final es una planilla.

Integrar el procesamiento en tu aplicación

Cuando el prototipo se convierte en producto, le pides al agente que integre DocuTray directo en tu código. Mismos tipos de documento, mismos schemas, ahora vía SDK.

Le dices: "Agrega extracción de facturas a mi app." El agente decide la integración según tu stack.

Python

from docutray import Client

client = Client()  # lee DOCUTRAY_API_KEY del entorno
result = client.convert(file_path="factura.pdf", document_type="invoice")
print(result.data)

Node

import { DocuTray } from "docutray";

const client = new DocuTray();
const result = await client.convert({
  filePath: "factura.pdf",
  documentType: "invoice",
});
console.log(result.data);

Y si tu stack no es ninguno de los dos, queda la API REST directa, sin instalar nada:

curl -X POST \
  -H "Authorization: Bearer $DOCUTRAY_API_KEY" \
  -F "file=@factura.pdf" \
  -F "document_type=invoice" \
  https://app.docutray.com/api/convert

Resumiendo

Instalas el CLI, autenticas con una API key, identificas tus documentos contra el catálogo de tipos públicos, y si no calzan, creas un tipo personalizado con su schema. Desde ahí, la extracción de datos es un comando que puedes meter en un script, un cron, un pipeline de CI, o delegar completo a tu agente con el Skill.

La documentación completa del CLI está en https://docs.docutray.com/docs/cli.

Si lo pruebas y algo no funciona como esperabas, escríbenos: el CLI está en beta y el feedback de los primeros usuarios es lo que más lo mejora.