Linha de comando

Um binário autocontido. A máquina não precisa de nada instalado antes — nem runtime, nem gerenciador de pacotes. É o que permite usá-lo numa imagem de CI enxuta.

curl -fsSL https://api.datarunner.app/downloads/cli/install.sh | bash

irm https://api.datarunner.app/downloads/cli/install.ps1 | iex

Nenhum dos dois pede root ou administrador: instala no diretório do usuário e ajusta o PATH dele. O instalador confere o SHA256 publicado antes de instalar e recusa se não bater.

Em CI, fixe a versão. Um pipeline que resolve “latest” a cada execução é um pipeline cujo comportamento muda sem ninguém ter feito um commit.

curl -fsSL https://api.datarunner.app/downloads/cli/install.sh | bash -s -- --version 0.1.1

Depois de instalar, isto é uma sessão inteira do começo ao fim. O passo que costuma faltar é o segundo: uma consulta tem um id, e listar é o único lugar de onde ele sai.

1. 01Entrar, uma vez por máquina. A chave sai do console em Configurações → Chaves de API, e só é mostrada no momento em que você a cria. O comando pede a chave sem mostrar na tela — ela nunca passa pela linha de comando nem fica no histórico do shell.
2. 02Listar o que existe no workspace. É daqui que sai o id que os outros comandos pedem.
3. 03Rodar uma consulta e olhar o resultado.
4. 04Transformar a consulta numa verificação que o build entende.

datarunner auth login

  → chave: ••••••••••••••••••••••••

  ✔ servidor respondeu       api.datarunner.app • 84 ms
  ✔ chave aceita             voce@acme.com • admin • Acme
  ✔ perfil 'default' salvo   cifrado para este usuário do Windows (DPAPI)

datarunner query list

id                                    nome             conexao     atualizada
────────────────────────────────────  ───────────────  ──────────  ──────────────
3f2a91c4-8e17-4b2a-9f03-1d5c7e8a2b60  Receita mensal   Postgres    2026-09-01 14:22
a7c04e12-3b95-4d81-b6ef-92a10c4d7f38  Pedidos orfaos   Postgres    2026-08-28 09:10

datarunner query run 3f2a91c4-8e17-4b2a-9f03-1d5c7e8a2b60

mes         total
──────────  ─────────
2026-07     184320.50
2026-08     201455.00

2 linha(s) em 340ms.

datarunner query assert a7c04e12-3b95-4d81-b6ef-92a10c4d7f38 --expect-empty

ok — 0 linha(s) em 120ms.

Esse último comando sai com código 0 quando não veio linha nenhuma e 1 quando veio. É isso, e só isso, que faz um pipeline parar quando a integridade dos dados quebrou.

A chave sai de Configurações → Chaves de API. Os escopos dela limitam o que a ferramenta alcança por cima do papel de quem a criou: uma chave restrita continua restrita mesmo pertencendo a um administrador, e nunca concede poderes de plataforma.

datarunner auth login
datarunner auth login --url https://datarunner.suaempresa.com   # servidor próprio

export DATARUNNER_URL=https://api.datarunner.app
export DATARUNNER_KEY=dr_...

Para rodar consultas num pipeline, marque o escopo run:queries. Ele já inclui a leitura e não permite alterar nada. Listar consultas e executar SQL contra um banco de produção são poderes diferentes, então read:queries sozinho não executa.

Chaves de API existem a partir do Team, então a linha de comando também — não no Solo nem no Pro.

Uma consulta que lista linhas órfãs é algo que qualquer pessoa escreve hoje e não consegue impor em lugar nenhum. Com o comando abaixo ela vira um passo do pipeline: se a migração quebrou a integridade referencial, o build falha, em vez de a produção descobrir depois.

datarunner query assert 3f2a... --expect-empty

Se o resultado bater no teto de linhas do plano, a verificação falha em vez de passar. Uma contagem cortada não é uma contagem, e um --expect-empty que passa porque o teto escondeu as linhas é pior que verificação nenhuma — alguém está confiando nele.

