Documentação HorusBI
Buscar K

Aparência

Abrir no Claude Abrir no ChatGPT

Primeiros Passos com o Lumo CLI ​

O Lumo foi feito para ser operado por um agente de IA (Claude Code, Codex…). Seu papel é preparar o terreno — três passos que você faz uma vez, por fora — e a partir daí é só conversar com a IA, que comanda o lumo por você.

O que você faz (uma vez):

  1. 💻 Instalar o lumo
  2. 🔑 Autenticar (lumo auth login) — é a sua sessão
  3. 🤖 Instalar a skill no seu agente

Depois disso: converse com a IA. Ela inicializa o workspace, cria e edita os recursos, roda os flows e monta os dashboards.

NOTE

O acesso ao Lumo CLI é controlado por permissão. Um administrador precisa conceder a função "Uso do Lumo CLI" ao seu usuário antes que você consiga autenticar. Entre em contato com o administrador do tenant caso receba um erro de acesso negado.

TIP

Não conhece os termos do HorusBI (flow, tabela DW, mesa, tipo de carga)? Comece pela página de Conceitos — ela liga cada recurso do Lumo à explicação completa do conceito.

1. 💻 Instalação ​

Instalação rápida (recomendado) ​

O caminho recomendado em todas as plataformas é o instalador remoto: um comando que detecta seu sistema e arquitetura (amd64 ou arm64), baixa o binário, verifica o checksum e instala o lumo no seu PATH.

bash
curl -fsSL https://storage.horusbi.com.br/download/lumo/install.sh | bash
powershell
irm https://storage.horusbi.com.br/download/lumo/install.ps1 | iex

Alternativa para Windows: instalador gráfico (.exe) ​

Se você prefere um instalador com duplo-clique em vez da linha de comando, baixe o LumoCLI-Setup.exe — ele coloca o lumo no PATH automaticamente.

NOTE

O instalador .exe é compilado apenas para Windows x64. Em Windows ARM, use a instalação rápida acima ou o pacote LumoCLI-windows-arm64.zip do download manual — ambos entregam o binário nativo arm64. Não use o instalador x64 no ARM: ele rodaria só sob emulação.

Download manual ​

Prefere baixar o pacote e instalar à mão? Pegue o arquivo do seu sistema:

SistemaDownload
Linux (amd64)LumoCLI-linux-amd64.tar.gz
Linux (arm64)LumoCLI-linux-arm64.tar.gz
macOS (Intel)LumoCLI-darwin-amd64.tar.gz
macOS (Apple Silicon)LumoCLI-darwin-arm64.tar.gz
Windows (amd64)LumoCLI-windows-amd64.zip
Windows (arm64)LumoCLI-windows-arm64.zip

Extraia o pacote e coloque o binário lumo em um diretório presente no seu PATH. Para conferir a integridade, compare com o checksums.txt.

Verificar a instalação ​

bash
lumo --help

2. 🔑 Autenticação ​

Faça login com suas credenciais HorusBI:

bash
lumo auth login

O CLI solicitará seu e-mail e senha interativamente. A sessão fica armazenada localmente.

IMPORTANT

O login é seu e fica por fora da IA. A IA não tem suas credenciais — ela apenas usa a sessão que você abriu aqui. Faça este passo você mesmo no terminal.

TIP

Em máquinas compartilhadas ou pipelines de CI/CD, defina a variável de ambiente LUMO_PASSWORD em vez de usar --password na linha de comando. Isso evita que a senha apareça no histórico do shell ou em logs de processo.

Para verificar o status da sessão:

bash
lumo auth status

Para encerrar a sessão:

bash
lumo auth logout

3. 🤖 Instale a skill no seu agente ​

A skill ensina o agente a operar o lumo corretamente. É o que permite pedir as coisas em linguagem natural.

Baixe o instalador de skills, rode, e ele detecta seu agente automaticamente — o passo a passo completo (Claude Code, Codex e instalação manual) está em Integrações com IA.

TIP

Antes de instalar a skill, garanta que o lumo já está instalado e autenticado (passos 1 e 2). A skill usa o lumo; ela não o instala.

4. 💬 A partir daqui, é com a IA ​

Com CLI instalado, sessão ativa e skill no agente, abra o seu agente na pasta onde quer o workspace e converse. Você não precisa rodar comandos: a IA inicializa o workspace, cria e edita recursos, roda flows e monta dashboards.

Um bom primeiro pedido para confirmar que tudo está conectado:

Verifique minha sessão do Lumo, inicialize o workspace do tenant <tenant-id> e liste meus flows.

A partir daí, aprenda a colaborar bem com ela: Trabalhando com a IA (o que é seu vs. da IA, dicas de prompt) e Revisando o trabalho da IA (como conferir o que ela fez).

5. ⚙️ Operação manual (referência) ​

Você normalmente não precisa desta seção — a IA roda estes comandos por você. Ela serve para quem quer operar à mão, automatizar em CI, ou apenas entender o que acontece nos bastidores.

Um workspace é um diretório local que espelha um tenant. O ciclo é:

bash
lumo tenants list                 # ver tenants disponíveis
lumo init <tenant-id> ./meu-tenant # criar o workspace (cria flows/, tables/, apps/…)
cd ./meu-tenant

lumo status                       # o que mudou localmente
# editar YAML em flows/, tables/, apps/, …
lumo lint flows/meu-flow.yaml     # validar antes de enviar
lumo push                         # enviar ao servidor (reescreve o YAML com a resposta canônica)

lumo fetch                        # ver mudanças do servidor sem alterar arquivos
lumo pull                         # trazer mudanças do servidor para os arquivos

TIP

Use Git para versionar o workspace — é a rede de segurança para revisar e desfazer o que a IA faz. O CLI já ignora os arquivos internos; só os seus YAMLs e o workspace.json ficam versionados.

bash
cd ./meu-tenant
git init && git add . && git commit -m "checkpoint: init tenant <tenant-id>"

A referência completa de comandos e flags está em Referência de Comandos.

6. ⬆️ Mantendo o CLI Atualizado ​

O Lumo verifica periodicamente se há uma versão nova disponível e exibe um aviso no stderr quando há:

⬆  lumo vX.Y.Z disponível (atual: vA.B.C) — rode: lumo update

Para atualizar:

bash
lumo update

Para verificar se há atualização sem instalar:

bash
lumo update --check

Se o diretório do binário exigir permissão elevada, o comando para e instrui a ação exata (ex.: sudo lumo update) com exit code 20.

Para silenciar o aviso de atualização, defina a variável de ambiente:

bash
export LUMO_NO_UPDATE_NOTIFIER=1

🔗 Próximos Passos ​