> 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/code/devops-cli/installing-flosum-cli-node.js-package.md).

# Installing Flosum CLI Node.js Package

{% hint style="warning" %}

#### Known Issues: Required Update

**An update is required.** The current release of Flosum DevOps requires the latest versions of the Flosum CLI (**@flosum/cli** package) and the **Flosum DevOps-CLI Extension**. Earlier CLI releases do not support topologies and cannot work with a DevOps tenant that uses them, so existing installations must be updated.

**Node.js 22 is required.** On **Node.js 24**, the install and update commands appear to succeed but leave you on an earlier release. Move to Node.js 22 before installing or updating.
{% endhint %}

{% hint style="success" %}

#### Operating System Compatibility

**Flosum CLI** and **Flosum DevOps-CLI Extension** are compatible with the following operating systems:

* **macOS**
* **Linux**

These tools are currently not designed to work with Windows.
{% endhint %}

## ![](https://1800549522-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) Overview

This article explains how to install the Flosum CLI, the command-line tool for Flosum DevOps. You can use the Flosum CLI on its own from a terminal, and it is also required by the **Flosum DevOps-CLI Extension** for Visual Studio Code.

The Flosum CLI compiles a native component on your machine during installation, so it requires a working build toolchain (Python and a C++ compiler) in addition to Node.js. Complete all prerequisites below before running the install command.

## Prerequisites

{% stepper %}
{% step %}

### Node.js and npm

The Flosum CLI requires **Node.js 22** and **npm 10**. Newer Node.js releases are not supported.

