Skip to content

INSTALL-ADVANCED.md

Latest commit

 

History

History
168 lines (128 loc) · 8.42 KB

INSTALL-ADVANCED.md

File metadata and controls

168 lines (128 loc) · 8.42 KB
Raw

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 tar.gz Package: these are plain tar.gz files with the balena CLI bundled within. 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:

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 tar 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 tar.gz 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 tar.gz Package

  1. Download the latest tar.gz 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.tar.gz ← also for the Windows Subsystem for Linux
    balena-cli-vX.Y.Z-macOS-x64-standalone.tar.gz balena-cli-vX.Y.Z-windows-x64-standalone.tar.gz

  2. Extract the tar.gz file contents to any folder you choose. The extracted contents will be a balena folder containing a bin subdirectory.

  3. Add the balena/bin 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 tar.gz 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/bin/balena executable out of the extracted balena 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 folder.

To update the CLI to a new version, download a new release tar.gz 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 > 24.11.0 Versions 25 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 22

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

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

Windows (not WSL)

Install:

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

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:

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.