Academy
CLI y MCP

CLI Dattos: instalación y primeros pasos

CLI Dattos: instalación y primeros pasos

La CLI Dattos es la interfaz de línea de comandos de la plataforma, diseñada para operar Dattos mediante scripts, pipelines de automatización y agentes de inteligencia artificial. Toda la salida está en JSON (fácil de procesar en cualquier lenguaje o con jq), los errores se muestran estructurados con orientación para corregirlos, y la misma instalación incluye también el SDK de Python y el servidor MCP para asistentes de inteligencia artificial.

Cuándo la CLI es la opción adecuada. Cuando el procedimiento ya se conoce y debe repetirse de la misma manera: ejecución programada, pipeline de automatización o replicación de un proceso entre entornos. La salida en JSON y los códigos de salida (0 éxito, 1 error de la API, 2 error de autenticación o configuración) permiten que el script se detenga por sí solo en el punto exacto en el que algo falló. Si el camino depende de lo que se encuentre —por ejemplo, investigar por qué una conciliación no cuadró— o si quien va a operar no es técnico, MCP es una opción más adecuada: consulta "Conectar asistentes de inteligencia artificial mediante MCP".

Requisitos e instalación

  • Dattos 16.4 o superior. Es la versión mínima de la plataforma; dattos doctor confirma la versión de tu instancia.

  • Python 3.11 o superior, en cualquier sistema operativo.

  • Instala con pip:

pip install dattos

  • Comprueba la instalación:

dattos version

La instalación proporciona tres comandos: dattos (la CLI), dattos-mcp (servidor MCP para asistentes de inteligencia artificial) y dattos-mcp-http (variante del servidor para uso hospedado).

¿Vas a utilizar el servidor MCP local? Instálalo con los complementos: pip install "dattos[mcp,security]". Sin ellos, el comando dattos-mcp se instala, pero no se inicia. Para conectar asistentes en la nube, no necesitas nada de esto; consulta "Conectar asistentes de inteligencia artificial mediante MCP".

Genera tu clave de API

Accede a Mi perfil > Claves de API, crea una clave nueva y copia el valor generado; comienza con api-. La clave se muestra una sola vez.

La clave hereda los permisos del usuario que la generó: las carpetas, pantallas y niveles de aprobación siguen su perfil de privacidad. Revocar la clave en la misma pantalla corta el acceso de cualquier integración que la utilice, y la operación no se puede deshacer.

Guarda la clave en variables de entorno

Este es el patrón recomendado. La clave no queda guardada en un archivo del proyecto, no se repite en el historial de la terminal y no corre el riesgo de llegar al control de versiones. También es el mecanismo que ya utilizan los servidores de automatización y los contenedores.

Son cuatro variables, dos obligatorias:

  • DATTOS_API_URL — obligatoria. La dirección completa: https://sua-empresa.dattos.com.br/dattos.api.

  • DATTOS_API_KEY — obligatoria. La clave que acabas de generar.

  • DATTOS_FOLDER_ID — opcional. Carpeta predeterminada de todos los comandos.

  • DATTOS_PROFILE — opcional. Perfil activo.

Las variables de entorno tienen precedencia sobre cualquier otra configuración de la CLI. Es decir, siempre prevalecen.

Las instrucciones siguientes guardan las variables de forma permanente, para tu usuario en el equipo; las configuras una vez y serán válidas para siempre, en cualquier terminal que abras después.

En Windows — mediante la interfaz (más sencillo)

  1. Abre Inicio y escribe editar variables de entorno.

  2. Haz clic en Editar las variables de entorno de tu cuenta. (Esta opción corresponde a tu usuario y no solicita una contraseña de administrador).

  3. En el cuadro superior, Variables de usuario, haz clic en Nuevo....

  4. En Nombre de la variable, escribe DATTOS_API_URL. En Valor de la variable, pega https://sua-empresa.dattos.com.br/dattos.api. Haz clic en Aceptar.

  5. Haz clic en Nuevo... otra vez. Ahora, en Nombre de la variable, escribe DATTOS_API_KEY y, en Valor de la variable, pega tu clave (api-...). Haz clic en Aceptar.

  6. Haz clic en Aceptar para cerrar las ventanas restantes.

En Windows — mediante PowerShell (alternativa)

Si prefieres la línea de comandos, abre PowerShell y ejecuta los dos comandos, sustituyendo los valores por los tuyos:

