Add alias device ssh for ssh command

Change-type: minor

INSTALL-ADVANCED.md

@@ -145,7 +145,7 @@ container) in order to allow npm scripts like `postinstall` to be executed.
 
 ## Additional Dependencies
 
-The `balena ssh`, `device detect`, `build`, `deploy` and `preload` commands may require
+The `balena device ssh`, `device detect`, `build`, `deploy` and `preload` commands may require
 additional software to be installed. Check the Additional Dependencies sections for each operating
 system:
 

INSTALL-LINUX.md

@@ -61,13 +61,13 @@ instructions](https://docs.docker.com/install/overview/) to install Docker on th
 workstation as the balena CLI. The [advanced installation
 options](./INSTALL-ADVANCED.md#additional-dependencies) document describes other possibilities.
 
-### balena ssh
+### balena device ssh
 
-The `balena ssh` command requires the `ssh` command-line tool to be available. Most Linux
+The `balena device 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
+The `balena device 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`.
 

INSTALL-MAC.md

@@ -19,7 +19,7 @@ Selected operating system: **macOS**
    - On the terminal prompt, type `balena version` and hit Enter. It should display
      the version of the balena CLI that you have installed.
 
-No further steps are required to run most CLI commands. The `balena ssh`, `build`, `deploy`
+No further steps are required to run most CLI commands. The `balena device ssh`, `build`, `deploy`
 and `preload` commands may require additional software to be installed, as described
 in the next section.
 
@@ -41,9 +41,9 @@ instructions](https://docs.docker.com/install/overview/) to install Docker on th
 workstation as the balena CLI. The [advanced installation
 options](./INSTALL-ADVANCED.md#additional-dependencies) document describes other possibilities.
 
-### balena ssh
+### balena device ssh
 
-The `balena ssh` command requires the `ssh` command-line tool to be available. To check whether
+The `balena device 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:
 
@@ -52,7 +52,7 @@ include:
   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
+The `balena device 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`.
 

INSTALL-WINDOWS.md

@@ -19,7 +19,7 @@ Selected operating system: **Windows**
    - On the command prompt, type `balena version` and hit Enter. It should display
      the version of the balena CLI that you have installed.
 
-No further steps are required to run most CLI commands. The `balena ssh`, `device detect`, `build`,
+No further steps are required to run most CLI commands. The `balena device ssh`, `device detect`, `build`,
 `deploy` and `preload` commands may require additional software to be installed, as
 described below.
 
@@ -34,17 +34,17 @@ instructions](https://docs.docker.com/install/overview/) to install Docker on th
 workstation as the balena CLI. The [advanced installation
 options](./INSTALL-ADVANCED.md#additional-dependencies) document describes other possibilities.
 
-### balena ssh
+### balena device ssh
 
-The `balena ssh` command requires the `ssh` command-line tool to be available. Microsoft started
+The `balena device 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
+The `balena device 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`.
 

README.md

@@ -88,9 +88,9 @@ 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
   `BALENARC_PROXY`.
 
-### Proxy setup for balena ssh
+### Proxy setup for balena device ssh
 
-In order to work behind a proxy server, the `balena ssh` command requires the
+In order to work behind a proxy server, the `balena device 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
@@ -110,7 +110,7 @@ The `BALENARC_NO_PROXY` variable may be used to exclude specified destinations f
 > * This feature requires CLI version 11.30.8 or later. In the case of the npm [installation
 >   option](https://github.com/balena-io/balena-cli/blob/master/INSTALL.md), 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
+> * To exclude a `balena device 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

TROUBLESHOOTING.md

@@ -79,10 +79,10 @@ Try resetting the ownership by running:
 $ sudo chown -R <user> $HOME/.balena
 ```
 
-## Broken line wrapping / cursor behavior with `balena ssh`
+## Broken line wrapping / cursor behavior with `balena device 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`
+when long command lines are typed in a `balena device 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`

automation/capitanodoc/capitanodoc.ts

@@ -61,7 +61,6 @@ const commandHeadings: { [key: string]: string } = {
 	organization: 'Organizations',
 	os: 'OS',
 	util: 'Utilities',
-	ssh: 'Network',
 	tunnel: 'Network',
 	build: 'Deploy',
 	join: 'Platform',

completion/_balena

@@ -8,13 +8,13 @@ _balena() {
   local context state line curcontext="$curcontext"
 
   # Valid top-level completions
-  main_commands=( api-key app block build config deploy device devices env fleet internal join leave local login logout notes organization os preload push release settings ssh ssh-key support tag tunnel util version whoami )
+  main_commands=( api-key app block build config deploy device devices env fleet internal join leave local login logout notes organization os preload push release settings ssh-key support tag tunnel util version whoami )
   # Sub-completions
   api_key_cmds=( generate list revoke )
   app_cmds=( create )
   block_cmds=( create )
   config_cmds=( generate inject read reconfigure write )
-  device_cmds=( deactivate detect identify init list local-mode logs move os-update pin public-url purge reboot register rename restart rm shutdown start-service stop-service track-fleet )
+  device_cmds=( deactivate detect identify init list local-mode logs move os-update pin public-url purge reboot register rename restart rm shutdown ssh start-service stop-service track-fleet )
   devices_cmds=( supported )
   env_cmds=( add list rename rm )
   fleet_cmds=( create list pin purge rename restart rm track-latest )

completion/balena-completion.bash

@@ -7,13 +7,13 @@ _balena_complete()
   local cur prev
 
   # Valid top-level completions
-  main_commands="api-key app block build config deploy device devices env fleet internal join leave local login logout notes organization os preload push release settings ssh ssh-key support tag tunnel util version whoami"
+  main_commands="api-key app block build config deploy device devices env fleet internal join leave local login logout notes organization os preload push release settings ssh-key support tag tunnel util version whoami"
   # Sub-completions
   api_key_cmds="generate list revoke"
   app_cmds="create"
   block_cmds="create"
   config_cmds="generate inject read reconfigure write"
-  device_cmds="deactivate detect identify init list local-mode logs move os-update pin public-url purge reboot register rename restart rm shutdown start-service stop-service track-fleet"
+  device_cmds="deactivate detect identify init list local-mode logs move os-update pin public-url purge reboot register rename restart rm shutdown ssh start-service stop-service track-fleet"
   devices_cmds="supported"
   env_cmds="add list rename rm"
   fleet_cmds="create list pin purge rename restart rm track-latest"

docs/balena-cli.md

@@ -81,9 +81,9 @@ 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
   `BALENARC_PROXY`.
 
-### Proxy setup for balena ssh
+### Proxy setup for balena device ssh
 
-In order to work behind a proxy server, the `balena ssh` command requires the
+In order to work behind a proxy server, the `balena device 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
@@ -103,7 +103,7 @@ The `BALENARC_NO_PROXY` variable may be used to exclude specified destinations f
 > * This feature requires CLI version 11.30.8 or later. In the case of the npm [installation
 >   option](https://github.com/balena-io/balena-cli/blob/master/INSTALL.md), 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
+> * To exclude a `balena device 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
@@ -214,6 +214,7 @@ are encouraged to regularly update the balena CLI to the latest version.
 	- [device restart](#device-restart)
 	- [device rm](#device-rm)
 	- [device shutdown](#device-shutdown)
+	- [device ssh](#device-ssh)
 	- [device start-service](#device-start-service)
 	- [device stop-service](#device-stop-service)
 	- [device track-fleet](#device-track-fleet)
@@ -245,7 +246,6 @@ are encouraged to regularly update the balena CLI to the latest version.
 
 - Network
 
-	- [ssh](#ssh)
 	- [tunnel](#tunnel)
 
 - Notes
@@ -1903,6 +1903,80 @@ the uuid of the device to shutdown
 
 force action if the update lock is set
 
+## device ssh
+
+### Aliases
+
+- `ssh`
+
+
+To use one of the aliases, replace `device ssh` with the alias.
+
+### Description
+
+Start a shell on a local or remote device. If a service name is not provided,
+a shell will be opened on the host OS.
+
+If a fleet is provided, an interactive menu will be presented for the selection
+of an online device. A shell will then be opened for the host OS or service
+container of the chosen device.
+
+For local devices, the IP address and .local domain name are supported.
+If the device is referenced by IP or `.local` address, the connection
+is initiated directly to balenaOS on port `22222` via an
+openssh-compatible client. Otherwise, any connection initiated remotely
+traverses the balenaCloud VPN.
+
+Commands may be piped to the standard input for remote execution (see examples).
+Note however that remote command execution on service containers (as opposed to
+the host OS) is not currently possible when a device UUID is used (instead of
+an IP address) because of a balenaCloud backend limitation.
+
+Note: `balena ssh` requires an openssh-compatible client to be correctly
+installed in your shell environment. For more information (including Windows
+support) please check:
+	https://github.com/balena-io/balena-cli/blob/master/INSTALL.md#additional-dependencies,
+
+Examples:
+
+	$ balena device ssh MyFleet
+	$ balena device ssh f49cefd
+	$ balena device ssh f49cefd my-service
+	$ balena device ssh f49cefd --port <port>
+	$ balena device ssh 192.168.0.1 --verbose
+	$ balena device ssh f49cefd.local my-service
+	$ echo "uptime; exit;" | balena device ssh f49cefd
+	$ echo "uptime; exit;" | balena device ssh 192.168.0.1 myService
+
+### Arguments
+
+#### FLEETORDEVICE
+
+fleet name/slug, device uuid, or address of local device
+
+#### SERVICE
+
+service name, if connecting to a container
+
+### Options
+
+#### -p, --port PORT
+
+SSH server port number (default 22222) if the target is an IP address or .local
+hostname. Otherwise, port number for the balenaCloud gateway (default 22).
+
+#### -t, --tty
+
+force pseudo-terminal allocation (bypass TTY autodetection for stdin)
+
+#### -v, --verbose
+
+increase verbosity
+
+#### --noproxy
+
+bypass global proxy configuration for the ssh connection
+
 ## device start-service
 
 ### Description
@@ -2635,73 +2709,6 @@ answer "yes" to all questions (non interactive use)
 
 # Network
 
-## ssh
-
-### Description
-
-Start a shell on a local or remote device. If a service name is not provided,
-a shell will be opened on the host OS.
-
-If a fleet is provided, an interactive menu will be presented for the selection
-of an online device. A shell will then be opened for the host OS or service
-container of the chosen device.
-
-For local devices, the IP address and .local domain name are supported.
-If the device is referenced by IP or `.local` address, the connection
-is initiated directly to balenaOS on port `22222` via an
-openssh-compatible client. Otherwise, any connection initiated remotely
-traverses the balenaCloud VPN.
-
-Commands may be piped to the standard input for remote execution (see examples).
-Note however that remote command execution on service containers (as opposed to
-the host OS) is not currently possible when a device UUID is used (instead of
-an IP address) because of a balenaCloud backend limitation.
-
-Note: `balena ssh` requires an openssh-compatible client to be correctly
-installed in your shell environment. For more information (including Windows
-support) please check:
-	https://github.com/balena-io/balena-cli/blob/master/INSTALL.md#additional-dependencies,
-
-Examples:
-
-	$ balena ssh MyFleet
-	$ balena ssh f49cefd
-	$ balena ssh f49cefd my-service
-	$ balena ssh f49cefd --port <port>
-	$ balena ssh 192.168.0.1 --verbose
-	$ balena ssh f49cefd.local my-service
-	$ echo "uptime; exit;" | balena ssh f49cefd
-	$ echo "uptime; exit;" | balena ssh 192.168.0.1 myService
-
-### Arguments
-
-#### FLEETORDEVICE
-
-fleet name/slug, device uuid, or address of local device
-
-#### SERVICE
-
-service name, if connecting to a container
-
-### Options
-
-#### -p, --port PORT
-
-SSH server port number (default 22222) if the target is an IP address or .local
-hostname. Otherwise, port number for the balenaCloud gateway (default 22).
-
-#### -t, --tty
-
-force pseudo-terminal allocation (bypass TTY autodetection for stdin)
-
-#### -v, --verbose
-
-increase verbosity
-
-#### --noproxy
-
-bypass global proxy configuration for the ssh connection
-
 ## tunnel
 
 ### Description

src/commands/device/ssh.ts

@@ -23,7 +23,9 @@ import {
 	validateLocalHostnameOrIp,
 } from '../../utils/validation';
 
-export default class SshCmd extends Command {
+export default class DeviceSSHCmd extends Command {
+	public static aliases = ['ssh'];
+
 	public static description = stripIndent`
 		Open a SSH prompt on a device's host OS or service container.
 
@@ -52,14 +54,14 @@ export default class SshCmd extends Command {
 	`;
 
 	public static examples = [
-		'$ balena ssh MyFleet',
-		'$ balena ssh f49cefd',
-		'$ balena ssh f49cefd my-service',
-		'$ balena ssh f49cefd --port <port>',
-		'$ balena ssh 192.168.0.1 --verbose',
-		'$ balena ssh f49cefd.local my-service',
-		'$ echo "uptime; exit;" | balena ssh f49cefd',
-		'$ echo "uptime; exit;" | balena ssh 192.168.0.1 myService',
+		'$ balena device ssh MyFleet',
+		'$ balena device ssh f49cefd',
+		'$ balena device ssh f49cefd my-service',
+		'$ balena device ssh f49cefd --port <port>',
+		'$ balena device ssh 192.168.0.1 --verbose',
+		'$ balena device ssh f49cefd.local my-service',
+		'$ echo "uptime; exit;" | balena device ssh f49cefd',
+		'$ echo "uptime; exit;" | balena device ssh 192.168.0.1 myService',
 	];
 
 	public static args = {
@@ -104,7 +106,7 @@ export default class SshCmd extends Command {
 	public static offlineCompatible = true;
 
 	public async run() {
-		const { args: params, flags: options } = await this.parse(SshCmd);
+		const { args: params, flags: options } = await this.parse(DeviceSSHCmd);
 
 		// Local connection
 		if (validateLocalHostnameOrIp(params.fleetOrDevice)) {