Add command app purge

Change-type: minor
Signed-off-by: Scott Lowe <scott@balena.io>

automation/capitanodoc/capitanodoc.ts

@@ -39,9 +39,10 @@ const capitanoDoc = {
 				'build/commands/apps.js',
 				'build/commands/app/index.js',
 				'build/commands/app/create.js',
-				'build/commands/app/rm.js',
+				'build/commands/app/purge.js',
 				'build/commands/app/rename.js',
 				'build/commands/app/restart.js',
+				'build/commands/app/rm.js',
 			],
 		},
 		{

doc/cli.markdown

@@ -162,9 +162,10 @@ Users are encouraged to regularly update the balena CLI to the latest version.
 	- [apps](#apps)
 	- [app <name>](#app-name)
 	- [app create <name>](#app-create-name)
-	- [app rm <name>](#app-rm-name)
+	- [app purge <name>](#app-purge-name)
 	- [app rename <name> [newname]](#app-rename-name-newname)
 	- [app restart <name>](#app-restart-name)
+	- [app rm <name>](#app-rm-name)
 
 - Authentication
 
@@ -365,16 +366,14 @@ application name
 
 application device type (Check available types with `balena devices supported`)
 
-## app rm <name>
+## app purge <name>
 
-Permanently remove a balena application.
-
-The --yes option may be used to avoid interactive confirmation.
+Purge data from all devices belonging to an application.
+This will clear the application's /data directory.
 
 Examples:
 
-	$ balena app rm MyApp
-	$ balena app rm MyApp --yes
+	$ balena app purge MyApp
 
 ### Arguments
 
@@ -384,10 +383,6 @@ application name or numeric ID
 
 ### Options
 
-#### -y, --yes
-
-answer "yes" to all questions (non interactive use)
-
 ## app rename <name> [newName]
 
 Rename an application.
@@ -414,7 +409,7 @@ the new name for the application
 
 ## app restart <name>
 
-Restart all devices that belongs to a certain application.
+Restart all devices belonging to an application.
 
 Examples:
 
@@ -428,6 +423,29 @@ application name or numeric ID
 
 ### Options
 
+## app rm <name>
+
+Permanently remove a balena application.
+
+The --yes option may be used to avoid interactive confirmation.
+
+Examples:
+
+	$ balena app rm MyApp
+	$ balena app rm MyApp --yes
+
+### Arguments
+
+#### NAME
+
+application name or numeric ID
+
+### Options
+
+#### -y, --yes
+
+answer "yes" to all questions (non interactive use)
+
 # Authentication
 
 ## login

lib/commands/app/purge.ts

@@ -0,0 +1,82 @@
+/**
+ * @license
+ * Copyright 2016-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 { flags } from '@oclif/command';
+import Command from '../../command';
+import * as cf from '../../utils/common-flags';
+import { getBalenaSdk, stripIndent } from '../../utils/lazy';
+import { tryAsInteger } from '../../utils/validation';
+
+interface FlagsDef {
+	help: void;
+}
+
+interface ArgsDef {
+	name: string;
+}
+
+export default class AppRestartCmd extends Command {
+	public static description = stripIndent`
+		Purge data from an application.
+
+		Purge data from all devices belonging to an application.
+		This will clear the application's /data directory.
+`;
+	public static examples = ['$ balena app purge MyApp'];
+
+	public static args = [
+		{
+			name: 'name',
+			description: 'application name or numeric ID',
+			required: true,
+		},
+	];
+
+	public static usage = 'app purge <name>';
+
+	public static flags: flags.Input<FlagsDef> = {
+		help: cf.help,
+	};
+
+	public static authenticated = true;
+
+	public async run() {
+		const { args: params } = this.parse<FlagsDef, ArgsDef>(AppRestartCmd);
+
+		const balena = getBalenaSdk();
+
+		// balena.models.application.purge only accepts a numeric id
+		// so we must first fetch the app to get it's id, if we have been given a name
+		let nameOrId = tryAsInteger(params.name);
+
+		if (typeof nameOrId === 'string') {
+			const app = await balena.models.application.get(nameOrId);
+			nameOrId = app.id;
+		}
+
+		try {
+			await balena.models.application.purge(nameOrId);
+		} catch (e) {
+			if (e.message.toLowerCase().includes('no online device(s) found')) {
+				// application.purge throws an error if no devices are online
+				// ignore in this case.
+			} else {
+				throw e;
+			}
+		}
+	}
+}

lib/commands/app/restart.ts

@@ -33,7 +33,7 @@ export default class AppRestartCmd extends Command {
 	public static description = stripIndent`
 		Restart an application.
 
-		Restart all devices that belongs to a certain application.
+		Restart all devices belonging to an application.
 `;
 	public static examples = ['$ balena app restart MyApp'];