balena-cli/README.md

balena CLI

The official balena CLI tool.

Getting Started

The easiest and recommended way of installing the CLI on all platforms (Linux, MacOS, Windows) is to use the Standalone Install described below. Some specific CLI commands like balena ssh and balena sync have additional dependencies: see section Additional Dependencies.

Windows users: we now have a YouTube video tutorial for installing and getting started with the balena CLI on Windows!

Standalone install

• Download the latest zip for your OS from https://github.com/balena-io/balena-cli/releases.
• Extract the contents, putting the balena-cli folder somewhere appropriate for your system (e.g. C:/balena-cli, /usr/local/lib/balena-cli, etc).
• Add the balena-cli folder to your PATH (Windows instructions, Linux instructions, OSX instructions)
• Running balena in a fresh command line should print the balena CLI help. See Windows Support section below for some notes regarding the shell.

To update the CLI to a new version, simply download a new release and replace the extracted folder.

NPM install

If you are a Node.js developer, you may wish to install the balena CLI through npm[https://www.npmjs.com]. The npm installation involves building native (platform-specific) binary modules, for which there are some pre-requisites:

• Node.js version 6 or above (soon version 8 or above)
• Python 2.7
• g++ compiler
• make
• git
• Under Windows, the windows-build-tools npm package should be installed too, running the following command in an administrator console (available as 'Command Prompt (Admin)' when pressing Windows+X in Windows 7+) :
  npm install -g --production windows-build-tools

With those in place, the CLI installation command is:

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

--unsafe-perm is only required on systems where the global install directory is not user-writable. This allows npm install steps to download and save prebuilt native binaries. You may be able to omit it, especially if you're using a user-managed node install 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 released an OpenSSH version of ssh for Windows 10, which we understand is automatically installed through Windows Update, but can be manually installed too. More information here. For other versions of Windows, there are several ssh/OpenSSH clients provided by 3rd parties.

  • If you need ssh to work behind a proxy, you also need proxytunnel installed (available as proxytunnel package for Ubuntu, for example).

• The balena sync command currently requires rsync (>= 2.6.9) to be installed:

  • Linux: apt-get install rsync
  • MacOS: Xcode command-line tools or homebrew
  • Windows: use MinGW as described in the Windows Support section.

Windows Support

We aim at supporting the standard Windows Command Prompt (cmd.exe) and the Windows PowerShell.

Some CLI commands like balena sync and balena ssh have not been thoroughly tested with the standard Windows shells. We are aware of users having a good experience with alternative shells, including:

• Microsoft's Windows Subsystem for Linux (a.k.a. Microsoft's "bash for Windows 10").
• Git for Windows.
• MinGW
  1. Install MinGW.
  2. Install the msys-rsync and msys-openssh packages.
  3. Add MinGW to the %PATH% if this hasn't been done by the installer already. The location where the binaries are places is usually C:\MinGW\msys\1.0\bin, but it can vary if you selected a different location in the installer.
  4. Copy your SSH keys to %homedrive%%homepath\.ssh.
  5. If you need ssh to work behind the proxy you also need to install proxytunnel

Login

$ balena login

(Typically useful, but not strictly required for all commands)

Run commands

Take a look at the full command documentation at https://balena.io/docs/tools/cli/, or by running balena help.

Bash completions

Optionally you can enable tab completions for the bash shell, enabling the shell to provide additional context and automatically complete arguments tobalena. To enable bash completions, copy the balena-completion.bash file to the default bash completions directory (usually /etc/bash_completion.d/) or append it to the end of ~/.bash_completion.

FAQ

Where is my configuration file?

The per-user configuration file lives in $HOME/.balenarc.yml or %UserProfile%\_balenarc.yml, in Unix based operating systems and Windows respectively.

The balena CLI also attempts to read a balenarc.yml file in the current directory, which takes precedence over the per-user configuration file.

How do I point the balena CLI to staging?

The easiest way is to set the BALENARC_BALENA_URL=balena-staging.com environment variable.

Alternatively, you can edit your configuration file and set balenaUrl: balena-staging.com to persist this setting.

How do I make the balena CLI persist data in another directory?

The balena CLI persists your session token, as well as cached images in $HOME/.balena or %UserProfile%\_balena.

Pointing the balena CLI to persist data in another location is necessary in certain environments, like a server, where there is no home directory, or a device running balenaOS, which erases all data after a restart.

You can accomplish this by setting BALENARC_DATA_DIRECTORY=/opt/balena or adding dataDirectory: /opt/balena to your configuration file, replacing /opt/balena with your desired directory.

Support

If you're having any problems or would like to get in touch:

• Check our troubleshooting guide
• Ask us a question through the balenaCloud forum: https://forums.balena.io/c/balena-cloud
• For bug reports or feature requests, have a look at the GitHub issues or create a new one at: https://github.com/balena-io/balena-cli/issues/

Development guidelines

The CLI was originally written in CoffeeScript, but we have decided to migrate to TypeScript in order to take advantage of static typing and formal programming interfaces. The migration is taking place gradually, as part of maintenance work or the implementation of new features.

After cloning this repository and running npm install you can build the CLI using npm run build. You can then run the generated build using ./bin/balena. In order to ease development:

• you can build the CLI using the npm run build:fast variant which skips some of the build steps or
• you can use ./bin/balena-dev which live transpiles the sources of the CLI.

In either case, before opening a PR make sure to also test your changes after doing a full build with npm run build.

License

The project is licensed under the Apache 2.0 license.