balena-cli/INSTALL-ADVANCED.md

balena CLI Advanced Installation Options

These are alternative, advanced installation options. Most users would prefer the recommended, streamlined installation instructions.

There are 3 options to choose from to install balena's CLI:

• Executable Installer: the easiest method on Windows and macOS, using the traditional graphical desktop application installers.
• Standalone Zip Package: these are plain zip files with the balena CLI executable in them: extract and run. Available for all platforms: Linux, Windows, macOS. Recommended also for scripted installation in CI (continuous integration) environments.
• NPM Installation: recommended for Node.js developers who may be interested in integrating the balena CLI in their existing projects or workflow.

Some specific CLI commands have a few extra installation steps: see section Additional Dependencies.

Executable Installer

This is the recommended installation option on macOS and Windows. Follow the specific OS instructions:

• Windows
• macOS

Note regarding WSL (Windows Subsystem for Linux)
If you would like to use WSL, follow the installations instructions for Linux rather than Windows, as WSL consists of a Linux environment.

If you had previously installed the CLI using a standalone zip package, it may be a good idea to check your system's PATH environment variable for duplicate entries, as the terminal will use the entry that comes first. Check the Standalone Zip Package instructions for how to modify the PATH variable.

By default, the CLI is installed to the following folders:

OS	Folders
Windows:	C:\Program Files\balena-cli\
macOS:	/usr/local/src/balena-cli/ /usr/local/bin/balena

Standalone Zip Package

1. Download the latest zip file from the releases page. Look for a file name that ends with the word "standalone", for example:
   balena-cli-vX.Y.Z-linux-x64-standalone.zip ← also for the Windows Subsystem for Linux
   balena-cli-vX.Y.Z-macOS-x64-standalone.zip
balena-cli-vX.Y.Z-windows-x64-standalone.zip

2. Extract the zip file contents to any folder you choose. The extracted contents will include a balena-cli folder.

3. Add the balena-cli folder to the system's PATH environment variable.
   See instructions for: Linux | macOS | Windows

• If you are using macOS 10.15 or later (Catalina, Big Sur), check this known issue and workaround.
• Linux Alpine and Busybox: the standalone zip package is not currently compatible with these "compact" Linux distributions, because of the alternative C libraries they ship with. For these, consider the NPM Installation option.
• Note that moving the balena executable out of the extracted balena-cli folder on its own (e.g. moving it to /usr/local/bin/balena) will not work, as it depends on the other folders and files also present in the balena-cli folder.

To update the CLI to a new version, download a new release zip file and replace the previous installation folder. To uninstall, simply delete the folder and edit the PATH environment variable as described above.

NPM Installation

If you are a Node.js developer, you may wish to install the balena CLI via npm. The npm installation involves building native (platform-specific) binary modules, which require some development tools to be installed first, as follows.

The balena CLI currently requires Node.js version ^20.6.0 Versions 21 and later are not yet fully supported.

Install development tools

Linux or WSL (Windows Subsystem for Linux)

$ sudo apt-get update && sudo apt-get -y install curl python3 git make g++
$ curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.38.0/install.sh | bash
$ . ~/.bashrc
$ nvm install 20

The curl command line above uses nvm to install Node.js, instead of using apt-get. Installing Node.js through apt-get is a common source of problems from permission errors to conflict with other system packages, and therefore not recommended.

macOS

• Download and install Apple's Command Line Tools from https://developer.apple.com/downloads/
• Install Node.js through nvm:

$ curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.38.0/install.sh | bash
$ . ~/.bashrc
$ nvm install 20

Windows (not WSL)

Install:

• If you'd like the ability to switch between Node.js versions, install

• Node.js v20 from the Nodejs.org releases page. nvm-windows instead.

• The MSYS2 shell, which provides git, make, g++ and more:
  • pacman -S git gcc make openssh p7zip
  • Set a Windows environment variable: MSYS2_PATH_TYPE=inherit
  • Note that a bug in the MSYS2 launch script (msys2_shell.cmd) makes text-based interactive CLI menus to misbehave. Check this Github issue for a workaround.
• The Windows Driver Kit (WDK), which is needed to compile some native Node modules. It is not necessary to install Visual Studio, only the WDK, which is "step 2" in the following guides:
  • WDK for Windows 10
  • WDK for earlier versions of Windows
• The windows-build-tools npm package, by running the following command on an administrator console:
  npm install --global --production windows-build-tools

Install the balena CLI

After installing the development tools, install the balena CLI with:

$ npm install balena-cli --global --production --unsafe-perm

--unsafe-perm is needed when npm install is executed as the root user (e.g. in a Docker container) in order to allow npm scripts like postinstall to be executed.

Additional Dependencies

The balena device ssh, device detect, build, deploy and preload commands may require additional software to be installed. Check the Additional Dependencies sections for each operating system:

• Windows
• macOS
• Linux

Where Docker or balenaEngine are required, they may be installed on the local machine (where the balena CLI is executed), on a remote server, or on a balenaOS device running a balenaOS development image. Reasons why this may be desirable include:

• To avoid having to install Docker on the development machine / laptop.
• To take advantage of a more powerful server (CPU, memory).
• To build or run images "natively" on an ARM device, avoiding the need for QEMU emulation.

To use a remote Docker Engine (daemon) or balenaEngine, specify the remote machine's IP address and port number with the --dockerHost and --dockerPort command-line options. The preload command has additional requirements because the bind mount feature is used. For more details, see balena help for each command or the online reference.