Academy
CLI e MCP

CLI Dattos: instalação e primeiros passos

CLI Dattos: instalação e primeiros passos

A CLI Dattos é a interface de linha de comando da plataforma — feita para operar a Dattos por scripts, pipelines de automação e agentes de inteligência artificial. Toda saída é em JSON (fácil de tratar em qualquer linguagem ou com jq), os erros saem estruturados com orientação de correção, e a mesma instalação traz também o SDK Python e o servidor MCP para assistentes de inteligência artificial.

Quando a CLI é o caminho certo. Quando o passo a passo já é conhecido e precisa repetir igual: execução agendada, pipeline de automação, replicar um processo entre ambientes. A saída em JSON e os códigos de saída (0 sucesso, 1 erro da API, 2 erro de autenticação ou configuração) permitem que o script pare sozinho no ponto exato em que algo falhou. Se o caminho depende do que for encontrado — investigar por que uma conciliação não bateu, por exemplo — ou se quem vai operar não é técnico, o MCP atende melhor: veja "Conectar assistentes de inteligência artificial via MCP".

Requisitos e instalação

  • Dattos 16.4 ou superior. É a versão mínima da plataforma; dattos doctor confirma a versão da sua instância.

  • Python 3.11 ou superior, em qualquer sistema operacional.

  • Instale com o pip:

pip install dattos

  • Confira a instalação:

dattos version

A instalação disponibiliza três comandos: dattos (a CLI), dattos-mcp (servidor MCP para assistentes de inteligência artificial) e dattos-mcp-http (variante do servidor para uso hospedado).

Vai usar o servidor MCP local? Instale com os complementos: pip install "dattos[mcp,security]". Sem eles, o comando dattos-mcp é instalado mas não inicia. Para conectar assistentes na nuvem, nada disso é necessário — veja "Conectar assistentes de inteligência artificial via MCP".

Gere a sua chave de API

Acesse Meu Perfil > Chaves de API, crie uma nova chave e copie o valor gerado — ele começa com api-. A chave é exibida uma única vez.

A chave carrega as permissões do usuário que a gerou: pastas, telas e níveis de aprovação seguem o perfil de privacidade dele. Revogar a chave na mesma tela corta o acesso de qualquer integração que a utilize, e a operação não pode ser desfeita.

Guarde a chave em variáveis de ambiente

Este é o padrão recomendado. A chave não fica gravada em arquivo de projeto, não se repete no histórico do terminal e não corre o risco de ir para o controle de versão. É também o mecanismo que servidores de automação e contêineres já usam.

São quatro variáveis, duas obrigatórias:

  • DATTOS_API_URL — obrigatória. O endereço completo: https://sua-empresa.dattos.com.br/dattos.api.

  • DATTOS_API_KEY — obrigatória. A chave que você acabou de gerar.

  • DATTOS_FOLDER_ID — opcional. Pasta padrão de todos os comandos.

  • DATTOS_PROFILE — opcional. Perfil ativo.

As variáveis de ambiente têm precedência sobre qualquer outra configuração da CLI. Ou seja, elas sempre ganham.

As instruções abaixo gravam as variáveis permanentemente, no seu usuário da máquina — você configura uma vez e vale para sempre, em qualquer terminal que abrir depois.

No Windows — pela interface (mais simples)

  1. Abra o Iniciar e digite editar variáveis de ambiente.

  2. Clique em Editar variáveis de ambiente para a sua conta. (Esta opção é a do seu usuário e não pede senha de administrador.)

  3. No quadro de cima, Variáveis de usuário, clique em Novo....

  4. Em Nome da variável, escreva DATTOS_API_URL. Em Valor da variável, cole https://sua-empresa.dattos.com.br/dattos.api. Clique OK.

  5. Clique em Novo... outra vez. Agora em Nome da variável escreva DATTOS_API_KEY e em Valor da variável cole a sua chave (api-...). Clique OK.

  6. Clique OK para fechar as janelas restantes.

No Windows — pelo PowerShell (alternativa)

