Instalando o pacote Node.js do Flosum CLI

Problemas conhecidos: atualização obrigatória

Uma atualização é necessária. A versão atual do Flosum DevOps requer as versões mais recentes do Flosum CLI (@flosum/cli pacote) e o Flosum DevOps-CLI Extension. Versões anteriores do CLI não oferecem suporte a topologias e não podem funcionar com um tenant do DevOps que as use, portanto as instalações existentes devem ser atualizadas.

O Node.js 22 é necessário. Em Node.js 24, os comandos de instalação e atualização parecem ser concluídos com sucesso, mas deixam você em uma versão anterior. Mude para o Node.js 22 antes de instalar ou atualizar.

Compatibilidade do sistema operacional

Flosum CLI e Extensão Flosum DevOps-CLI são compatíveis com os seguintes sistemas operacionais:

• macOS
• Linux

Essas ferramentas atualmente não foram projetadas para funcionar com o Windows.

Visão geral

Este artigo explica como instalar o Flosum CLI, a ferramenta de linha de comando para o Flosum DevOps. Você pode usar o Flosum CLI sozinho a partir de um terminal, e ele também é necessário pelo Flosum DevOps-CLI Extension para Visual Studio Code.

O Flosum CLI compila um componente nativo na sua máquina durante a instalação, então ele requer uma cadeia de ferramentas de compilação funcional (Python e um compilador C++) além do Node.js. Conclua todos os pré-requisitos abaixo antes de executar o comando de instalação.

Pré-requisitos

1

Node.js e npm

O Flosum CLI requer Node.js 22 e npm 10. Versões mais recentes do Node.js não são compatíveis.

1. Acesse nodejs.org. A página vem com a versão mais recente por padrão, então use o menu suspenso de versão para selecionar 22.x, depois baixe e execute o instalador. O Node.js 22 inclui npm 10.
2. Verifique ambas as versões em um terminal:

node --version
npm --version

1. Confirme que node --version retorna v22.x e que npm --version retorna 10.x.

Node.js 24 instala uma versão mais antiga sem aviso

Se você instalar o Flosum CLI com Node.js 24, o npm instalará uma versão mais antiga do Flosum CLI sem reportar nenhum erro. Executar flosum --version retorna a versão mais antiga. Versões mais antigas não oferecem suporte ao Flosum DevOps atual e não funcionarão.

Faça o downgrade para Node.js 22 antes de instalar. Se você já tiver instalado o CLI no Node.js 24, remova-o usando as etapas em Solução de problemas, instale o Node.js 22 e execute o comando de instalação novamente.

Não atualize o npm

Cada instalação termina com um aviso de que uma nova versão principal do npm está disponível, junto com um comando para instalá-la. Não execute esse comando. O Flosum CLI requer npm 10, e a atualização tira sua máquina da configuração compatível.

Se você já tiver atualizado, reinstale Node.js 22, que restaura npm 10.

Instale o Node.js para sua própria conta de usuário, em vez de um local compartilhado do sistema, sempre que possível. Isso mantém o caminho da pasta global do npm curto e evita o problema de comprimento do caminho descrito em Solução de problemas.

2

Ferramentas de compilação

O Flosum CLI depende de um módulo nativo compilado a partir de código-fonte C durante a instalação. Sua máquina precisa ter Python 3 e um compilador C++ disponíveis antes da instalação, ou a instalação falhará.

macOS

1. Instale as Ferramentas de Linha de Comando do Xcode, que fornecem o compilador e o Python:

xcode-select --install

Linux

1. Instale a cadeia de ferramentas do compilador e o Python. No Debian e Ubuntu:

sudo apt install build-essential python3

Use o grupo de pacotes equivalente para a sua distribuição.

Instalando o Flosum CLI

1

Execute o comando de instalação

1. Abra um terminal.
2. Execute o seguinte comando:

npm i -g @flosum/cli

1. Aguarde a conclusão da instalação. O componente nativo é compilado durante esta etapa, então o comando pode levar alguns minutos.

2

Verifique a instalação

1. Execute o seguinte comando:

flosum --version

1. Confirme que um número de versão é retornado. Um número de versão indica uma instalação bem-sucedida.
2. Compare a versão instalada com a versão publicada mais recente:

npm view @flosum/cli version

1. Confirme que ambos os comandos informam a mesma versão. Se flosum --version retornar um número menor, uma versão mais antiga foi instalada. Consulte Solução de problemas.

