Merge pull request #1106 from doronz88/refactor/documentation

cli: refactor command group usages to provide a TL;DR

README.md

@@ -139,37 +139,41 @@ subcommand. This also means that every feature which isn't there won't require i
 This is the main CLI usage:
 
 ```
-Usage: python -m pymobiledevice3 [OPTIONS] COMMAND [ARGS]...
+Usage: pymobiledevice3 [OPTIONS] COMMAND [ARGS]...
+
+ Interact with a connected iDevice (iPhone, iPad, ...)
+ For more information please look at:
+ https://github.com/doronz88/pymobiledevice3
 
 Options:
  -h, --help Show this message and exit.
 
 Commands:
- activation activation options
- afc FileSystem utils
- amfi amfi options
- apps application options
- backup2 backup utils
- bonjour bonjour options
- companion companion options
- crash crash report options
- developer developer options.
- diagnostics diagnostics options
- lockdown lockdown options
- mounter mounter options
- notification notification options
- pcap sniff device traffic
- power-assertion Create a power assertion (wraps...
- processes processes cli
- profile profile options
- provision provision options
- remote remote options
- restore restore options
- springboard springboard options
- syslog syslog options
- usbmux usbmuxd options
- webinspector webinspector options
- version get installed package version
+ activation Perform iCloud activate/deactivation or query the state
+ afc Manage device multimedia files
+ amfi Enable/Disable developer-mode or query its state
+ apps Manage installed applications
+ backup2 Backup/Restore options
+ bonjour Browse devices over bonjour
+ companion List paired "companion" devices
+ crash Manage crash reports
+ developer Perform developer operations
+ diagnostics Reboot/Shutdown device or diagnostics services
+ lockdown Pair/Unpair device or access other lockdown services
+ mounter Mount/Umount DeveloperDiskImage or query related info
+ notification Post/Observe notifications
+ pcap Sniff device traffic
+ power-assertion Create a power assertion
+ processes View process list using diagnosticsd API
+ profile Managed installed profiles or install SSL certificates
+ provision Manage installed provision profiles
+ remote Create RemoteXPC tunnels
+ restore Restore an IPSW or access device in recovery mode
+ springboard Access device UI
+ syslog Watch syslog messages
+ usbmux List devices or forward a TCP port
+ webinspector Access webinspector services
+ version Query pymobiledevice3 version
 ```
 
 ### Working with developer tools (iOS >= 17.0)

pymobiledevice3/__main__.py

@@ -92,6 +92,12 @@ def get_command(self, ctx, name):
 
 @click.command(cls=Pmd3Cli, context_settings=CONTEXT_SETTINGS)
 def cli():
+ """
+ \b
+ Interact with a connected iDevice (iPhone, iPad, ...)
+ For more information please look at:
+ https://github.com/doronz88/pymobiledevice3
+ """
  pass
 
 

pymobiledevice3/cli/activation.py

@@ -6,14 +6,13 @@
 
 
 @click.group()
-def cli():
- """ cli """
+def cli() -> None:
  pass
 
 
 @cli.group()
-def activation():
- """ activation options """
+def activation() -> None:
+ """ Perform iCloud activate/deactivation or query the state """
  pass
 
 

pymobiledevice3/cli/afc.py

@@ -7,14 +7,13 @@
 
 
 @click.group()
-def cli():
- """ apps cli """
+def cli() -> None:
  pass
 
 
 @cli.group()
-def afc():
- """ FileSystem utils """
+def afc() -> None:
+ """ Manage device multimedia files """
  pass
 
 

pymobiledevice3/cli/amfi.py

@@ -10,14 +10,13 @@
 
 
 @click.group()
-def cli():
- """ amfi cli """
+def cli() -> None:
  pass
 
 
 @cli.group()
-def amfi():
- """ amfi options """
+def amfi() -> None:
+ """ Enable/Disable developer-mode or query its state """
  pass
 
 

pymobiledevice3/cli/apps.py

@@ -10,14 +10,13 @@
 
 
 @click.group()
-def cli():
- """ apps cli """
+def cli() -> None:
  pass
 
 
 @cli.group()
-def apps():
- """ application options """
+def apps() -> None:
+ """ Manage installed applications """
  pass
 
 

pymobiledevice3/cli/backup.py

@@ -17,14 +17,13 @@
 
 
 @click.group()
-def cli():
- """ backup cli """
+def cli() -> None:
  pass
 
 
 @cli.group()
-def backup2():
- """ backup utils """
+def backup2() -> None:
+ """ Backup/Restore options """
  pass
 
 

pymobiledevice3/cli/bonjour.py

@@ -11,14 +11,13 @@
 
 
 @click.group()
-def cli():
- """ bonjour cli """
+def cli() -> None:
  pass
 
 
 @cli.group('bonjour')
-def bonjour_cli():
- """ bonjour options """
+def bonjour_cli() -> None:
+ """ Browse devices over bonjour """
  pass
 
 

pymobiledevice3/cli/companion_proxy.py

@@ -6,14 +6,13 @@
 
 
 @click.group()
-def cli():
- """ companion cli """
+def cli() -> None:
  pass
 
 
 @cli.group()
-def companion():
- """ companion options """
+def companion() -> None:
+ """ List paired "companion" devices """
  pass
 
 

pymobiledevice3/cli/crash.py

@@ -6,14 +6,13 @@
 
 
 @click.group()
-def cli():
- """ crash cli """
+def cli() -> None:
  pass
 
 
 @cli.group()
-def crash():
- """ crash report options """
+def crash() -> None:
+ """ Manage crash reports """
  pass
 
 

