pymobiledevice3 5.0.4__py3-none-any.whl → 7.0.6__py3-none-any.whl

misc/understanding_idevice_protocol_layers.md

@@ -287,14 +287,14 @@ pymobiledevice3 developer dvt launch com.apple.mobilesafari
 
 ## DVT
 
-One of the more interesting developer services, is the one exposed by `DTServiceHub`. It is using DTX protocol messages,
+One of the more interesting developer services is the one exposed by `DTServiceHub`. It is using DTX protocol messages,
 but since it mainly wraps and allows access to stuff in `DVTFoundation.framework` we called it DVT in our
 implementation (probably standing for DeveloperTools).
 
 We don't delve too much into this protocol, but we'll say in general it allows us to invoke a whitelist of ObjC methods
 in different ObjC objects. The terminology used by DVT to each such ObjC object is called "channels".
 
-In order to access this different object use the following APIs:
+To access this different object use the following APIs:
 
 ```python
 from pymobiledevice3.lockdown import create_using_usbmux
@@ -313,17 +313,22 @@ dvt_channel = Screenshot(dvt)
 open('/tmp/screen.png', 'wb').write(dvt_channel.get_screenshot())
 ```
 
-Looking for an unimplemented feature/channel? Feel free to play with it (and submit a PR afterwards 🙏) using the
+Looking for an unimplemented feature/channel? Feel free to play with it (and submit a PR afterward 🙏) using the
 following shell:
 
 ```shell
 pymobiledevice3 developer dvt shell
 ```
 
