Deprecate devices command in favor of device list

Change-type: minor

completion/_balena

@@ -14,7 +14,7 @@ _balena() {
   app_cmds=( create )
   block_cmds=( create )
   config_cmds=( generate inject read reconfigure write )
-  device_cmds=( deactivate identify init local-mode move os-update pin public-url purge reboot register rename restart rm shutdown start-service stop-service track-fleet )
+  device_cmds=( deactivate identify init list local-mode move os-update pin public-url purge reboot register rename restart rm shutdown start-service stop-service track-fleet )
   devices_cmds=( supported )
   env_cmds=( add rename rm )
   fleet_cmds=( create pin purge rename restart rm track-latest )

completion/balena-completion.bash

@@ -13,7 +13,7 @@ _balena_complete()
   app_cmds="create"
   block_cmds="create"
   config_cmds="generate inject read reconfigure write"
-  device_cmds="deactivate identify init local-mode move os-update pin public-url purge reboot register rename restart rm shutdown start-service stop-service track-fleet"
+  device_cmds="deactivate identify init list local-mode move os-update pin public-url purge reboot register rename restart rm shutdown start-service stop-service track-fleet"
   devices_cmds="supported"
   env_cmds="add rename rm"
   fleet_cmds="create pin purge rename restart rm track-latest"

docs/balena-cli.md

@@ -199,6 +199,7 @@ are encouraged to regularly update the balena CLI to the latest version.
 	- [device identify](#device-identify)
 	- [device](#device)
 	- [device init](#device-init)
+	- [device list](#device-list)
 	- [device local-mode](#device-local-mode)
 	- [device move](#device-move)
 	- [device os-update](#device-os-update)
@@ -214,7 +215,6 @@ are encouraged to regularly update the balena CLI to the latest version.
 	- [device start-service](#device-start-service)
 	- [device stop-service](#device-stop-service)
 	- [device track-fleet](#device-track-fleet)
-	- [devices](#devices)
 	- [devices supported](#devices-supported)
 
 - Environment Variables
@@ -1351,6 +1351,44 @@ custom key name assigned to generated provisioning api key
 
 expiry date assigned to generated provisioning api key (format: YYYY-MM-DD)
 
+## device list
+
+List all of your devices.
+
+Devices can be filtered by fleet with the `--fleet` option.
+
+Fleets may be specified by fleet name or slug. Fleet slugs are
+the recommended option, as they are unique and unambiguous. Slugs can be
+listed with the `balena fleets` command. Note that slugs may change if the
+fleet is renamed. Fleet names are not unique and may result in  "Fleet is
+ambiguous" errors at any time (even if it "used to work in the past"), for
+example if the name clashes with a newly created public fleet, or with fleets
+from other balena accounts that you may be invited to join under any role.
+For this reason, fleet names are especially discouraged in scripts (e.g. CI
+environments).
+
+The --json option is recommended when scripting the output of this command,
+because field names are less likely to change in JSON format and because it
+better represents data types like arrays, empty strings and null values.
+The 'jq' utility may be helpful for querying JSON fields in shell scripts
+(https://stedolan.github.io/jq/manual/).
+
+Examples:
+
+	$ balena device list
+	$ balena device list --fleet MyFleet
+	$ balena device list -f myorg/myfleet
+
+### Options
+
+#### -f, --fleet FLEET
+
+fleet name or slug (preferred)
+
+#### -j, --json
+
+produce JSON output instead of tabular output
+
 ## device local-mode
 
 Output current local mode status, or enable/disable local mode
@@ -1752,44 +1790,6 @@ the uuid of the device to make track the fleet's release
 
 ### Options
 
-## devices
-
-List all of your devices.
-
-Devices can be filtered by fleet with the `--fleet` option.
-
-Fleets may be specified by fleet name or slug. Fleet slugs are
-the recommended option, as they are unique and unambiguous. Slugs can be
-listed with the `balena fleets` command. Note that slugs may change if the
-fleet is renamed. Fleet names are not unique and may result in  "Fleet is
-ambiguous" errors at any time (even if it "used to work in the past"), for
-example if the name clashes with a newly created public fleet, or with fleets
-from other balena accounts that you may be invited to join under any role.
-For this reason, fleet names are especially discouraged in scripts (e.g. CI
-environments).
-
-The --json option is recommended when scripting the output of this command,
-because field names are less likely to change in JSON format and because it
-better represents data types like arrays, empty strings and null values.
-The 'jq' utility may be helpful for querying JSON fields in shell scripts
-(https://stedolan.github.io/jq/manual/).
-
-Examples:
-
-	$ balena devices
-	$ balena devices --fleet MyFleet
-	$ balena devices -f myorg/myfleet
-
-### Options
-
-#### -f, --fleet FLEET
-
-fleet name or slug (preferred)
-
-#### -j, --json
-
-produce JSON output instead of tabular output
-
 ## devices supported
 
 List the supported device types (like 'raspberrypi3' or 'intel-nuc').

src/commands/device/list.ts

@@ -35,7 +35,9 @@ const devicesSelectFields = {
 	],
 } satisfies PineOptions<Device>;
 
-export default class DevicesCmd extends Command {
+export default class DeviceListCmd extends Command {
+	public static aliases = ['devices'];
+
 	public static description = stripIndent`
 		List all devices.
 
@@ -48,9 +50,9 @@ export default class DevicesCmd extends Command {
 		${jsonInfo.split('\n').join('\n\t\t')}
 	`;
 	public static examples = [
-		'$ balena devices',
+		'$ balena device list',
-		'$ balena devices --fleet MyFleet',
+		'$ balena device list --fleet MyFleet',
-		'$ balena devices -f myorg/myfleet',
+		'$ balena device list -f myorg/myfleet',
 	];
 
 	public static flags = {
@@ -64,7 +66,7 @@ export default class DevicesCmd extends Command {
 	public static authenticated = true;
 
 	public async run() {
-		const { flags: options } = await this.parse(DevicesCmd);
+		const { flags: options } = await this.parse(DeviceListCmd);
 
 		const balena = getBalenaSdk();
 		const devicesOptions = {

src/help.ts

@@ -231,7 +231,6 @@ See: https://git.io/JRHUW#deprecation-policy`,
 		'ssh',
 		'fleets',
 		'fleet',
-		'devices',
 		'device',
 		'tunnel',
 		'preload',

tests/commands/device/device.spec.ts

@@ -121,4 +121,29 @@ describe('balena device', function () {
 		expect(json.belongs_to__application[0].app_name).to.equal('test app');
 		expect(json.device_tag[0].tag_key).to.equal('example');
 	});
+
+	it('should list devices from own and collaborator apps', async () => {
+		api.scope
+			.get(
+				'/v6/device?$orderby=device_name%20asc&$select=id,uuid,device_name,status,is_online,supervisor_version,os_version&$expand=belongs_to__application($select=app_name,slug),is_of__device_type($select=slug),is_running__release($select=commit)',
+			)
+			.replyWithFile(200, path.join(apiResponsePath, 'devices.json'), {
+				'Content-Type': 'application/json',
+			});
+
+		const { out } = await runCommand('device list');
+
+		const lines = cleanOutput(out);
+
+		expect(lines[0].replace(/  +/g, ' ')).to.equal(
+			'ID UUID DEVICE NAME DEVICE TYPE FLEET STATUS IS ONLINE SUPERVISOR VERSION OS VERSION DASHBOARD URL',
+		);
+		expect(lines).to.have.lengthOf.at.least(2);
+
+		expect(lines.some((l) => l.includes('org/test app'))).to.be.true;
+
+		// Devices with missing applications will have application name set to `N/a`.
+		// e.g. When user has a device associated with app that user is no longer a collaborator of.
+		expect(lines.some((l) => l.includes('N/a'))).to.be.true;
+	});
 });

tests/commands/device/devices.spec.ts

@@ -1,61 +0,0 @@
-/**
- * @license
- * Copyright 2019-2020 Balena Ltd.
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *    http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
-import { expect } from 'chai';
-import * as path from 'path';
-
-import { apiResponsePath, BalenaAPIMock } from '../../nock/balena-api-mock';
-import { cleanOutput, runCommand } from '../../helpers';
-
-describe('balena devices', function () {
-	let api: BalenaAPIMock;
-
-	beforeEach(() => {
-		api = new BalenaAPIMock();
-		api.expectGetWhoAmI({ optional: true, persist: true });
-	});
-
-	afterEach(() => {
-		// Check all expected api calls have been made and clean up.
-		api.done();
-	});
-
-	it('should list devices from own and collaborator apps', async () => {
-		api.scope
-			.get(
-				'/v6/device?$orderby=device_name%20asc&$select=id,uuid,device_name,status,is_online,supervisor_version,os_version&$expand=belongs_to__application($select=app_name,slug),is_of__device_type($select=slug),is_running__release($select=commit)',
-			)
-			.replyWithFile(200, path.join(apiResponsePath, 'devices.json'), {
-				'Content-Type': 'application/json',
-			});
-
-		const { out } = await runCommand('devices');
-
-		const lines = cleanOutput(out);
-
-		expect(lines[0].replace(/  +/g, ' ')).to.equal(
-			'ID UUID DEVICE NAME DEVICE TYPE FLEET STATUS IS ONLINE SUPERVISOR VERSION OS VERSION DASHBOARD URL',
-		);
-		expect(lines).to.have.lengthOf.at.least(2);
-
-		expect(lines.some((l) => l.includes('org/test app'))).to.be.true;
-
-		// Devices with missing applications will have application name set to `N/a`.
-		// e.g. When user has a device associated with app that user is no longer a collaborator of.
-		expect(lines.some((l) => l.includes('N/a'))).to.be.true;
-	});
-});

tests/commands/help.spec.ts

@@ -32,7 +32,6 @@ PRIMARY COMMANDS
   ssh <applicationOrDevice> [service]    SSH into the host or application container of a device
   apps                                   list all applications
   app <name>                             display information about a single application
-  devices                                list all devices
   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)
@@ -57,6 +56,7 @@ ADDITIONAL COMMANDS
   config write <key> <value>             write a key-value pair to configuration of a device or OS image
   device identify <uuid>                 identify a device
   device init                            initialise a device with balenaOS
+  device list                            list all devices
   device move <uuid(s)>                  move one or more devices to another application
   device os-update <uuid>                start a Host OS update for a device
   device public-url <uuid>               get or manage the public URL for a device