device: Add --json option for JSON output

change-type: minor

docs/balena-cli.md

@@ -1261,10 +1261,17 @@ the uuid of the device to identify
 
 Show information about a single device.
 
+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 7cf02a6
 	$ balena device 7cf02a6 --view
+	$ balena device 7cf02a6 --json
 
 ### Arguments
 
@@ -1274,6 +1281,10 @@ the device uuid
 
 ### Options
 
+#### -j, --json
+
+produce JSON output instead of tabular output
+
 #### --view
 
 open device dashboard page

lib/commands/device/index.ts

@@ -20,6 +20,7 @@ import Command from '../../command';
 import * as cf from '../../utils/common-flags';
 import { expandForAppName } from '../../utils/helpers';
 import { getBalenaSdk, getVisuals, stripIndent } from '../../utils/lazy';
+import { jsonInfo } from '../../utils/messages';
 
 import type { Application, Release } from 'balena-sdk';
 
@@ -45,10 +46,13 @@ export default class DeviceCmd extends Command {
 		Show info about a single device.
 
 		Show information about a single device.
+
+		${jsonInfo.split('\n').join('\n\t\t')}
 		`;
 	public static examples = [
 		'$ balena device 7cf02a6',
 		'$ balena device 7cf02a6 --view',
+		'$ balena device 7cf02a6 --json',
 	];
 
 	public static args = {
@@ -61,6 +65,7 @@ export default class DeviceCmd extends Command {
 	public static usage = 'device <uuid>';
 
 	public static flags = {
+		json: cf.json,
 		help: cf.help,
 		view: Flags.boolean({
 			default: false,
@@ -76,33 +81,45 @@ export default class DeviceCmd extends Command {
 
 		const balena = getBalenaSdk();
 
-		const device = (await balena.models.device.get(params.uuid, {
+		const device = (await balena.models.device.get(
-			$select: [
+			params.uuid,
-				'device_name',
+			options.json
-				'id',
+				? {
-				'overall_status',
+						$expand: {
-				'is_online',
+							device_tag: {
-				'ip_address',
+								$select: ['tag_key', 'value'],
-				'mac_address',
+							},
-				'last_connectivity_event',
+							...expandForAppName.$expand,
-				'uuid',
+						},
-				'supervisor_version',
+				  }
-				'is_web_accessible',
+				: {
-				'note',
+						$select: [
-				'os_version',
+							'device_name',
-				'memory_usage',
+							'id',
-				'memory_total',
+							'overall_status',
-				'public_address',
+							'is_online',
-				'storage_block_device',
+							'ip_address',
-				'storage_usage',
+							'mac_address',
-				'storage_total',
+							'last_connectivity_event',
-				'cpu_usage',
+							'uuid',
-				'cpu_temp',
+							'supervisor_version',
-				'cpu_id',
+							'is_web_accessible',
-				'is_undervolted',
+							'note',
-			],
+							'os_version',
-			...expandForAppName,
+							'memory_usage',
-		})) as ExtendedDevice;
+							'memory_total',
+							'public_address',
+							'storage_block_device',
+							'storage_usage',
+							'storage_total',
+							'cpu_usage',
+							'cpu_temp',
+							'cpu_id',
+							'is_undervolted',
+						],
+						...expandForAppName,
+				  },
+		)) as ExtendedDevice;
 
 		if (options.view) {
 			const open = await import('open');
@@ -166,6 +183,11 @@ export default class DeviceCmd extends Command {
 			);
 		}
 
+		if (options.json) {
+			console.log(JSON.stringify(device, null, 4));
+			return;
+		}
+
 		console.log(
 			getVisuals().table.vertical(device, [
 				`$${device.device_name}$`,

tests/commands/device/device.spec.ts

@@ -107,4 +107,19 @@ describe('balena device', function () {
 		expect(lines[0]).to.equal('== SPARKLING WOOD');
 		expect(lines[6].split(':')[1].trim()).to.equal('N/a');
 	});
+
+	it('outputs device as JSON with the -j/--json flag', async () => {
+		api.scope
+			.get(/^\/v6\/device\?.+&\$expand=device_tag\(\$select=tag_key,value\)/)
+			.replyWithFile(200, path.join(apiResponsePath, 'device.json'), {
+				'Content-Type': 'application/json',
+			});
+
+		const { out, err } = await runCommand('device 27fda508c --json');
+		expect(err).to.be.empty;
+		const json = JSON.parse(out.join(''));
+		expect(json.device_name).to.equal('sparkling-wood');
+		expect(json.belongs_to__application[0].app_name).to.equal('test app');
+		expect(json.device_tag[0].tag_key).to.equal('example');
+	});
 });

tests/test-data/api-response/device.json

@@ -8,6 +8,12 @@
 					"__metadata": {}
 				}
 			],
+			"device_tag": [
+				{
+					"tag_key": "example",
+					"value": "true"
+				}
+			],
 			"id": 1747415,
 			"is_managed_by__device": null,
 			"device_name": "sparkling-wood",