O Flosum DevOps-CLI Extension para Visual Studio Code é instalado separadamente e tem seu próprio número de versão, então a versão dele não corresponde à informada aqui. Não compare as duas.

• Instalando a extensão Flosum DevOps-CLI

Usando o Flosum CLI

Revise os comandos do pacote Flosum CLI abaixo para ver uma lista dos comandos disponíveis e explicações sobre o que cada um faz. Como a Extensão DevOps-CLI chama esses comandos, você também pode revisar o artigo a seguir para obter instruções mais detalhadas.

• Usando o DevOps CLI no VS Code

Referência de comandos do Flosum CLI

Esta referência cobre @flosum/cli versão 0.0.5. Execute flosum --help ou flosum devops --help para ver a referência da versão instalada na sua máquina.

Todo comando aceita as seguintes opções, que não são repetidas abaixo.

Opção	Descrição
--json	Retorna o resultado em formato JSON. O padrão é false.
-h, --help	Exibe a ajuda para o comando.

O comando de nível superior também aceita -V, --version, que retorna o número da versão instalada.

Comandos da conta

Comando	Descrição
flosum login	Faz login em Global Settings e recupera os dados dos serviços relacionados.
flosum logout	Exclui as credenciais salvas.
flosum list-credentials	Exibe todas as credenciais autorizadas.
flosum list-topologies	Lista as topologias disponíveis.

Comandos do DevOps

Comando	Descrição
flosum devops init	Cria um projeto Salesforce e os arquivos do sistema do CLI.
flosum devops clone	Cria um projeto Salesforce e recupera a main branch do tenant do DevOps registrado.
flosum devops checkout	Faz checkout de outra branch e recupera quaisquer componentes que estejam faltando localmente.
flosum devops pull	Faz pull do commit mais recente da branch no DevOps.
flosum devops commit	Faz commit das alterações locais em uma branch remota no DevOps.
flosum devops rollback	Reverte a branch para o último estado com commit.
flosum devops status	Retorna todas as alterações locais que não foram commitadas.
flosum devops list-branches	Lista todas as branches remotas.
flosum devops config-set	Define um valor de configuração do projeto.
flosum devops config-unset	Limpa uma propriedade de configuração do projeto.

flosum login

Opção	Descrição
-a, --alias <string>	Alias com o qual as credenciais salvas são acessadas. O padrão é default.
-t, --token <string>	Token usado para acessar os serviços da Flosum. O comando o solicita durante a execução se você não o fornecer.
--global-settings-api-url <string>	URL base de uma API do Global Settings acessível. Use-a quando a API privada do Global Settings estiver exposta fora da rede Docker.

flosum logout

Opção	Descrição
-a, --alias <string>	Alias das credenciais salvas a excluir. O padrão é default.

flosum list-topologies

Opção	Descrição
-a, --alias <string>	Alias das credenciais a ser usado ao listar topologias. O padrão é default.

flosum devops init

Opção	Descrição
-n, --name <string>	Nome da pasta em que o projeto é armazenado. O comando o solicita durante a execução se você não o fornecer.
-a, --alias <string>	Alias das credenciais usadas para recuperar seus componentes do DevOps. O padrão é default.
-t, --topology <string>	Nome da topologia a ser usada para o projeto.
--topology-id <number>	ID da topologia a ser usado para o projeto.

flosum devops clone

Opção	Descrição
-n, --name <string>	Nome da pasta em que o projeto é armazenado. O comando o solicita durante a execução se você não o fornecer.
-a, --alias <string>	Alias das credenciais usadas para recuperar seus componentes do DevOps. O padrão é default.
-t, --topology <string>	Nome da topologia a ser usado para clonagem.
--topology-id <number>	ID da topologia a ser usado para clonagem.

flosum devops checkout

Opção	Descrição
-b, --branch <string>	Nome da branch a fazer checkout. O comando o solicita durante a execução se você não o fornecer.

flosum devops commit

Opção	Descrição
-m, --message <string>	Mensagem de commit. O comando o solicita durante a execução se você não o fornecer.

flosum devops config-set

Recebe dois argumentos, ambos obrigatórios.

Argument	Descrição
config-name	Nome da propriedade de configuração. Os valores permitidos são credentialsAlias e topologyId.
value	Valor ao qual a propriedade deve ser definida.

flosum devops config-unset

Recebe um argumento, que é obrigatório.

Argument	Descrição
config-name	Nome da propriedade de configuração a limpar. Os valores permitidos são credentialsAlias e topologyId.

Comandos sem opções adicionais

