The official balena CLI tool.
Switch branches/tags
452-other-fixes 508-fix-docs 520-include-command-line 565-log-node-version 566-fix-v4-compat 580-fix-emulated-build-arg 609-integrate-docker-preload 618-use-patched-global-tunnel-ng 731-add-analytics-lib 866-resource-tags-build-905ed80899dae48215d41c4f8029029c4933dcdb 866-resource-tags 947-resin-push-exit-code-build-cc6ea82 947-resin-push-exit-code-build-dffd16f 951-preload-propose-all-apps-with-same-arch-build-d409a8b 951-preload-propose-all-apps-with-same-arch-build-f65089b 951-preload-propose-all-apps-with-same-arch 969-resin-semver 978-oss-flow-build-c7b5c3050c73e99329116751f047e3fb1b7ae6a6 978-oss-flow 984-the-big-rename-build-f83732a1c8f11cbc81ede0a8c67891753af82877 1013-os-configure-device-type-build-b1e999e928dffbd9d20b05836f2fc96a2d176fa3 1013-os-configure-device-type 1015-build-secrets-command-line-options-build-9a1928bc80d16cce7d6243b4f3bd4c2eb7212e81 1015-build-secrets-command-line-options abrodersen/feature/reconfix actions-to-ts cli-form-intergration deploy-multi dont-choose-random-ssh-target feature/bundle feature/diskio feature/diskpart feature/globally-installed-node feature/heredoc-script feature/in-place-progress-bar feature/installation-script feature/windosu feature/windows-device-init fix/nodejs-ubuntu gh-templates-build-64f9b50e404944de50bf75ee37efc097f0b8f379 ignored-balena-dir jviotti/doc/anti-virus-ebusy jviotti/doc/readme jviotti/feature/222/windosu local-mode-v2 master no-resolve-symlink pdcastro-resin-semver-1.4.0 pin-typescript-version-build-cc3c6504e6faab43340975e8f0838ae12421c166 pin-typescript-version readme-typo resin-mc resin_rename_notice-build-c637fdc3c60509d94cd774ef21fa3cabd88b9a17 ssh-ts update-node-ext2fs-and-preload v7 v8-meta-branch
Nothing to show
Clone or download
Latest commit f096f4f Dec 3, 2018
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Extend the github repository templates Nov 16, 2018
automation Rename everything from 'resin' to 'balena' Oct 29, 2018
bin Rename everything from 'resin' to 'balena' Oct 29, 2018
doc Make architecture checking more stringent when installing emulators Dec 3, 2018
lib Make architecture checking more stringent when installing emulators Dec 3, 2018
tests Rename everything from 'resin' to 'balena' Oct 29, 2018
typings Make specifying the version during configuration optional Nov 16, 2018
.editorconfig fix resin local push help message and lint errors Mar 21, 2017
.gitignore Rename everything from 'resin' to 'balena' Oct 29, 2018
.hound.yml Change java_script to javascript in hound config Oct 19, 2015
.prettierrc Fix prettier configuration to avoid linting errors Mar 5, 2018
.travis.yml Rename everything from 'resin' to 'balena' Oct 29, 2018 v9.3.6 Dec 3, 2018
LICENSE Change license to Apache 2.0 Jan 4, 2016 Rename everything from 'resin' to 'balena' Oct 29, 2018 Rename everything from 'resin' to 'balena' Oct 29, 2018
appveyor.yml Autodeploy built standalone binaries for all platforms to github Dec 18, 2017
balena-completion.bash Rename everything from 'resin' to 'balena' Oct 29, 2018
capitanodoc.ts Include `join` and `leave` commands in API documentation Nov 16, 2018
coffeelint.json Add Coffeelint support Oct 31, 2014 Use spec test reporter, so we can debug with output Mar 29, 2018
package.json v9.3.6 Dec 3, 2018
tsconfig.json tconfig: Add skipLibCheck to tsconfig Oct 19, 2018

Balena CLI

The official balena CLI tool.

npm version dependencies Gitter


If you want to install the CLI directly through npm, you'll need the below. If this looks difficult, we do now have an experimental standalone binary release available, see 'Standalone install' below.

  • NodeJS (>= v6)
  • Git
  • The following executables should be correctly installed in your shell environment:
    • ssh: Any recent version of the OpenSSH ssh client (required by balena sync and balena ssh)
      • if you need ssh to work behind the proxy you also need proxytunnel installed (available as proxytunnel package for Ubuntu, for example)
    • rsync: >= 2.6.9 (required by balena sync)
Windows Support

Before installing balena-cli, you'll need a working node-gyp environment. If you don't already have one you'll see native module build errors during installation. To fix this, run npm install -g --production windows-build-tools in an administrator console (available as 'Command Prompt (Admin)' when pressing windows+x in Windows 7+).

balena sync and balena ssh have not been thoroughly tested on the standard Windows cmd.exe shell. We recommend using bash (or a similar) shell, like Bash for Windows 10 or Git for Windows.

If you still want to use cmd.exe you will have to use a package manager like MinGW or chocolatey. For MinGW the steps are:

  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

Getting Started

NPM install

If you've got all the requirements above, you should be able to install the CLI directly from npm. If not, or if you have any trouble with this, please try the new standalone install steps just below.

This might require elevated privileges in some environments.

$ 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.

In some environments, this process will need to build native modules. This may require a more complex build environment, and notably requires Python 2.7. If you hit any problems with this, we recommend you try the alternative standalone install below instead.

Standalone install

If you don't have node or a working pre-gyp environment, you can still install the CLI as a standalone binary. This is experimental and may not work perfectly yet in all environments, but it seems to work well in initial cross-platform testing, so it may be useful, and we'd love your feedback if you hit any issues.

To install the CLI as a standalone binary:

To update in future, simply download a new release and replace the extracted folder.

Have any problems, or see any unexpected behaviour? Please file an issue!


$ balena login

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

Run commands

Take a look at the full command documentation at, 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.


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 environment variable.

Alternatively, you can edit your configuration file and set balenaUrl: 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.


If you're having any problems, check our troubleshooting guide and if your problem is not addressed there, please raise an issue on GitHub and the balena team will be happy to help.

You can also get in touch with us in the balena forums.

Development guidelines

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.


The project is licensed under the Apache 2.0 license.