[Environment]::SetEnvironmentVariable("DATTOS_API_URL", "https://sua-empresa.dattos.com.br/dattos.api", "User")
[Environment]::SetEnvironmentVariable("DATTOS_API_KEY", "api-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "User")

En Linux y macOS

Añade las dos líneas al archivo de inicio de tu terminal: ~/.bashrc si utilizas bash, o ~/.zshrc si utilizas zsh (el estándar en macOS). Abre la Terminal y ejecuta:

echo 'export DATTOS_API_URL="https://sua-empresa.dattos.com.br/dattos.api"' >> ~/.bashrc
echo 'export DATTOS_API_KEY="api-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"' >> ~/.bashrc
source ~/.bashrc

Comprueba si funcionó

En Windows: abre Inicio, escribe cmd y abre el Símbolo del sistema. Escribe el comando siguiente y pulsa Intro:

echo %DATTOS_API_KEY%

En Linux o macOS: abre la Terminal, escribe el comando siguiente y pulsa Intro:

echo "$DATTOS_API_KEY"

En ambos casos, tu clave debería aparecer en pantalla. Si aparece el texto del comando (o no aparece nada), la variable no se guardó; repite los pasos.

Abre una terminal nueva. Las ventanas de terminal que ya estaban abiertas antes de guardar las variables no reciben los valores. Ciérrala y vuelve a abrirla antes de realizar la prueba.

En automatizaciones (Jenkins, GitHub Actions, Azure DevOps), guarda la clave en el almacén de secretos de la propia herramienta e inyéctala como variable de entorno. Nunca escribas la clave en el archivo del pipeline. Si utilizas un archivo .env dentro de un proyecto, inclúyelo en .gitignore antes de escribir la clave en él.

Otras formas de autenticarse

Todas las opciones siguientes dependen del almacén de credenciales del sistema operativo (Windows Credential Manager, macOS Keychain o Secret Service en Linux), que requiere instalar el complemento [security]:

pip install "dattos[security]"

  • Guardar en la configuración de la CLI — dattos config set api-url "sua-empresa" y dattos config set api-key "api-...". En api-url basta con indicar el nombre de la instancia: la CLI lo completa con la dirección completa.

  • Inicio de sesión interactivo — dattos auth login se autentica con usuario y contraseña y genera un token de sesión. dattos auth login --browser abre la página de claves de API en el navegador para que puedas crear y pegar la clave.

  • Comprobar y limpiar — dattos auth status muestra el método activo; dattos auth logout elimina las credenciales.

Sin el almacén disponible, estas opciones no se comportan como se espera. En un servidor sin sesión gráfica, o si el complemento [security] no está instalado: dattos config set api-key guarda la clave en texto plano en el archivo ~/.dattos/config.json, y dattos auth login informa de que se realizó correctamente sin guardar la credencial. Para confirmar que la clave se guardó en el almacén, comprueba que la respuesta de config set incluya "storage": "keyring". En servidores y automatizaciones, utiliza variables de entorno; es la opción recomendada precisamente porque no depende del almacén.

Conceptos básicos

  • Carpetas: buena parte de las operaciones se ejecuta en el contexto de una carpeta de ejecución. Selecciónala con dattos folders select (lista interactiva) y compruébala con dattos folders current.

  • Perfiles: para quienes trabajan con más de una instancia o entorno, dattos config profile list y dattos config profile switch <nome> permiten alternar configuraciones completas.

  • Salida y errores: resultados en JSON en stdout; errores en JSON en stderr, con el campo next_step indicando el comando que los resuelve y el correlation_id para contactar con soporte. Códigos de salida: 0 éxito, 1 error de la API, 2 error de autenticación o configuración; listos para controlar el flujo en scripts.

  • Diagnóstico: dattos doctor valida de una vez la configuración, la conectividad, la autenticación, la versión de la instancia y la carpeta activa. Con --deep, también prueba los servicios de inteligencia artificial de la plataforma. Es el primer comando que debes ejecutar cuando algo no funciona.

  • Glosario de estados: dattos status-glossary explica cualquier estado devuelto por la plataforma. Úsalo antes de interpretar un estado en un script.

Primer flujo completo

Crea una conciliación con la ayuda de Dattos AI y ejecútala directamente desde la terminal:

dattos folders select 2473
dattos etl create --name "Conciliação Vendas"
dattos etl add-source --etl 891 --file vendas.xlsx
dattos etl add-source --etl 891 --file extrato.csv
dattos etl pipeline create "Conciliar vendas com extrato por valor e data" --etl 891
dattos etl start 891 --date 2026-06-30 --wait

El orden es importante: el comando etl pipeline create necesita al menos una fuente de datos ya añadida. Si se ejecuta antes, indica exactamente qué paso falta.

Y consulta el resultado:

dattos etl execution-status 891 --date 2026-06-30
dattos matching status 891 <loadId> <matchingId>
dattos reports generate 891 --load-id <loadId> --dataset-id <datasetId> --format xlsx

El catálogo completo de comandos se encuentra en el artículo "CLI Dattos: comandos y capacidades".

Artículos relacionados

¿Te fue útil?
¿Te fue útil?