1. Go to [nodejs.org](https://nodejs.org/en/download). The page defaults to the newest release, so use the version dropdown to select **22.x**, then download and run the installer. Node.js 22 includes **npm 10**.
2. Verify both versions in a terminal:

```
node --version
npm --version
```

3. Confirm that `node --version` reports **v22.x** and that `npm --version` reports **10.x**.

{% hint style="warning" %}

#### Node.js 24 Installs an Older Release Without Warning

If you install Flosum CLI with **Node.js 24**, npm will install an older version of Flosum CLI without reporting any errors. Running `flosum --version` reports the older version. Older releases do not support current Flosum DevOps and will not work.

Downgrade to **Node.js 22** before you install. If you have already installed the CLI on Node.js 24, remove it using the steps in Troubleshooting, install Node.js 22, then run the install command again.
{% endhint %}

{% hint style="warning" %}

#### Do Not Upgrade npm

Every installation ends with a notice that a newer major version of npm is available, along with a command to install it. Do not run that command. The Flosum CLI requires **npm 10**, and upgrading moves your machine off the supported configuration.

If you have already upgraded, reinstall **Node.js 22**, which restores **npm 10**.
{% endhint %}

{% hint style="info" %}
Install Node.js for your own user account rather than a shared system location when possible. This keeps the npm global folder path short and avoids the path-length problem described in Troubleshooting.
{% endhint %}
{% endstep %}

{% step %}

### Build Tools

The Flosum CLI depends on a native module that is compiled from C source code during installation. Your machine needs **Python 3** and a **C++ compiler** available before installation, or the installation will fail.

**macOS**

1. Install the Xcode Command Line Tools, which provide the compiler and Python:

```
xcode-select --install
```

**Linux**

1. Install the compiler toolchain and Python. On Debian and Ubuntu:

```
sudo apt install build-essential python3
```

Use the equivalent package group for your distribution.
{% endstep %}
{% endstepper %}

## Installing the Flosum CLI

{% stepper %}
{% step %}

### Run the Install Command

1. Open a terminal.
2. Run the following command:

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

3. Wait for the installation to finish. The native component is compiled during this step, so the command can take a couple of minutes.
   {% endstep %}

{% step %}

### Verify the Installation

1. Run the following command:

```
flosum --version
```

2. Confirm that a version number is returned. A version number indicates a successful installation.
3. Compare the installed version against the latest published release:

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

4. Confirm that both commands report the same version. If `flosum --version` reports a lower number, an older release was installed. See Troubleshooting.

{% hint style="info" %}
The **Flosum DevOps-CLI Extension** for Visual Studio Code is installed separately and has its own version number, so its version does not match the one reported here. Do not compare the two.

* [Installing Flosum DevOps-CLI Extension](/devops/code/devops-cli/installing-flosum-devops-cli-extension.md)
  {% endhint %}
  {% endstep %}
  {% endstepper %}

## Using Flosum CLI

Review the Flosum CLI package commands below for a list of available commands and explanations of what each does. Because the DevOps-CLI Extension calls these commands, you can also review the following article for more detailed instructions.

* [Using DevOps CLI in VS Code](/devops/code/devops-cli/using-devops-cli-in-vs-code.md)

<details>

<summary>Flosum CLI Commands Reference</summary>

This reference covers **@flosum/cli** version **0.0.5**. Run `flosum --help` or `flosum devops --help` to see the reference for the version installed on your machine.

Every command accepts the following options, which are not repeated below.

<table><thead><tr><th width="250">Option</th><th>Description</th></tr></thead><tbody><tr><td><code>--json</code></td><td>Returns the result in JSON format. The default is false.</td></tr><tr><td><code>-h, --help</code></td><td>Displays help for the command.</td></tr></tbody></table>

The top-level command also accepts `-V, --version`, which returns the installed version number.

**Account commands**

<table><thead><tr><th width="250">Command</th><th>Description</th></tr></thead><tbody><tr><td><code>flosum login</code></td><td>Logs in to Global Settings and retrieves the data for the related services.</td></tr><tr><td><code>flosum logout</code></td><td>Deletes the saved credentials.</td></tr><tr><td><code>flosum list-credentials</code></td><td>Displays all authorized credentials.</td></tr><tr><td><code>flosum list-topologies</code></td><td>Lists the available topologies.</td></tr></tbody></table>

**DevOps commands**

<table><thead><tr><th width="250">Command</th><th>Description</th></tr></thead><tbody><tr><td><code>flosum devops init</code></td><td>Creates a Salesforce project and the CLI system files.</td></tr><tr><td><code>flosum devops clone</code></td><td>Creates a Salesforce project and retrieves the <strong>main</strong> branch from the registered DevOps tenant.</td></tr><tr><td><code>flosum devops checkout</code></td><td>Checks out another branch and retrieves any components that are missing locally.</td></tr><tr><td><code>flosum devops pull</code></td><td>Pulls the latest branch commit from DevOps.</td></tr><tr><td><code>flosum devops commit</code></td><td>Commits local changes to a remote branch on DevOps.</td></tr><tr><td><code>flosum devops rollback</code></td><td>Rolls the branch back to the last committed state.</td></tr><tr><td><code>flosum devops status</code></td><td>Returns all local changes that have not been committed.</td></tr><tr><td><code>flosum devops list-branches</code></td><td>Lists all remote branches.</td></tr><tr><td><code>flosum devops config-set</code></td><td>Sets a project config value.</td></tr><tr><td><code>flosum devops config-unset</code></td><td>Clears a project config property.</td></tr></tbody></table>

**flosum login**

<table><thead><tr><th width="250">Option</th><th>Description</th></tr></thead><tbody><tr><td><code>-a, --alias &#x3C;string></code></td><td>Alias the saved credentials are accessed with. The default is <code>default</code>.</td></tr><tr><td><code>-t, --token &#x3C;string></code></td><td>Token used to access Flosum services. The command requests it during execution if you do not supply it.</td></tr><tr><td><code>--global-settings-api-url &#x3C;string></code></td><td>Base URL of a reachable Global Settings API. Use it when the private Global Settings API is exposed outside the Docker network.</td></tr></tbody></table>

**flosum logout**

<table><thead><tr><th width="250">Option</th><th>Description</th></tr></thead><tbody><tr><td><code>-a, --alias &#x3C;string></code></td><td>Alias of the saved credentials to delete. The default is <code>default</code>.</td></tr></tbody></table>

**flosum list-topologies**

<table><thead><tr><th width="250">Option</th><th>Description</th></tr></thead><tbody><tr><td><code>-a, --alias &#x3C;string></code></td><td>Credentials alias to use when listing topologies. The default is <code>default</code>.</td></tr></tbody></table>

**flosum devops init**

<table><thead><tr><th width="250">Option</th><th>Description</th></tr></thead><tbody><tr><td><code>-n, --name &#x3C;string></code></td><td>Name of the folder the project is stored in. The command requests it during execution if you do not supply it.</td></tr><tr><td><code>-a, --alias &#x3C;string></code></td><td>Alias of the credentials used to retrieve your components from DevOps. The default is <code>default</code>.</td></tr><tr><td><code>-t, --topology &#x3C;string></code></td><td>Topology name to use for the project.</td></tr><tr><td><code>--topology-id &#x3C;number></code></td><td>Topology id to use for the project.</td></tr></tbody></table>

**flosum devops clone**

<table><thead><tr><th width="250">Option</th><th>Description</th></tr></thead><tbody><tr><td><code>-n, --name &#x3C;string></code></td><td>Name of the folder the project is stored in. The command requests it during execution if you do not supply it.</td></tr><tr><td><code>-a, --alias &#x3C;string></code></td><td>Alias of the credentials used to retrieve your components from DevOps. The default is <code>default</code>.</td></tr><tr><td><code>-t, --topology &#x3C;string></code></td><td>Topology name to use for cloning.</td></tr><tr><td><code>--topology-id &#x3C;number></code></td><td>Topology id to use for cloning.</td></tr></tbody></table>

**flosum devops checkout**

<table><thead><tr><th width="250">Option</th><th>Description</th></tr></thead><tbody><tr><td><code>-b, --branch &#x3C;string></code></td><td>Name of the branch to check out. The command requests it during execution if you do not supply it.</td></tr></tbody></table>

**flosum devops commit**

<table><thead><tr><th width="250">Option</th><th>Description</th></tr></thead><tbody><tr><td><code>-m, --message &#x3C;string></code></td><td>Commit message. The command requests it during execution if you do not supply it.</td></tr></tbody></table>

**flosum devops config-set**

Takes two arguments, both required.

<table><thead><tr><th width="250">Argument</th><th>Description</th></tr></thead><tbody><tr><td><code>config-name</code></td><td>Name of the config property. The allowed values are <code>credentialsAlias</code> and <code>topologyId</code>.</td></tr><tr><td><code>value</code></td><td>Value to set the property to.</td></tr></tbody></table>

**flosum devops config-unset**

Takes one argument, which is required.

<table><thead><tr><th width="250">Argument</th><th>Description</th></tr></thead><tbody><tr><td><code>config-name</code></td><td>Name of the config property to clear. The allowed values are <code>credentialsAlias</code> and <code>topologyId</code>.</td></tr></tbody></table>

**Commands with no additional options**

`flosum list-credentials`, `flosum devops pull`, `flosum devops rollback`, `flosum devops status`, and `flosum devops list-branches` take only the two options listed at the top of this reference.

</details>

## Troubleshooting

<details>

<summary>The installation fails with gyp ERR, node-gyp, or a Python error</summary>

The native component could not be compiled because the build toolchain is missing or incomplete.

1. Confirm that **Python 3** is installed and available on your **PATH** by running `python3 --version`.
2. Confirm that a C++ compiler is installed. On macOS, this is the Xcode Command Line Tools. On Linux, it is the compiler package group for your distribution.
3. Close and reopen your terminal so that it picks up the updated **PATH**.
4. Remove the partial installation, as described below.
5. Run the install command again.

{% hint style="warning" %}

#### Remove the Partial Installation Before Retrying

A failed installation leaves an incomplete copy of the CLI behind, along with the `flosum` command shortcuts. Remove both before retrying; otherwise, the next attempt may fail for reasons unrelated to the original error.

First, run the standard uninstall, which removes the package contents:

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

This does not remove the `flosum` shortcuts, so delete those as well.

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

Both steps are required. The `flosum` shortcuts are created even when the installation fails, and leaving them behind gives you a `flosum` command that still runs but points at files that are no longer there.

Then confirm that nothing remains:

```
flosum --version
```

The command should report `command not found`. If it reports a missing module instead, the shortcuts remain.
{% endhint %}

{% hint style="info" %}

#### You May See a Second, Different Error

The build checks for Python before it checks for a C++ compiler, so it reports only the first one that is missing. If Python was the only thing missing, installing it and retrying can produce a new error that names the C++ compiler instead. This is expected progress rather than a new problem. Install the C++ build tools, remove the partial installation again, and retry.
{% endhint %}

See the **Build Tools** prerequisite above for the full instructions per operating system.

The error message also links to the [node-gyp installation instructions](https://github.com/nodejs/node-gyp#installation), published by the build tool itself. They cover the same requirements for a general developer audience and serve as a useful second reference when troubleshooting an unusual setup.

</details>

<details>

<summary>flosum --version reports an older release than the published version</summary>

`flosum --version` returns a lower number than `npm view @flosum/cli version`. The installation reported success, but npm selected an older release.

This happens when the Node.js version on your machine is not **22**. npm chooses the newest release your Node.js version supports and does not report an error when that is not the current one.

1. Run `node --version`.
2. If it does not report **v22.x**, install **Node.js 22** as described in the **Node.js and npm** prerequisites.
3. Remove the existing installation using the steps in the first entry.
4. Run the install command again and compare the versions once more.

</details>

<details>

<summary>The flosum command reports "Cannot find module" instead of a version</summary>

An earlier installation failed partway through. The `flosum` shortcuts were created, but the files they point to were never finished, so the command runs and then reports a missing `cli.js` file.

1. Remove the partial installation using the steps in the first entry.
2. Complete the **Build Tools** prerequisite.
3. Run the install command again.

</details>

<details>

<summary>The installation fails with EBADENGINE or "Unsupported engine"</summary>

This message means the Node.js or npm version on your machine does not match the version required by the Flosum CLI.

1. Run `node --version` and `npm --version`.
2. If they do not report **v22.x** and **10.x**, install **Node.js 22** as described in the **Node.js and npm** prerequisite, then run the install command again.

On the supported versions, this message should not appear.

If you see it while running Node.js 22, check whether `engine-strict=true` is set in your `.npmrc` file. That setting turns version compatibility warnings into errors. Remove it, or override it for this installation only:

```
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/code/devops-cli/installing-flosum-cli-node.js-package.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.