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!
Check the balena CLI installation instructions on GitHub.
On Windows, the standard Command Prompt (cmd.exe
) and
PowerShell
are supported. We are aware of users also having a good experience with alternative shells,
including:
- MSYS2:
- Install additional packages with the command:
pacman -S git openssh rsync
- Set a Windows environment variable:
MSYS2_PATH_TYPE=inherit
- Note that a bug in the MSYS2 launch script (
msys2_shell.cmd
) makes text-based interactive CLI menus to break. Check this Github issue for a workaround.
- Install additional packages with the command:
- MSYS: select the
msys-rsync
andmsys-openssh
packages too - 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, bash
command
auto completion may be enabled by copying the
balena-completion.bash
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):
-
The
BALENARC_PROXY
environment variable in URL format, with protocol (http
orhttps
), host, port and optionally basic auth. Examples:export BALENARC_PROXY='https://bob:[email protected]:12345'
export BALENARC_PROXY='http://localhost:8000'
-
The
proxy
setting in the CLI config file. It may be:-
A string in URL format, e.g.
proxy: 'http://localhost:8000'
-
An object in the format:
proxy: protocol: 'http' host: 'proxy.company.com' port: 12345 proxyAuth: 'bob:secret'
-
-
The
HTTPS_PROXY
and/orHTTP_PROXY
environment variables, in the same URL format asBALENARC_PROXY
.
Note: The
balena ssh
command has additional setup requirements to work behind a proxy. Check the installation instructions, and 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 thesquid.conf
file:
acl SSL_ports port 22
acl Safe_ports port 22
The BALENARC_NO_PROXY
variable may be used to exclude specified destinations from proxying.
- This feature requires balena 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 ssh
target from proxying (IP address or.local
hostname), the--noproxy
option should be specified in addition to theBALENARC_NO_PROXY
variable.
By default (if BALENARC_NO_PROXY
is not defined), all private IPv4
addresses and '*.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.
localhost
and 127.0.0.1
are always excluded from proxying, regardless of the value of
BALENARC_NO_PROXY.
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:
export BALENARC_NO_PROXY='*.local,dev*.mycompany.com,192.168.*'
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
address like 192.168.1.2
.
The full CLI command reference is available on the web or by running balena help
and balena help --verbose
.
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.
The balena CLI uses semver versioning, with the concepts of major, minor and patch version releases.
The latest release of the previous major version of the balena CLI will remain compatible with the balenaCloud backend services for one year from the date when the next major version is released. For example, balena CLI v10.17.5, as the latest v10 release, would remain compatible with the balenaCloud backend for one year from the date when v11.0.0 is released.
At the end of this period, the older major version is considered deprecated and some of the functionality that depends on balenaCloud services may stop working at any time. Users are encouraged to regularly update the balena CLI to the latest version.
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.