> For the complete documentation index, see [llms.txt](https://docs.flosum.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flosum.com/devops/devops-pt-br/codigo/cli-do-devops/instalando-o-pacote-node.js-do-flosum-cli.md).

# Instalando o pacote Node.js do Flosum CLI

{% hint style="warning" %}

#### 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.
{% endhint %}

{% hint style="success" %}

#### 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.
{% endhint %}

## ![](https://2465342021-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRpUu5iMlzMFAudyBvMOl%2Fuploads%2FG5ZbxX918xOHwbAwAJ4n%2FSummary2-Small-Icon.svg?alt=media\&token=da26a67f-ff7f-47b3-8669-06be960dc2d7) 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

{% stepper %}
{% step %}

### 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](https://nodejs.org/en/download). 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
```

3. Confirme que `node --version` retorna **v22.x** e que `npm --version` retorna **10.x**.

{% hint style="warning" %}

#### 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.
{% endhint %}

{% hint style="warning" %}

#### 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**.
{% endhint %}

{% hint style="info" %}
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.
{% endhint %}
{% endstep %}

{% step %}

### 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.
{% endstep %}
{% endstepper %}

## Instalando o Flosum CLI

{% stepper %}
{% step %}

### Execute o comando de instalação

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

```
npm i -g @flosum/cli
```

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

{% step %}

### Verifique a instalação

1. Execute o seguinte comando:

```
flosum --version
```

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

```
npm view @flosum/cli version
```

4. 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.

{% hint style="info" %}
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](/devops/devops-pt-br/codigo/cli-do-devops/instalando-a-extensao-flosum-devops-cli.md)
  {% endhint %}
  {% endstep %}
  {% endstepper %}

## 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](/devops/devops-pt-br/codigo/cli-do-devops/usando-o-devops-cli-no-vs-code.md)

<details>

<summary>Referência de comandos do Flosum CLI</summary>

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.

<table><thead><tr><th width="250">Opção</th><th>Descrição</th></tr></thead><tbody><tr><td><code>--json</code></td><td>Retorna o resultado em formato JSON. O padrão é false.</td></tr><tr><td><code>-h, --help</code></td><td>Exibe a ajuda para o comando.</td></tr></tbody></table>

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

**Comandos da conta**

<table><thead><tr><th width="250">Comando</th><th>Descrição</th></tr></thead><tbody><tr><td><code>flosum login</code></td><td>Faz login em Global Settings e recupera os dados dos serviços relacionados.</td></tr><tr><td><code>flosum logout</code></td><td>Exclui as credenciais salvas.</td></tr><tr><td><code>flosum list-credentials</code></td><td>Exibe todas as credenciais autorizadas.</td></tr><tr><td><code>flosum list-topologies</code></td><td>Lista as topologias disponíveis.</td></tr></tbody></table>

**Comandos do DevOps**

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

**flosum login**

<table><thead><tr><th width="250">Opção</th><th>Descrição</th></tr></thead><tbody><tr><td><code>-a, --alias &#x3C;string></code></td><td>Alias com o qual as credenciais salvas são acessadas. O padrão é <code>default</code>.</td></tr><tr><td><code>-t, --token &#x3C;string></code></td><td>Token usado para acessar os serviços da Flosum. O comando o solicita durante a execução se você não o fornecer.</td></tr><tr><td><code>--global-settings-api-url &#x3C;string></code></td><td>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.</td></tr></tbody></table>

**flosum logout**

<table><thead><tr><th width="250">Opção</th><th>Descrição</th></tr></thead><tbody><tr><td><code>-a, --alias &#x3C;string></code></td><td>Alias das credenciais salvas a excluir. O padrão é <code>default</code>.</td></tr></tbody></table>

**flosum list-topologies**

<table><thead><tr><th width="250">Opção</th><th>Descrição</th></tr></thead><tbody><tr><td><code>-a, --alias &#x3C;string></code></td><td>Alias das credenciais a ser usado ao listar topologias. O padrão é <code>default</code>.</td></tr></tbody></table>

**flosum devops init**

<table><thead><tr><th width="250">Opção</th><th>Descrição</th></tr></thead><tbody><tr><td><code>-n, --name &#x3C;string></code></td><td>Nome da pasta em que o projeto é armazenado. O comando o solicita durante a execução se você não o fornecer.</td></tr><tr><td><code>-a, --alias &#x3C;string></code></td><td>Alias das credenciais usadas para recuperar seus componentes do DevOps. O padrão é <code>default</code>.</td></tr><tr><td><code>-t, --topology &#x3C;string></code></td><td>Nome da topologia a ser usada para o projeto.</td></tr><tr><td><code>--topology-id &#x3C;number></code></td><td>ID da topologia a ser usado para o projeto.</td></tr></tbody></table>

**flosum devops clone**

<table><thead><tr><th width="250">Opção</th><th>Descrição</th></tr></thead><tbody><tr><td><code>-n, --name &#x3C;string></code></td><td>Nome da pasta em que o projeto é armazenado. O comando o solicita durante a execução se você não o fornecer.</td></tr><tr><td><code>-a, --alias &#x3C;string></code></td><td>Alias das credenciais usadas para recuperar seus componentes do DevOps. O padrão é <code>default</code>.</td></tr><tr><td><code>-t, --topology &#x3C;string></code></td><td>Nome da topologia a ser usado para clonagem.</td></tr><tr><td><code>--topology-id &#x3C;number></code></td><td>ID da topologia a ser usado para clonagem.</td></tr></tbody></table>

**flosum devops checkout**

<table><thead><tr><th width="250">Opção</th><th>Descrição</th></tr></thead><tbody><tr><td><code>-b, --branch &#x3C;string></code></td><td>Nome da branch a fazer checkout. O comando o solicita durante a execução se você não o fornecer.</td></tr></tbody></table>

**flosum devops commit**

<table><thead><tr><th width="250">Opção</th><th>Descrição</th></tr></thead><tbody><tr><td><code>-m, --message &#x3C;string></code></td><td>Mensagem de commit. O comando o solicita durante a execução se você não o fornecer.</td></tr></tbody></table>

**flosum devops config-set**

Recebe dois argumentos, ambos obrigatórios.

<table><thead><tr><th width="250">Argument</th><th>Descrição</th></tr></thead><tbody><tr><td><code>config-name</code></td><td>Nome da propriedade de configuração. Os valores permitidos são <code>credentialsAlias</code> e <code>topologyId</code>.</td></tr><tr><td><code>value</code></td><td>Valor ao qual a propriedade deve ser definida.</td></tr></tbody></table>

**flosum devops config-unset**

Recebe um argumento, que é obrigatório.

<table><thead><tr><th width="250">Argument</th><th>Descrição</th></tr></thead><tbody><tr><td><code>config-name</code></td><td>Nome da propriedade de configuração a limpar. Os valores permitidos são <code>credentialsAlias</code> e <code>topologyId</code>.</td></tr></tbody></table>

**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.

</details>

## Solução de problemas

<details>

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

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.

{% hint style="warning" %}

#### 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.
{% endhint %}

{% hint style="info" %}

#### 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.
{% endhint %}

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](https://github.com/nodejs/node-gyp#installation), 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.

</details>

<details>

<summary>flosum --version retorna uma versão mais antiga do que a versão publicada</summary>

`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.

</details>

<details>

<summary>O comando flosum retorna "Cannot find module" em vez de uma versão</summary>

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.

</details>

<details>

<summary>A instalação falha com EBADENGINE ou "Unsupported engine"</summary>

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
```

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.flosum.com/devops/devops-pt-br/codigo/cli-do-devops/instalando-o-pacote-node.js-do-flosum-cli.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.