The official balena Command Line Interface.
The balena CLI is a Command Line Interface for balenaCloud or openBalena. It is a software tool available for Windows, macOS and Linux, used through a command prompt / terminal window. It can be used interactively or invoked in scripts. The balena CLI builds on the balena API and the balena SDK, and can also be directly imported in Node.js applications. The balena CLI is an open-source project on GitHub, and your contribution is also welcome!
Choosing a shell (command prompt/terminal)
On Windows, the standard Command Prompt (
are supported. Alternative shells include:
Microsoft's Windows Subsystem for Linux (WSL). In this case, a Linux distribution like Ubuntu is installed via the Microsoft Store, and a balena CLI release for Linux should be selected. See FAQ for using the balena CLI with WSL and Docker Desktop for Windows.
On macOS and Linux, the standard terminal window is supported. Optionally,
auto completion may be enabled by copying the
file to your system's
bash_completion directory: check Docker's command completion
guide for system setup instructions.
Several CLI commands require access to your balenaCloud account, for example in order to push a new release to your fleet. Those commands require creating a CLI login session by running:
$ balena login
HTTP(S) proxies can be configured through any of the following methods, in precedence order (from higher to lower):
BALENARC_PROXYenvironment variable in URL format, with protocol (
https), host, port and optionally basic auth. Examples:
proxysetting in the CLI config file. It may be:
- A string in URL format, e.g.
- An object in the format:
proxy: protocol: 'http' host: 'proxy.company.com' port: 12345 proxyAuth: 'bob:secret'
- A string in URL format, e.g.
HTTP_PROXYenvironment variables, in the same URL format as
Proxy setup for balena ssh
In order to work behind a proxy server, the
balena ssh command requires the
proxytunnel package (command-line tool) to be installed.
proxytunnel 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).
Ensure that the proxy server is configured to allow proxy requests to ssh port 22, using
SSL encryption. For example, in the case of the Squid proxy
server, it should be configured with the following rules in the
acl SSL_ports port 22
acl Safe_ports port 22
BALENARC_NO_PROXY variable may be used to exclude specified destinations from proxying.
- This feature requires CLI version 11.30.8 or later. In the case of the npm installation option, it also requires Node.js version 10.16.0 or later.
- To exclude a
balena sshtarget from proxying (IP address or
--noproxyoption should be specified in addition to the
By default (if
BALENARC_NO_PROXY is not defined), all private IPv4
'*.local' hostnames are excluded
from proxying. Other hostnames that resolve to private IPv4 addresses are not excluded by
default, because matching takes place before name resolution.
127.0.0.1 are always excluded from proxying, regardless of the value of
The format of the
BALENARC_NO_PROXY environment variable is a comma-separated list of patterns
that are matched against hostnames or IP addresses. For example:
Matched patterns are excluded from proxying. Wildcard expressions are documented at
matcher. Matching takes place before name
resolution, so a pattern like
'192.168.*' will not match a hostname that resolves to an IP
Command reference documentation
The full CLI command reference is available on the web or by running
balena help --verbose.
Support, FAQ and troubleshooting
To learn more, troubleshoot issues, or to contact us for support:
- Check the masterclass tutorials
- Check our FAQ / troubleshooting document
- Ask us a question through the balenaCloud forum
For CLI bug reports or feature requests, check the CLI GitHub issues.
The balena CLI uses semver versioning, with the concepts of major, minor and patch version releases.
The latest release of a major version of the balena CLI will remain compatible with the balenaCloud backend services for at least one year from the date when the following major version is released. For example, balena CLI v11.36.0, as the latest v11 release, would remain compatible with the balenaCloud backend for one year from the date when v12.0.0 was released.
Half way through to that period (6 months after the release of the next major
version), older major versions of the balena CLI will start printing a deprecation
warning message when it is used interactively (when
stderr is attached to a TTY
device file). At the end of that period, older major versions will exit with an
error message unless the
--unsupported flag is used. This behavior was
introduced in CLI version 12.47.0 and is also documented by
To take advantage of the latest backend features and ensure compatibility, users
are encouraged to regularly update the balena CLI to the latest version.
Contributing (including editing documentation files)
Please have a look at the CONTRIBUTING.md file for some guidance before submitting a pull request or updating documentation (because some files are automatically generated). Thank you for your help and interest!
The project is licensed under the Apache 2.0 License. A copy is also available in the LICENSE file in this repository.