pymobiledevice3 5.0.0__py3-none-any.whl → 5.0.2__py3-none-any.whl

pymobiledevice3/cli/backup.py

@@ -8,11 +8,12 @@ from pymobiledevice3.lockdown import LockdownClient
 from pymobiledevice3.lockdown_service_provider import LockdownServiceProvider
 from pymobiledevice3.services.mobilebackup2 import Mobilebackup2Service
 
-source_option = click.option('--source', default='', help='The UDID of the source device.')
-password_option = click.option('-p', '--password', default='', help='Backup password.')
-backup_directory_arg = click.argument('backup-directory', type=click.Path(exists=True, file_okay=False))
-backup_directory_option = click.option('-b', '--backup-directory', type=click.Path(exists=True, file_okay=False),
-                                       default='.')
+source_option = click.option("--source", default="", help="The UDID of the source device.")
+password_option = click.option("-p", "--password", default="", help="Backup password.")
+backup_directory_arg = click.argument("backup-directory", type=click.Path(exists=True, file_okay=False))
+backup_directory_option = click.option(
+    "-b", "--backup-directory", type=click.Path(exists=True, file_okay=False), default="."
+)
 
 logger = logging.getLogger(__name__)
 
@@ -24,14 +25,17 @@ def cli() -> None:
 
 @cli.group()
 def backup2() -> None:
-    """ Backup/Restore options """
+    """Backup/Restore options"""
     pass
 
 
 @backup2.command(cls=Command)
-@click.argument('backup-directory', type=click.Path(file_okay=False))
-@click.option('--full', is_flag=True, help=('Whether to do a full backup.'
-                                            ' If full is True, any previous backup attempts will be discarded.'))
+@click.argument("backup-directory", type=click.Path(file_okay=False))
+@click.option(
+    "--full",
+    is_flag=True,
+    help=("Whether to do a full backup. If full is True, any previous backup attempts will be discarded."),
+)
 def backup(service_provider: LockdownServiceProvider, backup_directory: str, full: bool) -> None:
     """
     Backup device.
@@ -40,6 +44,7 @@ def backup(service_provider: LockdownServiceProvider, backup_directory: str, ful
     """
     backup_client = Mobilebackup2Service(service_provider)
     with tqdm(total=100, dynamic_ncols=True) as pbar:
+
         def update_bar(percentage):
             pbar.n = percentage
             pbar.refresh()
