Saltar a contenido

El CLI

tai-storage viene con una línea de comandos para lo que se hace a mano mientras se monta un ETL: comprobar que las credenciales funcionan, ver qué hay en una carpeta, saber cómo se va a leer un fichero y sacar el informe de unos datos. Tiene la misma forma que tai-sql y tai-api.

tai-storage --help
Comando Qué hace
ping Conecta con los orígenes configurados y dice qué falla
ls Lista una carpeta de cualquier origen
read Cómo lee get_data() un fichero: su informe y las primeras filas
analyze El informe HTML de un fichero
rules Las reglas para asistentes de IA de la versión instalada

Cómo se nombra un fichero

Los comandos reciben un origen y una ruta:

sharepoint:Clientes/Entrada/pedidos.xlsx     la biblioteca de las variables SHAREPOINT_*
azure:2026/10/db.dump                        el container de AZURE_STORAGE_CONTAINER
googledrive:informes                         la raíz de GOOGLE_DRIVE_ROOT_FOLDER_ID
local:/datos/ventas.csv                      el disco
/datos/ventas.csv, ./datos                   lo mismo: sin prefijo, es una ruta local

Los orígenes remotos se crean con StorageFactory y sus variables de entorno, igual que en el código. C:\datos o informe:2024.csv no se confunden con un origen: solo cuentan los cuatro prefijos de arriba.

Las opciones comunes

Opción Qué hace
--env-file .env Carga las variables de un .env antes de crear los orígenes, sin pisar las que ya haya. La librería no lee .env por su cuenta; el CLI, solo si se le pide
-v, -vv Enseña los logs de la librería: -v lo que cambia algo, -vv además cada petición. Sin ella, el CLI solo cuenta lo suyo
--debug La traza completa si ocurre un error interno
--version La versión instalada
-h, --help La ayuda, en cualquier comando
tai-storage --env-file .env -v ls sharepoint:Clientes

Los errores y los códigos de salida

Un problema que puedes arreglar sale con qué ha pasado y qué hacer, sin traza, y con las opciones del CLI en la solución:

$ tai-storage read ventas.csv -c importe=float

❌ 1 valor de la columna 'importe' no es un número: 'pendiente' (línea 4, columna 3)
   💡 Corrige esos valores en el fichero, declara otro tipo o formato para la columna, o pasa -O errors=null para dejarlos vacíos
Salida Cuándo
0 Ha ido bien
1 Un problema con arreglo (credenciales, una ruta, un fichero que no se puede leer, un extra que falta), o rules check / ping con algo pendiente
2 Un error de uso: una opción que no existe, un argumento que falta
70 Un fallo de tai-storage: el mensaje dice cómo reportarlo, y --debug enseña la traza
130 Cancelado con Ctrl-C
141 La salida se ha cerrado antes de terminar (tai-storage ls … \| head)

ping

tai-storage ping                    # todos los orígenes con alguna variable definida
tai-storage ping sharepoint azure   # solo esos, aunque les falte configuración
🔌 Conectando…

   ✅ SharePoint contoso.sharepoint.com/sites/Ventas (1,2 s)
   ❌ Azure Blob Storage: No existe el container 'backups' en Azure Blob micuenta/backups
      💡 Créalo en el portal de Azure, o pasa create_container=True

❌ 1 de 2 orígenes no responde

Es lo primero que se mira cuando un ETL no arranca en un servidor nuevo: dice qué variable falta, qué credencial rechaza el servicio o qué sitio no existe. Sale con 1 si alguno falla, así que vale también como comprobación en un despliegue.

ls

tai-storage ls sharepoint:Clientes/Entrada
tai-storage ls azure:2026 -r -p '\.dump$'
tai-storage ls ./datos
📂 'Clientes/Entrada' de SharePoint contoso.sharepoint.com/sites/Ventas

                                2024/
   2026-09-30 10:12     1,2 MB  pedidos_septiembre.xlsx
   2026-10-01 08:03   812,4 KB  pedidos_octubre.xlsx

2 ficheros · 1 carpeta · 2,0 MB
Opción Qué hace
-r, --recursive Incluye las subcarpetas (y enseña la ruta de cada fichero)
-p, --pattern Expresión regular buscada en el nombre, sin distinguir mayúsculas

Las fechas, en hora local. El tamaño y la fecha vienen del listado: no cuesta una petición más por fichero.

read

Cómo va a leer get_data() un fichero, antes de escribir el ETL:

tai-storage read sharepoint:Clientes/Entrada/pedidos.xlsx --sheet Pedidos --entrypoint Código
tai-storage read ./export.csv -c importe=float -c cp=string -n 20
📄 'ventas.csv' de Local /home/ana/proyecto/datos/entrada

   ventas.csv · csv · utf-8 · separador ';'
   3 filas (1 fila en blanco descartada)
   columna  en el fichero  tipo     vacíos  notas
   codigo   1              string   0       texto: tiene ceros a la izquierda, como '001' (línea 2, columna 1): es un código
   cliente  2              string   0
   importe  3              string   0       texto: 'pendiente' (línea 4, columna 3) no es un número en formato 'es'
   fecha    4              date     0
   cp       5              string   0       texto: tiene ceros a la izquierda, como '08001' (línea 2, columna 5): es un código
   col_6    6              string   0
   activo   7              boolean  0
   ⚠️  la columna 6 no tiene nombre en la cabecera: se llama 'col_6'

     codigo cliente   importe      fecha     cp col_6  activo
   0    001     Ana  1.234,50 2024-01-31  08001     x    True
   1    002    Luis     12,00 2024-02-01  28001     y   False
   … 1 fila más

Lo que salga aquí es lo que hará el ETL con los mismos parámetros. Las opciones son las de get_data():

Opción Parámetro
--sheet sheet_name
--entrypoint entrypoint
--sep, --encoding sep, encoding
--format format (si la extensión no lo dice)
--en number_format="en" y date_format="en"
--no-infer infer_types=False
-c COLUMNA=TIPO columns={...}; se repite. Tipos: string, integer, float, boolean, date, datetime
-O CLAVE=VALOR Cualquier otro; se repite. El valor admite JSON: -O 'with_fields=["codigo","importe"]', -O height=20, -O errors=null
-n, --rows Las filas que se enseñan (10 por defecto; 0, ninguna)

Necesita el extra data.

analyze

El informe HTML de un fichero, sin escribir código:

tai-storage analyze sharepoint:Clientes/Entrada/pedidos.xlsx --sheet Pedidos -k id_pedido
tai-storage analyze ./ventas.csv -o sharepoint:Informes/ventas.html
📊 'ventas.csv' de Local /home/ana/proyecto/datos/entrada: 3 filas × 7 columnas
   2 avisos: 2 baja
   [baja] 'codigo' tiene valores con ceros a la izquierda: es un código, no lo conviertas en número
   [baja] 'cp' tiene valores con ceros a la izquierda: es un código, no lo conviertas en número

✅ Informe guardado en 'ventas.html' de Local /home/ana/proyecto
Opción Qué hace
-o, --output Dónde guardarlo: una ruta local o origen:ruta. Por defecto, <nombre>.html en el directorio actual
-k, --key La columna que debería identificar cada fila; se repite para una clave compuesta
--title El título (por defecto, el nombre del fichero)
--cdn Plotly desde su CDN: unos 100 KB en vez de 5 MB, pero necesita internet al abrirlo
--no-overwrite Falla si el informe ya existe

Admite también las opciones de lectura de read. Necesita los extras data y analysis.