feat: add a --include-beta filter to CLI scan/list/status commands

The CLI showed beta-only firmware updates unfiltered (no channel
awareness at all), unlike the web UI's "Show beta updates" toggle.
Adds an --include-beta flag to scan, device list, and device status,
off by default: a beta-only update now reports as "no update needed"
in the table view, and the detail view says so plainly instead of
listing it, mirroring the web app's default behavior.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VApHaH9KZ6BPV9SwvUAVLH

Author: valentinocossar

packages/cli/README.md

@@ -83,6 +83,7 @@ shelly-manager scan --target 192.168.1.0/24 --export csv --export-file devices.c
 - `--use-mdns`: Use mDNS service discovery
 - `--timeout`: Timeout per device (default: 3.0s)
 - `--workers`: Concurrent workers (default: 50)
+- `--include-beta`: Count beta-only firmware updates as available (hidden by default)
 - `--export`: Export format (json, csv)
 - `--export-file`: Output file path
 
@@ -94,12 +95,19 @@ shelly-manager scan --target 192.168.1.0/24 --export csv --export-file devices.c
 # Check device status
 shelly-manager device status 192.168.1.100
 shelly-manager device status 192.168.1.100 192.168.1.101
+shelly-manager device status 192.168.1.100 --include-beta  # Also surface beta-only updates
+
+# List known devices in a table
+shelly-manager device list 192.168.1.0/24
+shelly-manager device list 192.168.1.0/24 --include-beta
 
 # Reboot devices
 shelly-manager device reboot 192.168.1.100
 shelly-manager device reboot 192.168.1.100 --force  # Skip confirmation
 ```
 
+By default, `scan`, `device list`, and `device status` report a device as up to date when the only firmware update available is on the beta channel — pass `--include-beta` to see it. A beta release is always installable explicitly regardless of this flag, via `device update --channel beta`.
+
 **Device Status Output:**
 
 ```

packages/cli/src/cli/commands/device_commands.py

@@ -35,6 +35,11 @@ def device_commands() -> None:
 @device_commands.command()
 @click.argument("targets", nargs=-1)
 @click.option("--use-mdns", is_flag=True, help="Use mDNS to discover devices")
+@click.option(
+    "--include-beta",
+    is_flag=True,
+    help="Count beta-only firmware updates as available (hidden by default)",
+)
 @device_targeting_options
 @common_options
 @click.pass_context
@@ -44,6 +49,7 @@ async def scan(
     targets: tuple[str, ...],
     targets_opt: tuple[str, ...],
     use_mdns: bool,
+    include_beta: bool,
     timeout: int,
     workers: int,
 ) -> None:
