The official balena CLI tool.
The balena CLI (Command-Line Interface) allows you to interact with the balenaCloud and the balena API through a terminal window on Linux, macOS or Windows. You can also write shell scripts around it, or import its Node.js modules to use it programmatically. As an open-source project on GitHub, your contribution is also welcome!
Choosing a shell (command prompt/terminal)
On Windows, the standard Command Prompt (
are supported. We are aware of users also having a good experience with alternative shells,
- MSYS: select the
- Git for Windows
- 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 is recommended. See FAQ for using 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 application. 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: 12345proxyAuth: 'bob:secret'
HTTP_PROXYenvironment variables, in the same URL format as
balena sshcommand has additional setup requirements to work behind a proxy.
Check the installation instructions.
Some installations of the balena CLI also include support for the
variable, which allows proxy exclusion patterns to be defined. The current support status is listed
below. Eventually, all installation types will have support for it.
|OS||Installation type||BALENARC_NO_PROXY environment variable support|
|Windows||standalone zip||Supported with CLI v11.24.0 and later|
|macOS||standalone zip||Not supported|
|macOS||native/GUI||Supported with CLI v11.24.0 and later|
|Linux||standalone zip||Not supported|
|Any||npm||Supported with Node.js >= v10.16.0 and CLI >= v11.24.0|
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. Matching takes place before name resolution, so a
'192.168.*' will not match a hostname like
proxy.company.com even if the
hostname resolves to an IP address like
192.168.1.2. Pattern matching expressions are documented
By default, if BALENARC_NO_PROXY is not defined, all private IPv4
'*.local' are excluded from
proxying. Other hostnames that may resolve to private IPv4 addresses are not excluded by
default, as matching takes place before name resolution. In addition,
are always excluded from proxying, regardless of the value of BALENARC_NO_PROXY. These default
exclusions only apply to the CLI installations where BALENARC_NO_PROXY is supported, as listed in
the table above.
Command reference documentation
The full CLI command reference is available on the web or by running
balena help and
balena help --verbose.
Support, FAQ and troubleshooting
If you come across any problems or would like to get in touch:
- Check our FAQ / troubleshooting document.
- Ask us a question through the balenaCloud forum.
- For bug reports or feature requests, have a look at the GitHub issues or create a new one.
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.