@@ -49,16 +54,26 @@ def backup(service_provider: LockdownServiceProvider, backup_directory: str, ful
 
 @backup2.command(cls=Command)
 @backup_directory_arg
-@click.option('--system/--no-system', default=False, help='Restore system files.')
-@click.option('--reboot/--no-reboot', default=True, help='Reboot the device when done.')
-@click.option('--copy/--no-copy', default=False, help='Create a copy of backup folder before restoring.')
-@click.option('--settings/--no-settings', default=True, help='Restore device settings.')
-@click.option('--remove/--no-remove', default=False, help='Remove items which aren\'t being restored.')
-@click.option('--skip-apps', is_flag=True, help='Do not trigger re-installation of apps after restore')
+@click.option("--system/--no-system", default=False, help="Restore system files.")
+@click.option("--reboot/--no-reboot", default=True, help="Reboot the device when done.")
+@click.option("--copy/--no-copy", default=False, help="Create a copy of backup folder before restoring.")
+@click.option("--settings/--no-settings", default=True, help="Restore device settings.")
+@click.option("--remove/--no-remove", default=False, help="Remove items which aren't being restored.")
+@click.option("--skip-apps", is_flag=True, help="Do not trigger re-installation of apps after restore")
 @password_option
 @source_option
-def restore(service_provider: LockdownServiceProvider, backup_directory: str, system: bool, reboot: bool, copy: bool,
-            settings: bool, remove: bool, skip_apps: bool, password: str, source: str) -> None:
+def restore(
+    service_provider: LockdownServiceProvider,
+    backup_directory: str,
+    system: bool,
+    reboot: bool,
+    copy: bool,
+    settings: bool,
+    remove: bool,
+    skip_apps: bool,
+    password: str,
+    source: str,
+) -> None:
     """
     Restore a backup to a device.
 
@@ -66,13 +81,23 @@ def restore(service_provider: LockdownServiceProvider, backup_directory: str, sy
     """
     backup_client = Mobilebackup2Service(service_provider)
     with tqdm(total=100, dynamic_ncols=True) as pbar:
+
         def update_bar(percentage):
             pbar.n = percentage
             pbar.refresh()
 
-        backup_client.restore(backup_directory=backup_directory, progress_callback=update_bar, system=system,
-                              reboot=reboot, copy=copy, settings=settings, remove=remove, password=password,
-                              source=source, skip_apps=skip_apps)
+        backup_client.restore(
+            backup_directory=backup_directory,
+            progress_callback=update_bar,
+            system=system,
+            reboot=reboot,
+            copy=copy,
+            settings=settings,
+            remove=remove,
+            password=password,
+            source=source,
+            skip_apps=skip_apps,
+        )
 
 
 @backup2.command(cls=Command)
@@ -86,7 +111,7 @@ def info(service_provider: LockdownClient, backup_directory, source):
     print(backup_client.info(backup_directory=backup_directory, source=source))
 
 
-@backup2.command('list', cls=Command)
+@backup2.command("list", cls=Command)
 @backup_directory_arg
 @source_option
 def list_(service_provider: LockdownClient, backup_directory, source):
@@ -110,8 +135,8 @@ def unback(service_provider: LockdownClient, backup_directory, password, source)
 
 
 @backup2.command(cls=Command)
-@click.argument('domain-name')
-@click.argument('relative-path')
+@click.argument("domain-name")
+@click.argument("relative-path")
 @backup_directory_arg
 @password_option
 @source_option
@@ -123,13 +148,14 @@ def extract(service_provider: LockdownClient, domain_name, relative_path, backup
     will be extracted to the BACKUP_DIRECTORY.
     """
     backup_client = Mobilebackup2Service(service_provider)
-    backup_client.extract(domain_name, relative_path, backup_directory=backup_directory, password=password,
-                          source=source)
+    backup_client.extract(
+        domain_name, relative_path, backup_directory=backup_directory, password=password, source=source
+    )
 
 
 @backup2.command(cls=Command)
-@click.argument('mode', type=click.Choice(['on', 'off'], case_sensitive=False))
-@click.argument('password')
+@click.argument("mode", type=click.Choice(["on", "off"], case_sensitive=False))
+@click.argument("password")
 @backup_directory_option
 def encryption(service_provider: LockdownClient, backup_directory, mode, password):
     """
@@ -139,9 +165,9 @@ def encryption(service_provider: LockdownClient, backup_directory, mode, passwor
     When off, PASSWORD is the current backup password.
     """
     backup_client = Mobilebackup2Service(service_provider)
-    should_encrypt = mode.lower() == 'on'
+    should_encrypt = mode.lower() == "on"
     if should_encrypt == backup_client.will_encrypt:
-        logger.error('Encryption already ' + ('on!' if should_encrypt else 'off!'))
+        logger.error("Encryption already " + ("on!" if should_encrypt else "off!"))
         return
     if should_encrypt:
         backup_client.change_password(backup_directory, new=password)
@@ -150,8 +176,8 @@ def encryption(service_provider: LockdownClient, backup_directory, mode, passwor
 
 
 @backup2.command(cls=Command)
-@click.argument('old-password')
-@click.argument('new-password')
+@click.argument("old-password")
+@click.argument("new-password")
 @backup_directory_option
 def change_password(service_provider: LockdownClient, old_password, new_password, backup_directory):
     """
@@ -159,7 +185,7 @@ def change_password(service_provider: LockdownClient, old_password, new_password
     """
     backup_client = Mobilebackup2Service(service_provider)
     if not backup_client.will_encrypt:
-        logger.error('Encryption is not turned on!')
+        logger.error("Encryption is not turned on!")
         return
     backup_client.change_password(backup_directory, old=old_password, new=new_password)
 

pymobiledevice3/cli/bonjour.py

@@ -14,9 +14,9 @@ def cli() -> None:
     pass
 
 
-@cli.group('bonjour')
+@cli.group("bonjour")
 def bonjour_cli() -> None:
-    """ Browse devices over bonjour """
+    """Browse devices over bonjour"""
     pass
 
 
@@ -24,17 +24,20 @@ async def cli_mobdev2_task(timeout: float, pair_records: Optional[str]) -> None:
     output = []
     async for ip, lockdown in get_mobdev2_lockdowns(timeout=timeout, pair_records=pair_records):
         short_info = lockdown.short_info
-        short_info['ip'] = ip
+        short_info["ip"] = ip
         output.append(short_info)
     print_json(output)
 
 
-@bonjour_cli.command('mobdev2', cls=BaseCommand)
-@click.option('--timeout', default=DEFAULT_BONJOUR_TIMEOUT, type=click.INT)
-@click.option('--pair-records', type=click.Path(dir_okay=True, file_okay=False, exists=True),
-              help='pair records to attempt validation with')
+@bonjour_cli.command("mobdev2", cls=BaseCommand)
+@click.option("--timeout", default=DEFAULT_BONJOUR_TIMEOUT, type=click.INT)
+@click.option(
+    "--pair-records",
+    type=click.Path(dir_okay=True, file_okay=False, exists=True),
+    help="pair records to attempt validation with",
+)
 def cli_mobdev2(timeout: float, pair_records: Optional[str]) -> None:
-    """ browse for mobdev2 devices over bonjour """
+    """browse for mobdev2 devices over bonjour"""
     asyncio.run(cli_mobdev2_task(timeout, pair_records))
 
 
@@ -42,14 +45,14 @@ async def cli_remotepairing_task(timeout: float) -> None:
     output = []
     for answer in await browse_remotepairing(timeout=timeout):
         for address in answer.addresses:
-            output.append({'hostname': address.full_ip, 'port': answer.port})
+            output.append({"hostname": address.full_ip, "port": answer.port})
     print_json(output)
 
 
-@bonjour_cli.command('remotepairing', cls=BaseCommand)
-@click.option('--timeout', default=DEFAULT_BONJOUR_TIMEOUT, type=click.FLOAT)
+@bonjour_cli.command("remotepairing", cls=BaseCommand)
+@click.option("--timeout", default=DEFAULT_BONJOUR_TIMEOUT, type=click.FLOAT)
 def cli_remotepairing(timeout: float) -> None:
-    """ browse for remotepairing devices over bonjour (without attempting pair verification) """
+    """browse for remotepairing devices over bonjour (without attempting pair verification)"""
     asyncio.run(cli_remotepairing_task(timeout=timeout))
 
 
@@ -57,14 +60,18 @@ async def cli_remotepairing_manual_pairing_task(timeout: float) -> None:
     output = []
     for answer in await browse_remotepairing_manual_pairing(timeout=timeout):
         for address in answer.addresses:
-            output.append({'hostname': address.full_ip, 'port': answer.port, 'name': answer.properties[b'name'].decode()})
+            output.append({
+                "hostname": address.full_ip,
+                "port": answer.port,
+                "name": answer.properties[b"name"].decode(),
+            })
     print_json(output)
 
 
-@bonjour_cli.command('remotepairing-manual-pairing', cls=BaseCommand)
-@click.option('--timeout', default=DEFAULT_BONJOUR_TIMEOUT, type=click.FLOAT)
+@bonjour_cli.command("remotepairing-manual-pairing", cls=BaseCommand)
+@click.option("--timeout", default=DEFAULT_BONJOUR_TIMEOUT, type=click.FLOAT)
 def cli_remotepairing_manual_pairing(timeout: float) -> None:
-    """ browse for remotepairing-manual-pairing devices over bonjour """
+    """browse for remotepairing-manual-pairing devices over bonjour"""
     asyncio.run(cli_remotepairing_manual_pairing_task(timeout=timeout))
 
 
@@ -72,7 +79,7 @@ async def cli_browse_rsd() -> None:
     print_json(await browse_rsd())
 
 
-@bonjour_cli.command('rsd', cls=BaseCommand)
+@bonjour_cli.command("rsd", cls=BaseCommand)
 def cli_rsd() -> None:
-    """ browse RemoteXPC devices using bonjour """
+    """browse RemoteXPC devices using bonjour"""
     asyncio.run(cli_browse_rsd(), debug=True)

pymobiledevice3/cli/cli_common.py

@@ -24,51 +24,50 @@ from pymobiledevice3.tunneld.api import TUNNELD_DEFAULT_ADDRESS, async_get_tunne
 from pymobiledevice3.usbmux import select_devices_by_connection_type
 
 COLORED_OUTPUT = True
-UDID_ENV_VAR = 'PYMOBILEDEVICE3_UDID'
-TUNNEL_ENV_VAR = 'PYMOBILEDEVICE3_TUNNEL'
-USBMUX_ENV_VAR = 'PYMOBILEDEVICE3_USBMUX'
+UDID_ENV_VAR = "PYMOBILEDEVICE3_UDID"
+TUNNEL_ENV_VAR = "PYMOBILEDEVICE3_TUNNEL"
+USBMUX_ENV_VAR = "PYMOBILEDEVICE3_USBMUX"
 OSUTILS = get_os_utils()
 
-USBMUX_OPTION_HELP = (f'usbmuxd listener address (in the form of either /path/to/unix/socket OR HOST:PORT). '
-                      f'Can be specified via {USBMUX_ENV_VAR} envvar')
+USBMUX_OPTION_HELP = (
+    f"usbmuxd listener address (in the form of either /path/to/unix/socket OR HOST:PORT). "
+    f"Can be specified via {USBMUX_ENV_VAR} envvar"
+)
 
 
 class RSDOption(Option):
     def __init__(self, *args, **kwargs):
-        self.mutually_exclusive = set(kwargs.pop('mutually_exclusive', []))
-        help = kwargs.get('help', '')
+        self.mutually_exclusive = set(kwargs.pop("mutually_exclusive", []))
+        help_option = kwargs.get("help", "")
         if self.mutually_exclusive:
-            ex_str = ', '.join(self.mutually_exclusive)
-            kwargs['help'] = help + (
-                    '\nNOTE: This argument is mutually exclusive with '
-                    ' arguments: [' + ex_str + '].'
+            ex_str = ", ".join(self.mutually_exclusive)
+            kwargs["help"] = help_option + (
+                "\nNOTE: This argument is mutually exclusive with  arguments: [" + ex_str + "]."
             )
         super().__init__(*args, **kwargs)
 
     def handle_parse_result(self, ctx, opts, args):
-        if (isinstance(ctx.command, RSDCommand) and not (isinstance(ctx.command, Command)) and
-                ('rsd_service_provider_using_tunneld' not in opts) and ('rsd_service_provider_manually' not in opts)):
+        if (
+            isinstance(ctx.command, RSDCommand)
+            and not (isinstance(ctx.command, Command))
+            and ("rsd_service_provider_using_tunneld" not in opts)
+            and ("rsd_service_provider_manually" not in opts)
+        ):
             # defaulting to `--tunnel ''` if no remote option was specified
-            opts['rsd_service_provider_using_tunneld'] = ''
+            opts["rsd_service_provider_using_tunneld"] = ""
         if self.mutually_exclusive.intersection(opts) and self.name in opts:
             raise UsageError(
-                'Illegal usage: `{}` is mutually exclusive with '
-                'arguments `{}`.'.format(
-                    self.name,
-                    ', '.join(self.mutually_exclusive)
+                "Illegal usage: `{}` is mutually exclusive with arguments `{}`.".format(
+                    self.name, ", ".join(self.mutually_exclusive)
                 )
             )
 
-        return super().handle_parse_result(
-            ctx,
-            opts,
-            args
-        )
+        return super().handle_parse_result(ctx, opts, args)
 
 
 def default_json_encoder(obj):
     if isinstance(obj, bytes):
-        return f'<{obj.hex()}>'
+        return f"<{obj.hex()}>"
     if isinstance(obj, datetime.datetime):
         return str(obj)
     if isinstance(obj, uuid.UUID):
@@ -81,8 +80,9 @@ def print_json(buf, colored: Optional[bool] = None, default=default_json_encoder
         colored = user_requested_colored_output()
     formatted_json = json.dumps(buf, sort_keys=True, indent=4, default=default)
     if colored and os.isatty(sys.stdout.fileno()):
-        colorful_json = highlight(formatted_json, lexers.JsonLexer(),
-                                  formatters.Terminal256Formatter(style='stata-dark'))
+        colorful_json = highlight(
+            formatted_json, lexers.JsonLexer(), formatters.Terminal256Formatter(style="stata-dark")
+        )
         print(colorful_json)
         return colorful_json
     else:
@@ -91,11 +91,11 @@ def print_json(buf, colored: Optional[bool] = None, default=default_json_encoder
 
 
 def print_hex(data, colored=True):
-    hex_dump = hexdump.hexdump(data, result='return')
+    hex_dump = hexdump.hexdump(data, result="return")
     if colored:
-        print(highlight(hex_dump, lexers.HexdumpLexer(), formatters.Terminal256Formatter(style='native')))
+        print(highlight(hex_dump, lexers.HexdumpLexer(), formatters.Terminal256Formatter(style="native")))
     else:
-        print(hex_dump, end='\n\n')
+        print(hex_dump, end="\n\n")
 
 
 def set_verbosity(ctx, param, value):
@@ -116,7 +116,7 @@ def user_requested_colored_output() -> bool:
 
 
 def get_last_used_terminal_formatting(buf: str) -> str:
-    return '\x1b' + buf.rsplit('\x1b', 1)[1].split('m')[0] + 'm'
+    return "\x1b" + buf.rsplit("\x1b", 1)[1].split("m")[0] + "m"
 
 
 def sudo_required(func):
@@ -131,24 +131,24 @@ def sudo_required(func):
 
 
 def prompt_selection(choices: list[Any], message: str, idx: bool = False) -> Any:
-    question = [inquirer3.List('selection', message=message, choices=choices, carousel=True)]
+    question = [inquirer3.List("selection", message=message, choices=choices, carousel=True)]
     try:
         result = inquirer3.prompt(question, theme=GreenPassion(), raise_keyboard_interrupt=True)
-    except KeyboardInterrupt:
-        raise click.ClickException('No selection was made')
-    return result['selection'] if not idx else choices.index(result['selection'])
+    except KeyboardInterrupt as e:
+        raise click.ClickException("No selection was made") from e
+    return result["selection"] if not idx else choices.index(result["selection"])
 
 
 def prompt_device_list(device_list: list):
-    return prompt_selection(device_list, 'Choose device')
+    return prompt_selection(device_list, "Choose device")
 
 
 def choose_service_provider(callback: Callable):
     def wrap_callback_calling(**kwargs: dict) -> None:
         service_provider = None
-        lockdown_service_provider = kwargs.pop('lockdown_service_provider', None)
-        rsd_service_provider_manually = kwargs.pop('rsd_service_provider_manually', None)
-        rsd_service_provider_using_tunneld = kwargs.pop('rsd_service_provider_using_tunneld', None)
+        lockdown_service_provider = kwargs.pop("lockdown_service_provider", None)
+        rsd_service_provider_manually = kwargs.pop("rsd_service_provider_manually", None)
+        rsd_service_provider_using_tunneld = kwargs.pop("rsd_service_provider_using_tunneld", None)
         if lockdown_service_provider is not None:
             service_provider = lockdown_service_provider
         if rsd_service_provider_manually is not None:
@@ -161,20 +161,23 @@ def choose_service_provider(callback: Callable):
 
 
 def is_invoked_for_completion() -> bool:
-    """ Returns True if the command is ivoked for autocompletion. """
-    for env in os.environ.keys():
-        if env.startswith('_') and env.endswith('_COMPLETE'):
-            return True
-    return False
+    """Returns True if the command is ivoked for autocompletion."""
+    return any(env.startswith("_") and env.endswith("_COMPLETE") for env in os.environ)
 
 
 class BaseCommand(click.Command):
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
         self.params[:0] = [
-            click.Option(('verbosity', '-v', '--verbose'), count=True, callback=set_verbosity, expose_value=False),
-            click.Option(('color', '--color/--no-color'), default=True, callback=set_color_flag, is_flag=True,
-                         expose_value=False, help='colorize output'),
+            click.Option(("verbosity", "-v", "--verbose"), count=True, callback=set_verbosity, expose_value=False),
+            click.Option(
+                ("color", "--color/--no-color"),
+                default=True,
+                callback=set_color_flag,
+                is_flag=True,
+                expose_value=False,
+                help="colorize output",
+            ),
         ]
 
 
@@ -191,20 +194,35 @@ class LockdownCommand(BaseServiceProviderCommand):
         self.usbmux_address = None
         self.mobdev2_option = None
         self.params[:0] = [
-            click.Option(('mobdev2', '--mobdev2'), callback=self.mobdev2, expose_value=False, default=None,
-                         help='Use bonjour browse for mobdev2 devices. Expected value IP address of the interface to '
-                              'use. Leave empty to browse through all interfaces'),
-            click.Option(('usbmux', '--usbmux'), callback=self.usbmux, expose_value=False,
-                         envvar=USBMUX_ENV_VAR, help=USBMUX_OPTION_HELP),
-            click.Option(('lockdown_service_provider', '--udid'), envvar=UDID_ENV_VAR, callback=self.udid,
-                         help=f'Device unique identifier. You may pass {UDID_ENV_VAR} environment variable to pass this'
-                              f' option as well'),
+            click.Option(
+                ("mobdev2", "--mobdev2"),
+                callback=self.mobdev2,
+                expose_value=False,
+                default=None,
+                help="Use bonjour browse for mobdev2 devices. Expected value IP address of the interface to "
+                "use. Leave empty to browse through all interfaces",
+            ),
+            click.Option(
+                ("usbmux", "--usbmux"),
+                callback=self.usbmux,
+                expose_value=False,
+                envvar=USBMUX_ENV_VAR,
+                help=USBMUX_OPTION_HELP,
+            ),
+            click.Option(
+                ("lockdown_service_provider", "--udid"),
+                envvar=UDID_ENV_VAR,
+                callback=self.udid,
+                help=f"Device unique identifier. You may pass {UDID_ENV_VAR} environment variable to pass this"
+                f" option as well",
+            ),
         ]
 
-    async def get_mobdev2_devices(self, udid: Optional[str] = None, ips: Optional[list[str]] = None) \
-            -> list[TcpLockdownClient]:
+    async def get_mobdev2_devices(
+        self, udid: Optional[str] = None, ips: Optional[list[str]] = None
+    ) -> list[TcpLockdownClient]:
         result = []
-        async for ip, lockdown in get_mobdev2_lockdowns(udid=udid, ips=ips):
+        async for _ip, lockdown in get_mobdev2_lockdowns(udid=udid, ips=ips):
             result.append(lockdown)
         return result
 
@@ -225,8 +243,11 @@ class LockdownCommand(BaseServiceProviderCommand):
             return self.service_provider
 
         if self.mobdev2_option is not None:
-            devices = asyncio.run(self.get_mobdev2_devices(
-                udid=value if value else None, ips=[self.mobdev2_option] if self.mobdev2_option else None))
+            devices = asyncio.run(
+                self.get_mobdev2_devices(
+                    udid=value if value else None, ips=[self.mobdev2_option] if self.mobdev2_option else None
+                )
+            )
             if not devices:
                 raise NoDeviceConnectedError()
 
@@ -240,29 +261,37 @@ class LockdownCommand(BaseServiceProviderCommand):
         if value is not None:
             return create_using_usbmux(serial=value)
 
-        devices = select_devices_by_connection_type(connection_type='USB', usbmux_address=self.usbmux_address)
+        devices = select_devices_by_connection_type(connection_type="USB", usbmux_address=self.usbmux_address)
         if len(devices) <= 1:
             return create_using_usbmux(usbmux_address=self.usbmux_address)
 
-        return prompt_device_list(
-            [create_using_usbmux(serial=device.serial, usbmux_address=self.usbmux_address) for device in devices])
+        return prompt_device_list([
+            create_using_usbmux(serial=device.serial, usbmux_address=self.usbmux_address) for device in devices
+        ])
 
 
 class RSDCommand(BaseServiceProviderCommand):
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
         self.params[:0] = [
-            RSDOption(('rsd_service_provider_manually', '--rsd'), type=(str, int), callback=self.rsd,
-                      mutually_exclusive=['rsd_service_provider_using_tunneld'],
-                      help='\b\n'
-                           'RSD hostname and port number (as provided by a `start-tunnel` subcommand).'),
-            RSDOption(('rsd_service_provider_using_tunneld', '--tunnel'), callback=self.tunneld,
-                      mutually_exclusive=['rsd_service_provider_manually'], envvar=TUNNEL_ENV_VAR,
-                      help='\b\n'
-                           'Either an empty string to force tunneld device selection, or a UDID of a tunneld '
-                           'discovered device.\n'
-                           'The string may be suffixed with :PORT in case tunneld is not serving at the default port.\n'
-                           f'This option may also be transferred as an environment variable: {TUNNEL_ENV_VAR}')
+            RSDOption(
+                ("rsd_service_provider_manually", "--rsd"),
+                type=(str, int),
+                callback=self.rsd,
+                mutually_exclusive=["rsd_service_provider_using_tunneld"],
+                help="\b\nRSD hostname and port number (as provided by a `start-tunnel` subcommand).",
+            ),
+            RSDOption(
+                ("rsd_service_provider_using_tunneld", "--tunnel"),
+                callback=self.tunneld,
+                mutually_exclusive=["rsd_service_provider_manually"],
+                envvar=TUNNEL_ENV_VAR,
+                help="\b\n"
+                "Either an empty string to force tunneld device selection, or a UDID of a tunneld "
+                "discovered device.\n"
+                "The string may be suffixed with :PORT in case tunneld is not serving at the default port.\n"
+                f"This option may also be transferred as an environment variable: {TUNNEL_ENV_VAR}",
+            ),
         ]
 
     def rsd(self, ctx, param: str, value: Optional[tuple[str, int]]) -> Optional[RemoteServiceDiscoveryService]:
@@ -278,19 +307,21 @@ class RSDCommand(BaseServiceProviderCommand):
 
         udid = udid.strip()
         port = TUNNELD_DEFAULT_ADDRESS[1]
-        if ':' in udid:
-            udid, port = udid.split(':')
+        if ":" in udid:
+            udid, port = udid.split(":")
 
         rsds = await async_get_tunneld_devices((TUNNELD_DEFAULT_ADDRESS[0], port))
         if len(rsds) == 0:
             raise NoDeviceConnectedError()
 
-        if udid != '':
+        if udid != "":
             try:
                 # Connect to the specified device
-                self.service_provider = [rsd for rsd in rsds if rsd.udid == udid or rsd.udid.replace('-', '') == udid][0]
-            except IndexError:
-                raise DeviceNotFoundError(udid)
+                self.service_provider = next(
+                    rsd for rsd in rsds if rsd.udid == udid or rsd.udid.replace("-", "") == udid
+                )
+            except IndexError as e:
+                raise DeviceNotFoundError(udid) from e
         else:
             if len(rsds) == 1:
                 self.service_provider = rsds[0]
@@ -323,13 +354,13 @@ class CommandWithoutAutopair(Command):
 
 
 class BasedIntParamType(click.ParamType):
-    name = 'based int'
+    name = "based int"
 
     def convert(self, value, param, ctx):
         try:
             return int(value, 0)
         except ValueError:
-            self.fail(f'{value!r} is not a valid int.', param, ctx)
+            self.fail(f"{value!r} is not a valid int.", param, ctx)
 
 
 BASED_INT = BasedIntParamType()

pymobiledevice3/cli/companion_proxy.py

@@ -12,11 +12,11 @@ def cli() -> None:
 
 @cli.group()
 def companion() -> None:
-    """ List paired "companion" devices """
+    """List paired "companion" devices"""
     pass
 
 
-@companion.command('list', cls=Command)
+@companion.command("list", cls=Command)
 def companion_list(service_provider: LockdownClient):
-    """ list all paired companion devices """
-    print_json(CompanionProxyService(service_provider).list(), default=lambda x: '<non-serializable>')
+    """list all paired companion devices"""
+    print_json(CompanionProxyService(service_provider).list(), default=lambda x: "<non-serializable>")