Include join and leave commands in API documentation

Change-type: patch

capitanodoc.ts

@@ -143,6 +143,10 @@ environment variable (in the same standard URL format).\
 			title: 'Deploy',
 			files: ['build/actions/build.js', 'build/actions/deploy.js'],
 		},
+		{
+			title: 'Platform',
+			files: ['build/actions/join.js', 'build/actions/leave.js'],
+		},
 		{
 			title: 'Utilities',
 			files: ['build/actions/util.js'],

doc/cli.markdown

@@ -184,6 +184,11 @@ environment variable (in the same standard URL format).
 	- [build [source]](#build-source-)
 	- [deploy <appName> [image]](#deploy-appname-image-)
 
+- Platform
+
+	- [join [deviceIp]](#join-deviceip-)
+	- [leave [deviceIp]](#leave-deviceip-)
+
 - Utilities
 
 	- [util available-drives](#util-available-drives)
@@ -1724,6 +1729,54 @@ Don't use docker layer caching when building
 
 Squash newly built layers into a single new layer
 
+# Platform
+
+## join [deviceIp]
+
+Use this command to move a local device to an application on another balena server.
+
+For example, you could provision a device against an openBalena installation
+where you perform end-to-end tests and then move it to balenaCloud when it's
+ready for production.
+
+Moving a device between applications on the same server is not supported.
+
+If you don't specify a device hostname or IP, this command will automatically
+scan the local network for balenaOS devices and prompt you to select one
+from an interactive picker. This usually requires root privileges.
+
+Examples:
+
+	$ balena join
+	$ balena join balena.local
+	$ balena join balena.local --application MyApp
+	$ balena join 192.168.1.25
+	$ balena join 192.168.1.25 --application MyApp
+
+### Options
+
+#### --application, -a <application>
+
+The name of the application the device should join
+
+## leave [deviceIp]
+
+Use this command to make a local device leave the balena server it is
+provisioned on. This effectively makes the device "unmanaged".
+
+The device entry on the server is preserved after running this command,
+so the device can subsequently re-join the server if needed.
+
+If you don't specify a device hostname or IP, this command will automatically
+scan the local network for balenaOS devices and prompt you to select one
+from an interactive picker. This usually requires root privileges.
+
+Examples:
+
+	$ balena leave
+	$ balena leave balena.local
+	$ balena leave 192.168.1.25
+
 # Utilities
 
 ## util available-drives

lib/actions/join.ts

@@ -28,8 +28,20 @@ interface Options {
 export const join: CommandDefinition<Args, Options> = {
 	signature: 'join [deviceIp]',
 	description:
-		'Promote a local device running unmanaged balenaOS to join a balena application',
+		'Promote a local device running balenaOS to join an application on a balena server',
 	help: stripIndent`
+		Use this command to move a local device to an application on another balena server.
+
+		For example, you could provision a device against an openBalena installation
+		where you perform end-to-end tests and then move it to balenaCloud when it's
+		ready for production.
+
+		Moving a device between applications on the same server is not supported.
+
+		If you don't specify a device hostname or IP, this command will automatically
+		scan the local network for balenaOS devices and prompt you to select one
+		from an interactive picker. This usually requires root privileges.
+
 		Examples:
 
 			$ balena join

lib/actions/leave.ts

@@ -25,6 +25,16 @@ export const leave: CommandDefinition<Args, {}> = {
 	signature: 'leave [deviceIp]',
 	description: 'Detach a local device from its balena application',
 	help: stripIndent`
+		Use this command to make a local device leave the balena server it is
+		provisioned on. This effectively makes the device "unmanaged".
+
+		The device entry on the server is preserved after running this command,
+		so the device can subsequently re-join the server if needed.
+
+		If you don't specify a device hostname or IP, this command will automatically
+		scan the local network for balenaOS devices and prompt you to select one
+		from an interactive picker. This usually requires root privileges.
+
 		Examples:
 
 			$ balena leave