Deprecate tunnel command in favor of device tunnel

Change-type: patch

TROUBLESHOOTING.md

@@ -31,7 +31,7 @@ command again.
 
 Check whether the SD card is locked (a physical switch on the side of the card).
 
-## I get `connect ETIMEDOUT` with `balena tunnel`
+## I get `connect ETIMEDOUT` with `balena device tunnel`
 
 Please update the CLI to the latest version. This issue was fixed in v12.38.5.
 For more details, see: https://github.com/balena-io/balena-cli/issues/2172

automation/capitanodoc/capitanodoc.ts

@@ -61,7 +61,6 @@ const commandHeadings: { [key: string]: string } = {
 	organization: 'Organizations',
 	os: 'OS',
 	util: 'Utilities',
-	tunnel: 'Network',
 	build: 'Deploy',
 	join: 'Platform',
 	leave: '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-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 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 ssh 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 tunnel )
   devices_cmds=( supported )
   env_cmds=( list rename rm set )
   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-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 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 ssh 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 tunnel"
   devices_cmds="supported"
   env_cmds="list rename rm set"
   fleet_cmds="create list pin purge rename restart rm track-latest"

docs/balena-cli.md

@@ -218,6 +218,7 @@ are encouraged to regularly update the balena CLI to the latest version.
 	- [device start-service <uuid>](#device-start-service-uuid)
 	- [device stop-service <uuid>](#device-stop-service-uuid)
 	- [device track-fleet <uuid>](#device-track-fleet-uuid)
+	- [device tunnel <deviceorfleet>](#device-tunnel-deviceorfleet)
 	- [devices supported](#devices-supported)
 
 - Environment Variables
@@ -244,10 +245,6 @@ are encouraged to regularly update the balena CLI to the latest version.
 	- [local configure <target>](#local-configure-target)
 	- [local flash <image>](#local-flash-image)
 
-- Network
-
-	- [tunnel <deviceorfleet>](#tunnel-deviceorfleet)
-
 - Notes
 
 	- [note <|note>](#note-note)
@@ -1936,6 +1933,57 @@ the uuid of the device to make track the fleet's release
 
 ### Options
 
+## device tunnel <deviceOrFleet>
+
+Use this command to open local TCP ports that tunnel to listening sockets in a
+balenaOS device.
+
+For example, this command could be used to expose the ssh server of a balenaOS
+device (port number 22222) on the local machine, or to expose a web server
+running on the device. The port numbers do not have be the same between the
+device and the local machine, and multiple ports may be tunneled in a single
+command line.
+
+Port mappings are specified in the format: <remotePort>[:[localIP:]localPort]
+localIP defaults to 'localhost', and localPort defaults to the specified
+remotePort value.
+
+Note: the -p (--port) flag must be provided at the end of the command line,
+as per examples.
+
+In the case of openBalena, the tunnel command in CLI v12.38.5 or later requires
+openBalena v3.1.2 or later. Older CLI versions work with older openBalena
+versions.
+
+Examples:
+
+	# map remote port 22222 to localhost:22222
+	$ balena device tunnel myFleet -p 22222
+	
+	# map remote port 22222 to localhost:222
+	$ balena device tunnel 2ead211 -p 22222:222
+	
+	# map remote port 22222 to any address on your host machine, port 22222
+	$ balena device tunnel 1546690 -p 22222:0.0.0.0
+	
+	# map remote port 22222 to any address on your host machine, port 222
+	$ balena device tunnel myFleet -p 22222:0.0.0.0:222
+	
+	# multiple port tunnels can be specified at any one time
+	$ balena device tunnel myFleet -p 8080:3000 -p 8081:9000
+
+### Arguments
+
+#### DEVICEORFLEET
+
+device UUID or fleet name/slug
+
+### Options
+
+#### -p, --port PORT
+
+port mapping in the format <remotePort>[:[localIP:]localPort]
+
 ## devices supported
 
 List the supported device types (like 'raspberrypi3' or 'intel-nuc').
@@ -2550,59 +2598,6 @@ Check `balena util available-drives` for available options.
 
 answer "yes" to all questions (non interactive use)
 
-# Network
-
-## tunnel &#60;deviceOrFleet&#62;
-
-Use this command to open local TCP ports that tunnel to listening sockets in a
-balenaOS device.
-
-For example, this command could be used to expose the ssh server of a balenaOS
-device (port number 22222) on the local machine, or to expose a web server
-running on the device. The port numbers do not have be the same between the
-device and the local machine, and multiple ports may be tunneled in a single
-command line.
-
-Port mappings are specified in the format: <remotePort>[:[localIP:]localPort]
-localIP defaults to 'localhost', and localPort defaults to the specified
-remotePort value.
-
-Note: the -p (--port) flag must be provided at the end of the command line,
-as per examples.
-
-In the case of openBalena, the tunnel command in CLI v12.38.5 or later requires
-openBalena v3.1.2 or later. Older CLI versions work with older openBalena
-versions.
-
-Examples:
-
-	# map remote port 22222 to localhost:22222
-	$ balena tunnel myFleet -p 22222
-	
-	# map remote port 22222 to localhost:222
-	$ balena tunnel 2ead211 -p 22222:222
-	
-	# map remote port 22222 to any address on your host machine, port 22222
-	$ balena tunnel 1546690 -p 22222:0.0.0.0
-	
-	# map remote port 22222 to any address on your host machine, port 222
-	$ balena tunnel myFleet -p 22222:0.0.0.0:222
-	
-	# multiple port tunnels can be specified at any one time
-	$ balena tunnel myFleet -p 8080:3000 -p 8081:9000
-
-### Arguments
-
-#### DEVICEORFLEET
-
-device UUID or fleet name/slug
-
-### Options
-
-#### -p, --port PORT
-
-port mapping in the format <remotePort>[:[localIP:]localPort]
-
 # Notes
 
 ## note &#60;|note&#62;

src/commands/device/tunnel.ts

@@ -28,7 +28,7 @@ import { lowercaseIfSlug } from '../../utils/normalization';
 
 import type { Server, Socket } from 'net';
 
-export default class TunnelCmd extends Command {
+export default class DeviceTunnelCmd extends Command {
 	public static description = stripIndent`
 		Tunnel local ports to your balenaOS device.
 
@@ -55,19 +55,19 @@ export default class TunnelCmd extends Command {
 
 	public static examples = [
 		'# map remote port 22222 to localhost:22222',
-		'$ balena tunnel myFleet -p 22222',
+		'$ balena device tunnel myFleet -p 22222',
 		'',
 		'# map remote port 22222 to localhost:222',
-		'$ balena tunnel 2ead211 -p 22222:222',
+		'$ balena device tunnel 2ead211 -p 22222:222',
 		'',
 		'# map remote port 22222 to any address on your host machine, port 22222',
-		'$ balena tunnel 1546690 -p 22222:0.0.0.0',
+		'$ balena device tunnel 1546690 -p 22222:0.0.0.0',
 		'',
 		'# map remote port 22222 to any address on your host machine, port 222',
-		'$ balena tunnel myFleet -p 22222:0.0.0.0:222',
+		'$ balena device tunnel myFleet -p 22222:0.0.0.0:222',
 		'',
 		'# multiple port tunnels can be specified at any one time',
-		'$ balena tunnel myFleet -p 8080:3000 -p 8081:9000',
+		'$ balena device tunnel myFleet -p 8080:3000 -p 8081:9000',
 	];
 
 	public static args = {
@@ -78,7 +78,7 @@ export default class TunnelCmd extends Command {
 		}),
 	};
 
-	public static usage = 'tunnel <deviceOrFleet>';
+	public static usage = 'device tunnel <deviceOrFleet>';
 
 	public static flags = {
 		port: Flags.string({
@@ -94,7 +94,7 @@ export default class TunnelCmd extends Command {
 	public static authenticated = true;
 
 	public async run() {
-		const { args: params, flags: options } = await this.parse(TunnelCmd);
+		const { args: params, flags: options } = await this.parse(DeviceTunnelCmd);
 
 		const logger = await Command.getLogger();
 		const sdk = getBalenaSdk();

src/help.ts

@@ -225,7 +225,6 @@ See: https://git.io/JRHUW#deprecation-policy`,
 		'push',
 		'fleet',
 		'device',
-		'tunnel',
 		'preload',
 		'build',
 		'deploy',

tests/commands/help.spec.ts

@@ -30,7 +30,6 @@ PRIMARY COMMANDS
   push <applicationOrDevice>             start a remote build on the balenaCloud build servers or a local mode device
   app <name>                             display information about a single application
   device <uuid>                          show info about a single device
-  tunnel <deviceOrApplication>           tunnel local ports to your balenaOS device
   preload <image>                        preload an app on a disk image (or Edison zip archive)
   build [source]                         build a project locally
   deploy <appName> [image]               deploy a single image or a multicontainer project to a balena application
@@ -64,6 +63,7 @@ ADDITIONAL COMMANDS
   device shutdown <uuid>                 shutdown a device
   device ssh <applicationOrDevice> [service]    SSH into the host or application container of a device
   devices supported                      list the supported device types (like 'raspberrypi3' or 'intel-nuc')
+  device tunnel <deviceOrApplication>    tunnel local ports to your balenaOS device
   env set <name> [value]                 add or update env or config variable to application(s), device(s) or service(s)
   env list                               list the environment or config variables of an application, device or service
   env rename <name> <value>              change the value of a config or env var for an app, device or service

tests/test-data/pkg/expected-warnings-darwin-arm64.txt

@@ -228,7 +228,7 @@
   %2: build/commands/tag/set.js
 > Warning Entry 'main' not found in %1
   %1: node_modules/@oclif/core/package.json
-  %2: build/commands/tunnel/index.js
+  %2: build/commands/device/tunnel.js
 > Warning Entry 'main' not found in %1
   %1: node_modules/@oclif/core/package.json
   %2: build/commands/version/index.js

tests/test-data/pkg/expected-warnings-darwin-x64.txt

@@ -228,7 +228,7 @@
   %2: build/commands/tag/set.js
 > Warning Entry 'main' not found in %1
   %1: node_modules/@oclif/core/package.json
-  %2: build/commands/tunnel/index.js
+  %2: build/commands/device/tunnel.js
 > Warning Entry 'main' not found in %1
   %1: node_modules/@oclif/core/package.json
   %2: build/commands/version/index.js

tests/test-data/pkg/expected-warnings-linux-arm64.txt

@@ -228,7 +228,7 @@
   %2: build/commands/tag/set.js
 > Warning Entry 'main' not found in %1
   %1: node_modules/@oclif/core/package.json
-  %2: build/commands/tunnel/index.js
+  %2: build/commands/device/tunnel.js
 > Warning Entry 'main' not found in %1
   %1: node_modules/@oclif/core/package.json
   %2: build/commands/version/index.js

tests/test-data/pkg/expected-warnings-linux-x64.txt

@@ -228,7 +228,7 @@
   %2: build/commands/tag/set.js
 > Warning Entry 'main' not found in %1
   %1: node_modules/@oclif/core/package.json
-  %2: build/commands/tunnel/index.js
+  %2: build/commands/device/tunnel.js
 > Warning Entry 'main' not found in %1
   %1: node_modules/@oclif/core/package.json
   %2: build/commands/version/index.js

tests/test-data/pkg/expected-warnings-win32-x64.txt

@@ -228,7 +228,7 @@
   %2: build\commands\tag\set.js
 > Warning Entry 'main' not found in %1
   %1: node_modules\@oclif\core\package.json
-  %2: build\commands\tunnel\index.js
+  %2: build\commands\device\tunnel.js
 > Warning Entry 'main' not found in %1
   %1: node_modules\@oclif\core\package.json
   %2: build\commands\version\index.js