+> **NOTE:** The full list of the methods that can be invoked on a DVT channel can be found by looking at all ObjC
+> classes in `DVTInstrumentsFoundation.framework` implementing the `DTXAllowedRPC` protocol.
+> There is an existing [Anubis rule](https://github.com/netanelc305/anubis/blob/9da337178ebd7e9f168e9df2d82b192eba4f1b30/example_rules.yaml#L14-L17)
+> I use to diff new methods against the existing ones.
+
 ## RemoteXPC
 
 Starting at iOS 17.0, Apple made a large refactor in the manner we all interact with the developer services. There can
-be multiple reasons for that decision, but in general this refactor main key points are:
+be multiple reasons for that decision, but in general these refactor main key points are:
 
 - Create a single standard for interacting with the new lockdown services (XPC Messages, Apple's proprietary IPC)
 - Optimize the protocol for large file transfers (such as the dyld_shared_cache)
@@ -347,7 +352,7 @@ Since all this communication is IP-based, but without any additional exported TC
 help us here. Instead, starting at iOS 16.0, when connecting an iDevice, it exports another non-standard USB-Ethernet
 adapter (with IPv6 link-local address), placing us in a subnet with the device's `remoted`.
 
-As we've said this communication is non-standard, and requires either:
+As we've said, this communication is non-standard and requires either:
 
 - macOS Monterey or higher
 - Special driver on your linux/Windows machine

pymobiledevice3/__main__.py

@@ -1,5 +1,6 @@
 import asyncio
 import difflib
+import importlib
 import logging
 import os
 import re
@@ -7,12 +8,18 @@ import sys
 import textwrap
 import traceback
 import warnings
-from typing import Union
+from collections.abc import Sequence
+from typing import Annotated, Optional, Union
 
 import click
 import coloredlogs
+import typer
+import typer.core
+from packaging.version import Version
+from typer.core import TyperGroup
+from typer_injector import InjectingTyper
 
-from pymobiledevice3.cli.cli_common import TUNNEL_ENV_VAR, isatty
+from pymobiledevice3.cli.cli_common import TUNNEL_ENV_VAR, isatty, set_color_flag, set_verbosity
 from pymobiledevice3.exceptions import (
     AccessDeniedError,
     CloudConfigurationAlreadyPresentError,
@@ -37,10 +44,11 @@ from pymobiledevice3.exceptions import (
     QuicProtocolNotSupportedError,
     RSDRequiredError,
     SetProhibitedError,
+    StartServiceError,
     TunneldConnectionError,
     UserDeniedPairingError,
 )
-from pymobiledevice3.lockdown import retry_create_using_usbmux
+from pymobiledevice3.lockdown import create_using_usbmux, retry_create_using_usbmux
 from pymobiledevice3.osu.os_utils import get_os_utils
 
 coloredlogs.install(level=logging.INFO)
@@ -109,26 +117,28 @@ CLI_GROUPS = {
     "syslog": "syslog",
     "usbmux": "usbmux",
     "webinspector": "webinspector",
+    "idam": "idam",
     "version": "version",
-    "install-completions": "completions",
 }
 
 # Set if used the `--reconnect` option
 RECONNECT = False
 
 
-class Pmd3Cli(click.Group):
-    def list_commands(self, ctx):
-        return CLI_GROUPS.keys()
+class Pmd3TyperGroup(TyperGroup):
+    def list_commands(self, ctx: click.Context) -> list[str]:
+        # Order is preserved by dict insertion; adjust if you want alphabetical
+        return list(CLI_GROUPS.keys())
 
-    def get_command(self, ctx: click.Context, name: str) -> click.Command:
-        if name not in CLI_GROUPS:
-            self.handle_invalid_command(ctx, name)
-        return self.import_and_get_command(ctx, name)
+    def get_command(self, ctx: click.Context, cmd_name: str) -> click.Command:
+        if cmd_name not in CLI_GROUPS:
+            self.handle_invalid_command(ctx, cmd_name)
+        return self.import_and_get_command(ctx, cmd_name)
 
-    def handle_invalid_command(self, ctx: click.Context, name: str) -> None:
+    def handle_invalid_command(self, ctx, name: str) -> None:
         suggested_commands = self.search_commands(name)
         suggestion = self.format_suggestions(suggested_commands)
+        # ctx.fail raises a ClickException underneath, which Typer displays nicely
         ctx.fail(f"No such command {name!r}{suggestion}")
 
     @staticmethod
@@ -136,70 +146,162 @@ class Pmd3Cli(click.Group):
         if not suggestions:
             return ""
         cmds = textwrap.indent("\n".join(suggestions), " " * 4)
-        return f"\nDid you mean this?\n{cmds}"
+        return f"\nDid you mean:\n{cmds}"
 
     @staticmethod
     def import_and_get_command(ctx: click.Context, name: str) -> click.Command:
         module_name = f"pymobiledevice3.cli.{CLI_GROUPS[name]}"
-        mod = __import__(module_name, None, None, ["cli"])
-        command = mod.cli.get_command(ctx, name)
-        if not command:
-            command_name = mod.cli.list_commands(ctx)[0]
-            command = mod.cli.get_command(ctx, command_name)
-        return command
+        mod = importlib.import_module(module_name)
+        # submodules expose a Typer Group named "cli"
+        cli: typer.Typer = mod.cli
+        return typer.main.get_command(cli)
 
     @staticmethod
     def highlight_keyword(text: str, keyword: str) -> str:
-        return re.sub(f"({keyword})", click.style("\\1", bold=True), text, flags=re.IGNORECASE)
+        return re.sub(f"({keyword})", typer.style("\\1", bold=True), text, flags=re.IGNORECASE)
 
     @staticmethod
-    def collect_commands(command: click.Command) -> Union[str, list[str]]:
-        commands = []
-        if isinstance(command, click.Group):
-            for _k, v in command.commands.items():
-                cmd = Pmd3Cli.collect_commands(v)
-                if isinstance(cmd, list):
-                    commands.extend([f"{command.name} {c}" for c in cmd])
+    def collect_commands(command: Union[TyperGroup, click.Command]) -> Union[str, list[str]]:
+        if isinstance(command, TyperGroup):  # group
+            cmds = []
+            for v in command.commands.values():
+                child = Pmd3TyperGroup.collect_commands(v)
+                if isinstance(child, list):
+                    cmds.extend([f"{command.name} {c}" for c in child])
                 else:
-                    commands.append(f"{command.name} {cmd}")
-            return commands
-        return f"{command.name}"
+                    cmds.append(f"{command.name} {child}")
+            return cmds
+        return command.name or ""
 
     @staticmethod
     def search_commands(pattern: str) -> list[str]:
-        all_commands = Pmd3Cli.load_all_commands()
+        all_commands = Pmd3TyperGroup.load_all_commands()
         matched = sorted(filter(lambda cmd: re.search(pattern, cmd), all_commands))
         if not matched:
             matched = difflib.get_close_matches(pattern, all_commands, n=20, cutoff=0.4)
         if isatty():
-            matched = [Pmd3Cli.highlight_keyword(cmd, pattern) for cmd in matched]
+            matched = [Pmd3TyperGroup.highlight_keyword(cmd, pattern) for cmd in matched]
         return matched
 
     @staticmethod
     def load_all_commands() -> list[str]:
-        all_commands = []
+        all_commands: list[str] = []
         for key in CLI_GROUPS:
             module_name = f"pymobiledevice3.cli.{CLI_GROUPS[key]}"
-            mod = __import__(module_name, None, None, ["cli"])
-            cmd = Pmd3Cli.collect_commands(mod.cli.commands[key])
+            mod = importlib.import_module(module_name)
+            if isinstance(mod.cli, typer.Typer):
+                cmd = Pmd3TyperGroup.collect_commands(typer.main.get_group(mod.cli))
+            else:
+                cmd = Pmd3TyperGroup.collect_commands(mod.cli.commands[key])
             if isinstance(cmd, list):
                 all_commands.extend(cmd)
             else:
                 all_commands.append(cmd)
         return all_commands
 
+    def resolve_command(
+        self, ctx: click.Context, args: list[str]
+    ) -> tuple[Optional[str], Optional[click.Command], list[str]]:
+        return super().resolve_command(ctx, args)
+
+
+app = InjectingTyper(
+    cls=Pmd3TyperGroup,
+    context_settings=CONTEXT_SETTINGS,
+    no_args_is_help=True,
+    # add_completion=False,
+    rich_markup_mode="markdown",
+    help=(
+        "Swiss-army CLI for pairing, inspecting, backing up, and automating iOS devices.\n\n"
+        "Docs and examples: https://github.com/doronz88/pymobiledevice3"
+    ),
+)
+
 
-@click.command(cls=Pmd3Cli, context_settings=CONTEXT_SETTINGS)
-@click.option("--reconnect", is_flag=True, default=False, help="Reconnect to device when disconnected.")
-def cli(reconnect: bool) -> None:
+@app.callback()
+def _root(
+    reconnect: Annotated[
+        bool,
+        typer.Option(
+            "--reconnect",
+            help="Automatically reconnect if the device disconnects mid-command.",
+            show_default=False,
+        ),
+    ] = False,
+    verbosity: Annotated[
+        int,
+        typer.Option(
+            "--verbose",
+            "-v",
+            count=True,
+            help="Increase logging verbosity (repeat for more detail).",
+        ),
+    ] = 0,
+    color: Annotated[
+        bool,
+        typer.Option(help="Colorize output; disable with --no-color for plain logs."),
+    ] = True,
+) -> None:
     """
-    \b
-    Interact with a connected iDevice (iPhone, iPad, ...)
-    For more information please look at:
-        https://github.com/doronz88/pymobiledevice3
+    Top-level options for pymobiledevice3.
     """
     global RECONNECT
     RECONNECT = reconnect
+    set_verbosity(verbosity)
+    set_color_flag(color)
+
+
+def device_might_need_tunneld(identifier: str) -> bool:
+    """
+    Determines if the device might require tunneling based on its product version.
+
+    This function uses the `create_using_usbmux` context manager to establish a lockdown
+    session with the specified identifier. It retrieves the device's product version,
+    and checks if it is greater than or equal to version "17.0". If so, the function
+    returns True, indicating that the device might require tunneling. Otherwise, it
+    returns False.
+
+    :param identifier: A string representing the device identifier.
+    :return: A boolean indicating whether the device might require tunneling.
+    """
+    with create_using_usbmux(identifier) as lockdown:
+        return Version(lockdown.product_version) >= Version("17.0")
+
+
+class PossiblyMisplacedOption(click.NoSuchOption):
+    def __init__(
+        self,
+        option_name: str,
+        message: Optional[str] = None,
+        possibilities: Optional[Sequence[str]] = None,
+        ctx: Optional[click.Context] = None,
+        suggested_ctx: Optional[click.Context] = None,
+    ) -> None:
+        super().__init__(option_name, message, possibilities, ctx)
+        if suggested_ctx is not None:
+            if ctx is not None:
+                self.message += f" for subcommand: {ctx.command_path}"
+
+            suggestion = f"{suggested_ctx.command_path} {option_name}"
+            suggestion += ctx.command_path.removeprefix(suggested_ctx.command_path) if ctx is not None else " ..."
+
+            self.message += f"\nDid you mean: {suggestion}?"
+
+    @staticmethod
+    def from_no_such_option(e: click.NoSuchOption) -> "PossiblyMisplacedOption":
+        ctx = e.ctx
+        while ctx:
+            for param in ctx.command.params:
+                if isinstance(param, typer.core.TyperOption) and (
+                    e.option_name in param.opts or e.option_name in param.secondary_opts
+                ):
+                    break
+            else:
+                ctx = ctx.parent
+                continue
+            break
+
+        return PossiblyMisplacedOption(e.option_name, e.message, e.possibilities, e.ctx, ctx)
 
 
 def invoke_cli_with_error_handling() -> bool:
@@ -208,7 +310,11 @@ def invoke_cli_with_error_handling() -> bool:
     disconnected.
     """
     try:
-        cli()
+        # Typer apps are callable; this executes the CLI with current sys.argv
+        try:
+            app(standalone_mode=False)
+        except click.NoSuchOption as e:
+            raise PossiblyMisplacedOption.from_no_such_option(e) from e
     except NoDeviceConnectedError:
         logger.error("Device is not connected")
         return True
@@ -249,13 +355,19 @@ def invoke_cli_with_error_handling() -> bool:
         if isinstance(e, RSDRequiredError):
             logger.warning("Trying again over tunneld since RSD is required for this command")
             should_retry_over_tunneld = True
-        elif (e.identifier is not None) and ("developer" in sys.argv) and ("--tunnel" not in sys.argv):
+        elif (
+            (e.identifier is not None)
+            and ("developer" in sys.argv)
+            and ("--tunnel" not in sys.argv)
+            and device_might_need_tunneld(e.identifier)
+        ):
             logger.warning("Got an InvalidServiceError. Trying again over tunneld since it is a developer command")
             should_retry_over_tunneld = True
         if should_retry_over_tunneld:
-            # use a single space because click will ignore envvars of empty strings
+            # use a single space because Typer/Click will ignore envvars of empty strings
             os.environ[TUNNEL_ENV_VAR] = e.identifier or " "
-            return main()
+            main()
+            return False
         logger.error(INVALID_SERVICE_MESSAGE)
     except PasswordRequiredError:
         logger.error("Device is password protected. Please unlock and retry")
@@ -291,6 +403,19 @@ def invoke_cli_with_error_handling() -> bool:
         )
     except QuicProtocolNotSupportedError:
         logger.error("Encountered a QUIC protocol error.")
+    except StartServiceError as e:
+        if e.message == "ServiceProhibited" and e.service_name == "com.apple.pcapd.shim.remote":
+            logger.error(
+                f"The {e.service_name} service is USB only (at least for some iOS versions).\n"
+                "Full discussion is available in: https://github.com/doronz88/pymobiledevice3/issues/1515"
+            )
+        else:
+            logger.error(f"Failed to start: {e.service_name} with. Received error: {e.message}.")
+    except click.ClickException as e:
+        from typer import rich_utils
+
+        rich_utils.rich_format_error(e)
+        sys.exit(e.exit_code)
 
     return False
 

pymobiledevice3/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '5.0.4'
-__version_tuple__ = version_tuple = (5, 0, 4)
+__version__ = version = '7.0.6'
+__version_tuple__ = version_tuple = (7, 0, 6)
 
 __commit_id__ = commit_id = None

pymobiledevice3/bonjour.py

@@ -50,7 +50,7 @@ def dataclass_compat(*d_args, **d_kwargs):
 @dataclass_compat(slots=True)
 class Address:
     ip: str
-    iface: Optional[str]  # local interface name (e.g., "en0"), or None if unknown
+    iface: str  # local interface name (e.g., "en0"), or None if unknown
 
     @property
     def full_ip(self) -> str:
@@ -300,10 +300,9 @@ async def browse_service(service_type: str, timeout: float = 4.0) -> list[Servic
     adapters = _Adapters()
 
     ptr_targets: set[str] = set()
-    srv_map: dict[str, dict] = {}
+    srv_map: dict[str, list[dict]] = defaultdict(list)  # instance_name -> list of {"target", "port"}
     txt_map: dict[str, dict] = {}
-    # host -> list[(ip, iface)]
-    host_addrs: dict[str, list[Address]] = defaultdict(list)
+    host_addrs: dict[str, list[Address]] = defaultdict(list)  # host -> list[(ip, iface)]
 
     def _record_addr(rr_name: str, ip_str: str, pkt_addr):
         # Determine family and possible scopeid from the packet that delivered this RR
@@ -312,7 +311,9 @@ async def browse_service(service_type: str, timeout: float = 4.0) -> list[Servic
         if isinstance(pkt_addr, tuple) and len(pkt_addr) == 4:  # IPv6 remote tuple
             scopeid = pkt_addr[3]
         iface = adapters.pick_iface_for_ip(ip_str, family, scopeid)
-        # avoid duplicates for the same host/ip
+        if iface is None:
+            return
+        # Avoid duplicates for the same host/ip
         existing = host_addrs[rr_name]
         if not any(a.ip == ip_str for a in existing):
             existing.append(Address(ip=ip_str, iface=iface))
@@ -331,11 +332,10 @@ async def browse_service(service_type: str, timeout: float = 4.0) -> list[Servic
                 if t == QTYPE_PTR and rr.get("name") == service_type:
                     ptr_targets.add(rr.get("ptrdname"))
                 elif t == QTYPE_SRV:
-                    srv_map[rr["name"]] = {
-                        "target": rr.get("target"),
-                        "port": rr.get("port"),
-                    }
+                    srv_map[rr["name"]].append({"target": rr.get("target"), "port": rr.get("port")})
                 elif t == QTYPE_TXT:
+                    # TODO: This could possibly mix the properties of multiple TXT records for the same instance.
+                    #       However, it's currently unused.
                     txt_map[rr["name"]] = rr.get("txt", {})
                 elif (t == QTYPE_A and rr.get("address")) or (t == QTYPE_AAAA and rr.get("address")):
                     _record_addr(rr["name"], rr["address"], pkt_addr)
@@ -346,20 +346,21 @@ async def browse_service(service_type: str, timeout: float = 4.0) -> list[Servic
     # Assemble dataclasses
     results: list[ServiceInstance] = []
     for inst in sorted(ptr_targets):
-        srv = srv_map.get(inst, {})
-        target = srv.get("target")
-        host = (target[:-1] if target and target.endswith(".") else target) or None
-        addrs = host_addrs.get(target, []) if target else []
+        srv_entries = srv_map.get(inst, [])
         props = txt_map.get(inst, {})
-        results.append(
-            ServiceInstance(
-                instance=inst,
-                host=host,
-                port=srv.get("port"),
-                addresses=addrs,
-                properties=props,
+        for srv in srv_entries:
+            target = srv.get("target")
+            host = (target[:-1] if target and target.endswith(".") else target) or None
+            addrs = host_addrs.get(target, []) if target else []
+            results.append(
+                ServiceInstance(
+                    instance=inst,
+                    host=host,
+                    port=srv.get("port"),
+                    addresses=addrs,
+                    properties=props,
+                )
             )
-        )
     return results
 
 

pymobiledevice3/cli/activation.py

@@ -1,30 +1,32 @@
-import click
-
-from pymobiledevice3.cli.cli_common import Command
-from pymobiledevice3.lockdown import LockdownClient
-from pymobiledevice3.services.mobile_activation import MobileActivationService
+from typing import Annotated
 
+import typer
+from typer_injector import InjectingTyper
 
-@click.group()
-def cli() -> None:
-    pass
-
+from pymobiledevice3.cli.cli_common import ServiceProviderDep
+from pymobiledevice3.services.mobile_activation import MobileActivationService
 
-@cli.group()
-def activation() -> None:
-    """Perform iCloud activation/deactivation or query the current state"""
-    pass
+cli = InjectingTyper(
+    name="activation",
+    help="Perform iCloud activation/deactivation or query the current state",
+    no_args_is_help=True,
+)
 
 
-@activation.command(cls=Command)
-def state(service_provider: LockdownClient):
+@cli.command()
+def state(service_provider: ServiceProviderDep) -> None:
     """Get current activation state"""
     print(MobileActivationService(service_provider).state)
 
 
-@activation.command(cls=Command)
-@click.option("--now", is_flag=True, help="do not wait for next nonce cycle")
-def activate(service_provider: LockdownClient, now):
+@cli.command()
+def activate(
+    service_provider: ServiceProviderDep,
+    now: Annotated[
+        bool,
+        typer.Option(help="do not wait for next nonce cycle"),
+    ] = False,
+) -> None:
     """Activate device"""
     activation_service = MobileActivationService(service_provider)
     if not now:
@@ -32,13 +34,13 @@ def activate(service_provider: LockdownClient, now):
     activation_service.activate()
 
 
-@activation.command(cls=Command)
-def deactivate(service_provider: LockdownClient):
+@cli.command()
+def deactivate(service_provider: ServiceProviderDep) -> None:
     """Deactivate device"""
     MobileActivationService(service_provider).deactivate()
 
 
-@activation.command(cls=Command)
-def itunes(service_provider: LockdownClient):
+@cli.command()
+def itunes(service_provider: ServiceProviderDep) -> None:
     """Tell the device that it has been connected to iTunes (useful for < iOS 4)"""
     service_provider.set_value(True, key="iTunesHasConnected")

pymobiledevice3/cli/afc.py

@@ -1,56 +1,64 @@
-import click
-
-from pymobiledevice3.cli.cli_common import Command
-from pymobiledevice3.lockdown import LockdownClient
-from pymobiledevice3.lockdown_service_provider import LockdownServiceProvider
-from pymobiledevice3.services.afc import AfcService, AfcShell
+from pathlib import Path
+from typing import Annotated
 
+import typer
+from typer_injector import InjectingTyper
 
-@click.group()
-def cli() -> None:
-    pass
-
+from pymobiledevice3.cli.cli_common import ServiceProviderDep
+from pymobiledevice3.services.afc import AfcService, AfcShell
 
-@cli.group()
-def afc() -> None:
-    """Manage device multimedia files"""
-    pass
+cli = InjectingTyper(
+    name="afc",
+    help="Browse, push, and pull files via the AFC service (/var/mobile/Media).",
+    no_args_is_help=True,
+)
 
 
-@afc.command("shell", cls=Command)
-def afc_shell(service_provider: LockdownClient):
-    """open an AFC shell rooted at /var/mobile/Media"""
+@cli.command("shell")
+def afc_shell(service_provider: ServiceProviderDep) -> None:
+    """Open an interactive AFC shell rooted at /var/mobile/Media."""
     AfcShell.create(service_provider)
 
 
-@afc.command("pull", cls=Command)
-@click.option("-i", "--ignore-errors", is_flag=True, help="Ignore AFC pull errors")
-@click.argument("remote_file", type=click.Path(exists=False))
-@click.argument("local_file", type=click.Path(exists=False))
-def afc_pull(service_provider: LockdownServiceProvider, remote_file: str, local_file: str, ignore_errors: bool) -> None:
-    """pull remote file from /var/mobile/Media"""
-    AfcService(lockdown=service_provider).pull(remote_file, local_file, ignore_errors=ignore_errors)
+@cli.command("pull")
+def afc_pull(
+    service_provider: ServiceProviderDep,
+    remote_file: Path,
+    local_file: Path,
+    ignore_errors: Annotated[
+        bool,
+        typer.Option(
+            "--ignore-errors",
+            "-i",
+            help="Continue downloading even if some files error (best-effort pull).",
+        ),
+    ],
+) -> None:
+    """Download a remote path under /var/mobile/Media to the local filesystem."""
+    AfcService(lockdown=service_provider).pull(str(remote_file), str(local_file), ignore_errors=ignore_errors)
 
 
-@afc.command("push", cls=Command)
-@click.argument("local_file", type=click.Path(exists=False))
-@click.argument("remote_file", type=click.Path(exists=False))
-def afc_push(service_provider: LockdownServiceProvider, local_file: str, remote_file: str) -> None:
-    """push local file into /var/mobile/Media"""
-    AfcService(lockdown=service_provider).push(local_file, remote_file)
+@cli.command("push")
+def afc_push(service_provider: ServiceProviderDep, local_file: Path, remote_file: Path) -> None:
+    """Upload a local file into /var/mobile/Media."""
+    AfcService(lockdown=service_provider).push(str(local_file), str(remote_file))
 
 
-@afc.command("ls", cls=Command)
-@click.argument("remote_file", type=click.Path(exists=False))
-@click.option("-r", "--recursive", is_flag=True)
-def afc_ls(service_provider: LockdownClient, remote_file, recursive):
-    """perform a dirlist rooted at /var/mobile/Media"""
-    for path in AfcService(lockdown=service_provider).dirlist(remote_file, -1 if recursive else 1):
+@cli.command("ls")
+def afc_ls(
+    service_provider: ServiceProviderDep,
+    remote_file: Path,
+    recursive: Annotated[
+        bool,
+        typer.Option("--recursive", "-r", help="Recurse into subdirectories when listing."),
+    ] = False,
+) -> None:
+    """List files under /var/mobile/Media (optionally recursively)."""
+    for path in AfcService(lockdown=service_provider).dirlist(str(remote_file), -1 if recursive else 1):
         print(path)
 
 
-@afc.command("rm", cls=Command)
-@click.argument("remote_file", type=click.Path(exists=False))
-def afc_rm(service_provider: LockdownClient, remote_file):
-    """remove a file rooted at /var/mobile/Media"""
-    AfcService(lockdown=service_provider).rm(remote_file)
+@cli.command("rm")
+def afc_rm(service_provider: ServiceProviderDep, remote_file: Path) -> None:
+    """Delete a file under /var/mobile/Media."""
+    AfcService(lockdown=service_provider).rm(str(remote_file))