AEGIS CLI

Orquestração da frota AEGIS pela linha de comando. Um produto da Safe Core.

@safecore/aegis-cli provisiona, diagnostica, atualiza e audita a frota de servidores de borda do AEGIS — sem SSH manual, sem passo-a-passo reconstruído de memória. A régua é a dos CLIs de referência (Vercel, Firebase): o caminho comum é curto, previsível e difícil de fazer errado.

npx @safecore/aegis-cli use http://<mothership>:8091
npx @safecore/aegis-cli login
npx @safecore/aegis-cli doctor

Instalado globalmente (npm i -g @safecore/aegis-cli), o binário é aegis. Os exemplos deste documento usam aegis.

O que é a frota

O AEGIS entrega a operação de cada cliente numa ilha — uma instância soberana e independente rodando num servidor de borda, onde os dados sensíveis ficam. Um plano de controle central (o mothership) cataloga versões, governa os canais de release e coordena atualizações; cada host roda um agente que aplica as ordens nas suas ilhas.

Esta CLI é a interface desse plano de controle. Ela conversa com a API do mothership — nunca contém regra de negócio, e nunca contorna o registro por um atalho de SSH. O que ela faz fica auditável no servidor.

Conceitos

| Termo | O que é | |---|---| | mothership | O plano de controle: cataloga releases, governa canais, guarda a auditoria. Uma caixa em "modo servidor". | | host | Uma máquina física (servidor de borda) adotada na frota, com um agente. | | ilha | Uma instância AEGIS num host — a operação de um cliente. Um host pode hospedar várias. | | canal | dev, rc ou stable. Aponta para a release que as ilhas naquele canal devem convergir. | | release / manifesto | Um conjunto de imagens fixadas por dígest, mais as seeds de domínio que sabe instalar. | | matrícula | A credencial de uso único que uma caixa nova apresenta ao se juntar à frota. | | vertical / seed | O domínio que uma ilha materializa (ex.: safetag, hotelaria). Vem das releases, nunca hardcoded. | | pseudônimo | O nome de uma máquina — sempre aleatório e memorável (sereno-falcao-a1b2). O domínio do cliente é da camada de aplicação, nunca o nome da caixa. |

Instalação

Requer Node 20.10+ (a CLI usa parseArgs, fetch e node:test nativos — e zero dependências, porque a ferramenta que administra a infraestrutura é o último lugar onde se quer superfície de supply chain).

npx @safecore/aegis-cli --ajuda        # sem instalar
npm i -g @safecore/aegis-cli           # instala o binário `aegis`

Fluxo típico

# 1. Apontar para o painel e autenticar
aegis use http://<mothership>:8091
aegis login

# 2. Diagnosticar o caminho inteiro (o 1º comando de todo suporte)
aegis doctor

# 3. Emitir a matrícula de uma caixa nova (pseudônimo gerado; tailnet embutido)
#    --saida grava a matrícula pronta para o flash-usb / instalar-em-disco
aegis nova --cliente "Cliente X" --dominio cliente-x.com \
           --vertical safetag --ts-authkey tskey-... --registry-token ghp_... \
           --saida matricula.json

# 4. Publicar e promover uma versão
aegis releases importar manifesto.json
aegis promover stable v1.0.0
aegis distribuicao                     # acompanhar a convergência da frota

Cada comando aceita --json, que imprime apenas o objeto de resposta — para encadear em jq ou consumir em automação.

Tutorial completo, do zero à ilha em produção — com pré-requisitos, gravação da mídia, o que acontece no primeiro boot e a governança: veja o Guia de operação da frota.

Referência de comandos

Orientação

| Comando | Função | |---|---| | aegis doctor | Diagnostica o caminho inteiro: Node, painel configurado, painel alcançável, sessão, release promovida, ilhas reportando. Sai com código diferente de zero se algo essencial falhou. | | aegis use <url> | Fixa o painel padrão. | | aegis login | Abre sessão (pergunta a senha sem eco; --usuario/--senha para automação). | | aegis sair | Encerra a sessão. | | aegis credencial-console <host> | Guarda a âncora de privilégio daquela caixa — uma vez, e nenhum comando pede de novo. Pergunta sem eco e prova na caixa antes de guardar. | | aegis config | Mostra a configuração do usuário (a sessão nunca é impressa). |

Inventário

