Installing Flosum CLI Node.js Package

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.

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.

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

1

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

1. Confirm that node --version reports v22.x and that npm --version reports 10.x.

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.

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.

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.

2

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.

Installing the Flosum CLI

1

Run the Install Command

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

npm i -g @flosum/cli

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

2

Verify the Installation

1. Run the following command:

flosum --version

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

npm view @flosum/cli version

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

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

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

Flosum CLI Commands Reference

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.

Option	Description
--json	Returns the result in JSON format. The default is false.
-h, --help	Displays help for the command.

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

Account commands

Command	Description
flosum login	Logs in to Global Settings and retrieves the data for the related services.
flosum logout	Deletes the saved credentials.
flosum list-credentials	Displays all authorized credentials.
flosum list-topologies	Lists the available topologies.

DevOps commands

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

flosum login

Option	Description
-a, --alias <string>	Alias the saved credentials are accessed with. The default is default.
-t, --token <string>	Token used to access Flosum services. The command requests it during execution if you do not supply it.
--global-settings-api-url <string>	Base URL of a reachable Global Settings API. Use it when the private Global Settings API is exposed outside the Docker network.

flosum logout

Option	Description
-a, --alias <string>	Alias of the saved credentials to delete. The default is default.

flosum list-topologies

Option	Description
-a, --alias <string>	Credentials alias to use when listing topologies. The default is default.

flosum devops init

Option	Description
-n, --name <string>	Name of the folder the project is stored in. The command requests it during execution if you do not supply it.
-a, --alias <string>	Alias of the credentials used to retrieve your components from DevOps. The default is default.
-t, --topology <string>	Topology name to use for the project.
--topology-id <number>	Topology id to use for the project.

flosum devops clone

Option	Description
-n, --name <string>	Name of the folder the project is stored in. The command requests it during execution if you do not supply it.
-a, --alias <string>	Alias of the credentials used to retrieve your components from DevOps. The default is default.
-t, --topology <string>	Topology name to use for cloning.
--topology-id <number>	Topology id to use for cloning.

flosum devops checkout

Option	Description
-b, --branch <string>	Name of the branch to check out. The command requests it during execution if you do not supply it.

flosum devops commit

Option	Description
-m, --message <string>	Commit message. The command requests it during execution if you do not supply it.

flosum devops config-set

Takes two arguments, both required.

Argument	Description
config-name	Name of the config property. The allowed values are credentialsAlias and topologyId.
value	Value to set the property to.

flosum devops config-unset

Takes one argument, which is required.

Argument	Description
config-name	Name of the config property to clear. The allowed values are credentialsAlias and topologyId.

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.

Troubleshooting

The installation fails with gyp ERR, node-gyp, or a Python error

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.

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.

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.

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

The error message also links to the node-gyp installation instructions, 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.

flosum --version reports an older release than the published version

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.

The flosum command reports "Cannot find module" instead of a version

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.

The installation fails with EBADENGINE or "Unsupported engine"

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