ExternalVendorCode/balena-cli
1
0
Fork 0
mirror of https://github.com/balena-io/balena-cli.git synced 2024-12-19 05:37:51 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Merge pull request #2039 from balena-io/1760-simplify-install-docs

Browse Source 
Reorganize and simplify installation instructions
This commit is contained in:
bulldozer-balena[bot] 2020-09-19 09:21:20 +00:00 committed by GitHub
commit e484701276
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
30 changed files with 581 additions and 402 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
.github/ISSUE_TEMPLATE.md vendored
View File

@ -1,7 +1,7 @@
# About this issue tracker # About this issue tracker
*The balena CLI (Command Line Interface) is a tool used to interact with the balena platform. *balenaCLI (Command Line Interface) is a tool used to interact with the balena platform.
This GitHub issue tracker is used for bug reports and feature requests regarding the CLI This GitHub issue tracker is used for bug reports and feature requests regarding the CLI
tool. General and troubleshooting questions (such as setting up your project to work with a tool. General and troubleshooting questions (such as setting up your project to work with a
balenalib base image) are encouraged to be posted to the [balena balenalib base image) are encouraged to be posted to the [balena
@ -11,7 +11,7 @@ community can both contribute and benefit from the answers.*
*Please also check that this issue is not a duplicate. If there is another issue describing *Please also check that this issue is not a duplicate. If there is another issue describing
the same problem or feature please add comments to the existing issue.* the same problem or feature please add comments to the existing issue.*
*Thank you for your time and effort creating the issue report, and helping us improve the *Thank you for your time and effort creating the issue report, and helping us improve
balenaCLI!* balenaCLI!*
--- ---

2
CONTRIBUTING.md
View File

@ -1,6 +1,6 @@
# Contributing # Contributing
The balena CLI is an open source project and your contribution is welcome! balenaCLI is an open source project and your contribution is welcome!
* Install the dependencies listed in the [NPM Installation](./INSTALL.md#npm-installation) * Install the dependencies listed in the [NPM Installation](./INSTALL.md#npm-installation)
section of the `INSTALL.md` file. Check the section [Additional section of the `INSTALL.md` file. Check the section [Additional

150
INSTALL-ADVANCED.md Normal file
View File

@ -0,0 +1,150 @@
# balenaCLI Advanced Installation Options
**These are alternative, advanced installation options. Most users would prefer the [recommended,
streamlined installation
instructions](https://github.com/balena-io/balena-cli/blob/master/INSTALL.md).**
There are 3 options to choose from to install balena's CLI:
* [Executable Installer](#executable-installer): the easiest method on Windows and macOS, using the
traditional graphical desktop application installers.
* [Standalone Zip Package](#standalone-zip-package): these are plain zip files with the balenaCLI
executable in them: extract and run. Available for all platforms: Linux, Windows, macOS.
Recommended also for scripted installation in CI (continuous integration) environments.
* [NPM Installation](#npm-installation): recommended for Node.js developers who may be interested
in integrating balenaCLI in their existing projects or workflow.
Some specific CLI commands have a few extra installation steps: see section [Additional
Dependencies](#additional-dependencies).
## Executable Installer
This is the recommended installation option on macOS and Windows. Follow the specific OS
instructions:
* [Windows](./INSTALL-WINDOWS.md)
* [macOS](./INSTALL-MAC.md)
> Note regarding WSL ([Windows Subsystem for
> Linux](https://docs.microsoft.com/en-us/windows/wsl/about))
> If you would like to use WSL, follow the [installations instructions for
> Linux](./INSTALL-LINUX.md) rather than Windows, as WSL consists of a Linux environment.
If you had previously installed the CLI using a standalone zip package, it may be a good idea to
check your system's `PATH` environment variable for duplicate entries, as the terminal will use the
entry that comes first. Check the [Standalone Zip Package](#standalone-zip-package) instructions
for how to modify the PATH variable.
By default, the CLI is installed to the following folders:
OS | Folders
--- | ---
Windows: | `C:\Program Files\balena-cli\`
macOS: | `/usr/local/lib/balena-cli/` <br> `/usr/local/bin/balena`
## Standalone Zip Package
1. Download the latest zip file from the [releases page](https://github.com/balena-io/balena-cli/releases).
Look for a file name that ends with the word "standalone", for example:
`balena-cli-vX.Y.Z-linux-x64-standalone.zip` ← _also for the Windows Subsystem for Linux_
`balena-cli-vX.Y.Z-macOS-x64-standalone.zip`
`balena-cli-vX.Y.Z-windows-x64-standalone.zip`
2. Extract the zip file contents to any folder you choose. The extracted contents will include a
`balena-cli` folder.
3. Add the `balena-cli` folder to the system's `PATH` environment variable.
See instructions for:
[Linux](https://stackoverflow.com/questions/14637979/how-to-permanently-set-path-on-linux-unix) |
[macOS](https://www.architectryan.com/2012/10/02/add-to-the-path-on-mac-os-x-mountain-lion/#.Uydjga1dXDg) |
[Windows](https://www.computerhope.com/issues/ch000549.htm)
> * If you are using macOS Catalina (10.15), [check this known issue and
> workaround](https://github.com/balena-io/balena-cli/issues/1479).
> * **Linux Alpine** and **Busybox:** the standalone zip package is not currently compatible with
> these "compact" Linux distributions, because of the alternative C libraries they ship with.
> For these, consider the [NPM Installation](#npm-installation) option.
> * Note that moving the `balena` executable out of the extracted `balena-cli` folder on its own
> (e.g. moving it to `/usr/local/bin/balena`) will **not** work, as it depends on the other
> folders and files also present in the `balena-cli` folder.
To update the CLI to a new version, download a new release zip file and replace the previous
installation folder. To uninstall, simply delete the folder and edit the PATH environment variable
as described above.
## NPM Installation
If you are a Node.js developer, you may wish to install balenaCLI via [npm](https://www.npmjs.com).
The npm installation involves building native (platform-specific) binary modules, which require
some additional development tools to be installed first:
* [Node.js](https://nodejs.org/) version 10 (min **10.20.0**) or 12 (version 14 is not yet fully supported)
* **Linux, macOS** and **Windows Subsystem for Linux (WSL):**
Installing Node via [nvm](https://github.com/nvm-sh/nvm/blob/master/README.md) is recommended.
When the "system" or "default" Node.js and npm packages are installed with "apt-get" in Linux
distributions like Ubuntu, users often report permission or compilation errors when running
"npm install". This [sample
Dockerfile](https://gist.github.com/pdcastro/5d4d96652181e7da685a32caf629dd44) shows the CLI
installation steps on an Ubuntu 18.04 base image.
* [Python 2.7](https://www.python.org/), [git](https://git-scm.com/), [make](https://www.gnu.org/software/make/), [g++](https://gcc.gnu.org/)
* **Linux** and **Windows Subsystem for Linux (WSL):**
`sudo apt-get install -y python git make g++`
* **macOS:** install Apple's Command Line Tools by running on a Terminal window:
`xcode-select --install`
On **Windows (not WSL),** the dependencies above and additional ones can be met by installing:
* Node.js from the [Nodejs.org download page](https://nodejs.org/en/download/).
* The [MSYS2 shell](https://www.msys2.org/), which provides `git`, `make`, `g++`, `ssh`, `rsync`
and more:
* `pacman -S git openssh rsync gcc make`
* [Set a Windows environment variable](https://www.onmsft.com/how-to/how-to-set-an-environment-variable-in-windows-10): `MSYS2_PATH_TYPE=inherit`
* Note that a bug in the MSYS2 launch script (`msys2_shell.cmd`) makes text-based
interactive CLI menus to misbehave. [Check this Github issue for a
workaround](https://github.com/msys2/MINGW-packages/issues/1633#issuecomment-240583890).
* The Windows Driver Kit (WDK), which is needed to compile some native Node modules. It is **not**
necessary to install Visual Studio, only the WDK, which is "step 2" in the following guides:
* [WDK for Windows 10](https://docs.microsoft.com/en-us/windows-hardware/drivers/download-the-wdk#download-icon-step-2-install-wdk-for-windows-10-version-1903)
* [WDK for earlier versions of Windows](https://docs.microsoft.com/en-us/windows-hardware/drivers/other-wdk-downloads#step-2-install-the-wdk)
* The [windows-build-tools](https://www.npmjs.com/package/windows-build-tools) npm package (which
provides Python 2.7 and more), by running the following command on an [administrator
console](https://www.howtogeek.com/194041/how-to-open-the-command-prompt-as-administrator-in-windows-8.1/):
`npm install -g --production windows-build-tools`
With these dependencies in place, the balenaCLI installation command is:
```sh
$ npm install balena-cli -g --production --unsafe-perm
```
`--unsafe-perm` is required when `npm install` is executed as the root user, or on systems where
the global install directory is not user-writable. It allows npm install steps to download and save
prebuilt native binaries, and also allows the execution of npm scripts like `postinstall` that are
used to patch dependencies. It is usually possible to omit `--unsafe-perm` if installing under a
regular (non-root) user account, especially if using a user-managed node installation such as
[nvm](https://github.com/creationix/nvm).
## Additional Dependencies
The `balena ssh`, `scan`, `build`, `deploy`, `preload` and `os configure` commands may require
additional software to be installed. Check the Additional Dependencies sections for each operating
system:
* [Windows](./INSTALL-WINDOWS.md#additional-dependencies)
* [macOS](./INSTALL-MAC.md#additional-dependencies)
* [Linux](./INSTALL-LINUX.md#additional-dependencies)
The `build` and `deploy` commands are also capable of using Docker or balenaEngine on a remote
server, or on a balenaOS device running a [balenaOS development
image](https://www.balena.io/docs/reference/OS/overview/2.x/#dev-vs-prod-images)). Reasons why this
may be desirable include:
* To avoid having to install Docker on the development machine / laptop.
* To take advantage of a more powerful server (CPU, memory).
* To build or run images "natively" on an ARM device, avoiding the need for QEMU emulation.
To use a remote Docker Engine (daemon) or balenaEngine, specify the remote machine's IP address and
port number with the `--dockerHost` and `--dockerPort` command-line options. For more details,
check `balena help build` or the [online
reference](https://www.balena.io/docs/reference/cli/#cli-command-reference).

66
INSTALL-LINUX.md Normal file
View File

@ -0,0 +1,66 @@
# balenaCLI Installation Instructions for Linux
These instructions are for the recommended installation option. They are suitable for most Linux
distributions, except notably for **Linux Alpine** or **Busybox**. For these distros, see [advanced
installation options](./INSTALL-ADVANCED.md).
Selected operating system: **Linux**
1. Download the latest zip file from the [latest release
page](https://github.com/balena-io/balena-cli/releases/latest). Look for a file name that ends
with "-standalone.zip", for example:
`balena-cli-vX.Y.Z-linux-x64-standalone.zip`
2. Extract the zip file contents to any folder you choose. The extracted contents will include a
`balena-cli` folder.
3. Add the `balena-cli` folder to the system's `PATH` environment variable. There are several
ways of achieving this on Linux: See this [StackOverflow post](https://stackoverflow.com/questions/14637979/how-to-permanently-set-path-on-linux-unix). Close and reopen the terminal window
so that the changes to PATH can take effect.
4. Check that the installation was successful by running the following commands on a
command terminal:
* `balena version` - should print balenaCLI's version
* `balena help` - should print a list of available commands
No further steps are required to run most balenaCLI commands. The `balena ssh`, `scan`, `build`,
`deploy` and `preload` commands may require additional software to be installed, as described
below.
To update balenaCLI to a new version, download a new release zip file and replace the previous
installation folder. To uninstall, simply delete the folder and edit the PATH environment variable
as described above.
## Additional Dependencies
### build, deploy
These commands require [Docker](https://docs.docker.com/install/overview/) or
[balenaEngine](https://www.balena.io/engine/) to be available (on a local or remote machine). Most
users will simply follow [Docker's installation
instructions](https://docs.docker.com/install/overview/) to install Docker on the same laptop (dev
machine) where balenaCLI is installed. The [advanced installation
options](./INSTALL-ADVANCED.md) document describes other possibilities.
### balena ssh
The `balena ssh` command requires the `ssh` command-line tool to be available. Most Linux
distributions will already have it installed. Otherwise, `sudo apt-get install openssh-client`
should do the trick on Debian or Ubuntu.
The `balena ssh` command also requires an SSH key to be added to your balena account: see [SSH
Access documentation](https://www.balena.io/docs/learn/manage/ssh-access/). The `balena key*`
command set can also be used to list and manage SSH keys: see `balena help -v`.
### balena scan
The `balena scan` command requires a multicast DNS (mDNS) service like
[Avahi](https://en.wikipedia.org/wiki/Avahi_(software)), which is installed by default on most
desktop Linux distributions. Otherwise, on Debian or Ubuntu, the installation command would be
`sudo apt-get install avahi-daemon`.
### balena preload
Like the `build` and `deploy` commands, the `preload` command requires Docker, with the additional
restriction that Docker must be installed on the local machine (because Docker's bind mounting
feature is used).

68
INSTALL-MAC.md Normal file
View File

@ -0,0 +1,68 @@
# balenaCLI Installation Instructions for macOS
These instructions are for the recommended installation option. Advanced users may also be
interested in [advanced installation options](./INSTALL-ADVANCED.md).
Selected operating system: **macOS**
1. Download the installer from the [latest release
page](https://github.com/balena-io/balena-cli/releases/latest).
Look for a file name that ends with "-installer.pkg":
`balena-cli-vX.Y.Z-macOS-x64-installer.pkg`
2. Double click the downloaded file to run the installer. After the installation completes,
close and re-open any open [command
terminal](https://www.balena.io/docs/reference/cli/#choosing-a-shell-command-promptterminal)
windows (so that the changes made by the installer to the PATH environment variable can take
effect).
3. Check that the installation was successful by running the following commands on a
command terminal:
* `balena version` - should print balenaCLI's version
* `balena help` - should print a list of available commands
No further steps are required to run most balenaCLI commands. The `balena ssh`, `build`, `deploy`
and `preload` commands may require additional software to be installed, as described below.
## Additional Dependencies
### build and deploy
These commands require [Docker](https://docs.docker.com/install/overview/) or
[balenaEngine](https://www.balena.io/engine/) to be available (on a local or remote machine). Most
users will simply follow [Docker's installation
instructions](https://docs.docker.com/install/overview/) to install Docker on the same laptop (dev
machine) where balenaCLI is installed. The [advanced installation
options](./INSTALL-ADVANCED.md) document describes other possibilities.
### balena ssh
The `balena ssh` command requires the `ssh` command-line tool to be available. To check whether
it is already installed, run `ssh` on a Terminal window. If it is not yet installed, the options
include:
* Download the Xcode Command Line Tools from https://developer.apple.com/downloads
* Or, if you have Xcode installed, open Xcode, choose Preferences → General → Downloads →
Components → Command Line Tools → Install.
* Or, install [Homebrew](https://brew.sh/), then `brew install openssh`
The `balena ssh` command also requires an SSH key to be added to your balena account: see [SSH
Access documentation](https://www.balena.io/docs/learn/manage/ssh-access/). The `balena key*`
command set can also be used to list and manage SSH keys: see `balena help -v`.
### balena preload
Like the `build` and `deploy` commands, the `preload` command requires Docker, with the additional
restriction that Docker must be installed on the local machine (because Docker's bind mounting
feature is used). Also, for some device types (such as the Raspberry Pi), the `preload` command
requires Docker to support the [AUFS storage
driver](https://docs.docker.com/storage/storagedriver/aufs-driver/). Unfortunately, Docker Desktop
for Windows dropped support for the AUFS filesystem in Docker CE versions greater than 18.06.1. The
present workaround is to either:
* Downgrade Docker Desktop to version 18.06.1. Link: [Docker CE for
Mac](https://docs.docker.com/docker-for-mac/release-notes/#docker-community-edition-18061-ce-mac73-2018-08-29)
* Install balenaCLI on a Linux machine (as Docker for Linux still supports AUFS). A Linux Virtual
Machine also works, but a Docker container is _not_ recommended.
Long term, we are working on replacing AUFS with overlay2 for the affected device types.

82
INSTALL-WINDOWS.md Normal file
View File

@ -0,0 +1,82 @@
# balenaCLI Installation Instructions for Windows
These instructions are for the recommended installation option. Advanced users may also be
interested in [advanced installation options](./INSTALL-ADVANCED.md).
Selected operating system: **Windows**
1. Download the installer from the [latest release
page](https://github.com/balena-io/balena-cli/releases/latest).
Look for a file name that ends with "-installer.exe":
`balena-cli-vX.Y.Z-windows-x64-installer.exe`
2. Double click the downloaded file to run the installer. After the installation completes,
close and re-open any open [command
terminal](https://www.balena.io/docs/reference/cli/#choosing-a-shell-command-promptterminal)
windows (so that the changes made by the installer to the PATH environment variable can take
effect).
3. Check that the installation was successful by running the following commands on a
command terminal:
* `balena version` - should print balenaCLI's version
* `balena help` - should print a list of available commands
No further steps are required to run most balenaCLI commands. The `balena ssh`, `scan`, `build`,
`deploy`, `preload` and `os configure` commands may require additional software to be installed, as
described below.
## Additional Dependencies
### build and deploy
These commands require [Docker](https://docs.docker.com/install/overview/) or
[balenaEngine](https://www.balena.io/engine/) to be available (on a local or remote machine). Most
users will simply follow [Docker's installation
instructions](https://docs.docker.com/install/overview/) to install Docker on the same laptop (dev
machine) where balenaCLI is installed. The [advanced installation
options](./INSTALL-ADVANCED.md) document describes other possibilities.
### balena ssh
The `balena ssh` command requires the `ssh` command-line tool to be available. Microsoft started
distributing an SSH client with Windows 10, which is automatically installed through Windows
Update. To check whether it is installed, run `ssh` on a Windows Command Prompt or PowerShell. It
can also be [manually
installed](https://docs.microsoft.com/en-us/windows-server/administration/openssh/openssh_install_firstuse)
if needed. For older versions of Windows, there are several ssh/OpenSSH clients provided by 3rd
parties.
The `balena ssh` command also requires an SSH key to be added to your balena account: see [SSH
Access documentation](https://www.balena.io/docs/learn/manage/ssh-access/). The `balena key*`
command set can also be used to list and manage SSH keys: see `balena help -v`.
### balena scan
The `balena scan` command requires a multicast DNS (mDNS) service like Apple's Bonjour.
Many Windows machines will already have this service installed, as it is bundled in popular
applications such as Skype (Wikipedia lists [several others](https://en.wikipedia.org/wiki/Bonjour_(software))).
Otherwise, Bonjour for Windows can be downloaded and installed from: https://support.apple.com/kb/DL999
### balena preload
Like the `build` and `deploy` commands, the `preload` command requires Docker, with the additional
restriction that Docker must be installed on the local machine (because Docker's bind mounting
feature is used). Also, for some device types (such as the Raspberry Pi), the `preload` command
requires Docker to support the [AUFS storage
driver](https://docs.docker.com/storage/storagedriver/aufs-driver/). Unfortunately, Docker Desktop
for Windows dropped support for the AUFS filesystem in Docker CE versions greater than 18.06.1. The
present workaround is to either:
* Downgrade Docker Desktop to version 18.06.1. Link: [Docker CE for
Windows](https://docs.docker.com/docker-for-windows/release-notes/#docker-community-edition-18061-ce-win73-2018-08-29)
* Install balenaCLI on a Linux machine (as Docker for Linux still supports AUFS). A Linux Virtual
Machine also works, but a Docker container is _not_ recommended.
Long term, we are working on replacing AUFS with overlay2 for the affected device types.
### balena os configure
* The `balena os configure` command is currently not supported on Windows natively, but works with
the [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/about) (WSL). When
using WSL, [install balenaCLI for
Linux](https://github.com/balena-io/balena-cli/blob/master/INSTALL-LINUX.md).

235
INSTALL.md
View File

@ -1,231 +1,12 @@
# balenaCLI Installation Instructions # balenaCLI Installation Instructions
There are 3 options to choose from to install balena's CLI: Please select your operating system:
* [Executable Installer](#executable-installer): the easiest method on Windows and macOS, using the * [Windows](./INSTALL-WINDOWS.md)
traditional graphical desktop application installers. * [macOS](./INSTALL-MAC.md)
* [Standalone Zip Package](#standalone-zip-package): these are plain zip files with the balena CLI * [Linux](./INSTALL-LINUX.md)
executable in them: extract and run. Available for all platforms: Linux, Windows, macOS.
Recommended also for scripted installation in CI (continuous integration) environments.
* [NPM Installation](#npm-installation): recommended for Node.js developers who may be interested
in integrating the balena CLI in their existing projects or workflow.
Some specific CLI commands have a few extra installation steps: see section [Additional > Note regarding WSL ([Windows Subsystem for
Dependencies](#additional-dependencies). > Linux](https://docs.microsoft.com/en-us/windows/wsl/about))
> If you would like to use WSL, follow the installations instructions for Linux
> **Windows users:** > rather than Windows, as WSL consists of a Linux environment.
> * There is a [YouTube video tutorial](https://www.youtube.com/watch?v=2LApclXFqsg) for installing
> and getting started with the balena CLI on Windows. (The video uses the standalone zip package
> option.)
> * If you are using Microsoft's [Windows Subsystem for
> Linux](https://docs.microsoft.com/en-us/windows/wsl/about) (WSL), install a balena CLI release
> for Linux rather than for Windows, like the standalone zip package for Linux. An installation
> with the graphical executable installer for Windows will **not** work with WSL.
## Executable Installer
Recommended for Windows (but not Windows Subsystem for Linux) and macOS:
1. Download the latest installer from the [releases page](https://github.com/balena-io/balena-cli/releases).
Look for a file name that ends with "-installer", for example:
`balena-cli-vX.Y.Z-windows-x64-installer.exe`
`balena-cli-vX.Y.Z-macOS-x64-installer.pkg`
2. Double click the downloaded file to run the installer.
_If you are using macOS Catalina (10.15), [check this known issue and
workaround](https://github.com/balena-io/balena-cli/issues/1479)._
3. After the installation completes, close and re-open any open [command
terminal](https://www.balena.io/docs/reference/cli/#choosing-a-shell-command-promptterminal)
windows so that the changes made by the installer to the PATH environment variable can take
effect. Check that the installation was successful by running the following commands on a
command terminal:
* `balena version` - should print the installed CLI version
* `balena help` - should print the balena CLI help
> Note: If you had previously installed the CLI using a standalone zip package, it may be a good
> idea to check your system's `PATH` environment variable for duplicate entries, as the terminal
> will use the entry that comes first. Check the [Standalone Zip Package](#standalone-zip-package)
> instructions for how to modify the PATH variable.
By default, the CLI is installed to the following folders:
OS | Folders
--- | ---
Windows: | `C:\Program Files\balena-cli\`
macOS: | `/usr/local/lib/balena-cli/` <br> `/usr/local/bin/balena`
## Standalone Zip Package
1. Download the latest zip file from the [releases page](https://github.com/balena-io/balena-cli/releases).
Look for a file name that ends with the word "standalone", for example:
`balena-cli-vX.Y.Z-linux-x64-standalone.zip` ← _also for the Windows Subsystem for Linux_
`balena-cli-vX.Y.Z-macOS-x64-standalone.zip`
`balena-cli-vX.Y.Z-windows-x64-standalone.zip`
2. Extract the zip file contents to any folder you choose. The extracted contents will include a
`balena-cli` folder.
3. Add the `balena-cli` folder to the system's `PATH` environment variable.
See instructions for:
[Linux](https://stackoverflow.com/questions/14637979/how-to-permanently-set-path-on-linux-unix) |
[macOS](https://www.architectryan.com/2012/10/02/add-to-the-path-on-mac-os-x-mountain-lion/#.Uydjga1dXDg) |
[Windows](https://www.computerhope.com/issues/ch000549.htm)
> * If you are using macOS Catalina (10.15), [check this known issue and
> workaround](https://github.com/balena-io/balena-cli/issues/1479).
> * **Linux Alpine** and **Busybox:** the standalone zip package is not currently compatible with
> these "compact" Linux distributions, because of the alternative C libraries they ship with.
> It should however work with all "desktop" or "server" distributions, e.g. Ubuntu, Debian, Suse,
> Fedora, Arch Linux and many more.
> * Note that moving the `balena` executable out of the extracted `balena-cli` folder on its own
> (e.g. moving it to `/usr/local/bin/balena`) will **not** work, as it depends on the other
> folders and files also present in the `balena-cli` folder.
To update the CLI to a new version, download a new release zip file and replace the previous
installation folder. To uninstall, simply delete the folder and edit the PATH environment variable
as described above.
## NPM Installation
If you are a Node.js developer, you may wish to install the balena CLI via [npm](https://www.npmjs.com).
The npm installation involves building native (platform-specific) binary modules, which require
some additional development tools to be installed first:
* [Node.js](https://nodejs.org/) version 10 (min **10.20.0**) or 12 (version 14 is not yet fully supported)
* **Linux, macOS** and **Windows Subsystem for Linux (WSL):**
Installing Node via [nvm](https://github.com/nvm-sh/nvm/blob/master/README.md) is recommended.
When the "system" or "default" Node.js and npm packages are installed with "apt-get" in Linux
distributions like Ubuntu, users often report permission or compilation errors when running
"npm install". This [sample
Dockerfile](https://gist.github.com/pdcastro/5d4d96652181e7da685a32caf629dd44) shows the CLI
installation steps on an Ubuntu 18.04 base image.
* [Python 2.7](https://www.python.org/), [git](https://git-scm.com/), [make](https://www.gnu.org/software/make/), [g++](https://gcc.gnu.org/)
* **Linux** and **Windows Subsystem for Linux (WSL):**
`sudo apt-get install -y python git make g++`
* **macOS:** install Apple's Command Line Tools by running on a Terminal window:
`xcode-select --install`
On **Windows (not WSL),** the dependencies above and additional ones can be met by installing:
* Node.js from the [Nodejs.org download page](https://nodejs.org/en/download/).
* The [MSYS2 shell](https://www.msys2.org/), which provides `git`, `make`, `g++`, `ssh`, `rsync`
and more:
* `pacman -S git openssh rsync gcc make`
* [Set a Windows environment variable](https://www.onmsft.com/how-to/how-to-set-an-environment-variable-in-windows-10): `MSYS2_PATH_TYPE=inherit`
* Note that a bug in the MSYS2 launch script (`msys2_shell.cmd`) makes text-based
interactive CLI menus to misbehave. [Check this Github issue for a
workaround](https://github.com/msys2/MINGW-packages/issues/1633#issuecomment-240583890).
* The Windows Driver Kit (WDK), which is needed to compile some native Node modules. It is **not**
necessary to install Visual Studio, only the WDK, which is "step 2" in the following guides:
* [WDK for Windows 10](https://docs.microsoft.com/en-us/windows-hardware/drivers/download-the-wdk#download-icon-step-2-install-wdk-for-windows-10-version-1903)
* [WDK for earlier versions of Windows](https://docs.microsoft.com/en-us/windows-hardware/drivers/other-wdk-downloads#step-2-install-the-wdk)
* The [windows-build-tools](https://www.npmjs.com/package/windows-build-tools) npm package (which
provides Python 2.7 and more), by running the following command on an [administrator
console](https://www.howtogeek.com/194041/how-to-open-the-command-prompt-as-administrator-in-windows-8.1/):
`npm install -g --production windows-build-tools`
With these dependencies in place, the balena CLI installation command is:
```sh
$ npm install balena-cli -g --production --unsafe-perm
```
`--unsafe-perm` is required when `npm install` is executed as the root user, or on systems where
the global install directory is not user-writable. It allows npm install steps to download and save
prebuilt native binaries, and also allows the execution of npm scripts like `postinstall` that are
used to patch dependencies. It is usually possible to omit `--unsafe-perm` if installing under a
regular (non-root) user account, especially if using a user-managed node installation such as
[nvm](https://github.com/creationix/nvm).
## Additional Dependencies
* The `balena ssh` command requires a recent version of the `ssh` command-line tool to be available:
* macOS and Linux usually already have it installed. Otherwise, search for the available packages
on your specific Linux distribution, or for the Mac consider the [Xcode command-line
tools](https://developer.apple.com/xcode/features/) or [homebrew](https://brew.sh/).
* Microsoft started distributing an SSH client with Windows 10, which we understand is
automatically installed through Windows Update, but can be manually installed too
([more information](https://docs.microsoft.com/en-us/windows-server/administration/openssh/openssh_install_firstuse)).
For other versions of Windows, there are several ssh/OpenSSH clients provided by 3rd parties.
* The [`proxytunnel`](http://proxytunnel.sourceforge.net/) package (command-line tool) is needed
for the `balena ssh` command to work behind a proxy. It is available for Linux distributions
like Ubuntu/Debian (`apt install proxytunnel`), and for macOS through
[Homebrew](https://brew.sh/). Windows support is limited to the Windows Subsystem for Linux
(e.g., by installing Ubuntu through the Microsoft App Store). Check the
[README](https://github.com/balena-io/balena-cli/blob/master/README.md) file for proxy
configuration instructions.
* The `balena preload`, `balena build` and `balena deploy --build` commands require
[Docker](https://docs.docker.com/install/overview/) or [balenaEngine](https://www.balena.io/engine/)
to be available:
* The `balena preload` command requires the Docker Engine to support the [AUFS storage
driver](https://docs.docker.com/storage/storagedriver/aufs-driver/). Docker Desktop for Mac and
Windows dropped support for the AUFS filesystem in Docker CE versions greater than 18.06.1, so
the workaround is to downgrade to version 18.06.1 (links: [Docker CE for
Windows](https://docs.docker.com/docker-for-windows/release-notes/#docker-community-edition-18061-ce-win73-2018-08-29)
and [Docker CE for
Mac](https://docs.docker.com/docker-for-mac/release-notes/#docker-community-edition-18061-ce-mac73-2018-08-29)).
See more details in [CLI issue 1099](https://github.com/balena-io/balena-cli/issues/1099).
* Commonly, Docker is installed on the same machine where the CLI is being used, but the
`balena build` and `balena deploy` commands can also use a remote Docker Engine (daemon)
or balenaEngine (which could be a remote device running a [balenaOS development
image](https://www.balena.io/docs/reference/OS/overview/2.x/#dev-vs-prod-images)) by specifying
its IP address and port number as command-line options. Check the documentation for each
command, e.g. `balena help build`, or the [online
reference](https://www.balena.io/docs/reference/cli/#cli-command-reference).
* If you are using Microsoft's [Windows Subsystem for
Linux](https://docs.microsoft.com/en-us/windows/wsl/about) (WSL) and Docker Desktop for
Windows, check the [FAQ item "Docker seems to be
unavailable"](https://github.com/balena-io/balena-cli/blob/master/TROUBLESHOOTING.md#docker-seems-to-be-unavailable-error-when-using-windows-subsystem-for-linux-wsl).
* The `balena scan` command requires a multicast DNS (mDNS) service like Bonjour or Avahi:
* On Windows, check if 'Bonjour' is installed (Control Panel > Programs and Features).
If not, you can download Bonjour for Windows from https://support.apple.com/kb/DL999
* Most 'desktop' Linux distributions ship with [Avahi](https://en.wikipedia.org/wiki/Avahi_(software)).
Search for the installation command for your distribution. E.g. for Ubuntu:
`sudo apt-get install avahi-daemon`
* macOS comes with [Bonjour](https://en.wikipedia.org/wiki/Bonjour_(software)) built-in.
* The `balena os configure` command is currently not supported on Windows natively. Windows users are advised
to install the [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/about) (WSL)
with Ubuntu, and use the Linux release of the balena CLI.
## Configuring SSH keys
The `balena ssh` command requires an SSH key to be added to your balena account. If you had
already added a SSH key in order to [deploy with 'git push'](https://www.balena.io/docs/learn/getting-started/raspberrypi3/nodejs/#adding-an-ssh-key),
then you are probably done and may skip this section. You can check whether you already have
an SSH key in your balena account with the `balena keys` command, or by visiting the
[balena web dashboard](https://dashboard.balena-cloud.com/), clicking on your name -> Preferences
-> SSH Keys.
> Note: An "SSH key" actually consists of a public/private key pair. A typical name for the private
> key file is "id_rsa", and a typical name for the public key file is "id_rsa.pub". Both key files
> are saved to your computer (with the private key optionally protected by a password), but only
> the public key is saved to your balena account. This means that if you change computers or
> otherwise lose the private key, _you cannot recover the private key through your balena account._
> You can however add new keys, and delete the old ones.
If you don't have an SSH key in your balena account:
* If you have an existing SSH key in your computer that you would like to use, you can add it
to your balena account through the balena web dashboard (Preferences -> SSH Keys), or through
the CLI itself:
```bash
# Windows 10 (cmd.exe prompt) example:
$ balena key add MyKey %userprofile%\.ssh\id_rsa.pub
# Linux / macOS example:
$ balena key add MyKey ~/.ssh/id_rsa.pub
```
* To generate a new key, you can follow [GitHub's documentation](https://help.github.com/en/articles/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent),
skipping the step about adding the key to your GitHub account, and instead adding the key to
your balena account as described above.

72
README.md
View File

@ -1,31 +1,30 @@
# balenaCLI # balenaCLI
The official balena CLI tool. The official balena Command Line Interface.
[![npm version](https://badge.fury.io/js/balena-cli.svg)](http://badge.fury.io/js/balena-cli) [![npm version](https://badge.fury.io/js/balena-cli.svg)](http://badge.fury.io/js/balena-cli)
[![dependencies](https://david-dm.org/balena-io/balena-cli.svg)](https://david-dm.org/balena-io/balena-cli) [![dependencies](https://david-dm.org/balena-io/balena-cli.svg)](https://david-dm.org/balena-io/balena-cli)
## About ## About
The balena CLI (Command-Line Interface) allows you to interact with the balenaCloud and the balenaCLI is a Command Line Interface for [balenaCloud](https://www.balena.io/cloud/) or
[balena API](https://www.balena.io/docs/reference/api/overview/) through a terminal window [openBalena](https://www.balena.io/open/). It is a software tool available for Windows, macOS and
on Linux, macOS or Windows. You can also write shell scripts around it, or import its Node.js Linux, used through a command prompt / terminal window. It can be used interactively or invoked in
modules to use it programmatically. scripts. balenaCLI builds on the [balena API](https://www.balena.io/docs/reference/api/overview/)
As an [open-source project on GitHub](https://github.com/balena-io/balena-cli/), your contribution and the [balena SDK](https://www.balena.io/docs/reference/sdk/node-sdk/), and can also be directly
is also welcome! imported in Node.js applications. balenaCLI is an [open-source project on
GitHub](https://github.com/balena-io/balena-cli/), and your contribution is also welcome!
## Installation ## Installation
Check the [balena CLI installation instructions on GitHub](https://github.com/balena-io/balena-cli/blob/master/INSTALL.md). Check the [balenaCLI installation instructions on
GitHub](https://github.com/balena-io/balena-cli/blob/master/INSTALL.md).
## Getting Started ## Choosing a shell (command prompt/terminal)
### Choosing a shell (command prompt/terminal)
On **Windows,** the standard Command Prompt (`cmd.exe`) and On **Windows,** the standard Command Prompt (`cmd.exe`) and
[PowerShell](https://docs.microsoft.com/en-us/powershell/scripting/getting-started/getting-started-with-windows-powershell?view=powershell-6) [PowerShell](https://docs.microsoft.com/en-us/powershell/scripting/getting-started/getting-started-with-windows-powershell?view=powershell-6)
are supported. We are aware of users also having a good experience with alternative shells, are supported. Alternative shells include:
including:
* [MSYS2](https://www.msys2.org/): * [MSYS2](https://www.msys2.org/):
* Install additional packages with the command: * Install additional packages with the command:
@ -43,17 +42,17 @@ including:
[comment](https://github.com/balena-io/balena-cli/issues/598#issuecomment-556513098). [comment](https://github.com/balena-io/balena-cli/issues/598#issuecomment-556513098).
* Microsoft's [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/about) * Microsoft's [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/about)
(WSL). In this case, a Linux distribution like Ubuntu is installed via the Microsoft Store, and a (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 balenaCLI release **for Linux** should be selected. See
[FAQ](https://github.com/balena-io/balena-cli/blob/master/TROUBLESHOOTING.md) for using balena [FAQ](https://github.com/balena-io/balena-cli/blob/master/TROUBLESHOOTING.md) for using balenaCLI
CLI with WSL and Docker Desktop for Windows. with WSL and Docker Desktop for Windows.
On **macOS** and **Linux,** the standard terminal window is supported. _Optionally,_ `bash` command On **macOS** and **Linux,** the standard terminal window is supported. Optionally, `bash` command
auto completion may be enabled by copying the auto completion may be enabled by copying the
[balena-completion.bash](https://github.com/balena-io/balena-cli/blob/master/balena-completion.bash) [balena-completion.bash](https://github.com/balena-io/balena-cli/blob/master/balena-completion.bash)
file to your system's `bash_completion` directory: check [Docker's command completion file to your system's `bash_completion` directory: check [Docker's command completion
guide](https://docs.docker.com/compose/completion/) for system setup instructions. guide](https://docs.docker.com/compose/completion/) for system setup instructions.
### Logging in ## Logging in
Several CLI commands require access to your balenaCloud account, for example in order to push a 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: new release to your application. Those commands require creating a CLI login session by running:
@ -62,7 +61,7 @@ new release to your application. Those commands require creating a CLI login ses
$ balena login $ balena login
``` ```
### Proxy support ## Proxy support
HTTP(S) proxies can be configured through any of the following methods, in precedence order HTTP(S) proxies can be configured through any of the following methods, in precedence order
(from higher to lower): (from higher to lower):
@ -88,15 +87,22 @@ HTTP(S) proxies can be configured through any of the following methods, in prece
* The `HTTPS_PROXY` and/or `HTTP_PROXY` environment variables, in the same URL format as * The `HTTPS_PROXY` and/or `HTTP_PROXY` environment variables, in the same URL format as
`BALENARC_PROXY`. `BALENARC_PROXY`.
> Note: The `balena ssh` command has additional setup requirements to work behind a proxy. ### Proxy setup for balena ssh
> Check the [installation instructions](https://github.com/balena-io/balena-cli/blob/master/INSTALL.md),
> 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](http://www.squid-cache.org/) 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 In order to work behind a proxy server, the `balena ssh` command requires the
[`proxytunnel`](http://proxytunnel.sourceforge.net/) package (command-line tool) to be installed.
`proxytunnel` is available for Linux distributions like Ubuntu/Debian (`apt install proxytunnel`),
and for macOS through [Homebrew](https://brew.sh/). Windows support is limited to the [Windows
Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/about) (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](http://www.squid-cache.org/) 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. The `BALENARC_NO_PROXY` variable may be used to exclude specified destinations from proxying.
@ -129,7 +135,7 @@ address like `192.168.1.2`.
## Command reference documentation ## Command reference documentation
The full CLI command reference is available [on the web](https://www.balena.io/docs/reference/cli/ The full CLI command reference is available [on the web](https://www.balena.io/docs/reference/cli/
) or by running `balena help` and `balena help --verbose`. ) or by running `balena help --verbose`.
## Support, FAQ and troubleshooting ## Support, FAQ and troubleshooting
@ -142,19 +148,19 @@ If you come across any problems or would like to get in touch:
## Deprecation policy ## Deprecation policy
The balena CLI uses [semver versioning](https://semver.org/), with the concepts balenaCLI uses [semver versioning](https://semver.org/), with the concepts
of major, minor and patch version releases. of major, minor and patch version releases.
The latest release of the previous major version of the balena CLI will remain The latest release of a major version of balenaCLI will remain compatible with
compatible with the balenaCloud backend services for one year from the date when the balenaCloud backend services for at least one year from the date when the
the next major version is released. For example, balena CLI v10.17.5, as the following major version is released. For example, balenaCLI v10.17.5, as the
latest v10 release, would remain compatible with the balenaCloud backend for one latest v10 release, would remain compatible with the balenaCloud backend for one
year from the date when v11.0.0 is released. year from the date when v11.0.0 is released.
At the end of this period, the older major version is considered deprecated and 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 some of the functionality that depends on balenaCloud services may stop working
at any time. at any time.
Users are encouraged to regularly update the balena CLI to the latest version. Users are encouraged to regularly update balenaCLI to the latest version.
## Contributing (including editing documentation files) ## Contributing (including editing documentation files)

70
TROUBLESHOOTING.md
View File

@ -1,62 +1,50 @@
# FAQ & Troubleshooting # balenaCLI FAQ & Troubleshooting
This document contains some common issues, questions and answers related to the balena CLI. ## Where is balenaCLI's configuration file located?
## Where is my configuration file?
The per-user configuration file lives in `$HOME/.balenarc.yml` or `%UserProfile%\_balenarc.yml`, in The per-user configuration file lives in `$HOME/.balenarc.yml` or `%UserProfile%\_balenarc.yml`, in
Unix based operating systems and Windows respectively. Unix based operating systems and Windows respectively.
The balena CLI also attempts to read a `balenarc.yml` file in the current directory, which takes balenaCLI also attempts to read a `balenarc.yml` file in the current directory, which takes
precedence over the per-user configuration file. precedence over the per-user configuration file.
## How do I point the balena CLI to staging? ## How do I point balenaCLI to the staging environment?
The easiest way is to set the `BALENARC_BALENA_URL=balena-staging.com` environment variable. Set the `BALENARC_BALENA_URL=balena-staging.com` environment variable, or add
`balenaUrl: balena-staging.com` to balenaCLI's configuration file.
Alternatively, you can edit your configuration file and set `balenaUrl: balena-staging.com` to ## How do I make balenaCLI persist data in another directory?
persist this setting.
## How do I make the balena CLI persist data in another directory? balenaCLI persists the session token, as well as cached assets, to `$HOME/.balena` or
`%UserProfile%\_balena`. This directory can be changed by setting an environment variable,
`BALENARC_DATA_DIRECTORY=/opt/balena`, or by adding `dataDirectory: /opt/balena` to balenaCLI's
configuration file, replacing `/opt/balena` with the desired directory.
The balena CLI persists your session token, as well as cached images in `$HOME/.balena` or ## After burning to an SD card, my device doesn't boot
`%UserProfile%\_balena`.
Pointing the balena CLI to persist data in another location is necessary in certain environments, Check whether the downloaded image is incomplete (download was interrupted) or corrupted.
like a server, where there is no home directory, or a device running balenaOS, which erases all
data after a restart.
You can accomplish this by setting `BALENARC_DATA_DIRECTORY=/opt/balena` or adding `dataDirectory: Try clearing the cache (`%HOME/.balena/cache` or `C:\Users\<user>\_balena\cache`) and running the
/opt/balena` to your configuration file, replacing `/opt/balena` with your desired directory. command again.
## After burning to an sdcard, my device doesn't boot ## I get a permission error when burning to an SD card
- The downloaded image is not complete (download was interrupted). Check whether the SD card is locked (a physical switch on the side of the card).
Please clean the cache (`%HOME/.balena/cache` or `C:\Users\<user>\_balena\cache`) and run the command again. In the future, the CLI will check that the image is not complete and clean the cache for you. ## I get EINVAL errors on Cygwin
## I get a permission error when burning to an sdcard The errors may look something like this:
- The SDCard is locked.
### I get EINVAL errors on Cygwin
The errors look something like this:
``` ```
net.js:156 net.js:156
this._handle.open(options.fd); this._handle.open(options.fd);
^ ^
Error: EINVAL, invalid argument Error: EINVAL, invalid argument
at new Socket (net.js:156:18)
at process.stdin (node.js:664:19)
at Object.Interface.createInterface (C:\cygwin\home\Juan Cruz Viotti\Projects\balena-cli\node_modules\inquirer\node_modules\readline2\index.js:31:43)
at PromptUI.UI (C:\cygwin\home\Juan Cruz Viotti\Projects\balena-cli\node_modules\inquirer\lib\ui\baseUI.js:23:40)
at new PromptUI (C:\cygwin\home\Juan Cruz Viotti\Projects\balena-cli\node_modules\inquirer\lib\ui\prompt.js:26:8)
at Object.promptModule [as prompt] (C:\cygwin\home\Juan Cruz Viotti\Projects\balena-cli\node_modules\inquirer\lib\inquirer.js:27:14)
``` ```
- Some interactive widgets don't work on `Cygwin`. If you're running Windows, it's preferrable that you use `cmd.exe`, as `Cygwin` is [not official supported by Node.js](https://github.com/chjj/blessed/issues/56#issuecomment-42671945). Some interactive widgets don't work on `Cygwin`. On Windows, PowerShell or `cmd.exe` are better
supported. Alternative shells are [listed in the README
file](./README.md#choosing-a-shell-command-promptterminal).
## I get `Invalid MBR boot signature` when configuring a device ## I get `Invalid MBR boot signature` when configuring a device
@ -76,7 +64,9 @@ Or in Windows:
## I get `EACCES: permission denied` when logging in ## I get `EACCES: permission denied` when logging in
The balena CLI stores the session token in `$HOME/.balena` or `C:\Users\<user>\_balena` in UNIX based operating systems and Windows respectively. This error usually indicates that the user doesn't have permissions over that directory, which can happen if you ran the balena CLI as `root`, and thus the directory got owned by him. balenaCLI stores the session token in `$HOME/.balena` or `C:\Users\<user>\_balena` in UNIX based
operating systems and Windows respectively. This error usually indicates that the user doesn't have
permissions over that directory, which can happen if balenaCLI was executed as the `root` user.
Try resetting the ownership by running: Try resetting the ownership by running:
@ -86,7 +76,7 @@ $ sudo chown -R <user> $HOME/.balena
## Broken line wrapping / cursor behavior with `balena ssh` ## Broken line wrapping / cursor behavior with `balena ssh`
Users sometimes come across broken line wrapping or cursor behavior in text terminals, for example when long command lines are typed in a `balena ssh` session, or when using text editors like `vim` or `nano`. This is not something specific to the balena CLI, being also a commonly reported issue with standard remote terminal tools like `ssh` or `telnet`. It is often a remote shell configuration issue (files like `/etc/profile`, `~/.bash_profile`, `~/.bash_login`, `~/.profile` and the like), including UTF-8 misconfiguration, the use of unsupported ASCII control characters in shell prompt formatting (e.g. the `$PS1` env var) or the output of tools or log files that use colored text. The issue can sometimes be fixed by resizing the client terminal window, or by running one or more of the following commands on the shell: Users sometimes come across broken line wrapping or cursor behavior in text terminals, for example when long command lines are typed in a `balena ssh` session, or when using text editors like `vim` or `nano`. This is not something specific to balenaCLI, being also a commonly reported issue with standard remote terminal tools like `ssh` or `telnet`. It is often a remote shell configuration issue (files like `/etc/profile`, `~/.bash_profile`, `~/.bash_login`, `~/.profile` and the like), including UTF-8 misconfiguration, the use of unsupported ASCII control characters in shell prompt formatting (e.g. the `$PS1` env var) or the output of tools or log files that use colored text. The issue can sometimes be fixed by resizing the client terminal window, or by running one or more of the following commands on the shell:
```sh ```sh
export TERMINAL=linux export TERMINAL=linux
@ -112,10 +102,10 @@ If nothing seems to help, consider also using a different client-side terminal a
## "Docker seems to be unavailable" error when using Windows Subsystem for Linux (WSL) ## "Docker seems to be unavailable" error when using Windows Subsystem for Linux (WSL)
When running on WSL, the recommendation is to install a CLI release for Linux, like the standalone When running on WSL, the recommendation is to install a CLI release for Linux, like the standalone
zip package for Linux. However, commands like "balena build" that contact a local Docker daemon, zip package for Linux. However, commands like "balena build" will, by default, attempt to reach the
like the Docker Desktop for Windows, will try to reach Docker at the Unix socket path Docker daemon at the Unix socket path `/var/run/docker.sock`, while Docker Desktop for Windows uses
`/var/run/docker.sock`, while Docker Desktop for Windows uses a Windows named pipe at a Windows named pipe at `//./pipe/docker_engine` (which the Linux CLI on WSL cannot use). A
`//./pipe/docker_engine` (which the Linux CLI on WSL cannot use). A solution is: solution is:
- Open the Docker Desktop for Windows settings panel and tick the checkbox _"Expose daemon on tcp://localhost:2375 without TLS"._ - Open the Docker Desktop for Windows settings panel and tick the checkbox _"Expose daemon on tcp://localhost:2375 without TLS"._
- On the WSL command line, set an env var: - On the WSL command line, set an env var:

6
automation/capitanodoc/capitanodoc.ts
View File

@ -26,7 +26,7 @@ import { MarkdownFileParser } from './utils';
* some content to this object. * some content to this object.
*/ */
const capitanoDoc = { const capitanoDoc = {
title: 'Balena CLI Documentation', title: 'balenaCLI Documentation',
introduction: '', introduction: '',
categories: [ categories: [
{ {
@ -191,7 +191,9 @@ export async function getCapitanoDoc(): Promise<typeof capitanoDoc> {
return match && match[2]; return match && match[2];
}), }),
mdParser.getSectionOfTitle('Installation'), mdParser.getSectionOfTitle('Installation'),
mdParser.getSectionOfTitle('Getting Started'), mdParser.getSectionOfTitle('Choosing a shell (command prompt/terminal)'),
mdParser.getSectionOfTitle('Logging in'),
mdParser.getSectionOfTitle('Proxy support'),
mdParser.getSectionOfTitle('Support, FAQ and troubleshooting'), mdParser.getSectionOfTitle('Support, FAQ and troubleshooting'),
mdParser.getSectionOfTitle('Deprecation policy'), mdParser.getSectionOfTitle('Deprecation policy'),
]); ]);

110
doc/cli.markdown
View File

@ -1,24 +1,23 @@
# Balena CLI Documentation # balenaCLI Documentation
The balena CLI (Command-Line Interface) allows you to interact with the balenaCloud and the balenaCLI is a Command Line Interface for [balenaCloud](https://www.balena.io/cloud/) or
[balena API](https://www.balena.io/docs/reference/api/overview/) through a terminal window [openBalena](https://www.balena.io/open/). It is a software tool available for Windows, macOS and
on Linux, macOS or Windows. You can also write shell scripts around it, or import its Node.js Linux, used through a command prompt / terminal window. It can be used interactively or invoked in
modules to use it programmatically. scripts. balenaCLI builds on the [balena API](https://www.balena.io/docs/reference/api/overview/)
As an [open-source project on GitHub](https://github.com/balena-io/balena-cli/), your contribution and the [balena SDK](https://www.balena.io/docs/reference/sdk/node-sdk/), and can also be directly
is also welcome! imported in Node.js applications. balenaCLI is an [open-source project on
GitHub](https://github.com/balena-io/balena-cli/), and your contribution is also welcome!
## Installation ## Installation
Check the [balena CLI installation instructions on GitHub](https://github.com/balena-io/balena-cli/blob/master/INSTALL.md). Check the [balenaCLI installation instructions on
GitHub](https://github.com/balena-io/balena-cli/blob/master/INSTALL.md).
## Getting Started ## Choosing a shell (command prompt/terminal)
### Choosing a shell (command prompt/terminal)
On **Windows,** the standard Command Prompt (`cmd.exe`) and On **Windows,** the standard Command Prompt (`cmd.exe`) and
[PowerShell](https://docs.microsoft.com/en-us/powershell/scripting/getting-started/getting-started-with-windows-powershell?view=powershell-6) [PowerShell](https://docs.microsoft.com/en-us/powershell/scripting/getting-started/getting-started-with-windows-powershell?view=powershell-6)
are supported. We are aware of users also having a good experience with alternative shells, are supported. Alternative shells include:
including:
* [MSYS2](https://www.msys2.org/): * [MSYS2](https://www.msys2.org/):
* Install additional packages with the command: * Install additional packages with the command:
@ -36,17 +35,17 @@ including:
[comment](https://github.com/balena-io/balena-cli/issues/598#issuecomment-556513098). [comment](https://github.com/balena-io/balena-cli/issues/598#issuecomment-556513098).
* Microsoft's [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/about) * Microsoft's [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/about)
(WSL). In this case, a Linux distribution like Ubuntu is installed via the Microsoft Store, and a (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 balenaCLI release **for Linux** should be selected. See
[FAQ](https://github.com/balena-io/balena-cli/blob/master/TROUBLESHOOTING.md) for using balena [FAQ](https://github.com/balena-io/balena-cli/blob/master/TROUBLESHOOTING.md) for using balenaCLI
CLI with WSL and Docker Desktop for Windows. with WSL and Docker Desktop for Windows.
On **macOS** and **Linux,** the standard terminal window is supported. _Optionally,_ `bash` command On **macOS** and **Linux,** the standard terminal window is supported. Optionally, `bash` command
auto completion may be enabled by copying the auto completion may be enabled by copying the
[balena-completion.bash](https://github.com/balena-io/balena-cli/blob/master/balena-completion.bash) [balena-completion.bash](https://github.com/balena-io/balena-cli/blob/master/balena-completion.bash)
file to your system's `bash_completion` directory: check [Docker's command completion file to your system's `bash_completion` directory: check [Docker's command completion
guide](https://docs.docker.com/compose/completion/) for system setup instructions. guide](https://docs.docker.com/compose/completion/) for system setup instructions.
### Logging in ## Logging in
Several CLI commands require access to your balenaCloud account, for example in order to push a 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: new release to your application. Those commands require creating a CLI login session by running:
@ -55,7 +54,7 @@ new release to your application. Those commands require creating a CLI login ses
$ balena login $ balena login
``` ```
### Proxy support ## Proxy support
HTTP(S) proxies can be configured through any of the following methods, in precedence order HTTP(S) proxies can be configured through any of the following methods, in precedence order
(from higher to lower): (from higher to lower):
@ -81,15 +80,22 @@ HTTP(S) proxies can be configured through any of the following methods, in prece
* The `HTTPS_PROXY` and/or `HTTP_PROXY` environment variables, in the same URL format as * The `HTTPS_PROXY` and/or `HTTP_PROXY` environment variables, in the same URL format as
`BALENARC_PROXY`. `BALENARC_PROXY`.
> Note: The `balena ssh` command has additional setup requirements to work behind a proxy. ### Proxy setup for balena ssh
> Check the [installation instructions](https://github.com/balena-io/balena-cli/blob/master/INSTALL.md),
> 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](http://www.squid-cache.org/) 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 In order to work behind a proxy server, the `balena ssh` command requires the
[`proxytunnel`](http://proxytunnel.sourceforge.net/) package (command-line tool) to be installed.
`proxytunnel` is available for Linux distributions like Ubuntu/Debian (`apt install proxytunnel`),
and for macOS through [Homebrew](https://brew.sh/). Windows support is limited to the [Windows
Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/about) (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](http://www.squid-cache.org/) 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. The `BALENARC_NO_PROXY` variable may be used to exclude specified destinations from proxying.
@ -130,19 +136,19 @@ If you come across any problems or would like to get in touch:
## Deprecation policy ## Deprecation policy
The balena CLI uses [semver versioning](https://semver.org/), with the concepts balenaCLI uses [semver versioning](https://semver.org/), with the concepts
of major, minor and patch version releases. of major, minor and patch version releases.
The latest release of the previous major version of the balena CLI will remain The latest release of a major version of balenaCLI will remain compatible with
compatible with the balenaCloud backend services for one year from the date when the balenaCloud backend services for at least one year from the date when the
the next major version is released. For example, balena CLI v10.17.5, as the following major version is released. For example, balenaCLI v10.17.5, as the
latest v10 release, would remain compatible with the balenaCloud backend for one latest v10 release, would remain compatible with the balenaCloud backend for one
year from the date when v11.0.0 is released. year from the date when v11.0.0 is released.
At the end of this period, the older major version is considered deprecated and 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 some of the functionality that depends on balenaCloud services may stop working
at any time. at any time.
Users are encouraged to regularly update the balena CLI to the latest version. Users are encouraged to regularly update balenaCLI to the latest version.
# CLI Command Reference # CLI Command Reference
@ -1236,7 +1242,7 @@ show additional commands
## version ## version
Display version information for the balena CLI and/or Node.js. Display version information for balenaCLI and/or Node.js.
The --json option is recommended when scripting the output of this command, The --json option is recommended when scripting the output of this command,
because the JSON format is less likely to change and it better represents because the JSON format is less likely to change and it better represents
@ -1293,15 +1299,30 @@ balenaCloud ID for the SSH key
## key add &#60;name&#62; [path] ## key add &#60;name&#62; [path]
Register an SSH in balenaCloud for the logged in user. Add an SSH key to the balenaCloud account of the logged in user.
If `path` is omitted, the command will attempt If `path` is omitted, the command will attempt to read the SSH key from stdin.
to read the SSH key from stdin.
About SSH keys
An "SSH key" actually consists of a public/private key pair. A typical name
for the private key file is "id_rsa", and a typical name for the public key
file is "id_rsa.pub". Both key files are saved to your computer (with the
private key optionally protected by a password), but only the public key is
saved to your balena account. This means that if you change computers or
otherwise lose the private key, you cannot recover the private key through
your balena account. You can however add new keys, and delete the old ones.
To generate a new SSH key pair, a nice guide can be found in GitHub's docs:
https://help.github.com/en/articles/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent
Skip the step about adding the key to a GitHub account, and instead add it to
your balena account.
Examples: Examples:
$ balena key add Main ~/.ssh/id_rsa.pub $ balena key add Main ~/.ssh/id_rsa.pub
$ cat ~/.ssh/id_rsa.pub | balena key add Main $ cat ~/.ssh/id_rsa.pub | balena key add Main
# Windows 10 (cmd.exe prompt) example
$ balena key add Main %userprofile%.sshid_rsa.pub
### Arguments ### Arguments
@ -1669,7 +1690,7 @@ A suitable key is automatically generated or fetched if this option is omitted.
Note: This command is currently not supported on Windows natively. Windows users Note: This command is currently not supported on Windows natively. Windows users
are advised to install the Windows Subsystem for Linux (WSL) with Ubuntu, and use are advised to install the Windows Subsystem for Linux (WSL) with Ubuntu, and use
the Linux release of the balena CLI: the Linux release of balenaCLI:
https://docs.microsoft.com/en-us/windows/wsl/about https://docs.microsoft.com/en-us/windows/wsl/about
Examples: Examples:
@ -2042,8 +2063,7 @@ Docker host TLS key file
## push &#60;applicationOrDevice&#62; ## push &#60;applicationOrDevice&#62;
start a build on the remote balena cloud builders, Start a build on the remote balenaCloud builders, or a local mode balena device.
or a local mode balena device.
When building on the balenaCloud servers, the given source directory will be When building on the balenaCloud servers, the given source directory will be
sent to the remote server. This can be used as a drop-in replacement for the sent to the remote server. This can be used as a drop-in replacement for the
@ -2089,7 +2109,7 @@ secrets.json file exists in the balena directory (usually $HOME/.balena),
this file will be used instead. this file will be used instead.
DOCKERIGNORE AND GITIGNORE FILES DOCKERIGNORE AND GITIGNORE FILES
By default, the balena CLI will use a single ".dockerignore" file (if any) at By default, balenaCLI will use a single ".dockerignore" file (if any) at
the project root (--source directory) in order to decide which source files to the project root (--source directory) in order to decide which source files to
exclude from the "build context" (tar stream) sent to balenaCloud, Docker exclude from the "build context" (tar stream) sent to balenaCloud, Docker
daemon or balenaEngine. In a microservices (multicontainer) application, the daemon or balenaEngine. In a microservices (multicontainer) application, the
@ -2114,7 +2134,7 @@ compatibility with the standard docker-compose tool, while still allowing a
root .dockerignore file (at the overall project root) to filter files and root .dockerignore file (at the overall project root) to filter files and
folders that are outside service subdirectories. folders that are outside service subdirectories.
Balena CLI releases older than v12.0.0 also took .gitignore files into account. balenaCLI releases older than v12.0.0 also took .gitignore files into account.
This behavior is deprecated, but may still be enabled with the --gitignore (-g) This behavior is deprecated, but may still be enabled with the --gitignore (-g)
option if compatibility is required. This option is mutually exclusive with option if compatibility is required. This option is mutually exclusive with
--multi-dockerignore (-m) and will be removed in the CLI's next major version --multi-dockerignore (-m) and will be removed in the CLI's next major version
@ -2365,7 +2385,7 @@ secrets.json file exists in the balena directory (usually $HOME/.balena),
this file will be used instead. this file will be used instead.
DOCKERIGNORE AND GITIGNORE FILES DOCKERIGNORE AND GITIGNORE FILES
By default, the balena CLI will use a single ".dockerignore" file (if any) at By default, balenaCLI will use a single ".dockerignore" file (if any) at
the project root (--source directory) in order to decide which source files to the project root (--source directory) in order to decide which source files to
exclude from the "build context" (tar stream) sent to balenaCloud, Docker exclude from the "build context" (tar stream) sent to balenaCloud, Docker
daemon or balenaEngine. In a microservices (multicontainer) application, the daemon or balenaEngine. In a microservices (multicontainer) application, the
@ -2390,7 +2410,7 @@ compatibility with the standard docker-compose tool, while still allowing a
root .dockerignore file (at the overall project root) to filter files and root .dockerignore file (at the overall project root) to filter files and
folders that are outside service subdirectories. folders that are outside service subdirectories.
Balena CLI releases older than v12.0.0 also took .gitignore files into account. balenaCLI releases older than v12.0.0 also took .gitignore files into account.
This behavior is deprecated, but may still be enabled with the --gitignore (-g) This behavior is deprecated, but may still be enabled with the --gitignore (-g)
option if compatibility is required. This option is mutually exclusive with option if compatibility is required. This option is mutually exclusive with
--multi-dockerignore (-m) and will be removed in the CLI's next major version --multi-dockerignore (-m) and will be removed in the CLI's next major version
@ -2587,7 +2607,7 @@ secrets.json file exists in the balena directory (usually $HOME/.balena),
this file will be used instead. this file will be used instead.
DOCKERIGNORE AND GITIGNORE FILES DOCKERIGNORE AND GITIGNORE FILES
By default, the balena CLI will use a single ".dockerignore" file (if any) at By default, balenaCLI will use a single ".dockerignore" file (if any) at
the project root (--source directory) in order to decide which source files to the project root (--source directory) in order to decide which source files to
exclude from the "build context" (tar stream) sent to balenaCloud, Docker exclude from the "build context" (tar stream) sent to balenaCloud, Docker
daemon or balenaEngine. In a microservices (multicontainer) application, the daemon or balenaEngine. In a microservices (multicontainer) application, the
@ -2612,7 +2632,7 @@ compatibility with the standard docker-compose tool, while still allowing a
root .dockerignore file (at the overall project root) to filter files and root .dockerignore file (at the overall project root) to filter files and
folders that are outside service subdirectories. folders that are outside service subdirectories.
Balena CLI releases older than v12.0.0 also took .gitignore files into account. balenaCLI releases older than v12.0.0 also took .gitignore files into account.
This behavior is deprecated, but may still be enabled with the --gitignore (-g) This behavior is deprecated, but may still be enabled with the --gitignore (-g)
option if compatibility is required. This option is mutually exclusive with option if compatibility is required. This option is mutually exclusive with
--multi-dockerignore (-m) and will be removed in the CLI's next major version --multi-dockerignore (-m) and will be removed in the CLI's next major version

21
lib/actions-oclif/key/add.ts
View File

@ -34,15 +34,30 @@ export default class KeyAddCmd extends Command {
public static description = stripIndent` public static description = stripIndent`
Add an SSH key to balenaCloud. Add an SSH key to balenaCloud.
Register an SSH in balenaCloud for the logged in user. Add an SSH key to the balenaCloud account of the logged in user.
If \`path\` is omitted, the command will attempt If \`path\` is omitted, the command will attempt to read the SSH key from stdin.
to read the SSH key from stdin.
About SSH keys
An "SSH key" actually consists of a public/private key pair. A typical name
for the private key file is "id_rsa", and a typical name for the public key
file is "id_rsa.pub". Both key files are saved to your computer (with the
private key optionally protected by a password), but only the public key is
saved to your balena account. This means that if you change computers or
otherwise lose the private key, you cannot recover the private key through
your balena account. You can however add new keys, and delete the old ones.
To generate a new SSH key pair, a nice guide can be found in GitHub's docs:
https://help.github.com/en/articles/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent
Skip the step about adding the key to a GitHub account, and instead add it to
your balena account.
`; `;
public static examples = [ public static examples = [
'$ balena key add Main ~/.ssh/id_rsa.pub', '$ balena key add Main ~/.ssh/id_rsa.pub',
'$ cat ~/.ssh/id_rsa.pub | balena key add Main', '$ cat ~/.ssh/id_rsa.pub | balena key add Main',
'# Windows 10 (cmd.exe prompt) example',
'$ balena key add Main %userprofile%.sshid_rsa.pub',
]; ];
public static args = [ public static args = [

2
lib/actions-oclif/os/configure.ts
View File

@ -90,7 +90,7 @@ export default class OsConfigureCmd extends Command {
Note: This command is currently not supported on Windows natively. Windows users Note: This command is currently not supported on Windows natively. Windows users
are advised to install the Windows Subsystem for Linux (WSL) with Ubuntu, and use are advised to install the Windows Subsystem for Linux (WSL) with Ubuntu, and use
the Linux release of the balena CLI: the Linux release of balenaCLI:
https://docs.microsoft.com/en-us/windows/wsl/about https://docs.microsoft.com/en-us/windows/wsl/about
`; `;
public static examples = [ public static examples = [

5
lib/actions-oclif/push.ts
View File

@ -55,10 +55,9 @@ interface ArgsDef {
export default class PushCmd extends Command { export default class PushCmd extends Command {
public static description = stripIndent` public static description = stripIndent`
Start a remote build on the balena cloud build servers or a local mode device. Start a remote build on the balenaCloud build servers or a local mode device.
start a build on the remote balena cloud builders, Start a build on the remote balenaCloud builders, or a local mode balena device.
or a local mode balena device.
When building on the balenaCloud servers, the given source directory will be When building on the balenaCloud servers, the given source directory will be
sent to the remote server. This can be used as a drop-in replacement for the sent to the remote server. This can be used as a drop-in replacement for the

4
lib/actions-oclif/version.ts
View File

@ -32,9 +32,9 @@ export interface JsonVersions {
export default class VersionCmd extends Command { export default class VersionCmd extends Command {
public static description = stripIndent` public static description = stripIndent`
Display version information for the balena CLI and/or Node.js. Display version information for balenaCLI and/or Node.js.
Display version information for the balena CLI and/or Node.js. Display version information for balenaCLI and/or Node.js.
The --json option is recommended when scripting the output of this command, The --json option is recommended when scripting the output of this command,
because the JSON format is less likely to change and it better represents because the JSON format is less likely to change and it better represents

2
lib/auth/index.ts
View File

@ -22,7 +22,7 @@ import { LoginServer } from './server';
*/ */
/** /**
* @summary Login to the balena CLI using the web dashboard * @summary Login to balenaCLI using the web dashboard
* @function * @function
* @public * @public
* *

2
lib/auth/pages/error.ejs
View File

@ -3,7 +3,7 @@
<head> <head>
<meta charset="utf-8"> <meta charset="utf-8">
<meta http-equiv="x-ua-compatible" content="ie=edge"> <meta http-equiv="x-ua-compatible" content="ie=edge">
<title>Balena CLI - Error</title> <title>balenaCLI - Error</title>
<meta name="description" content=""> <meta name="description" content="">
<meta name="viewport" content="width=device-width, initial-scale=1"> <meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="stylesheet" type="text/css" href="./static/style.css" inline> <link rel="stylesheet" type="text/css" href="./static/style.css" inline>

2
lib/auth/pages/success.ejs
View File

@ -3,7 +3,7 @@
<head> <head>
<meta charset="utf-8"> <meta charset="utf-8">
<meta http-equiv="x-ua-compatible" content="ie=edge"> <meta http-equiv="x-ua-compatible" content="ie=edge">
<title>Balena CLI - Success</title> <title>balenaCLI - Success</title>
<meta name="description" content=""> <meta name="description" content="">
<meta name="viewport" content="width=device-width, initial-scale=1"> <meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="stylesheet" type="text/css" href="./static/style.css" inline> <link rel="stylesheet" type="text/css" href="./static/style.css" inline>

4
lib/utils/compose.js
View File

@ -63,7 +63,7 @@ export function appendOptions(opts) {
}, },
{ {
signature: 'nogitignore', signature: 'nogitignore',
description: `No-op (default behavior) since balena CLI v12.0.0. See "balena help build".`, description: `No-op (default behavior) since v12.0.0. See "balena help build".`,
boolean: true, boolean: true,
alias: 'G', alias: 'G',
}, },
@ -82,7 +82,7 @@ export function appendOptions(opts) {
}, },
{ {
signature: 'convert-eol', signature: 'convert-eol',
description: 'No-op and deprecated since balena CLI v12.0.0', description: 'No-op and deprecated since v12.0.0',
boolean: true, boolean: true,
alias: 'l', alias: 'l',
}, },

4
lib/utils/messages.ts
View File

@ -69,7 +69,7 @@ this file will be used instead.`;
export const dockerignoreHelp = `\ export const dockerignoreHelp = `\
DOCKERIGNORE AND GITIGNORE FILES DOCKERIGNORE AND GITIGNORE FILES
By default, the balena CLI will use a single ".dockerignore" file (if any) at By default, balenaCLI will use a single ".dockerignore" file (if any) at
the project root (--source directory) in order to decide which source files to the project root (--source directory) in order to decide which source files to
exclude from the "build context" (tar stream) sent to balenaCloud, Docker exclude from the "build context" (tar stream) sent to balenaCloud, Docker
daemon or balenaEngine. In a microservices (multicontainer) application, the daemon or balenaEngine. In a microservices (multicontainer) application, the
@ -94,7 +94,7 @@ compatibility with the standard docker-compose tool, while still allowing a
root .dockerignore file (at the overall project root) to filter files and root .dockerignore file (at the overall project root) to filter files and
folders that are outside service subdirectories. folders that are outside service subdirectories.
Balena CLI releases older than v12.0.0 also took .gitignore files into account. balenaCLI releases older than v12.0.0 also took .gitignore files into account.
This behavior is deprecated, but may still be enabled with the --gitignore (-g) This behavior is deprecated, but may still be enabled with the --gitignore (-g)
option if compatibility is required. This option is mutually exclusive with option if compatibility is required. This option is mutually exclusive with
--multi-dockerignore (-m) and will be removed in the CLI's next major version --multi-dockerignore (-m) and will be removed in the CLI's next major version

2
lib/utils/remote-build.ts
View File

@ -384,7 +384,7 @@ async function getRemoteBuildStream(
if (process.stdout.isTTY) { if (process.stdout.isTTY) {
const visuals = getVisuals(); const visuals = getVisuals();
uploadSpinner = new visuals.Spinner( uploadSpinner = new visuals.Spinner(
'Uploading source package to balena cloud', 'Uploading source package to balenaCloud',
); );
exitOnError = (error: Error): never => { exitOnError = (error: Error): never => {
uploadSpinner.stop(); uploadSpinner.stop();

2
package.json
View File

@ -1,7 +1,7 @@
{ {
"name": "balena-cli", "name": "balena-cli",
"version": "12.22.0", "version": "12.22.0",
"description": "The official balena CLI tool", "description": "The official balena Command Line Interface",
"main": "./build/app.js", "main": "./build/app.js",
"homepage": "https://github.com/balena-io/balena-cli", "homepage": "https://github.com/balena-io/balena-cli",
"repository": { "repository": {

4
tests/commands/help.spec.ts
View File

@ -26,7 +26,7 @@ $ balena [COMMAND] [OPTIONS]
PRIMARY COMMANDS PRIMARY COMMANDS
login login to balena login login to balena
push <applicationOrDevice> start a remote build on the balena cloud build servers or a local mode device push <applicationOrDevice> start a remote build on the balenaCloud build servers or a local mode device
logs <device> show device logs logs <device> show device logs
ssh <applicationOrDevice> [service] SSH into the host or application container of a device ssh <applicationOrDevice> [service] SSH into the host or application container of a device
apps list all applications apps list all applications
@ -87,7 +87,7 @@ ADDITIONAL COMMANDS
tag set <tagKey> [value] set a tag on an application, device or release tag set <tagKey> [value] set a tag on an application, device or release
tags list all tags for an application, device or release tags list all tags for an application, device or release
util available-drives list available drives util available-drives list available drives
version display version information for the balena CLI and/or Node.js version display version information for balenaCLI and/or Node.js
whoami display account information for current user whoami display account information for current user
`; `;