flosum list-credentials, flosum devops pull, flosum devops rollback, flosum devops status, e flosum devops list-branches aceitam apenas as duas opções listadas no topo desta referência.

Solução de problemas

A instalação falha com gyp ERR, node-gyp ou um erro de Python

O componente nativo não pôde ser compilado porque a cadeia de ferramentas de compilação está ausente ou incompleta.

1. Confirme que Python 3 está instalado e disponível no seu PATH executando python3 --version.
2. Confirme que um compilador C++ está instalado. No macOS, isso é as Ferramentas de Linha de Comando do Xcode. No Linux, é o grupo de pacotes do compilador da sua distribuição.
3. Feche e reabra o terminal para que ele carregue o PATH.
4. Remova a instalação parcial, conforme descrito abaixo.
5. Execute o comando de instalação novamente.

Remover a Instalação Parcial Antes de Tentar Novamente

Uma instalação com falha deixa para trás uma cópia incompleta do CLI, junto com os flosum atalhos de comando. Remova ambos antes de tentar novamente; caso contrário, a próxima tentativa pode falhar por motivos não relacionados ao erro original.

Primeiro, execute a desinstalação padrão, que remove o conteúdo do pacote:

npm uninstall -g @flosum/cli

Isso não remove os flosum atalhos, então exclua-os também.

sudo rm -f "$(npm prefix -g)/bin/flosum"
sudo rm -rf "$(npm root -g)/@flosum"

Ambas as etapas são necessárias. Os flosum atalhos são criados mesmo quando a instalação falha, e deixá-los para trás faz com que você tenha um flosum comando que ainda é executado, mas aponta para arquivos que não existem mais.

Em seguida, confirme que nada permaneceu:

flosum --version

O comando deve informar comando não encontrado. Se ele informar um módulo ausente em vez disso, os atalhos permanecem.

Você pode ver um segundo erro diferente

As verificações de compilação procuram Python antes de procurar um compilador C++, então elas informam apenas o primeiro que estiver faltando. Se o Python era a única coisa ausente, instalá-lo e tentar novamente pode produzir um novo erro que mencione o compilador C++ em vez disso. Isso é um progresso esperado, e não um novo problema. Instale as ferramentas de compilação C++, remova a instalação parcial novamente e tente outra vez.

Consulte o Ferramentas de compilação pré-requisito acima para obter as instruções completas por sistema operacional.

A mensagem de erro também inclui um link para as instruções de instalação do node-gyp, publicadas pela própria ferramenta de compilação. Elas cobrem os mesmos requisitos para um público geral de desenvolvedores e servem como uma segunda referência útil ao solucionar uma configuração incomum.

flosum --version retorna uma versão mais antiga do que a versão publicada

flosum --version retorna um número menor que npm view @flosum/cli version. A instalação informou sucesso, mas o npm selecionou uma versão mais antiga.

Isso acontece quando a versão do Node.js na sua máquina não é 22. o npm escolhe a versão mais recente compatível com sua versão do Node.js e não relata um erro quando essa não é a atual.

1. Execute node --version.
2. Se ele não informar v22.x, instale Node.js 22 como descrito nos Node.js e npm pré-requisitos.
3. Remova a instalação existente usando as etapas da primeira entrada.
4. Execute o comando de instalação novamente e compare as versões mais uma vez.

O comando flosum retorna "Cannot find module" em vez de uma versão

Uma instalação anterior falhou no meio do processo. Os flosum atalhos foram criados, mas os arquivos a que apontam nunca foram concluídos, então o comando é executado e depois informa um cli.js arquivo ausente.

1. Remova a instalação parcial usando as etapas da primeira entrada.
2. Conclua o Ferramentas de compilação pré-requisito.
3. Execute o comando de instalação novamente.

A instalação falha com EBADENGINE ou "Unsupported engine"

Essa mensagem significa que a versão do Node.js ou do npm na sua máquina não corresponde à versão exigida pelo Flosum CLI.

1. Execute node --version e npm --version.
2. Se eles não informarem v22.x e 10.x, instale Node.js 22 como descrito nos Node.js e npm pré-requisito, execute o comando de instalação novamente.

Nas versões compatíveis, essa mensagem não deve aparecer.

Se você a vir ao executar o Node.js 22, verifique se engine-strict=true está definido no seu .npmrc arquivo. Essa configuração transforma avisos de compatibilidade de versão em erros. Remova-a ou substitua-a apenas para esta instalação:

npm i -g @flosum/cli --engine-strict=false