The official balena CLI tool.
Go to file
Otavio Jacobi 63674c8201 Use standard visuals table component for fleet/s
This effectively removes the ability to filter/sort/customize the output table.
The cli cannot properly handle this operations on all models and this one was inconsistent.
For now we recommend that users that require parsing the CLI output use the output json format and do any kind of necessary parsing on it.

Change-type: major
2024-08-07 13:14:24 -03:00
.github Switch to self-hosted 2024-07-23 11:10:09 -07:00
.versionbot v18.2.34 2024-07-29 11:08:38 +00:00
automation Remove unused code 2024-07-16 07:46:18 -03:00
bin Mark bin/dev & bin/run as executable 2024-04-09 17:16:30 +03:00
completion Fix complete generation intermitency 2024-07-10 21:22:20 -03:00
docs Use standard visuals table component for fleet/s 2024-08-07 13:14:24 -03:00
lib Use standard visuals table component for fleet/s 2024-08-07 13:14:24 -03:00
patches Fix complete generation intermitency 2024-07-10 21:22:20 -03:00
tests Use standard visuals table component for fleet/s 2024-08-07 13:14:24 -03:00
typings Remove unused code 2024-07-16 07:46:18 -03:00
.dockerignore docker: Add Docker images with the CLI and Docker-in-Docker 2021-03-15 08:34:23 -04:00
.editorconfig fix resin local push help message and lint errors 2017-03-21 12:06:05 +03:00
.eslintignore Bump balena-lint to 7.2.1 2023-10-30 07:45:51 -04:00
.eslintrc.js Bump balena-lint to 7.2.1 2023-10-30 07:45:51 -04:00
.gitattributes Revert flowzone to master 2023-08-17 20:22:53 -03:00
.gitignore Remove nvmrc 2023-04-28 10:27:15 -04:00
.hound.yml Convert gulpfile.coffee to javascript 2020-04-30 17:58:13 +01:00
.mocharc-standalone.js Test code optimization: avoid running ~70 test cases twice 2020-11-15 23:36:58 +00:00
.mocharc.js deploy: Ensure the release fails if an image's digest (hash) is missing 2021-11-16 11:55:07 +00:00
.prettierrc Fix prettier configuration to avoid linting errors 2018-03-05 16:02:09 +01:00
CHANGELOG.md v18.2.34 2024-07-29 11:08:38 +00:00
CONTRIBUTING.md Update CONTRIBUTING.md with docs instructions 2023-11-03 20:39:25 +05:30
INSTALL-ADVANCED.md Mark node 20.6.0 as the minimum working version 2024-04-16 15:42:41 +03:00
INSTALL-LINUX.md Clarify installation instructions 2021-08-29 02:08:53 +01:00
INSTALL-MAC.md Clarify installation instructions 2021-08-29 02:08:53 +01:00
INSTALL-WINDOWS.md Clarify installation instructions 2021-08-29 02:08:53 +01:00
INSTALL.md Revert styling of "balena CLI" as "balenaCLI" 2020-10-21 00:07:46 +01:00
LICENSE Change license to Apache 2.0 2016-01-03 23:58:51 -04:00
npm-shrinkwrap.json v18.2.34 2024-07-29 11:08:38 +00:00
package.json v18.2.34 2024-07-29 11:08:38 +00:00
README.md Fix forums support link in README.md 2021-04-21 06:57:28 +00:00
repo.yml Update @balena/compose to 3.0.5 2023-11-10 11:05:42 +02:00
TROUBLESHOOTING.md docs: Add entry to FAQ/Troubleshooting for ETIMEDOUT with 'balena tunnel' 2021-07-23 11:54:13 +01:00
tsconfig.dev.json Automation: enforce noImplicitAny for the type-checked javascript 2022-01-04 16:27:06 +00:00
tsconfig.json Bump balena-lint to 7.2.1 2023-10-30 07:45:51 -04:00

balena CLI

The official balena Command Line Interface.

npm version dependencies

About

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!

Installation

Check the balena CLI installation instructions on GitHub.

Choosing a shell (command prompt/terminal)

On Windows, the standard Command Prompt (cmd.exe) and PowerShell are supported. Alternative shells include:

  • MSYS2:

  • MSYS

  • Git for Windows

    • During the installation, you will be prompted to choose between "Use MinTTY" and "Use Windows' default console window". Choose the latter, because of the same MSYS2 bug mentioned above (Git for Windows actually uses MSYS2). For a screenshot, check this comment.
  • 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, bash command auto completion may be enabled by copying the balena_comp file to your system's bash_completion directory: check Docker's command completion guide for system setup instructions.

Logging in

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

Proxy support

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 or https), host, port and optionally basic auth. Examples:

    • export BALENARC_PROXY='https://bob:secret@proxy.company.com: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/or HTTP_PROXY environment variables, in the same URL format as BALENARC_PROXY.

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 squid.conf file:
acl SSL_ports port 22
acl Safe_ports port 22

Proxy exclusion

The 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 ssh target from proxying (IP address or .local hostname), the --noproxy option should be specified in addition to the BALENARC_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.

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:

For CLI bug reports or feature requests, check the CLI GitHub issues.

Deprecation policy

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 balena help. 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!

License

The project is licensed under the Apache 2.0 License. A copy is also available in the LICENSE file in this repository.