Cada comando tem ajuda própria: datarunner help query, datarunner help sync, e assim por diante. O comando datarunner help ci imprime um arquivo de pipeline pronto.

run:queries já inclui a leitura, então uma chave de CI que só verifica dados precisa apenas dele. Listar consultas e executar SQL contra um banco de produção são poderes diferentes — por isso read:queries sozinho não executa nada.

O primeiro reflexo de quem usa isto é apontar para homologação e depois para produção. Perfis existem para essa troca não ser um novo login.

datarunner auth login --url https://api.acme.dev --profile dev
datarunner auth login --url https://api.acme.com --profile prod

datarunner auth use prod
datarunner query list --profile dev    # sem trocar o atual

O arquivo fica em ~/.datarunner/config.json. No Windows a chave é cifrada com DPAPI para o seu usuário — o arquivo copiado para outra máquina, outra conta ou um backup não abre. No Linux e no macOS, permissão 600 num diretório 700. O logout remove o perfil da sua máquina; a chave continua válida no servidor até alguém revogá-la no console.

Digite só datarunner num terminal. A tela de abertura conecta ao servidor e mostra quem você é e em qual workspace está; depois fica um prompt que aceita os mesmos comandos sem o prefixo. Em script ou CI nada muda: sem terminal, o binário puro continua imprimindo a ajuda e saindo com 2.

datarunner:prod › query run Receita men⇥
datarunner:prod › query run 3f2a91c4-8e17-4b2a-9f03-1d5c7e8a2b60
→ Receita mensal (3f2a91c4)

• Tab completa comandos, opções e ids — pelo nome. A lista vem da API com as permissões da sua chave.
• Onde um comando pede id, vale também o nome ou o começo do id, dentro e fora do modo interativo. Se servir para mais de um, a CLI recusa e lista as opções em vez de escolher.
• Ctrl+C para o comando em andamento, não o shell. O histórico fica só na memória e nunca guarda linha com chave.

A CLI também é um servidor MCP (Model Context Protocol). Claude Desktop, Claude Code, Cursor e Windsurf passam a enxergar o workspace: conexões, esquemas, consultas salvas, SQL só de leitura, monitores, hosts, alertas e syncs. O agente faz no máximo o que a chave pode fazer — a permissão é conferida no servidor, igual ao console.

datarunner auth login
datarunner mcp install claude-desktop    # ou: cursor, windsurf, claude-code

datarunner mcp tools                     # o que o agente pode fazer com esta chave

• Nenhuma chave vai para o arquivo do cliente de IA: ele aponta para o perfil, que fica cifrado. O perfil vai fixado pelo nome, então um auth use prod depois não redireciona o agente para produção.
• Somente leitura por padrão. Reconhecer alerta, testar conexão e disparar sync nem aparecem para o modelo sem --allow-writes.
• Todo id é conferido antes de virar URL, as consultas têm limite por minuto e as instruções dizem ao modelo que o conteúdo dos bancos é dado, nunca instrução.

O SQL livre passa pelo mesmo caminho do editor do console: o servidor recusa comando destrutivo e aplica as políticas de mascaramento de coluna antes de o resultado chegar ao modelo.

O formato padrão é tabela. Passe --json ou --csv quando um programa for ler a saída — e é só nesse caso que o progresso sai pela saída de erro, para não sujar o que você está capturando. Não há adivinhação: o PowerShell reporta a saída como redirecionada mesmo num prompt comum, então tentar detectar isso dava JSON na cara de quem só queria olhar.

datarunner query run 3f2a... | jq '.rows[0]'
datarunner query run 3f2a... --format csv > receita.csv

A separação entre 1 e 4 é o ponto: um pipeline precisa distinguir “o dado está errado” de “a ferramenta está quebrada” sem interpretar texto.

• datarunner monitor status --fail-on-down — trava um deploy enquanto algo já está fora do ar.
• datarunner sync run <id> --wait — dispara um sync e acompanha até o fim. Sem --wait, “enfileirado” não é “funcionou”.
• datarunner query list, connection list, whoami.