From 62dfae371c31b1267d5f517226f5f117d5a6986e Mon Sep 17 00:00:00 2001
From: Paulo Castro <paulo@balena.io>
Date: Fri, 7 Aug 2020 15:08:20 +0100
Subject: [PATCH] devices: Add '--json' option to help with scripting

Change-type: minor
---
 doc/cli.markdown                      |  9 +++++
 lib/actions-oclif/devices/index.ts    | 48 +++++++++++++++++++--------
 tests/commands/device/devices.spec.ts |  6 ++++
 3 files changed, 49 insertions(+), 14 deletions(-)

diff --git a/doc/cli.markdown b/doc/cli.markdown
index ffd9ae10..a2baebbc 100644
--- a/doc/cli.markdown
+++ b/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').
diff --git a/lib/actions-oclif/devices/index.ts b/lib/actions-oclif/devices/index.ts
index 0e0fe2dc..8502ded7 100644
--- a/lib/actions-oclif/devices/index.ts
+++ b/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));
+		}
 	}
 }
diff --git a/tests/commands/device/devices.spec.ts b/tests/commands/device/devices.spec.ts
index 73ea39d0..c8627a17 100644
--- a/tests/commands/device/devices.spec.ts
+++ b/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