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.
| 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 |
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.