The official balena CLI tool.
Go to file
Paulo Castro 1319e0642b
Merge pull request from balena-io/fix-instance-of
Unpin balena-sdk and review 'instanceof' usage
2020-04-20 14:15:19 +01:00
.github Fix proxy support and add proxy exclusion feature (Node.js >= 10.16.0 only) 2020-01-27 12:11:11 +00:00
.versionbot v11.31.3 2020-04-17 02:40:26 +03:00
automation Convert commands join, leave to oclif. 2020-04-09 20:50:42 +02:00
bin Fix ts-node invocation in balena-dev 2019-06-07 15:02:25 +01:00
doc Convert commands join, leave to oclif. 2020-04-09 20:50:42 +02:00
lib Review 'instanceof' usage with classes of external packages 2020-04-18 02:50:00 +01:00
patches Fix opn patch (npm installation warning) 2020-03-12 22:34:59 +00:00
tests Convert commands join, leave to oclif. 2020-04-09 20:50:42 +02:00
typings Convert internal scandevices, internal osinit to typescript & oclif 2020-04-03 16:39:39 +02:00
.editorconfig fix resin local push help message and lint errors 2017-03-21 12:06:05 +03:00
.gitattributes Prevent auto merge of npm-shrinkwrap.json and explain it in CONTRIBUTING.md 2020-03-11 22:11:54 +00:00
.gitignore Add '.nyc_output' folder to '.gitignore' (test coverage reporting) 2020-01-14 16:19:08 +00:00
.hound.yml Change java_script to javascript in hound config 2015-10-19 14:21:10 -04:00
.prettierrc Fix prettier configuration to avoid linting errors 2018-03-05 16:02:09 +01:00
.resinci.yml Update README and INSTALL docs (review typos and some rewording) 2019-05-01 18:15:47 +01:00
.travis.yml Add 'npm run package' command 2019-07-04 20:01:07 +01:00
appveyor.yml Add 'npm run package' command 2019-07-04 20:01:07 +01:00
balena-completion.bash Remove 'signup' command 2019-06-04 17:06:46 +01:00
CHANGELOG.md v11.31.3 2020-04-17 02:40:26 +03:00
coffeelint.json Add Coffeelint support 2014-10-31 09:48:53 -04:00
CONTRIBUTING.md Review CONTRIBUTING.md and add 'instanceof' usage advice 2020-04-18 02:50:00 +01:00
gulpfile.coffee Convert test files to Typescript 2019-08-08 16:50:50 +01:00
INSTALL.md INSTALL.md: emphasize the standalone zip package recommendation for WSL 2020-03-18 22:35:12 +00:00
LICENSE Change license to Apache 2.0 2016-01-03 23:58:51 -04:00
npm-shrinkwrap.json Unpin balena-sdk (bump balena-sdk to v12.33.0) 2020-04-18 02:50:00 +01:00
package.json Review 'instanceof' usage with classes of external packages 2020-04-18 02:50:00 +01:00
README.md Update README regarding proxy server support 2020-03-30 14:45:16 +01:00
repo.yml Add a script to automate nested changelogs 2020-02-21 15:18:17 +02:00
TROUBLESHOOTING.md Update/improve npm install instructions for Windows 2019-10-14 13:34:02 +01:00
tsconfig.dev.json Use balena-lint for javascript linting and add javascript type-checking 2020-03-25 12:12:03 +00:00
tsconfig.js.json Use balena-lint for javascript linting and add javascript type-checking 2020-03-25 12:12:03 +00:00
tsconfig.json Use balena-lint for javascript linting and add javascript type-checking 2020-03-25 12:12:03 +00:00
tslint.json Use balena-lint for javascript linting and add javascript type-checking 2020-03-25 12:12:03 +00:00

balena CLI

The official balena CLI tool.

npm version dependencies

About

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!

Installation

Check the balena CLI installation instructions on GitHub.

Getting Started

Choosing a shell (command prompt/terminal)

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:
  • MSYS: select the msys-rsync and msys-openssh packages too
  • 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 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.

Logging in

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

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.

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 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 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 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 and balena help --verbose.

Support, FAQ and troubleshooting

If you come across any problems or would like to get in touch:

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.