pymobiledevice3/cli/developer.py

@@ -21,8 +21,8 @@
 import pymobiledevice3
 from pymobiledevice3.cli.cli_common import BASED_INT, Command, RSDCommand, default_json_encoder, print_json, \
  user_requested_colored_output
-from pymobiledevice3.exceptions import ArgumentError, DeviceAlreadyInUseError, DvtDirListError, \
- ExtractingStackshotError, RSDRequiredError, UnrecognizedSelectorError
+from pymobiledevice3.exceptions import DeviceAlreadyInUseError, DvtDirListError, ExtractingStackshotError, \
+ RSDRequiredError, UnrecognizedSelectorError
 from pymobiledevice3.lockdown import LockdownClient
 from pymobiledevice3.lockdown_service_provider import LockdownServiceProvider
 from pymobiledevice3.osu.os_utils import get_os_utils
@@ -76,15 +76,14 @@
 
 
 @click.group()
-def cli():
- """ developer cli """
+def cli() -> None:
  pass
 
 
 @cli.group()
-def developer():
+def developer() -> None:
  """
- developer options.
+ Perform developer operations
 
  These options require the DeveloperDiskImage.dmg to be mounted on the device prior
  to execution. You can achieve this using:
@@ -102,20 +101,20 @@ def developer():
 @click.argument('service')
 @click.option('-r', '--remove-ssl-context', is_flag=True)
 def developer_shell(service_provider: LockdownClient, service, remove_ssl_context):
- """ Launch developer shell. """
+ """ Launch developer IPython shell """
  with RemoteServer(service_provider, service, remove_ssl_context) as service:
  service.shell()
 
 
 @developer.group()
-def dvt():
- """ dvt operations """
+def dvt() -> None:
+ """ Access advanced instrumentation APIs """
  pass
 
 
 @dvt.command('proclist', cls=Command)
 def proclist(service_provider: LockdownClient):
- """ show process list """
+ """ Show process list """
  with DvtSecureSocketProxyService(lockdown=service_provider) as dvt:
  processes = DeviceInfo(dvt).proclist()
  for process in processes:
@@ -127,7 +126,7 @@ def proclist(service_provider: LockdownClient):
 
 @dvt.command('applist', cls=Command)
 def applist(service_provider: LockdownServiceProvider) -> None:
- """ show application list """
+ """ Show application list """
  with DvtSecureSocketProxyService(lockdown=service_provider) as dvt:
  apps = ApplicationListing(dvt).applist()
  print_json(apps)

pymobiledevice3/cli/diagnostics.py

@@ -11,38 +11,37 @@
 
 
 @click.group()
-def cli():
- """ apps cli """
+def cli() -> None:
  pass
 
 
 @cli.group()
-def diagnostics():
- """ diagnostics options """
+def diagnostics() -> None:
+ """ Reboot/Shutdown device or diagnostics services """
  pass
 
 
 @diagnostics.command('restart', cls=Command)
 def diagnostics_restart(service_provider: LockdownClient):
- """ restart device """
+ """ Restart device """
  DiagnosticsService(lockdown=service_provider).restart()
 
 
 @diagnostics.command('shutdown', cls=Command)
 def diagnostics_shutdown(service_provider: LockdownClient):
- """ shutdown device """
+ """ Shutdown device """
  DiagnosticsService(lockdown=service_provider).shutdown()
 
 
 @diagnostics.command('sleep', cls=Command)
 def diagnostics_sleep(service_provider: LockdownClient):
- """ put device into sleep """
+ """ Put device into sleep """
  DiagnosticsService(lockdown=service_provider).sleep()
 
 
 @diagnostics.command('info', cls=Command)
 def diagnostics_info(service_provider: LockdownClient):
- """ get diagnostics info """
+ """ Get diagnostics info """
  print_json(DiagnosticsService(lockdown=service_provider).info())
 
 
@@ -51,20 +50,20 @@ def diagnostics_info(service_provider: LockdownClient):
 @click.option('--name')
 @click.option('--ioclass')
 def diagnostics_ioregistry(service_provider: LockdownClient, plane, name, ioclass):
- """ get ioregistry info """
+ """ Get ioregistry info """
  print_json(DiagnosticsService(lockdown=service_provider).ioregistry(plane=plane, name=name, ioclass=ioclass))
 
 
 @diagnostics.command('mg', cls=Command)
 @click.argument('keys', nargs=-1, default=None)
 def diagnostics_mg(service_provider: LockdownClient, keys):
- """ get MobileGestalt key values from given list. If empty, return all known. """
+ """ Get MobileGestalt key values from given list. If empty, return all known. """
  print_json(DiagnosticsService(lockdown=service_provider).mobilegestalt(keys=keys))
 
 
 @diagnostics.group('battery')
 def diagnostics_battery():
- """ battery options """
+ """ Battery options """
  pass
 
 

pymobiledevice3/cli/lockdown.py

@@ -16,14 +16,13 @@
 
 
 @click.group()
-def cli():
- """ apps cli """
+def cli() -> None:
  pass
 
 
 @cli.group('lockdown')
-def lockdown_group():
- """ lockdown options """
+def lockdown_group() -> None:
+ """ Pair/Unpair device or access other lockdown services """
  pass
 
 

pymobiledevice3/cli/mounter.py

@@ -30,14 +30,13 @@ def catch_function(*args, **kwargs):
 
 
 @click.group()
-def cli():
- """ mounter cli """
+def cli() -> None:
  pass
 
 
 @cli.group()
-def mounter():
- """ mounter options """
+def mounter() -> None:
+ """ Mount/Umount DeveloperDiskImage or query related info """
  pass