Buscar K
Aparência
Referência de Comandos
Referência completa dos comandos do Lumo CLI. Use lumo <comando> --help para a ajuda detalhada de qualquer um: a tabela abaixo lista o que existe, o --help explica cada flag em detalhe.
TIP
Termos como tipo de carga (--context), mesa, rascunho/publicado e star schema estão explicados na página de Conceitos.
TIP
A maioria dos comandos aceita referências no formato tipo:id - por exemplo: flow:42, table:23913, app:7, credential:539. Nunca passe um número avulso; sempre inclua o prefixo do tipo.
Por onde começar
A tabela de comandos é exaustiva e ordenada alfabeticamente, o que é ótimo para procurar e péssimo para aprender. Esta seção dá a ordem em que os comandos costumam aparecer no trabalho real. Ela não repete o que cada comando faz nem quais flags ele aceita: isso está na tabela, gerada do próprio código.
1. Entrar. lumo auth login, depois lumo tenants list para achar o tenant e lumo init <tenant-id> para criar o workspace no diretório atual. lumo auth status confirma a sessão.
2. Olhar antes de mexer. lumo status mostra o que mudou localmente. lumo list <tipo> enumera recursos, lumo info <tipo>:<id> abre um, lumo columns table:<id> mostra as colunas de uma tabela DW e lumo diff <tipo>:<id> mostra a mudança pendente. Todos são de leitura e seguros para repetir.
3. Sincronizar. lumo fetch verifica o servidor sem tocar nos seus arquivos; lumo pull traz as mudanças para eles; lumo push envia as suas. lumo lint valida o YAML contra o schema, e o push já roda o lint sozinho antes de enviar.
4. Criar e remover. lumo new <tipo> cria um recurso novo; lumo rm <tipo>:<id> remove.
5. Clonar, editar, publicar. Recurso publicado é somente leitura. O ciclo é sempre clone (vira rascunho seu) → editar → publish (volta a ser compartilhado). Vale para flows (lumo flow clone / lumo flow publish, numa mesa de dados) e para apps (lumo app clone / lumo app publish, numa mesa de aplicação).
WARNING
Publicar é uma decisão humana. Um recurso publicado fica somente leitura e é compartilhado com outros usuários. Construa e itere como rascunho; publique apenas quando o trabalho estiver pronto.
6. Executar. lumo flow run dispara um flow publicado; lumo flow run-node executa um nó isolado de um rascunho. lumo flow status e lumo flow logs acompanham, lumo flow cancel interrompe. Do outro lado, lumo schedule run / pause / resume controla o agendamento, e lumo agent restart o agente.
7. Variáveis. lumo variables list / get / set / unset mexem no workspace local; lumo push variables envia ao servidor.
Todos os comandos
Tabela completa, gerada a partir do Use, do Short e das flags de cada comando cobra em cmd/lumo/*.go, na main do lumo-cli. É a única lista de comandos desta documentação: não existe uma segunda tabela escrita à mão para divergir dela.
| Comando | Descrição | Flags |
|---|---|---|
lumo agent | Agent management & investigation: link, restart, migrate, events, health | - |
lumo agent events <agent:id> | List problem schedule-events for an agent (missed/late/error/crashed) | --status |
lumo agent health <agent:id> | Show the agent's 24h health pulse (uptime, memory, jobs, queue, timeline) | --range --full --mac |
lumo agent link | Link an external agent to this tenant via its token | --token --name |
lumo agent migrate | Bulk-rebind flows and credentials to another agent | --flows --credentials --to-agent --force |
lumo agent restart <agent:id> | Force a remote agent to restart | - |
lumo app | BI app operations: query, export, open | - |
lumo app change-table <app:id> | Swap a table reference inside an app to a compatible one | --from-table --to-table --dry-run --force |
lumo app clone <app:id> | Clone an app under a new name | --name |
lumo app dashboard-preview <app:id> | Run each widget's query and return data + visual JSON (no PNG render) | --dashboard --widget --filter --limit --sql-only --debug-sql |
lumo app export <app:id> | Export a dashboard as PNG/PDF/SVG | --dashboard --image-format --output --dark-theme --landscape |
lumo app export-widget <app:id> | Export a single widget as PNG | --dashboard --widget --image-format --output --dark-theme |
lumo app open <app:id> | Open the app in the browser (or print the URL) | --no-browser |
lumo app publish <app:id> | Publish an app to a desk (drift-protected via If-Match) | --desk --new |
lumo app query <app:id> | Run a BI engine query against an app | --fields --filter --order-by --limit --sql-only |
lumo auth | Authentication commands | - |
lumo auth login | Log in to Horus BI | --email --password --otp --local |
lumo auth logout | Log out and clear stored credentials | - |
lumo auth status | Show current authentication status | - |
lumo backup | Snapshot the local workspace as a tar.gz | --output --exclude-state |
lumo columns <table:id> | List the columns of a DW table | - |
lumo credential | Credential operations: test, query, schema, transfer | - |
lumo credential query <credential:id> | Run an ad-hoc SQL query against the source | --sql --limit --timeout |
lumo credential schema <credential:id> | List schemas / tables / columns visible through this credential | --schema --timeout |
lumo credential test <credential:id> | Test connectivity to the source via its agent | - |
lumo credential transfer <credential:id> | Rebind the credential to a different agent | --to-agent |
lumo diff <resource> | Show diff between WORKING / STATE / SERVER | --include-remote --field |
lumo fetch [resource...] | Refresh STATE from the server (does not modify WORKING) | --parallel --full |
lumo flow | Imperative flow operations: clone, publish, run, node-level execution | - |
lumo flow cancel | Cancel a running flow execution | --execution --force |
lumo flow clone <flow:id> | Clone a flow under a new name | --name --dry-run |
lumo flow export-node <flow:id> | Export a node's output as a downloadable artifact | --node |
lumo flow force-batch | Dispatch a batch of flows in dependency order (a template apply's reloadPlan) | --from-reload-plan |
lumo flow logs <flow:id> | Show execution history for a flow | - |
lumo flow nodes <flow:id> | List nodes of a flow (internalId + kind + description) for run-node lookup | --type |
lumo flow preview-node <flow:id> | Preview a node's output rows without writing | --node |
lumo flow publish <flow:id> | Publish a flow to a desk (drift-protected via If-Match) | --desk --new --copy-data --dry-run |
lumo flow run <flow:id> | Trigger a flow execution | --wait --context --temporal-days |
lumo flow run-node <flow:id> | Execute a single node (write side-effects) | --node --wait |
lumo flow status <flow:id> | Show runtime status for a flow (running / idle / queued) | - |
lumo flow sync-table <flow:id> | Create or sync a flow's DW table from its InsertDatawarehouse node | --node --name |
lumo info <flow|table|app|credential|dw-desk|bi-desk|schedule|agent>:<id> | Show read-only metadata and runtime status for a resource | --full --dependents --field |
lumo init <tenant-id> [<dir>] | Bootstrap a workspace for a Horus BI tenant | --recover --fetch-only |
lumo lint [file...] | Validate dual-document YAML files against the v2 schemas | --strict |
lumo list <kind> | List resources of a kind (flow, table, app, credential, dw-desk, bi-desk, schedule, agent, variables) | --search --desk --remote --limit --offset |
lumo log [resource] | Show audit log of sync operations | --count --limit --since --operation --errors |
lumo new <flow|table|app|credential|schedule|dw-desk|bi-desk> | Create a new resource on the server (eager: server-first → STATE → WORKING) | - |
lumo new app | Create a new BI application | --name --table |
lumo new bi-desk | Create a new application desk (publish target for apps) | --name |
lumo new credential | Create a new HEC credential | --name --type |
lumo new dw-desk | Create a new data desk (publish target for flows / tables) | --name |
lumo new flow | Create a new flow | --name --load-type |
lumo new schedule | Create a new schedule | --name --cron |
lumo new table | Create a new DW table - must combine --from-flow + --node (workflow C) | --name --from-flow --node --from-node |
lumo pull [resource...] | Refresh STATE then overwrite WORKING with the cached payload | --discard-local --no-fetch --parallel --dry-run |
lumo push [resource...] | Save local edits to the server | --dry-run --no-lint --parallel --continue-on-error --force-ours --i-know-what-im-doing --force-recreate |
lumo rm <flow|table|app|credential|schedule|dw-desk|bi-desk|agent>:<id> | Delete a resource on the server and locally | --force --yes --cascade --dry-run |
lumo scaffold [<kind> [<variant>]] | Print embedded YAML reference + examples for any Lumo kind | --variant |
lumo scaffold ls | Flat list of every embedded scaffold (kind.variant - tagline) | - |
lumo schedule | Schedule operations: run, pause, resume, logs | - |
lumo schedule logs <schedule:id> | List recent trigger executions for a schedule | --since --tail |
lumo schedule pause <schedule:id> | Pause a schedule (sets ativo=false) | - |
lumo schedule resume <schedule:id> | Resume a schedule (sets ativo=true) | - |
lumo schedule run <schedule:id> | Trigger a schedule one-shot | - |
lumo status | Show local-modified, deleted, and untracked resources | --summary --filter |
lumo table | Table operations: truncate, preview | - |
lumo table clone <table:id> | (not supported) - clone the FLOW that owns the table instead | - |
lumo table preview <table:id> | Preview rows from the DW table | --limit |
lumo table truncate <table:id> | Remove all rows from the DW table (schema preserved) | --force --yes --dry-run |
lumo tenants | Tenant discovery | - |
lumo tenants list | List tenants available to the authenticated user | - |
lumo update | Atualiza o lumo para a última versão (binário + skills) | --check |
lumo variables | Tenant variable operations: list, get, set, unset | - |
lumo variables get <key> | Read one variable by key | --remote |
lumo variables list | List all tenant variables | --remote |
lumo variables set <key>=<value> | Create or update a tenant variable | --from-stdin |
lumo variables unset <key> | Remove a tenant variable | - |
lumo version | Print build information | - |
Códigos de Saída
Retirados de cmd/lumo/errors.go e dos pontos onde o CLI de fato os retorna.
| Exit | Significado | Primeira ação |
|---|---|---|
| 0 | Sucesso (inclui "nada a fazer" e "sem diff") | - |
| 1 | Erro genérico. O lumo diff também usa 1 no sentido Unix: "há diff" | Leia a mensagem em stderr. Vindo do diff, é resultado, não erro |
| 2 | Erro de uso | Leia lumo <cmd> --help |
| 3 | Servidor mudou desde sua última sincronização | lumo diff <r> e escolha pull / merge / --force-ours |
| 4 | Conflito local + servidor | Mesclagem manual |
| 5 | Recurso não encontrado | Verifique tipo:id; talvez lumo fetch |
| 6 | Problema de auth/acesso | lumo auth login; se o acesso mudou, re-execute lumo init <tenant-id> |
| 7 | Rede/timeout, retriável | Execute novamente o mesmo comando |
| 8 | Lint/schema falhou | Leia o caminho; corrija o YAML |
| 9 | Validação do servidor falhou | Leia a mensagem; comum: FLOW_READONLY (clone primeiro), SCHEDULE_UNPUBLISHED_FLOW |
| 10 | Servidor 5xx | Transitório. Tente uma vez; se persistir, pare e reporte |
| 11 | Workspace já inicializado no diretório, ou vinculado a outro tenant. Só o lumo init retorna este código | lumo init <tenant-id> --recover para reaproveitar o .lumo/ que já está lá, ou escolha outro diretório |
| 12 | Recurso ainda não sincronizado localmente | lumo fetch <r> primeiro |
| 13 | rm bloqueado por dependências | Execute com --cascade ou remova os dependentes primeiro |
| 14 | Pré-condição (If-Match) falhou | lumo fetch, re-edite e faça push novamente |
| 15 | Aplicação parcial: o servidor ignorou ao menos 1 campo | Workspace já auto-corrigido; leia o diff no stdout e corrija a causa raiz |
| 20 | lumo update precisa de privilégio | Execute a ação que o comando imprime (ex.: sudo lumo update) |
| 21 | lumo update falhou (rede/checksum/IO) | Tente novamente; se persistir, verifique a conectividade |
NOTE
São seguros para retry: comandos de leitura (status, info, list, columns, diff, log, fetch). Não são seguros para retry cego: imperativos (new, push, clone, publish, run, rm, truncate). O estado pode ter mudado, resolva antes de tentar novamente.
Flags Globais
Valem para qualquer comando. Geradas de root.PersistentFlags() em cmd/lumo/root.go.
| Flag | Descrição |
|---|---|
--debug | verbose debug output to stderr |
--format | output format: text | json | yaml (yaml is honored by info and diff; other commands fall back to text or json) |
--no-color | disable colored output |
--no-input | disable interactive prompts |
--server | API base URL (overrides workspace.json) |
--workspace | workspace path (default: walk up from PWD) |
Além destas, o cobra adiciona --help (-h) a todo comando.