| Comando | Função | |---|---| | aegis ilhas | Grade da frota: ilha, cliente, canal, versão, saúde, último heartbeat. | | aegis ilha <id\|nome> | Detalha uma ilha. | | aegis hosts | Hosts e seus endereços de tailnet. | | aegis logs [ilha] [--n 30] | Eventos da frota, sem SSH. |

Provisionamento

| Comando | Função | |---|---| | aegis bootstrap <host> [--resetar-admin] [--ts-authkey K] | Reivindica uma caixa em modo servidor: sobe o tailnet e recupera a credencial do operador. | | aegis nova [--cliente] [--dominio] [--vertical] [--canal] [--ts-authkey] [--registry-token] [--saida m.json] | Emite a matrícula de uma caixa nova (pseudônimo gerado). --saida grava a matrícula pronta para gravar. | | aegis nova-instancia <ilha> --projeto <n> [--vertical <seed>] | Sobe uma ilha a mais num host que já roda AEGIS. | | aegis verticais | As seeds que a frota sabe instalar (derivadas das releases). | | aegis disco ajuda\|assar\|instalar | Prepara um disco de servidor novo (assar a ISO fina, instalar num disco físico). |

bootstrap é o comando que substitui o SSH manual para reivindicar o mothership: sobe o tailnet e confere/recupera a senha do operador, idempotentemente. A âncora de privilégio (a senha de console do appliance) vem por --senha-console/AEGIS_CONSOLE_SENHA — nunca embutida na ferramenta.

nova cria uma CAIXA nova (que ainda será instalada). nova-instancia sobe uma ILHA a mais num host que já roda AEGIS. O nome da máquina é sempre um pseudônimo; o domínio do cliente entra em --dominio (camada de aplicação) e é entregue à ilha no pareamento, por TLS — nunca no pendrive.

Release

| Comando | Função | |---|---| | aegis releases [importar <manifesto.json>] | Catálogo de releases e canais; importa um manifesto (recuperação ou mothership novo). | | aegis promover <canal> <versao> | Aponta um canal para uma versão. | | aegis recall <canal> | Volta o canal para a versão anterior. | | aegis distribuicao | Quem já convergiu, quem está atrás, quem falhou. | | aegis push [--sim] | Envia a melhoria local para o pipeline de CI. | | aegis pull [canal] | Traz o estado desejado de um canal. |

push não copia arquivo para caixa nenhuma — envia o commit, e quem constrói é o CI. Copiar um artefato para dentro de um container seria código rodando que não existe em commit nenhum. promover é o que confere produção; verde no dev é candidatura, não release.

Operação

| Comando | Função | |---|---| | aegis atualizar <ilha> | Enfileira uma atualização. | | aegis snapshot <ilha> | Snapshot do banco de uma ilha. | | aegis copiar-cofre <ilha> | Copia o backup para o cofre. | | aegis restaurar <ilha> --confirmacao <ilha> | Restaura um backup (destrutivo). | | aegis reiniciar <ilha> | Reinício orquestrado. | | aegis cofre | Backups da frota inteira. |

restaurar sobrescreve o banco de um cliente; por isso exige o nome da ilha digitado, antes de tocar o servidor.

Operações de caixa (por SSH, não pelo painel)

Estes gestos falam direto com a máquina — inclusive quando o painel está fora do ar, que é justamente quando eles são necessários.

| Comando | Função | |---|---| | aegis bootstrap <host> | Reivindica uma caixa nova: tailnet + credencial do operador. | | aegis rede <host> [--consertar] | DNAT órfão do netavark (porta responde 200 dentro do container e 000 no host). | | aegis destravar <host> [--container N] | Container encalhado em stopping/removing. | | aegis agente <host> [--enviar] | O agente de frota da caixa. Ele viaja no bundle desde a 1.2.0; este comando é para inspecionar e para apressar um fix sem esperar release. | | aegis mothership <host> --tag T --aplicar | O plano de controle (api+painel) da própria caixa. | | aegis autosync <host> [--instalar] | A ponte AutoSync (sistema legado → AEGIS) de uma caixa. |

Nível 0 — abaixo do sistema operacional

Quando o SSH não alcança, é porque o sistema operacional morreu — e é exatamente aí que se precisa entrar. Estes falam com o BMC (o controlador de gerência da placa), que vive mesmo com a máquina desligada.

