Conceitos do Lumo CLI

Tipo

Conceito

Para

Desenvolvedor, Analista

O Lumo CLI trata um Tenant como um diretório de arquivos YAML. Você muda o arquivo, o CLI leva a mudança ao servidor e traz de volta o que o servidor gravou. O ciclo para no push: ele grava no servidor, e quem publica é outro comando.

Workspace

O workspace é o diretório criado por lumo init <tenant-id>. Ele fica ligado a um Tenant só; para trabalhar em outro, crie outro workspace em outro diretório.

Cada recurso vira um arquivo <slug>--<id>.yaml na pasta do seu tipo: flows/fato-vendas--5101.yaml, apps/comercial--7302.yaml. As variáveis do Tenant são a exceção, num arquivo único, variables/tenant.yaml. A pasta .lumo/ guarda o workspace.json (Tenant e endereço da API) e o cache interno do CLI. Não edite nada dentro dela.

O workspace só traz o que o seu usuário pode editar: os recursos das Mesas a que você tem acesso, as conexões suas ou abertas a todos e os tipos que as suas funções permitem. Um tipo sem permissão aparece no lumo init como pulado, com o motivo. Um recurso que sai do seu acesso depois (uma Mesa revogada) continua no disco e aparece no lumo status como Out of scope: ele existe no servidor, só não é mais seu, e o push o ignora.

O arquivo

Todo arquivo tem dois documentos YAML separados por ---. O primeiro, o cabeçalho, diz o que o recurso é. O segundo, o corpo, é o que você edita.

id: 5101          # atribuído pelo servidor no lumo new
kind: flow
lumo: v2
tenantId: 1200
---
nome: Fato Vendas
load_type: Temporal
# ... o resto do corpo

O cabeçalho não muda depois que o recurso existe. Um arquivo com um documento só, ou com o cabeçalho e o corpo aninhados sob header: e body:, é recusado pelo lumo lint com dualdoc: missing body document. Os campos de cada tipo estão na referência YAML.

Alguns campos do corpo pertencem ao servidor, como _state, deskId, version e as datas de criação e publicação. Eles aparecem depois de um pull e são ignorados no push.

Três cópias de cada recurso

Cada recurso existe em três lugares, e os comandos de sincronização movem dados entre eles:

Cópia	Onde fica	Quem mexe
Arquivo (WORKING)	O YAML na pasta do tipo	Você ou o agente
Cache (STATE)	.lumo/state/, a versão do servidor na última sincronização	Só o CLI
Servidor (SERVER)	O Tenant	Todo mundo: você, a tela, outros usuários

O cache é o que permite ao CLI saber o que você mudou (arquivo diferente do cache) e o que outra pessoa mudou (servidor diferente do cache). Sem ele, um push apagaria em silêncio o trabalho de quem editou pela tela.

Comando	O que faz	Toca no arquivo?	Fala com o servidor?
lumo status	Lista o que difere entre arquivo e cache: Modified, Deleted, Untracked, Orphaned, Out of scope	Não	Não
lumo diff <tipo>:<id>	Mostra a diferença entre arquivo e cache. Com --include-remote, compara também com o servidor	Não	Só com --include-remote
lumo fetch	Atualiza o cache com o servidor	Não	Sim
lumo pull	Faz o fetch e sobrescreve o arquivo com o cache. Para com código de saída 4 se o arquivo tem mudança sua, a menos que você passe --discard-local	Sim	Sim
lumo push	Valida, confere se o servidor mudou desde o cache, grava e reescreve o arquivo com a resposta do servidor	Sim	Sim

Se o servidor mudou desde a última sincronização, o push para com código de saída 3 e mostra três saídas: ver a diferença, ficar com a versão do servidor ou sobrescrevê-la. Como escolher está em Drift e conflitos.

Depois de um push, o arquivo passa a ser o que o servidor guardou, que pode ter campos a mais (preenchidos pelo servidor) ou a menos (ignorados por serem dele). O push imprime essa diferença campo a campo.

Criar e remover

Recurso novo nasce no servidor primeiro: lumo new <tipo> cria, recebe o id e escreve o arquivo. Um YAML escrito do zero, ou copiado da saída de lumo scaffold, fica de fora: o CLI não tem cache dele, o lumo status o lista como Untracked e o push sem argumento não o envia. Use o scaffold como modelo para editar o arquivo que o new criou.

Apagar o arquivo não apaga o recurso: o lumo status o lista como Deleted, o push o ignora e o lumo pull o escreve de novo. Para remover no servidor, use lumo rm <tipo>:<id>, que apaga na hora e recusa com código de saída 13 se outro recurso depende dele (--cascade remove os dependentes junto).

Quando alguém apaga um recurso no servidor, o fetch deixa o arquivo no disco para você poder recuperar um erro, e o lumo status o lista como Orphaned. lumo pull --prune limpa todos de uma vez.

Rascunho e publicado

O push grava no servidor, mas nunca publica. Dataflows, Aplicações e Cadastros nascem na Minha Mesa, como rascunho, e só aparecem para os outros quando alguém os publica numa Mesa. O que é Minha Mesa e o que muda com a publicação está em Mesas e publicação. Cada tipo tem a sua regra:

Tipo	Publicar	Editar depois de publicado
flow	lumo flow publish flow:<id> --desk <dw-desk>	Não aceita push. Clone com lumo flow clone, edite o clone e publique por cima
table	Vai junto com o Dataflow que a alimenta	Aceita rótulo, máscara, comportamento padrão, descrição e papel das colunas, e a edição de expressões que já existem (sem criar nem remover). O esquema é do Dataflow
app	lumo app publish app:<id> --desk <bi-desk>	Aceita nome, descricao, icon, color, indicators, reports, filtros, filter_mode, allow_new_filters e os filtros de cada Dashboard. O resto (tabelas, expressões, relacionamentos, widgets e abas dos Dashboards) pede lumo app clone e publicação
writeback	lumo writeback publish writeback:<id> --desk <dw-desk>, uma vez	Continua editável por push
investigation	lumo investigation publish investigation:<id>	Sem volta: uma investigação publicada não volta a ser pessoal
deck, presentation	lumo deck publish, lumo presentation publish	Publicar aqui gera um link público /p/<código>, sem relação com Mesas

Credenciais, agendamentos, Agentes ETL, Mesas e variáveis não têm rascunho: o push vale na hora.

Publicar um clone por cima do original (o padrão) funde o clone no original e tira o clone do workspace. Com --new, o clone entra na Mesa como recurso novo, ao lado do original. Uma Aplicação só publica se as tabelas que ela usa já estiverem publicadas, e um agendamento só aceita Dataflows publicados.

Objetos instalados por um Template recusam edição e publicação por cima com TEMPLATE_PROTECTED. Para personalizar, clone e publique com --new. Veja Templates.

Referência a um recurso

Os comandos apontam para um recurso no formato tipo:id: flow:5101, table:6230, app:7302. Um número solto não basta, porque ids de tipos diferentes se repetem. lumo list <tipo> mostra os ids, e lumo info <tipo>:<id> mostra os detalhes de um recurso.

Relacionado

• Trabalhar com IA
• Drift e conflitos
• Comandos