Instalar a CLI

A CLI finnest prepara, implanta e opera o Finnest Power na conta de nuvem da instituição. Ela roda na estação do operador ou num pipeline de CI e usa as credenciais de nuvem da própria instituição.

Plataformas suportadas

Sistema	Suporte
macOS (Apple Silicon e Intel)	Completo
Linux glibc (amd64 e arm64)	Completo
Windows com WSL2	Completo (instale dentro do WSL)
Windows nativo	Instala e executa; a atualização automática não está disponível
Linux musl (Alpine)	Não suportado

Instalação

curl --proto '=https' --proto-redir '=https' -fL --progress-bar https://get.finnest.com.br | sh

O instalador:

• baixa a versão estável mais recente da CLI e o pacote de runtime correspondente;
• confere o SHA-256 e a assinatura cosign de cada arquivo antes de instalar e interrompe a instalação se algo não conferir;
• instala em ~/.finnest/bin, sem sudo, e adiciona esse diretório ao PATH do shell.

Opções úteis: --install-dir <diretório> para instalar em outro lugar e --no-modify-path para não alterar o PATH.

Confira a instalação:

finnest version

Também há uma imagem de contêiner, para pipelines: ghcr.io/finnestbr/finnest:<versão>.

Atualização

finnest update --check   # só verifica se há versão nova
finnest update --yes     # instala a versão nova

A atualização troca a CLI e o pacote de runtime juntos. Ela depende de self_update = true na seção [plane] de ~/.finnest/config.toml, que o finnest init deixa desligado; sem isso, rode de novo o instalador. A versão da plataforma implantada acompanha a versão da CLI; veja Atualização de versão.

Pré-requisitos na estação do operador

• Credenciais de nuvem:

  • AWS: AWS CLI com perfil ou SSO ativo na conta de destino.
  • Azure: az login concluído na assinatura de destino. No WSL, use a Azure CLI para Linux.

• Node.js 20 LTS ou mais recente no PATH.

• Credencial de download das imagens, fornecida pela Finnest. Grave o usuário e o token em arquivos com permissão 0600:

  (
    umask 077
    mkdir -p ~/.finnest/credentials
    rm -f ~/.finnest/credentials/image-pull-username ~/.finnest/credentials/image-pull-token
    printf '%s' '<usuário fornecido pela Finnest>' > ~/.finnest/credentials/image-pull-username
    printf '%s' '<token fornecido pela Finnest>' > ~/.finnest/credentials/image-pull-token
  )

• DNS: a plataforma cria a zona do domínio da instalação (Route 53 na AWS, Azure DNS na Azure). A zona pai precisa delegar os registros NS para ela. Se a zona pai estiver na Cloudflare, a CLI pode fazer a delegação automaticamente com um token em ~/.finnest/credentials/cloudflare-api-token.

Os detalhes de permissões por nuvem estão em Deploy na AWS ou Azure.

Primeiros passos

O vídeo mostra a versão instalada e o setup num projeto novo: ele cria o finnest.toml, fixa as ferramentas, confere a prontidão e indica o próximo passo.

1. Prepare a estação e o alvo de deploy. O setup grava o finnest.toml e roda as verificações iniciais:

   finnest setup --cloud=aws --environment=sandbox --participant-role=transmitter

   Papéis possíveis: transmitter (transmissora), receiver (receptora) ou both (ambos).

2. Informe o material regulado (certificados ICP-Brasil, chaves e segredos). Use o Configuration Workspace, que mostra o que falta para o seu papel:

   finnest config workspace open --goal=apply

   Ou grave item a item com finnest secrets write <item> --file <arquivo> --yes.

3. Confira a prontidão:

   finnest config readiness --goal=apply
   finnest doctor --cloud=aws --environment=sandbox

4. Faça o deploy. Veja o passo a passo em Deploy na AWS ou Azure.

Painel interativo

Rodar finnest sem argumentos num terminal abre o painel interativo (cockpit). Ele mostra a prontidão do alvo e reúne as ações de verificação, configuração, histórico de execuções, alvos, deploy e atualização. Nenhuma ação altera a nuvem sem a sua confirmação. Ao abrir, as verificações ao vivo ainda não rodaram; no vídeo, a paleta de comandos (ctrl+p) roda a prontidão e o cabeçalho passa a mostrar o resultado.

Tecla	Ação
↑ ↓	Navegar
enter	Abrir a ação
g	Configuration Workspace
s	Trocar o alvo de deploy
ctrl+p	Paleta de comandos
?	Ajuda
q	Sair

Saída para automação

Todo comando aceita --json, que imprime um envelope versionado. A exceção é o finnest schema, que imprime o próprio documento de schema, sem envelope. Para acompanhar um deploy longo, use --output=ndjson, que emite um evento por linha e termina com o envelope final. O formato do envelope está publicado em schema do envelope 2.0.0.

Próximos passos

• Deploy na AWS ou Azure
• Referência de comandos
• Solução de problemas