@@ -55,6 +61,7 @@ async def scan(
       shelly-manager scan 192.168.1.0/24
       shelly-manager scan -t 192.168.1.100 -t 192.168.1.101
       shelly-manager scan --use-mdns
+      shelly-manager scan 192.168.1.0/24 --include-beta
     """
     console = ctx.obj.console
     container = ctx.obj.container
@@ -70,11 +77,16 @@ async def scan(
     )
 
     devices_found = await scan_use_case.execute(request)
-    scan_use_case.display_results(devices_found)
+    scan_use_case.display_results(devices_found, include_beta=include_beta)
 
 
 @device_commands.command("list")
 @click.argument("targets", nargs=-1)
+@click.option(
+    "--include-beta",
+    is_flag=True,
+    help="Count beta-only firmware updates as available (hidden by default)",
+)
 @device_targeting_options
 @common_options
 @click.pass_context
@@ -83,15 +95,17 @@ async def list_devices(
     ctx: click.Context,
     targets: tuple[str, ...],
     targets_opt: tuple[str, ...],
+    include_beta: bool,
     timeout: int,
     workers: int,
 ) -> None:
     """
     Similar to scan but optimized for listing known devices with full details in a table format.
 
     Examples:
-      shelly-manager list 192.168.1.0/24
-      shelly-manager list -t 192.168.1.100 -t 192.168.1.101
+      shelly-manager device list 192.168.1.0/24
+      shelly-manager device list -t 192.168.1.100 -t 192.168.1.101
+      shelly-manager device list 192.168.1.0/24 --include-beta
     """
     console = ctx.obj.console
     container = ctx.obj.container
@@ -108,13 +122,20 @@ async def list_devices(
     devices_found = await scan_use_case.execute(request)
 
     if devices_found:
-        scan_use_case.display_results(devices_found, show_table=True)
+        scan_use_case.display_results(
+            devices_found, show_table=True, include_beta=include_beta
+        )
     else:
         console.print(f"\n{Messages.warning('No devices found')}")
 
 
 @device_commands.command()
 @click.argument("targets", nargs=-1, required=False)
+@click.option(
+    "--include-beta",
+    is_flag=True,
+    help="Include beta-only firmware updates in the update list (hidden by default)",
+)
 @device_targeting_options
 @common_options
 @click.pass_context
@@ -123,6 +144,7 @@ async def status(
     ctx: click.Context,
     targets: tuple[str, ...],
     targets_opt: tuple[str, ...],
+    include_beta: bool,
     timeout: int,
     workers: int,
 ) -> None:
@@ -133,6 +155,7 @@ async def status(
     Examples:
       shelly-manager status 192.168.1.100 192.168.1.101
       shelly-manager status -t 192.168.1.0/24
+      shelly-manager status 192.168.1.100 --include-beta
     """
     console = ctx.obj.console
     container = ctx.obj.container
@@ -156,7 +179,7 @@ async def status(
             "shelly-manager device status 192.168.1.0/24",
         )
         sys.exit(EXIT_VALIDATION)
-    status_use_case.display_results(results)
+    status_use_case.display_results(results, include_beta=include_beta)
 
 
 @click.group()

packages/cli/src/cli/use_cases/common/result_formatting.py

@@ -5,6 +5,7 @@
 from typing import Any
 
 from core.domain.entities import DeviceStatus, DiscoveredDevice
+from core.domain.enums.enums import Status
 from rich.console import Console
 from rich.table import Table
 
@@ -21,27 +22,45 @@ def __init__(self, console: Console):
         self._console = console
 
     def format_device_table(
-        self, devices: list[Any], title: str = "Shelly Devices"
+        self,
+        devices: list[Any],
+        title: str = "Shelly Devices",
+        include_beta: bool = False,
     ) -> None:
         """
         Format and display a table of devices.
 
         Args:
             devices: List of device objects or dictionaries
             title: Table title
+            include_beta: Whether beta-only updates should be surfaced as
+                available, instead of reported as up to date
         """
         if not devices:
             return
 
         if devices and isinstance(devices[0], DiscoveredDevice):
-            self._format_discovered_devices_table(devices, title)
+            self._format_discovered_devices_table(devices, title, include_beta)
         elif devices and isinstance(devices[0], DeviceStatus):
-            self._format_device_status_table(devices)
+            self._format_device_status_table(devices, include_beta)
         else:
             self._format_legacy_device_table(devices, title)
 
+    def _effective_status(self, device: DiscoveredDevice, include_beta: bool) -> str:
+        """The status to display, downgrading a beta-only update to "no
+        update needed" when beta visibility is off — mirrors the same
+        allowed-channels rule the web UI applies."""
+        status = device.status
+        if (
+            not include_beta
+            and str(status) == Status.UPDATE_AVAILABLE.value
+            and getattr(device, "available_firmware_channel", None) == "beta"
+        ):
+            return Status.NO_UPDATE_NEEDED.value
+        return status
+
     def _format_discovered_devices_table(
-        self, devices: list[DiscoveredDevice], title: str
+        self, devices: list[DiscoveredDevice], title: str, include_beta: bool = False
     ) -> None:
         """Format table for DiscoveredDevice entities."""
         table = Table(title=title)
@@ -61,17 +80,19 @@ def _format_discovered_devices_table(
                 device.model_name or device.device_type or "Unknown",
                 device.device_name or "Unknown",
                 device.firmware_version or "Unknown",
-                format_device_status(device.status),
+                format_device_status(self._effective_status(device, include_beta)),
                 response_time,
             )
 
         self._console.print(table)
 
-    def _format_device_status_table(self, devices: list[DeviceStatus]) -> None:
+    def _format_device_status_table(
+        self, devices: list[DeviceStatus], include_beta: bool = False
+    ) -> None:
         """Format table for DeviceStatus entities."""
 
         for device_status in devices:
-            self.format_detailed_device_status(device_status)
+            self.format_detailed_device_status(device_status, include_beta)
 
     def _format_legacy_device_table(self, devices: list[Any], title: str) -> None:
         """Legacy format for backward compatibility."""
@@ -106,7 +127,9 @@ def _format_legacy_device_table(self, devices: list[Any], title: str) -> None:
 
         self._console.print(table)
 
-    def format_detailed_device_status(self, device_status: DeviceStatus) -> None:
+    def format_detailed_device_status(
+        self, device_status: DeviceStatus, include_beta: bool = False
+    ) -> None:
         """Format detailed component information for a single device."""
         from rich.columns import Columns
         from rich.panel import Panel
@@ -132,18 +155,33 @@ def format_detailed_device_status(self, device_status: DeviceStatus) -> None:
             # Show available firmware updates with version information
             if system_info.available_updates:
                 device_summary = device_status.get_device_summary()
-                available_updates = device_summary.get("available_updates", {})
+                raw_available_updates = device_summary.get("available_updates", {})
+                available_updates = (
+                    raw_available_updates
+                    if include_beta
+                    else {
+                        channel: info
+                        for channel, info in raw_available_updates.items()
+                        if channel != "beta"
+                    }
+                )
 
                 if available_updates:
                     system_content.append("[yellow]Updates Available:[/yellow]")
                     for update_type, update_info in available_updates.items():
                         version = update_info.get("version", "Unknown")
                         name = update_info.get("name", update_type) or update_type
                         system_content.append(f"  [cyan]• {name}:[/cyan] {version}")
-                else:
+                elif not raw_available_updates:
+                    # The raw component data has entries but none carried a
+                    # usable version, so get_device_summary filtered
+                    # everything out — unrelated to beta visibility.
                     system_content.append(
                         f"[yellow]Updates Available:[/yellow] {len(system_info.available_updates)}"
                     )
+                # else: only a beta release exists and beta visibility is
+                # off — show nothing, exactly like a device with no
+                # updates at all. No partial hint.
 
             system_panel = Panel(
                 "\n".join(system_content),

packages/cli/src/cli/use_cases/device/device_status.py

@@ -97,6 +97,6 @@ async def _check_device_status(
 
         return results
 
-    def display_results(self, results: list[Any]) -> None:
+    def display_results(self, results: list[Any], include_beta: bool = False) -> None:
         """Display status results to console."""
-        self._result_formatter.format_device_table(results)
+        self._result_formatter.format_device_table(results, include_beta=include_beta)

packages/cli/src/cli/use_cases/device/scan_devices.py

@@ -60,17 +60,23 @@ async def execute(self, request: DeviceScanRequest) -> list[Any]:
         return devices_found
 
     def display_results(
-        self, devices_found: list[Any], show_table: bool = True
+        self,
+        devices_found: list[Any],
+        show_table: bool = True,
+        include_beta: bool = False,
     ) -> None:
         """
         Display scan results to console.
 
         Args:
             devices_found: List of discovered devices
             show_table: Whether to show device table
+            include_beta: Whether beta-only updates count as available
         """
         if show_table:
-            self._result_formatter.format_device_table(devices_found)
+            self._result_formatter.format_device_table(
+                devices_found, include_beta=include_beta
+            )
 
         if devices_found:
             self._console.print(

packages/cli/tests/unit/commands/test_device_commands.py

@@ -134,6 +134,28 @@ def test_scan_with_custom_timeout_and_workers(
         assert call_args.timeout == 5.0
         assert call_args.max_workers == 20
 
+    def test_scan_help_documents_include_beta(self, cli_context):
+        runner = CliRunner()
+        result = runner.invoke(device_commands, ["scan", "--help"], obj=cli_context)
+
+        assert result.exit_code == 0
+        assert "--include-beta" in result.output
+
+    def test_scan_accepts_include_beta_flag(
+        self, cli_context_with_scan, sample_devices, mock_scan_interactor
+    ):
+        mock_scan_interactor.execute.return_value = sample_devices
+
+        runner = CliRunner()
+        result = runner.invoke(
+            device_commands,
+            ["scan", "192.168.1.1-50", "--include-beta"],
+            obj=cli_context_with_scan,
+        )
+
+        assert result.exit_code == 0
+        mock_scan_interactor.execute.assert_called_once()
+
 
 class TestListCommand:
 
@@ -178,6 +200,28 @@ def test_list_no_devices(self, cli_context_with_list, mock_scan_interactor):
         assert result.exit_code == 0
         mock_scan_interactor.execute.assert_called_once()
 
+    def test_list_help_documents_include_beta(self, cli_context):
+        runner = CliRunner()
+        result = runner.invoke(device_commands, ["list", "--help"], obj=cli_context)
+
+        assert result.exit_code == 0
+        assert "--include-beta" in result.output
+
+    def test_list_accepts_include_beta_flag(
+        self, cli_context_with_list, sample_devices, mock_scan_interactor
+    ):
+        mock_scan_interactor.execute.return_value = sample_devices
+
+        runner = CliRunner()
+        result = runner.invoke(
+            device_commands,
+            ["list", "10.0.0.1", "--include-beta"],
+            obj=cli_context_with_list,
+        )
+
+        assert result.exit_code == 0
+        mock_scan_interactor.execute.assert_called_once()
+
 
 class TestStatusCommand:
 
@@ -296,6 +340,34 @@ def test_status_verbose_error_output(
         assert result.exit_code == 0
         mock_status_interactor.execute.assert_called_once()
 
+    def test_status_help_documents_include_beta(self, cli_context):
+        runner = CliRunner()
+        result = runner.invoke(device_commands, ["status", "--help"], obj=cli_context)
+
+        assert result.exit_code == 0
+        assert "--include-beta" in result.output
+
+    def test_status_accepts_include_beta_flag(
+        self,
+        cli_context_with_status,
+        mock_status_interactor,
+        mock_scan_interactor_for_status,
+        sample_devices,
+        sample_device,
+    ):
+        mock_scan_interactor_for_status.execute.return_value = sample_devices
+        mock_status_interactor.execute.return_value = sample_device
+
+        runner = CliRunner()
+        result = runner.invoke(
+            device_commands,
+            ["status", "192.168.1.100", "192.168.1.101", "--include-beta"],
+            obj=cli_context_with_status,
+        )
+
+        assert result.exit_code == 0
+        assert mock_status_interactor.execute.call_count == 2
+
 
 class TestDeviceRebootCommand: