Refactor CLI to use subcommands for utility functions (#215)

## Summary
Refactored the CLI to introduce dedicated subcommands (`audio-devices`,
`servers`, `clients`) for utility functions, replacing the previous
flag-based approach (`--list-audio-devices`, `--list-servers`,
`--list-clients`). The old flags are deprecated but remain functional
with warnings for backward compatibility.

## Key Changes

- **New subcommand structure**: Added three new top-level subcommands
with `list` subcommands:
  - `sendspin audio-devices list` (replaces `--list-audio-devices`)
  - `sendspin servers list` (replaces `--list-servers`)
  - `sendspin clients list` (replaces `--list-clients`)

- **Parser updates**: 
- Added `audio-devices`, `servers`, and `clients` to `EXPLICIT_APPS`
frozenset
- Created dedicated argument parsers for each new subcommand with
appropriate help text
  - Added routing logic in `main()` to handle the new subcommands

- **Backward compatibility**:
- Deprecated flags still work but now print a warning message directing
users to the new subcommands
- Old flags remain in the player argument parser with updated help text
indicating deprecation

- **Documentation updates**:
  - Updated help text throughout to reference new subcommand syntax
  - Updated README.md examples to use new subcommand format
  - Updated AGENTS.md to reflect new device enumeration approach
  - Updated systemd installation script to use new subcommand syntax
- Added example output showing both old and new syntax in
`list_audio_devices()`

## Implementation Details

- New subcommands are handled before the main player/daemon/serve logic
in `main()`
- Each new subcommand validates that a `list` subcommand was provided;
otherwise shows help
- Deprecation warnings are printed to stdout when old flags are used
- All three new subcommands follow the same pattern for consistency and
extensibility

https://claude.ai/code/session_018Mj2pQj7Lqu5YTGnB97E94

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: balloob

AGENTS.md

@@ -48,7 +48,7 @@ Project documentation, installation instructions, usage guide (including command
 Main entry point and orchestrator. Responsibilities:
 - **Argument parsing**: Commands (`serve`, `daemon`), flags (`--url`, `--name`, `--id`, `--audio-device`, `--static-delay-ms`)
 - **Command routing**: Routes to appropriate mode (TUI app, daemon, or server)
-- **Device enumeration**: Lists audio devices and servers via `--list-audio-devices` and `--list-servers`
+- **Device enumeration**: Lists audio devices and servers via `audio-devices list` and `servers list` subcommands
 - **Backward compatibility**: Handles deprecated `--headless` flag with warning
 
 ### `sendspin/tui/` (TUI Mode Package)
@@ -96,7 +96,7 @@ Daemon mode for headless operation (via `sendspin daemon` or deprecated `--headl
 ### `sendspin/audio_devices.py`
 Audio device resolution and ALSA device listing. Responsibilities:
 - **Device resolution**: Resolves `--audio-device` argument by index, name prefix, or raw ALSA device name (via `resolve_audio_device()`)
-- **ALSA device listing**: Enumerates ALSA PCM devices via `aplay -L` for display in `--list-audio-devices`
+- **ALSA device listing**: Enumerates ALSA PCM devices via `aplay -L` for display in `sendspin audio-devices list`
 - **ALSA device fallback**: Opens ALSA plugin devices (dmix, plug) not enumerated by PortAudio, using safe defaults if PortAudio can't query device info
 
 ### `sendspin/audio.py`

README.md

@@ -190,7 +190,7 @@ sendspin --url ws://192.168.1.100:8080/sendspin
 
 **List available servers on the network:**
 ```bash
-sendspin --list-servers
+sendspin servers list
 ```
 
 ### Client Identification
@@ -211,7 +211,7 @@ By default, the player uses your system's default audio output device. You can l
 
 **List available audio devices:**
 ```bash
-sendspin --list-audio-devices
+sendspin audio-devices list
 ```
 
 This displays all audio output devices with their IDs, channel configurations, and sample rates. The default device is marked.
@@ -231,7 +231,7 @@ sendspin --audio-device "MacBook"
 sendspin --audio-device dmixer
 ```
 
-This is useful for ALSA plugin devices (dmix, plug, etc.) that don't appear in `--list-audio-devices`. For example, in a dual mono setup where two daemons share a single sound card via dmix, each daemon can target a different ALSA device that routes to a specific channel:
+This is useful for ALSA plugin devices (dmix, plug, etc.) that may not appear in the numbered PortAudio device list (though they may be shown in the ALSA devices section on Linux). For example, in a dual mono setup where two daemons share a single sound card via dmix, each daemon can target a different ALSA device that routes to a specific channel:
 
 ```bash
 # Room 1: left channel via dmix

scripts/systemd/install-systemd.sh

@@ -239,9 +239,9 @@ else
     fi
 
     if [ -n "$DAEMON_DBUS" ]; then
-        sudo -u "$DAEMON_USER" env XDG_RUNTIME_DIR="$DAEMON_RUNTIME_DIR" DBUS_SESSION_BUS_ADDRESS="$DAEMON_DBUS" "$SENDSPIN_BIN" --list-audio-devices 2>&1 | head -n -2
+        sudo -u "$DAEMON_USER" env XDG_RUNTIME_DIR="$DAEMON_RUNTIME_DIR" DBUS_SESSION_BUS_ADDRESS="$DAEMON_DBUS" "$SENDSPIN_BIN" audio-devices list 2>&1 | grep -v -e "^To select an audio device" -e "^  sendspin"
     else
-        sudo -u "$DAEMON_USER" "$SENDSPIN_BIN" --list-audio-devices 2>&1 | head -n -2 || echo -e "${D}(Audio devices will be detected when daemon starts)${N}"
+        sudo -u "$DAEMON_USER" "$SENDSPIN_BIN" audio-devices list 2>&1 | grep -v -e "^To select an audio device" -e "^  sendspin" || echo -e "${D}(Audio devices will be detected when daemon starts)${N}"
     fi
 
     DEVICE=$(prompt_input "Audio device" "default")

sendspin/cli.py

@@ -41,7 +41,9 @@
   • Other systems: https://www.portaudio.com/"""
 
 PLAYER_APP_SENTINEL = "player"
-EXPLICIT_APPS = frozenset({PLAYER_APP_SENTINEL, "daemon", "serve"})
+EXPLICIT_APPS = frozenset(
+    {PLAYER_APP_SENTINEL, "daemon", "serve", "audio-devices", "servers", "clients"}
+)
 TOP_LEVEL_ACTIONS = frozenset({"-h", "--help", "--version"})
 
 
@@ -92,6 +94,7 @@ def list_audio_devices() -> None:
         )
     if devices:
         print(f"\nTo select an audio device:\n  sendspin --audio-device {devices[0].index}")
+        print(f"  sendspin daemon --audio-device {devices[0].index}")
 
     if sys.platform.startswith("linux"):
         alsa_devices = list_alsa_devices()
@@ -143,7 +146,7 @@ def _add_player_runtime_options(target: ArgumentTarget, *, suppress_defaults: bo
         help=(
             "Audio output device by index (e.g., 0, 1, 2), name prefix (e.g., 'MacBook'), "
             "or raw ALSA device name (e.g., 'dmixer', 'olohuone') for plugin devices like dmix. "
-            "Use --list-audio-devices to see enumerated devices."
+            "Use 'sendspin audio-devices list' to see enumerated devices."
         ),
     )
     target.add_argument(
@@ -206,19 +209,19 @@ def _add_player_actions(target: ArgumentTarget, *, suppress_defaults: bool = Fal
         "--list-audio-devices",
         action="store_true",
         default=argparse.SUPPRESS if suppress_defaults else False,
-        help="List available audio output devices and exit",
+        help="(deprecated: use 'sendspin audio-devices list') List audio devices and exit",
     )
     target.add_argument(
         "--list-servers",
         action="store_true",
         default=argparse.SUPPRESS if suppress_defaults else False,
-        help="Discover and list available Sendspin servers on the network",
+        help="(deprecated: use 'sendspin servers list') List Sendspin servers and exit",
     )
     target.add_argument(
         "--list-clients",
         action="store_true",
         default=argparse.SUPPRESS if suppress_defaults else False,
-        help="Discover and list available Sendspin clients on the network",
+        help="(deprecated: use 'sendspin clients list') List Sendspin clients and exit",
     )
     target.add_argument(
         "--headless",
@@ -357,7 +360,7 @@ def _build_parser() -> argparse.ArgumentParser:
         default=None,
         help=(
             "Audio output device by index (e.g., 0, 1, 2) or name prefix (e.g., 'MacBook'). "
-            "Use --list-audio-devices to see available devices."
+            "Use 'sendspin audio-devices list' to see available devices."
         ),
     )
     daemon_parser.add_argument(
@@ -418,6 +421,57 @@ def _build_parser() -> argparse.ArgumentParser:
         help="Product name reported in the client hello (defaults to auto-detected OS/platform name)",
     )
 
+    # audio-devices subcommand
+    audio_devices_parser = subparsers.add_parser(
+        "audio-devices",
+        help="Audio device utilities",
+        description="Audio device utilities.",
+    )
+    audio_devices_sub = audio_devices_parser.add_subparsers(
+        dest="audio_devices_command",
+        title="Commands",
+        required=True,
+    )
+    audio_devices_sub.add_parser(
+        "list",
+        help="List available audio output devices",
+        description="List all available audio output devices and exit.",
+    )
+
+    # servers subcommand
+    servers_parser = subparsers.add_parser(
+        "servers",
+        help="Server discovery utilities",
+        description="Server discovery utilities.",
+    )
+    servers_sub = servers_parser.add_subparsers(
+        dest="servers_command",
+        title="Commands",
+        required=True,
+    )
+    servers_sub.add_parser(
+        "list",
+        help="Discover and list available Sendspin servers on the network",
+        description="Discover and list available Sendspin servers on the network.",
+    )
+
+    # clients subcommand
+    clients_parser = subparsers.add_parser(
+        "clients",
+        help="Client discovery utilities",
+        description="Client discovery utilities.",
+    )
+    clients_sub = clients_parser.add_subparsers(
+        dest="clients_command",
+        title="Commands",
+        required=True,
+    )
+    clients_sub.add_parser(
+        "list",
+        help="Discover and list available Sendspin clients on the network",
+        description="Discover and list available Sendspin clients on the network.",
+    )
+
     return parser
 
 
@@ -613,17 +667,38 @@ def main() -> int:
             traceback.print_exc()
             return 1
 
+    # Handle utility subcommands
+    if args.command == "audio-devices":
+        if args.audio_devices_command == "list":
+            list_audio_devices()
+            return 0
+
+    if args.command == "servers":
+        if args.servers_command == "list":
+            asyncio.run(list_servers())
+            return 0
+
+    if args.command == "clients":
+        if args.clients_command == "list":
+            asyncio.run(list_clients())
+            return 0
+
     if args.command == PLAYER_APP_SENTINEL:
-        # Handle player-only actions before starting async runtime.
+        # Deprecated flags - route to new subcommands with a warning.
         if args.list_audio_devices:
+            print(
+                "Warning: --list-audio-devices is deprecated. Use 'sendspin audio-devices list'.\n"
+            )
             list_audio_devices()
             return 0
 
         if args.list_servers:
+            print("Warning: --list-servers is deprecated. Use 'sendspin servers list'.\n")
             asyncio.run(list_servers())
             return 0
 
         if args.list_clients:
+            print("Warning: --list-clients is deprecated. Use 'sendspin clients list'.\n")
             asyncio.run(list_clients())
             return 0