The official balena CLI tool.
Go to file
2019-04-25 13:37:06 +03:00
.github Add maintainer, reviewers, and devexp team as code owners 2019-03-12 13:34:27 +00:00
automation Bump resin-multibuild (2.1.4), docker-progress (3.0.5), resin-lint (3.0.1) 2019-03-18 14:09:06 +00:00
bin Improve startup time by adding fast-boot 2019-01-14 12:43:51 +00:00
doc Allow specifying a .local address for logs and push 2019-04-25 11:00:45 +01:00
lib Allow specifying a .local address for logs and push 2019-04-25 11:00:45 +01:00
tests Rename everything from 'resin' to 'balena' 2018-10-29 22:29:02 +01:00
typings Add livepush ability to balena push 2019-04-23 14:00:04 +01:00
.editorconfig fix resin local push help message and lint errors 2017-03-21 12:06:05 +03:00
.gitignore Add tslint config to enable consistent lint process 2019-04-24 12:48:52 +01:00
.hound.yml Change java_script to javascript in hound config 2015-10-19 14:21:10 -04:00
.prettierrc Fix prettier configuration to avoid linting errors 2018-03-05 16:02:09 +01:00
.travis.yml Rename everything from 'resin' to 'balena' 2018-10-29 22:29:02 +01:00
appveyor.yml Autodeploy built standalone binaries for all platforms to github 2017-12-18 14:55:07 +01:00
balena-completion.bash Rename everything from 'resin' to 'balena' 2018-10-29 22:29:02 +01:00
capitanodoc.ts Remove 'quickstart' command and deprecate 'local push'. 2019-04-03 17:34:55 +01:00
CHANGELOG.md v10.8.0 2019-04-25 13:37:06 +03:00
coffeelint.json Add Coffeelint support 2014-10-31 09:48:53 -04:00
gulpfile.coffee Use spec test reporter, so we can debug with output 2018-03-29 11:11:25 +02:00
LICENSE Change license to Apache 2.0 2016-01-03 23:58:51 -04:00
package.json v10.8.0 2019-04-25 13:37:06 +03:00
README.md Updated CLI installation notes on README.md and ran prettier 2019-04-18 14:52:51 +01:00
TROUBLESHOOTING.md Rename everything from 'resin' to 'balena' 2018-10-29 22:29:02 +01:00
tsconfig.json Update lib/actions/local/flash.coffee 2019-01-11 17:56:34 +01:00
tslint.json Add tslint config to enable consistent lint process 2019-04-24 12:48:52 +01:00

balena CLI

The official balena CLI tool.

npm version dependencies Gitter

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

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:

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:

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.