balena-cli/INSTALL.md

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

Windows users:

• There is a YouTube video tutorial for installing and getting started with the balena CLI on Windows. (The video uses the standalone zip package option.)
• If you are using Microsoft's Windows Subsystem for Linux (WSL), install a balena CLI release for Linux rather than for Windows, like the standalone zip package for Linux. An installation with the graphical executable installer for Windows will not work with WSL.

Executable Installer

Recommended for Windows (but not Windows Subsystem for Linux) and macOS:

1. Download the latest installer from the releases page. Look for a file name that ends with "-installer", for example:
   balena-cli-vX.Y.Z-windows-x64-installer.exe
balena-cli-vX.Y.Z-macOS-x64-installer.pkg

2. Double click the downloaded file to run the installer.
   If you are using macOS Catalina (10.15), check this known issue and workaround.

3. After the installation completes, close and re-open any open command terminal windows so that the changes made by the installer to the PATH environment variable can take effect. Check that the installation was successful by running the following commands on a command terminal:

• balena version - should print the installed CLI version
• balena help - should print the balena CLI help

Note: 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/lib/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 Catalina (10.15), 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. It should however work with all "desktop" or "server" distributions, e.g. Ubuntu, Debian, Suse, Fedora, Arch Linux and many more.
• 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 additional development tools to be installed first:

• Node.js version 10 (min 10.20.0) or 12 (version 14 is not yet fully supported)
  • Linux, macOS and Windows Subsystem for Linux (WSL):
    Installing Node via nvm is recommended. When the "system" or "default" Node.js and npm packages are installed with "apt-get" in Linux distributions like Ubuntu, users often report permission or compilation errors when running "npm install". This sample Dockerfile shows the CLI installation steps on an Ubuntu 18.04 base image.
• Python 2.7, git, make, g++
  • Linux and Windows Subsystem for Linux (WSL):
    sudo apt-get install -y python git make g++
  • macOS: install Apple's Command Line Tools by running on a Terminal window:
    xcode-select --install

On Windows (not WSL), the dependencies above and additional ones can be met by installing:

• Node.js from the Nodejs.org download page.

• The MSYS2 shell, which provides git, make, g++, ssh, rsync and more:

  • pacman -S git openssh rsync gcc make
  • 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 (which provides Python 2.7 and more), by running the following command on an administrator console:

  npm install -g --production windows-build-tools

With these dependencies in place, the balena CLI installation command is:

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

--unsafe-perm is required when npm install is executed as the root user, or on systems where the global install directory is not user-writable. It allows npm install steps to download and save prebuilt native binaries, and also allows the execution of npm scripts like postinstall that are used to patch dependencies. It is usually possible to omit --unsafe-perm if installing under a regular (non-root) user account, especially if using a user-managed node installation such as nvm.

Additional Dependencies

• The balena ssh command requires a recent version of the ssh command-line tool to be available:

  • macOS and Linux usually already have it installed. Otherwise, search for the available packages on your specific Linux distribution, or for the Mac consider the Xcode command-line tools or homebrew.

  • Microsoft started distributing an SSH client with Windows 10, which we understand is automatically installed through Windows Update, but can be manually installed too (more information). For other versions of Windows, there are several ssh/OpenSSH clients provided by 3rd parties.

  • The proxytunnel package (command-line tool) is needed for the balena ssh command to work behind a proxy. It is available for Linux distributions like Ubuntu/Debian (apt install proxytunnel), and for macOS through Homebrew. Windows support is limited to the Windows Subsystem for Linux (e.g., by installing Ubuntu through the Microsoft App Store). Check the README file for proxy configuration instructions.

• The balena preload, balena build and balena deploy --build commands require Docker or balenaEngine to be available:

  • The balena preload command requires the Docker Engine to support the AUFS storage driver. Docker Desktop for Mac and Windows dropped support for the AUFS filesystem in Docker CE versions greater than 18.06.1, so the workaround is to downgrade to version 18.06.1 (links: Docker CE for Windows and Docker CE for Mac). See more details in CLI issue 1099.
  • Commonly, Docker is installed on the same machine where the CLI is being used, but the balena build and balena deploy commands can also use a remote Docker Engine (daemon) or balenaEngine (which could be a remote device running a balenaOS development image) by specifying its IP address and port number as command-line options. Check the documentation for each command, e.g. balena help build, or the online reference.
  • If you are using Microsoft's Windows Subsystem for Linux (WSL) and Docker Desktop for Windows, check the FAQ item "Docker seems to be unavailable".

• The balena scan command requires a multicast DNS (mDNS) service like Bonjour or Avahi:

  • On Windows, check if 'Bonjour' is installed (Control Panel > Programs and Features). If not, you can download Bonjour for Windows from https://support.apple.com/kb/DL999
  • Most 'desktop' Linux distributions ship with Avahi. Search for the installation command for your distribution. E.g. for Ubuntu: sudo apt-get install avahi-daemon
  • macOS comes with Bonjour built-in.

• The balena os configure command is currently not supported on Windows natively. Windows users are advised to install the Windows Subsystem for Linux (WSL) with Ubuntu, and use the Linux release of the balena CLI.

Configuring SSH keys

The balena ssh command requires an SSH key to be added to your balena account. If you had already added a SSH key in order to deploy with 'git push', then you are probably done and may skip this section. You can check whether you already have an SSH key in your balena account with the balena keys command, or by visiting the balena web dashboard, clicking on your name -> Preferences -> SSH Keys.

Note: An "SSH key" actually consists of a public/private key pair. A typical name for the private key file is "id_rsa", and a typical name for the public key file is "id_rsa.pub". Both key files are saved to your computer (with the private key optionally protected by a password), but only the public key is saved to your balena account. This means that if you change computers or otherwise lose the private key, you cannot recover the private key through your balena account. You can however add new keys, and delete the old ones.

If you don't have an SSH key in your balena account:

• If you have an existing SSH key in your computer that you would like to use, you can add it to your balena account through the balena web dashboard (Preferences -> SSH Keys), or through the CLI itself:

# Windows 10 (cmd.exe prompt) example:
$ balena key add MyKey %userprofile%\.ssh\id_rsa.pub
# Linux / macOS example:
$ balena key add MyKey ~/.ssh/id_rsa.pub

• To generate a new key, you can follow GitHub's documentation, skipping the step about adding the key to your GitHub account, and instead adding the key to your balena account as described above.