| Comando | Função | |---|---| | aegis watchdog <host> [--ligar] | O contador em hardware que reinicia a caixa sozinha se ela travar. Sonda os módulos e só aceita o que criou /dev/watchdog — escolher pelo fabricante não funciona. | | aegis bmc <host> | Endereço, firmware e SEL (log de hardware): falha de fonte, ECC, erro de POST. É o que responde "por que ela reiniciou?" quando o journal não tem nada, porque aconteceu antes de o sistema subir. | | aegis energia <host> [--ligar\|--ciclo\|--desligar] | Liga, desliga e cicla com o sistema operacional morto. Ações destrutivas exigem o nome do host digitado. | | aegis console <host> | O console serial: mostra boot, GRUB, kernel em pânico e login. É o que substitui levar monitor e teclado até o rack. | | aegis observabilidade <host> [--instalar\|--prometheus] | A saúde do disco vira série temporal com alerta, não um banner. Responde "desde quando está assim?". |

O estado da frota

| Comando | Função | |---|---| | aegis plano <ilha> | O que a frota faria nesta ilha e por quê — sem fazer. | | aegis exportar [--saida arq] | O estado declarado da frota, versionável. Sai declaração, nunca fato observado, e segredo nenhum. | | aegis importar <arq> [--aplicar] | O caminho de volta. Mostra o que mudaria; só muda com --aplicar --confirmacao importar. 🔴 Nunca apaga: o que está na frota e não no arquivo é relatado, não removido. |

aegis autosync instala e inspeciona a ponte que traz as visitas do sistema legado do cliente para dentro do AEGIS: manda o compilado, monta as dependências na própria caixa, emite (ou reaproveita) o token OSDK e sobe um container rootless que volta do reboot. Os guarda-corpos são de campo: --allow é obrigatório (sem allowlist a ponte manda mensagem para gente de verdade), visita sem celular do destinatário não emite (senão o operador vira o destinatário de todas) e escrever na ontologia do cliente é opt-in (--com-dominio).

Se a sua máquina não estiver no tailnet, AEGIS_SSH troca o ssh por um invólucro que alcança a caixa por um salto: AEGIS_SSH="podman exec -i <container> ssh" aegis autosync <host>.

Ambiente de desenvolvimento

| Comando | Função | |---|---| | aegis skills listar\|instalar [--somente a,b] [--destino <dir>] [--forcar] | Instala as skills que o AEGIS usa, para o ambiente de um desenvolvedor nascer completo. |

Configuração

~/.aegis/config.json (permissão 0600 — guarda o cookie de sessão).

| Chave | Função | |---|---| | mothership | Painel padrão; evita repetir o endereço a cada comando. | | canal | Canal preferido nos comandos que aceitam um. | | sessao | Cookie de sessão; nunca é impresso. | | perfil | Operador da última sessão. |

Precedência do endereço: --mothership › AEGIS_MOTHERSHIP › configuração. AEGIS_HOME reposiciona a raiz inteira (útil em testes e CI).

Artefatos

Ações que produzem metadado gravam um artefato JSON em ~/.aegis/saidas/ (permissão 0600):

~/.aegis/saidas/2026-08-04T21-13-02-000Z-nova.json

Contêm o pedido, a resposta e o que o implementador precisa depois — código de matrícula, credenciais de primeiro acesso, dígests. Essa informação aparece uma vez só; deixá-la apenas no terminal é perdê-la. Gravam artefato: bootstrap, nova, nova-instancia, promover, recall, push, as ações de ilha e os comandos de disco.

Saída e códigos de saída

• --json imprime apenas o objeto — sem cabeçalho, sem cor, encadeável.
• Códigos: 0 sucesso · 1 erro esperado (uso ou ambiente, com mensagem limpa) · 2 erro de linha de comando · 70 defeito da própria CLI (imprime a pilha inteira).

Uma flag escrita errada é recusada, nunca ignorada: um --mothershp engolido em silêncio mandaria o comando para o painel errado.

Segurança

• Segredos viajam por stdin ou config, nunca por argumento de linha de comando (que apareceria em ps e no histórico do shell).
• A sessão fica num cookie httpOnly guardado com permissão 0600; nunca é impressa.
• A CLI é a interface; a verdade e a auditoria vivem no frota-api. Onde falta um endpoint, cria-se o endpoint — não um atalho por SSH.

Suporte

Referência do plano de frota: docs/frota/PLANO-FROTA.md no monorepo. Software proprietário da Safe Core Technologies.