> ## Content Index
> Fetch the complete content index at: https://blog.docutray.com/llms.txt
> Use this file to discover other available public pages before exploring further.

# Extracción de datos de PDFs desde el terminal: El CLI de DocuTray
- URL: https://blog.docutray.com/cli-docutray-extraccion-datos-pdf/
- Published: 2026-06-15T16:32:33.000Z
- Updated: 2026-06-16T19:30:45.000Z
- Author: Matías Sánchez Cabrera
- Tags: Document Processing, Guías

**Hoy lanzamos el CLI de** [**DocuTray**](https://www.docutray.com/?ref=blog.docutray.com). 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](https://docs.docutray.com/?ref=blog.docutray.com)).

**Instala el CLI así:**

```bash
npm install -g @docutray/cli

```

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

```bash
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:

Ejemplo de como usar el CLI de DocuTray

## **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](https://app.docutray.com/?ref=blog.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:

```bash
export DOCUTRAY_API_KEY="tu_key_aqui"
```

También puedes usar: 

```bash
docutray login
```

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

Verifica la autenticación con:

```bash
docutray status
```

Si el campo *authenticated* dice *true*, estás listo. El código del Skill está en [https://github.com/docutray/docutray-skills](https://github.com/docutray/docutray-skills?ref=blog.docutray.com) 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**

```bash
docutray identify documento.pdf
```

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

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

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

```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:

```JSON
{
  "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:

```bash
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."***

```bash
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**

```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**

```Typescript
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:

```bash
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](https://docs.docutray.com/docs/cli?ref=blog.docutray.com). 

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.