Se preferir a linha de comando, abra o PowerShell e rode os dois comandos, trocando os valores pelos seus:

[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")

No Linux e no macOS

Acrescente as duas linhas ao arquivo de inicialização do seu terminal — ~/.bashrc se você usa bash, ou ~/.zshrc se usa zsh (o padrão no macOS). Abra o Terminal e rode:

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

Confira se funcionou

No Windows: abra o Iniciar, digite cmd e abra o Prompt de Comando. Digite o comando abaixo e pressione Enter:

echo %DATTOS_API_KEY%

No Linux ou macOS: abra o Terminal, digite o comando abaixo e pressione Enter:

echo "$DATTOS_API_KEY"

Nos dois casos, a sua chave deve aparecer na tela. Se aparecer o próprio texto do comando (ou nada), a variável não foi gravada — repita os passos.

Abra um terminal novo. Janelas de terminal que já estavam abertas antes de você gravar as variáveis não recebem os valores. Feche e abra de novo antes de testar.

Em automações (Jenkins, GitHub Actions, Azure DevOps), guarde a chave no cofre de segredos da própria ferramenta e injete-a como variável de ambiente. Nunca escreva a chave no arquivo do pipeline. Se usar um arquivo .env dentro de um projeto, inclua-o no .gitignore antes de escrever a chave nele.

Outras formas de autenticar

Todas as opções abaixo dependem do cofre de credenciais do sistema operacional (Windows Credential Manager, macOS Keychain ou Secret Service no Linux), que exige a instalação com o complemento [security]:

pip install "dattos[security]"

  • Salvar na configuração da CLI — dattos config set api-url "sua-empresa" e dattos config set api-key "api-...". No api-url basta o nome da instância: a CLI completa para o endereço inteiro.

  • Login interativo — dattos auth login autentica com usuário e senha e gera um token de sessão. dattos auth login --browser abre a página de chaves de API no navegador para você criar e colar a chave.

  • Conferir e limpar — dattos auth status mostra o método ativo; dattos auth logout remove as credenciais.

Sem o cofre disponível, estas opções não se comportam como esperado. Em servidor sem sessão gráfica, ou se o complemento [security] não estiver instalado: o dattos config set api-key grava a chave em texto puro no arquivo ~/.dattos/config.json, e o dattos auth login informa sucesso sem guardar a credencial. Para confirmar que a chave foi para o cofre, verifique se a resposta do config set traz "storage": "keyring". Em servidores e automações, use variáveis de ambiente — é o caminho recomendado justamente por não depender do cofre.

Conceitos básicos

  • Pastas: boa parte das operações roda no contexto de uma pasta de execução. Selecione com dattos folders select (lista interativa) e confira com dattos folders current.

  • Perfis: para quem trabalha com mais de uma instância ou ambiente, dattos config profile list e dattos config profile switch <nome> alternam configurações completas.

  • Saída e erros: resultados em JSON no stdout; erros em JSON no stderr, com o campo next_step indicando o comando que resolve e o correlation_id para acionar o suporte. Códigos de saída: 0 sucesso, 1 erro da API, 2 erro de autenticação ou configuração — prontos para controle de fluxo em scripts.

  • Diagnóstico: dattos doctor valida configuração, conectividade, autenticação, versão da instância e pasta ativa de uma vez. Com --deep, testa também os serviços de inteligência artificial da plataforma. É o primeiro comando a rodar quando algo não funciona.

  • Glossário de status: dattos status-glossary explica qualquer status devolvido pela plataforma. Use antes de interpretar um status em script.

Primeiro fluxo completo

Criar uma conciliação com o apoio do Dattos AI e executá-la, direto do 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

A ordem importa: o comando etl pipeline create precisa de ao menos uma fonte de dados já adicionada. Chamado antes, ele avisa exatamente qual passo falta.

E consultar o 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

O catálogo completo de comandos está no artigo "CLI Dattos: comandos e capacidades".

Artigos relacionados

Isso foi útil?
Isso foi útil?