devices: Add '--json' option to help with scripting

Change-type: minor

doc/cli.markdown

@@ -693,6 +693,11 @@ list all devices that belong to you.
 
 You can filter the devices by application by using the `--application` option.
 
+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 and empty strings. The 'jq' utility
+may also be helpful in shell scripts (https://stedolan.github.io/jq/manual/).
+
 Examples:
 
 	$ balena devices
@@ -710,6 +715,10 @@ application name
 
 same as '--application'
 
+#### -j, --json
+
+produce JSON output instead of tabular output
+
 ## devices supported
 
 List the supported device types (like 'raspberrypi3' or 'intel-nuc').

lib/actions-oclif/devices/index.ts

@@ -32,6 +32,7 @@ interface FlagsDef {
 	application?: string;
 	app?: string;
 	help: void;
+	json: boolean;
 }
 
 export default class DevicesCmd extends Command {
@@ -41,6 +42,11 @@ export default class DevicesCmd extends Command {
 		list all devices that belong to you.
 
 		You can filter the devices by application by using the \`--application\` option.
+
+		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 and empty strings. The 'jq' utility
+		may also be helpful in shell scripts (https://stedolan.github.io/jq/manual/).
 	`;
 	public static examples = [
 		'$ balena devices',
@@ -55,6 +61,10 @@ export default class DevicesCmd extends Command {
 		application: cf.application,
 		app: cf.app,
 		help: cf.help,
+		json: flags.boolean({
+			char: 'j',
+			description: 'produce JSON output instead of tabular output',
+		}),
 	};
 
 	public static primary = true;
@@ -93,19 +103,29 @@ export default class DevicesCmd extends Command {
 			return device;
 		});
 
-		console.log(
-			getVisuals().table.horizontal(devices, [
-				'id',
-				'uuid',
-				'device_name',
-				'device_type',
-				'application_name',
-				'status',
-				'is_online',
-				'supervisor_version',
-				'os_version',
-				'dashboard_url',
-			]),
-		);
+		const fields = [
+			'id',
+			'uuid',
+			'device_name',
+			'device_type',
+			'application_name',
+			'status',
+			'is_online',
+			'supervisor_version',
+			'os_version',
+			'dashboard_url',
+		];
+		if (options.json) {
+			const _ = await import('lodash');
+			console.log(
+				JSON.stringify(
+					devices.map((device) => _.pick(device, fields)),
+					null,
+					4,
+				),
+			);
+		} else {
+			console.log(getVisuals().table.horizontal(devices, fields));
+		}
 	}
 }

tests/commands/device/devices.spec.ts

@@ -30,6 +30,7 @@ USAGE
 OPTIONS
   -a, --application <application>  application name
   -h, --help                       show CLI help
+  -j, --json                       produce JSON output instead of tabular output
   --app <app>                      same as '--application'
 
 DESCRIPTION
@@ -37,6 +38,11 @@ DESCRIPTION
 
   You can filter the devices by application by using the \`--application\` option.
 
+  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 and empty strings. The 'jq' utility
+  may also be helpful in shell scripts (https://stedolan.github.io/jq/manual/).
+
 EXAMPLES
   $ balena devices
   $ balena devices --application MyApp