diff --git a/capitanodoc.ts b/capitanodoc.ts
index 8a138c9f..5388394b 100644
--- a/capitanodoc.ts
+++ b/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'],
diff --git a/doc/cli.markdown b/doc/cli.markdown
index 5479f9e8..fed3ec5e 100644
--- a/doc/cli.markdown
+++ b/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
diff --git a/lib/actions/join.ts b/lib/actions/join.ts
index 166aa74b..6d26198d 100644
--- a/lib/actions/join.ts
+++ b/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
diff --git a/lib/actions/leave.ts b/lib/actions/leave.ts
index e2d29f84..fd75d656 100644
--- a/lib/actions/leave.ts
+++ b/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