Aparência
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
A CLI é instalada pelo instalador. Ele atende macOS (Apple Silicon e Intel) e Linux glibc (amd64 e arm64):
bash
curl --proto '=https' --proto-redir '=https' -fL --progress-bar https://get.finnest.com.br | shNo Windows nativo (x86_64), rode o mesmo comando num shell POSIX, como o Git Bash.
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, semsudo, e adiciona esse diretório aoPATHdo shell.
Opções úteis: --install-dir <diretório> para instalar em outro lugar e --no-modify-path para não alterar o PATH. Abra um novo shell depois da instalação para o PATH valer.
Confira a instalação:
bash
finnest versionAtualização
bash
finnest update --check # só verifica se há versão nova
finnest update --yes # instala a versão novaA atualização troca a CLI e o pacote de runtime juntos. A configuração só a bloqueia quando a seção [plane] de ~/.finnest/config.toml tem self_update = false, valor que o finnest init grava por padrão. Nesse caso, apague a linha ou rode de novo o instalador. No Windows nativo, a atualização automática não está disponível: 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 loginconcluído na assinatura de destino. No WSL, use a Azure CLI para Linux.
- Node.js 20 ou mais recente no
PATH. Prefira uma versão LTS em suporte, como a 22 ou a 24. - Acesso às imagens: na AWS, a conta liberada pela Finnest no registro de distribuição (recomendado); na Azure, ou na AWS sem esse registro, o usuário e o token somente leitura fornecidos pela Finnest. Veja Acesso às imagens.
- 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.
Prepare a estação e o alvo de deploy. O
setupgrava ofinnest.tomle roda as verificações iniciais:bashfinnest setup --cloud=aws --environment=sandbox --participant-role=transmitterPapéis possíveis:
transmitter(transmissora),receiver(receptora) ouboth(ambos).Informe o material regulado (certificados ICP-Brasil, chaves e segredos). Use o Configuration Workspace, que mostra o que falta para o seu papel:
bashfinnest config workspace open --goal=applyOu grave item a item com
finnest secrets write <item> --file <arquivo> --yes.Confira a prontidão:
bashfinnest config readiness --goal=apply finnest doctor --cloud=aws --environment=sandboxFaça o deploy. Veja o passo a passo em Deploy na AWS ou Azure.
Receptora e iniciadora Open Finance (OFB)
A receptora de dados e a iniciadora de Pix do Open Finance Brasil só funcionam depois que a instalação guarda o material regulado delas. Sem esse material, o deploy não as configura. O caminho completo de uma instalação só OFB está no Guia OFB da participante; esta seção resume o que a CLI faz.
Ligue o OFB e declare o egress das transmissoras na seção
[opin]dofinnest.toml:toml[opin] ofb_enabled = true ofb_egress_fqdns = ["<host de autorização da transmissora>", "<host de APIs da transmissora>"]Com
ofb_enabled = true, a política de egress FAPI (finnest-allow-fapi-egress) já libera o Diretório do ambiente:auth,data,keystore,matls-api,matls-authewebsobsandbox.directory.openbankingbrasil.org.brno sandbox e sobdirectory.openbankingbrasil.org.brem produção. Os hosts de cada transmissora (servidor de autorização e APIs) vão emofb_egress_fqdns, em minúsculas e sem repetição.Grave o material com
finnest secrets write, sem interação:--filepara um arquivo,--pair-filepara a chave de um certificado e--stdinpara um valor. O valor fica no armazenamento local da estação; o deploy o publica no cofre de segredos da nuvem.Item Conteúdo ofb-receiver-state-secretAssina o statedo redirecionamento; ao menos 32 caracteresofb-receiver-secret-key-base64Chave AES-256 que cifra os segredos das conexões; 32 bytes em base64 ofb-directory-client-idO client_iddo software da participante no Diretórioofb-software-statement-idO UUID do software statement (papéis DADOS e PAGTO) ofb-receiver-jwks-jsonJWKS público: uma chave sig/PS256e umaenc/RSA-OAEP, comkidúnicosofb-receiver-jws-private-jwk-json,ofb-receiver-jwe-private-jwk-jsonAs chaves privadas de assinatura e de cifra que o JWKS publica ofb-receiver-client-cert-pem,ofb-receiver-client-key-pemO certificado de transporte ICP-Brasil (folha e ACs) e a chave, para o mTLS ofb-receiver-jwe-retired-jwks-jsonSó durante a troca da chave de cifra: as chaves privadas aposentadas ofb-receiver-client-retired-cert-pem,ofb-receiver-client-retired-key-pemSó durante a troca do certificado: o certificado substituído e a chave bashfinnest secrets write ofb-receiver-state-secret --stdin --yes <<< '<segredo de 32 caracteres ou mais>' finnest secrets write ofb-receiver-secret-key-base64 --stdin --yes <<< '<32 bytes em base64>' finnest secrets write ofb-directory-client-id --stdin --yes <<< '<client_id do software>' finnest secrets write ofb-software-statement-id --stdin --yes <<< '<UUID do software statement>' finnest secrets write ofb-receiver-jwks-json --file ./jwks.json --yes finnest secrets write ofb-receiver-jws-private-jwk-json --file ./jws-priv.json --yes finnest secrets write ofb-receiver-jwe-private-jwk-json --file ./jwe-priv.json --yes finnest secrets write ofb-receiver-client-cert-pem --file ./brcac.crt --pair-file ./brcac.key --yesOs nove primeiros itens são tudo ou nada. Quem os torna obrigatórios é o material, não o
ofb_enabled: gravado qualquer itemofb-receiver-*,ofb-directory-client-idouofb-software-statement-id, ofinnest doctore a verificação prévia do deploy exigem os demais e os validam. Não háclient_idde transmissora para gravar: a receptora se registra sozinha em cada transmissora (DCR) a partir do software statement.A
ofb-receiver-secret-key-base64não pode ser trocada depois de gravada, porque não há como recifrar os segredos que ela protege; osecrets writerecusa um valor diferente. Os itens aposentados só existem durante uma troca (veja Rotação de certificados): o deploy os entrega ao banking enquanto estiverem gravados.Confira e faça o deploy:
bashfinnest secrets list --scope regulatory finnest doctor finnest deploy --previewCom o material gravado, o deploy declara o ExternalSecret
ofb-receiver-material, que só o banking monta. Ele continua declarado mesmo comofb_enabled = false: o ExternalSecret é protegido, e removê-lo travaria o deploy num delete protegido. Com o OFB desligado, o banking não monta nada dele.Confira o egress depois do deploy. A lista liberada precisa ter os hosts do Diretório e cada host de
ofb_egress_fqdns:bashkubectl get ciliumnetworkpolicy finnest-allow-fapi-egress -o yaml
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.