unifi_climgr.py

#!/usr/bin/python3
# SPDX-License-Identifier: GPL-3.0-or-later
# Copyright (C) 2025 netcon-sync contributors
#
# This file is part of netcon-sync.
# netcon-sync is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.

"""UniFi network management CLI - comprehensive client and network management."""

import os
import sys

import argparse
import json
import time
import tarfile
import shutil
import re
from datetime import datetime, timedelta
from collections import defaultdict
from pathlib import Path
from threading import Lock
from concurrent.futures import ThreadPoolExecutor, as_completed
# Import shared modules - config might fail if env vars are missing
UNIFI_NETWORK_URL = None
UNIFI_SITE_ID = None
_config_error = None

try:
    import nss.error
    import paramiko
    from scp import SCPClient
    import unifi_utils
    from config import UNIFI_NETWORK_URL, UNIFI_SITE_ID, DEFAULT_DOMAIN
    from trust import handle_trust_server_url, handle_trust_ca_cert, format_nss_error, ensure_nss_db
    from urllib.parse import urlparse
except ModuleNotFoundError as e:
    print(f"ERROR: Missing required dependency: {e}")
    print("\nPlease run the setup script:")
    print("  ./install_deps.sh")
    sys.exit(1)
except ValueError as e:
    # Store config error - we'll show help + error in main()
    _config_error = e
    UNIFI_NETWORK_URL = None
    UNIFI_SITE_ID = None
    DEFAULT_DOMAIN = ""

# ==============================================================================
# COLUMN SCHEMAS - Centralized column definitions for clients and APs
# ==============================================================================

# Client columns
CLIENT_COLUMN_SCHEMA = {
    "mac": ("MAC Address", 17),
    "hostname": ("Hostname", 10),
    "vendor": ("Vendor", 20),
    "description": ("Description", 10),
    "status": ("Status", 8),
    "ip": ("IP Address", 15),
    "dns_name": ("DNS Name", 10),
    "uptime": ("Uptime", 12),
    "connected_ap_name": ("AP", 10),
    "connected_ap_mac": ("AP MAC", 10),
    "channel": ("Channel", 8),
    "band": ("Band", 8),
    "wifi_generation": ("WiFi", 5),
    "ieee_version": ("IEEE", 6),
    "ssid": ("SSID", 20),
    "signal": ("Signal", 7),
    "retries": ("Retries", 9),
    "locked": ("Locked", 7),
    "locked_ap_name": ("Locked AP", 10),
    "locked_ap_mac": ("Locked AP MAC", 17),
    "last_seen": ("Last Seen", 11),
}

CLIENT_COLUMN_NAMES = list(CLIENT_COLUMN_SCHEMA.keys())

# Default columns for client listing (used when no +/- switches provided)
DEFAULT_CLIENT_COLUMNS = ["description", "mac", "status", "last_seen", "ip", "connected_ap_name", "signal", "locked"]

# AP columns
AP_COLUMN_SCHEMA = {
    "name": ("Device Name", 15),
    "mac": ("MAC Address", 17),
    "ip": ("IP Address", 15),
    "version": ("Firmware", 10),
    "uptime": ("Uptime", 12),
    "state": ("State", 20),
    "connection": ("Connection", 10),
    "enabled": ("Enabled", 9),
    "uplink_ap_name": ("Uplink AP Name", 15),
    "uplink_ap_mac": ("Uplink AP MAC", 17),
}

AP_COLUMN_NAMES = list(AP_COLUMN_SCHEMA.keys())

# SSID columns
SSID_COLUMN_SCHEMA = {
    "name": ("SSID Name", 20),
    "enabled": ("Enabled", 9),
    "security": ("Security", 10),
    "band": ("Band", 15),
}

SSID_COLUMN_NAMES = list(SSID_COLUMN_SCHEMA.keys())

# Legacy reference for backward compatibility
COLUMN_SCHEMA = CLIENT_COLUMN_SCHEMA
ALL_COLUMN_NAMES = CLIENT_COLUMN_NAMES

# ==============================================================================
# AP LOG COLLECTION FUNCTIONS
# ==============================================================================

# Thread-safe print lock for parallel operations
print_lock = Lock()


def get_ssh_credentials():
    """
    Retrieve SSH credentials from UniFi controller.

    Returns:
        tuple: (username, password) or (None, None) if not found
    """
    endpoint = f"/api/s/{UNIFI_SITE_ID}/rest/setting/mgmt"
    try:
        settings = unifi_utils.make_unifi_api_call("GET", endpoint)
        if isinstance(settings, dict) and 'data' in settings:
            settings = settings['data']

        if isinstance(settings, list) and len(settings) > 0:
            mgmt_settings = settings[0]
            username = mgmt_settings.get('x_ssh_username', 'ubnt')
            password = mgmt_settings.get('x_ssh_password', '')

            if username and password:
                print("[OK] Retrieved SSH credentials")
                return username, password
    except Exception as e:
        print(f"Warning: Could not retrieve SSH credentials from settings: {e}")

    # Fallback: try sysinfo endpoint
    endpoint = f"/api/s/{UNIFI_SITE_ID}/stat/sysinfo"
    try:
        sysinfo = unifi_utils.make_unifi_api_call("GET", endpoint)
        if isinstance(sysinfo, dict) and 'data' in sysinfo:
            sysinfo_data = sysinfo['data'][0] if isinstance(sysinfo['data'], list) else sysinfo['data']
            username = sysinfo_data.get('x_ssh_username', 'ubnt')
            password = sysinfo_data.get('x_ssh_password', '')

            if username and password:
                print("[OK] Retrieved SSH credentials from sysinfo")
                return username, password
    except Exception as e:
        print(f"Warning: Could not retrieve SSH credentials from sysinfo: {e}")

    return None, None


def collect_ap_support_bundle(ssh_client, ap_name):
    """
    Generate support bundle on AP using 'supp' command.

    Args:
        ssh_client: Active SSH client connection
        ap_name: AP name for logging

    Returns:
        tuple: (success, bundle_path, size_str) or (False, None, None)
    """
    try:
        print(f"[{ap_name}] Generating support info bundle...")
        print(f"[{ap_name}]   Trying 'supp' command...")

        start_time = time.time()
        stdin, stdout, stderr = ssh_client.exec_command('supp', timeout=120)
        output = stdout.read().decode('utf-8', errors='replace')
        stderr.read()  # Consume stderr
        elapsed = time.time() - start_time

        print(f"[{ap_name}]   supp command took {elapsed:.1f} seconds")

        # Check if file exists
        stdin, stdout, stderr = ssh_client.exec_command('ls -lh /tmp/support.tgz')
        ls_stdout = stdout.read().decode('utf-8')

        if 'support.tgz' in ls_stdout:
            size_match = re.search(r'(\d+(?:\.\d+)?[KMG]?)\s+\w+\s+\d+\s+[\d:]+\s+/tmp/support\.tgz', ls_stdout)
            size_str = size_match.group(1) if size_match else 'unknown size'
            print(f"[{ap_name}] [OK] Support bundle generated: /tmp/support.tgz ({size_str})")
            return True, '/tmp/support.tgz', size_str
        else:
            print(f"[{ap_name}]   supp: file not found after command completed")
            return False, None, None

    except Exception as e:
        print(f"[{ap_name}]   supp command failed: {e}")
        return False, None, None


def collect_logs_from_ap(ap_ip, ap_name, ap_mac, ssh_username, ssh_password, output_dir, timeout=60):
    """
    Collect diagnostic logs from a single AP via SSH/SCP.

    Args:
        ap_ip: AP IP address
        ap_name: AP display name
        ap_mac: AP MAC address
        ssh_username: SSH username
        ssh_password: SSH password
        output_dir: Local directory to save files
        timeout: SSH timeout in seconds

    Returns:
        dict: Collection result with success status, files, errors, timing
    """
    result = {
        'success': False,
        'ap_name': ap_name,
        'ap_mac': ap_mac,
        'ap_ip': ap_ip,
        'files': [],
        'error': None,
        'elapsed_time': 0,
        'start_timestamp': None,
        'end_timestamp': None
    }

    ssh_client = None
    start_time = time.time()
    start_timestamp = time.strftime('%Y-%m-%d %H:%M:%S')
    result['start_timestamp'] = start_timestamp

    # Create AP-specific directory
    safe_ap_name = ap_name.replace('/', '_').replace(' ', '_')
    ap_dir = output_dir / f"{safe_ap_name}_{ap_mac.replace(':', '-')}"
    ap_dir.mkdir(parents=True, exist_ok=True)

    try:
        with print_lock:
            print(f"\n{'='*60}")
            print(f"[{ap_name}] [{start_timestamp}] Connecting to {ap_ip}...")

        ssh_client = paramiko.SSHClient()
        ssh_client.set_missing_host_key_policy(paramiko.AutoAddPolicy())

        try:
            ssh_client.connect(
                hostname=ap_ip,
                username=ssh_username,
                password=ssh_password,
                timeout=timeout,
                allow_agent=False,
                look_for_keys=False,
                banner_timeout=30  # Increase banner timeout for slow APs
            )
        except paramiko.ssh_exception.AuthenticationException as e:
            result['error'] = f"Authentication failed: {e}"
            with print_lock:
                print(f"[{ap_name}] [FAIL] Authentication failed")
                print(f"[{ap_name}] Check: Settings > System > Advanced > Device SSH Authentication")
            return result
        except paramiko.ssh_exception.NoValidConnectionsError as e:
            result['error'] = f"SSH connection refused: {e}"
            with print_lock:
                print(f"[{ap_name}] [FAIL] SSH connection refused on port 22")
                print(f"[{ap_name}] Possible causes:")
                print(f"[{ap_name}]   - SSH not enabled on controller")
                print(f"[{ap_name}]   - AP firmware doesn't support SSH")
                print(f"[{ap_name}]   - Firewall blocking port 22")
            return result
        except paramiko.ssh_exception.SSHException as e:
            result['error'] = f"SSH protocol error: {e}"
            with print_lock:
                print(f"[{ap_name}] [FAIL] SSH protocol error: {e}")
            return result
        except Exception as e:
            result['error'] = f"SSH connection error: {e}"
            with print_lock:
                print(f"[{ap_name}] [FAIL] SSH connection error: {e}")
            return result

        with print_lock:
            print(f"[{ap_name}] [OK] Connected")

        # Generate support bundle
        success, bundle_path, size_str = collect_ap_support_bundle(ssh_client, ap_name)

        if success and bundle_path:
            # Download via SCP
            local_path = ap_dir / Path(bundle_path).name
            with print_lock:
                print(f"[{ap_name}]   Downloading {Path(bundle_path).name} ({size_str})...", end="", flush=True)

            try:
                with SCPClient(ssh_client.get_transport()) as scp:
                    scp.get(bundle_path, str(local_path))

                actual_size = local_path.stat().st_size
                with print_lock:
                    print(f" [OK]")

                result['files'].append({
                    'remote_path': bundle_path,
                    'local_path': str(local_path),
                    'size': actual_size,
                    'type': 'support_bundle'
                })

                # Clean up remote file
                try:
                    stdin, stdout, stderr = ssh_client.exec_command(f'rm -f {bundle_path}')
                    stdout.read()
                except:
                    pass
            except Exception as e:
                with print_lock:
                    print(f" [FAIL]: {e}")

        # Collect log files from /var/log/
        with print_lock:
            print(f"[{ap_name}] Collecting individual log files...")

        stdin, stdout, stderr = ssh_client.exec_command(
            r'find /var/log -type f \( -name "*.log" -o -name "messages" -o -name "syslog" \) 2>/dev/null | head -20'
        )
        log_files = stdout.read().decode('utf-8').strip().split('\n')
        log_files = [f.strip() for f in log_files if f.strip()]

        if log_files:
            with print_lock:
                print(f"[{ap_name}] Found {len(log_files)} log file(s)")

            for remote_path in log_files:
                filename = Path(remote_path).name
                local_path = ap_dir / filename

                if local_path.exists():
                    continue

                with print_lock:
                    print(f"[{ap_name}]   Downloading {filename}...", end="", flush=True)

                try:
                    with SCPClient(ssh_client.get_transport()) as scp:
                        scp.get(remote_path, str(local_path))

                    actual_size = local_path.stat().st_size
                    with print_lock:
                        print(f" [OK] ({actual_size:,} bytes)")

                    result['files'].append({
                        'remote_path': remote_path,
                        'local_path': str(local_path),
                        'size': actual_size,
                        'type': 'log_file'
                    })
                except Exception as e:
                    with print_lock:
                        print(f" [FAIL]: {e}")

        if result['files']:
            result['success'] = True
            with print_lock:
                print(f"[{ap_name}] [OK] Downloaded {len(result['files'])} file(s) to {ap_dir}")
        else:
            result['error'] = "No log files collected"
            with print_lock:
                print(f"[{ap_name}] WARNING: No log files were collected")

    except Exception as e:
        result['error'] = str(e)
        with print_lock:
            print(f"[{ap_name}] [FAIL] Error: {e}")
    finally:
        if ssh_client:
            try:
                ssh_client.close()
            except:
                pass

        result['elapsed_time'] = time.time() - start_time
        completion_timestamp = time.strftime('%Y-%m-%d %H:%M:%S')
        result['end_timestamp'] = completion_timestamp

        with print_lock:
            if result['success']:
                print(f"[{ap_name}] [{completion_timestamp}] [OK] Completed in {result['elapsed_time']:.1f}s")
            else:
                print(f"[{ap_name}] [{completion_timestamp}] [FAIL] Failed after {result['elapsed_time']:.1f}s")

    return result


def collect_controller_support_file(output_dir):
    """
    Collect support file from UniFi controller.

    Args:
        output_dir: Directory to save the support file

    Returns:
        dict: Result with success status, file path, size, timing
    """
    result = {
        'success': False,
        'file_path': None,
        'size': 0,
        'error': None,
        'elapsed_time': 0,
        'start_timestamp': None,
        'end_timestamp': None
    }

    start_time = time.time()
    start_timestamp = time.strftime('%Y-%m-%d %H:%M:%S')
    result['start_timestamp'] = start_timestamp

    try:
        with print_lock:
            print(f"\n[CONTROLLER] [{start_timestamp}] Generating network support file...")

        # Trigger support file generation
        # UniFi Network 10.x changed the command format
        endpoint = f'/api/s/{UNIFI_SITE_ID}/cmd/system'
        payload = {
            'cmd': 'support',
            'userAgent': 'unifi-climgr/1.0',
            'language': 'en-US'
        }

        try:
            response = unifi_utils.make_unifi_api_call('POST', endpoint, json=payload)
            with print_lock:
                print("[CONTROLLER] [OK] Support file generation initiated")
                # Debug: show response to understand controller behavior
                if response:
                    print(f"[CONTROLLER] Response: {response}")
        except Exception as e:
            result['error'] = f"Failed to initiate support file generation: {e}"
            with print_lock:
                print(f"[CONTROLLER] [FAIL] Failed to initiate generation: {e}")
            result['elapsed_time'] = time.time() - start_time
            return result

        # Get controller version for diagnostics
        try:
            status_endpoint = f'/api/s/{UNIFI_SITE_ID}/stat/sysinfo'
            status = unifi_utils.make_unifi_api_call('GET', status_endpoint)
            if isinstance(status, list) and len(status) > 0:
                sysinfo = status[0]
                version = sysinfo.get('version', 'unknown')
                with print_lock:
                    print(f"[CONTROLLER] Detected UniFi Network version: {version}")
        except Exception as e:
            with print_lock:
                print(f"[CONTROLLER] Could not get version info: {e}")

        # Download the support file - try multiple endpoints (controllers have different paths across versions)
        # After controller upgrades, generation may be synchronous, so try download immediately
        # Modern controllers (v8+) use /dl/support as primary endpoint
        download_urls = [
            '/dl/support',                               # Primary endpoint (works with modern controllers)
            f'/api/s/{UNIFI_SITE_ID}/dl/support',       # Alternative API path
            f'/api/s/{UNIFI_SITE_ID}/dl/support.tar.gz', # Explicit filename
            '/dl/support.tar.gz',                        # Legacy with filename
            f'/proxy/network/api/s/{UNIFI_SITE_ID}/dl/support', # UniFi OS path (UDM/UDR)
            f'/proxy/network/dl/support',                # UniFi OS simplified
            f'/api/download/support',                    # Alternative API path
            f'/dl/autobackup/support.tar.gz',            # Autobackup path (some versions)
        ]

        timestamp = time.strftime('%Y%m%d-%H%M%S')
        filename = f"controller_support_{timestamp}.tar.gz"
        file_path = output_dir / filename

        download_success = False
        total_bytes = 0

        # Try each endpoint with brief retries in case generation needs a moment
        # Modern controllers generate synchronously, so usually works on first try
        max_retries = 2
        retry_delay = 3  # Wait 3 seconds between retries if needed

        for retry in range(max_retries):
            if download_success:
                break

            if retry > 0:
                with print_lock:
                    print(f"[CONTROLLER] Retry {retry}/{max_retries-1} after {retry_delay}s delay...")
                time.sleep(retry_delay)

            for url in download_urls:
                try:
                    with print_lock:
                        print(f"[CONTROLLER] Trying download URL: {url}")
                        sys.stdout.flush()

                    download_start = time.time()
                    total_bytes = 0  # Reset for this attempt

                    response = unifi_utils.make_unifi_api_call('GET', url, stream=True)

                    chunk_size = 1024 * 1024  # 1MB chunks
                    with open(file_path, 'wb') as f:
                        while True:
                            chunk = response.read(chunk_size)
                            if not chunk:
                                break
                            f.write(chunk)
                            total_bytes += len(chunk)

                    response.close()

                    # Validate downloaded file (support files should be at least 100KB)
                    if total_bytes < 102400:
                        raise Exception(f"Downloaded file too small ({total_bytes} bytes), likely not a valid support file")

                    download_time = time.time() - download_start
                    speed_mbps = (total_bytes / (1024 * 1024)) / download_time if download_time > 0 else 0

                    with print_lock:
                        print(f"[CONTROLLER] [OK] Downloaded support file ({total_bytes} bytes) in {download_time:.1f}s ({speed_mbps:.1f} MB/s)")
                        sys.stdout.flush()

                    download_success = True
                    break
                except Exception as e:
                    error_msg = str(e)
                    with print_lock:
                        print(f"[CONTROLLER]   Failed: {error_msg}")
                        sys.stdout.flush()
                    if file_path.exists():
                        file_path.unlink()
                    continue

        if not download_success:
            attempted_urls = '\n    '.join(download_urls)
            result['error'] = f"Could not download support file from any known endpoint.\nAttempted URLs:\n    {attempted_urls}\n\nYou can manually download the support file from:\nSettings > System > Maintenance > Download Support File"
            with print_lock:
                print(f"[CONTROLLER] [FAIL] Could not download support file from any endpoint")
                print(f"[CONTROLLER] Attempted {len(download_urls)} different endpoints across {max_retries} retries")
                print(f"[CONTROLLER] You can manually download from: Settings > System > Maintenance > Download Support File")
            result['elapsed_time'] = time.time() - start_time
            return result

        result['success'] = True
        result['file_path'] = str(file_path)
        result['size'] = total_bytes
        result['elapsed_time'] = time.time() - start_time

        size_mb = total_bytes / (1024 * 1024)
        with print_lock:
            print(f"[CONTROLLER] [OK] Saved to {filename} ({size_mb:.1f} MB)")
            sys.stdout.flush()

    except Exception as e:
        result['error'] = f"Unexpected error: {e}"
        with print_lock:
            print(f"[CONTROLLER] [FAIL] Error: {e}")

    if result['elapsed_time'] == 0:
        result['elapsed_time'] = time.time() - start_time

    completion_timestamp = time.strftime('%Y-%m-%d %H:%M:%S')
    result['end_timestamp'] = completion_timestamp

    with print_lock:
        if result['success']:
            print(f"[CONTROLLER] [{completion_timestamp}] [OK] Completed in {result['elapsed_time']:.1f}s")
        else:
            print(f"[CONTROLLER] [{completion_timestamp}] [FAIL] Failed after {result['elapsed_time']:.1f}s")

    return result


def collect_all_ap_logs(output_dir, aps, ssh_username, ssh_password, parallel=0, timeout=60, include_controller=True):
    """
    Collect logs from multiple APs in parallel.

    Args:
        output_dir: Base output directory
        aps: List of AP dictionaries from UniFi API
        ssh_username: SSH username
        ssh_password: SSH password
        parallel: Number of parallel workers (0 = unlimited)
        timeout: SSH timeout in seconds
        include_controller: Whether to collect controller support file

    Returns:
        tuple: (ap_results, controller_result, collection_info)
    """
    # Create unique collection subdirectory
    timestamp = time.strftime('%Y%m%d-%H%M%S')
    collection_dir = output_dir / f"collection_{timestamp}"
    collection_dir.mkdir(parents=True, exist_ok=True)

    print(f"Output directory: {output_dir.absolute()}")
    print(f"Collection directory: {collection_dir.name}\n")

    collection_start_time = time.time()
    collection_start_timestamp = time.strftime('%Y-%m-%d %H:%M:%S')

    # Determine worker count
    if parallel > 0:
        max_workers = parallel + 1  # +1 for controller
    else:
        max_workers = len(aps) + 1  # All APs + controller

    print(f"Using parallel collection with {max_workers} worker(s)\n")

    results = []

    def collect_with_info(ap_info):
        i, total, ap = ap_info
        ap_name = ap.get("name", "Unknown")
        ap_mac = ap.get("mac", "unknown")
        ap_ip = ap.get("ip")
        ap_state = unifi_utils.get_ap_state(ap_mac)

        with print_lock:
            print(f"{'='*60}")
            print(f"[{i}/{total}] {ap_name} ({ap_ip}) - {ap_state}")
            print(f"{'='*60}\n")

        if not ap_ip:
            with print_lock:
                print(f"WARNING: Skipping {ap_name}: No IP address")
            return {
                'ap_name': ap_name,
                'success': False,
                'error': 'No IP address'
            }

        return collect_logs_from_ap(
            ap_ip=ap_ip,
            ap_name=ap_name,
            ap_mac=ap_mac,
            ssh_username=ssh_username,
            ssh_password=ssh_password,
            output_dir=collection_dir,
            timeout=timeout
        )

    # Execute parallel collection
    ap_infos = [(i, len(aps), ap) for i, ap in enumerate(aps, 1)]

    with ThreadPoolExecutor(max_workers=max_workers) as executor:
        # Submit controller task if requested
        controller_future = None
        if include_controller:
            controller_future = executor.submit(collect_controller_support_file, collection_dir)

        # Submit all AP tasks
        future_to_ap = {executor.submit(collect_with_info, ap_info): ap_info for ap_info in ap_infos}

        # Collect AP results as they complete
        for future in as_completed(future_to_ap):
            result = future.result()
            results.append(result)

        # Wait for controller result
        controller_result = controller_future.result() if controller_future else None

    collection_end_time = time.time()
    collection_end_timestamp = time.strftime('%Y-%m-%d %H:%M:%S')
    collection_elapsed = collection_end_time - collection_start_time

    collection_info = {
        'start_timestamp': collection_start_timestamp,
        'end_timestamp': collection_end_timestamp,
        'elapsed_time': collection_elapsed,
        'collection_dir': collection_dir,
        'timestamp': timestamp
    }

    return results, controller_result, collection_info


# ==============================================================================
# HELPER FUNCTIONS
# ==============================================================================

def _strip_default_domain(dns_name: str, default_domain: str = "") -> str:
    """
    Strip default domain suffix from DNS name to make it narrower.
    E.g., if default_domain is "example.com", "host.example.com" becomes "host"
    """
    if not dns_name or dns_name in ["N/A", "No reverse DNS"]:
        return dns_name

    if default_domain and dns_name.endswith("." + default_domain):
        return dns_name[: -(len(default_domain) + 1)]

    return dns_name

def _build_client_row(client: dict) -> dict:
    """
    Build a display row for a single client.
    Consolidates all display value transformations in one place.
    Returns a dict with all column values ready for display.
    """
    status_text = "Online" if client.get("is_connected_live", False) else "Offline"
    signal_display = (
        str(client.get('live_signal'))
        if client.get('is_connected_live') and client.get('live_signal') is not None
        else "N/A"
    )
    tx_retries_display = (
        str(client.get('tx_retries'))
        if client.get('is_connected_live') and client.get('tx_retries') is not None
        else "N/A"
    )
    locked_ap_status_display = "Yes" if client.get("is_ap_locked", False) else "No"

    # Format uptime for online clients
    uptime_display = "N/A"
    if client.get("is_connected_live") and client.get("live_uptime") is not None:
        uptime_seconds = client.get("live_uptime")
        try:
            uptime_display = _format_uptime(int(uptime_seconds))
        except (TypeError, ValueError):
            uptime_display = "N/A"

    # Normalize MAC addresses to lowercase
    locked_ap_mac_val = client.get("locked_ap_mac", "N/A")
    locked_ap_mac_display = locked_ap_mac_val.lower() if locked_ap_mac_val != "N/A" else "N/A"
    live_ap_mac_val = client.get("live_ap_mac", "N/A")
    live_ap_mac_display = live_ap_mac_val.lower() if live_ap_mac_val != "N/A" else "N/A"

    return {
        "mac": client.get("mac", "N/A").lower() if client.get("mac") else "N/A",
        "hostname": client.get("hostname") or "Unknown Host",
        "vendor": client.get("oui", "N/A"),
        "description": client.get("description", "N/A"),
        "status": status_text,
        "ip": client.get("display_ip", "N/A"),
        "dns_name": client.get("dns_name", "N/A"),
        "uptime": uptime_display,
        "connected_ap_name": client.get("connected_ap_name", "N/A"),
        "connected_ap_mac": live_ap_mac_display,
        "channel": client.get("live_channel", "N/A") if client.get("is_connected_live") else "N/A",
        "band": client.get("live_band", "N/A") if client.get("is_connected_live") else "N/A",
        "wifi_generation": client.get("live_wifi_generation", "N/A") if client.get("is_connected_live") else "N/A",
        "ieee_version": client.get("live_ieee_version", "N/A") if client.get("is_connected_live") else "N/A",
        "ssid": client.get("live_ssid", "N/A") if client.get("is_connected_live") else "N/A",
        "signal": signal_display,
        "retries": tx_retries_display,
        "locked": locked_ap_status_display,
        "locked_ap_name": client.get("locked_ap_name", "N/A"),
        "locked_ap_mac": locked_ap_mac_display,
        "last_seen": client.get("last_seen_formatted", "N/A"),
    }

def _format_security_display(ssid: dict) -> str:
    """
    Convert UniFi security info to human-readable format.
    Uses wpa_mode field to determine WPA version, handles WPA2/WPA3 transitions.
    """
    # Check for WPA2/WPA3 transition (mutual support)
    if ssid.get("wpa3_transition", False):
        return "WPA2/WPA3"

    # Get WPA mode (wpa, wpa2, wpa3, open, etc.)
    wpa_mode = ssid.get("wpa_mode", "").lower()

    # Direct mapping of wpa_mode values
    wpa_mode_map = {
        "wpa": "WPA",
        "wpa2": "WPA2",
        "wpa3": "WPA3",
        "open": "Open",
        "": "Open",
    }

    if wpa_mode in wpa_mode_map:
        return wpa_mode_map[wpa_mode]

    # Fallback to security field if wpa_mode is not recognized
    security_raw = ssid.get("security", "")
    if not security_raw:
        return "Open"

    sec_lower = security_raw.lower()

    security_map = {
        "open": "Open",
        "wpapsk": "WPA",
        "wpa2psk": "WPA2",
        "wpa3psk": "WPA3",
        "wep": "WEP",
    }

    if sec_lower in security_map:
        return security_map[sec_lower]

    # Fallback: capitalize if unknown
    return security_raw.upper()

def _calculate_mesh_hops(ap: dict, all_devices: list) -> int:
    """
    Calculate the number of mesh hops for an AP.
    Hops = number of AP-to-AP mesh connections from this AP to a wired AP.

    For example:
    - Wired AP = 0 hops
    - AP connected directly to wired AP = 1 hop
    - AP connected to an AP that is connected to wired = 2 hops
    - etc.

    Returns the hop count, or 0 if unable to determine.
    """
    visited = set()  # Prevent infinite loops
    current_ap = ap
    hop_count = 0

    while True:
        # Check if current AP is wired
        is_wired = current_ap.get('wired')
        if is_wired is True:
            return hop_count

        raw_uplink_type = current_ap.get('uplink', {}).get('type')
        if raw_uplink_type == 'wire':
            return hop_count

        # Get the uplink AP MAC
        uplink_mac = current_ap.get('uplink_ap_mac') or current_ap.get('last_uplink', {}).get('uplink_mac')

        if not uplink_mac or uplink_mac == "N/A":
            # No uplink found, return what we have
            return hop_count

        # Prevent infinite loops
        if uplink_mac in visited:
            return hop_count
        visited.add(uplink_mac)

        # Find the uplink AP device
        uplink_ap = None
        for device in all_devices:
            if device.get('mac') == uplink_mac and device.get('type') == 'uap':
                uplink_ap = device
                break

        if not uplink_ap:
            # Can't find the uplink AP, return what we have
            return hop_count

        # Move to uplink AP and increment hop count
        current_ap = uplink_ap
        hop_count += 1

def _build_ssid_row(ssid: dict) -> dict:
    """
    Build a display row for a single SSID.
    Returns a dict with all column values ready for display.

    Band is determined from wlan_bands field (array of "2g", "5g", "6g").
    Falls back to wlan_band if wlan_bands not available.
    Security is determined from wpa_mode with fallback to security field.
    """
    enabled_display = "Yes" if ssid.get("enabled", False) else "No"
    security_display = _format_security_display(ssid)

    # Get band from wlan_bands array or wlan_band string
    bands = []
    wlan_bands = ssid.get("wlan_bands", [])

    if wlan_bands:
        # wlan_bands is an array like ["5g"] or ["2g", "5g"]
        for band in wlan_bands:
            if band.lower() == "2g":
                bands.append("2.4GHz")
            elif band.lower() == "5g":
                bands.append("5GHz")
            elif band.lower() == "6g":
                bands.append("6GHz")
    else:
        # Fallback to wlan_band single string
        wlan_band = ssid.get("wlan_band", "").lower()
        if wlan_band == "2g":
            bands.append("2.4GHz")
        elif wlan_band == "5g":
            bands.append("5GHz")
        elif wlan_band == "6g":
            bands.append("6GHz")

    band_display = ", ".join(bands) if bands else "N/A"

    return {
        "name": ssid.get("name", "N/A"),
        "enabled": enabled_display,
        "security": security_display,
        "band": band_display,
    }

def _format_uptime(uptime_seconds: int) -> str:
    """
    Format uptime in human-readable format: y m w d h:m:s
    Omits zero values until first non-zero, then shows all remaining values.
    Examples: "4d 2h:03m:45s", "1y 2m 3d 4h:05m:06s", "45s"
    """
    if not uptime_seconds or uptime_seconds <= 0:
        return "N/A"

    # Calculate time units
    total_seconds = uptime_seconds
    years = total_seconds // (365 * 86400)
    total_seconds %= (365 * 86400)
    months = total_seconds // (30 * 86400)
    total_seconds %= (30 * 86400)
    weeks = total_seconds // (7 * 86400)
    total_seconds %= (7 * 86400)
    days = total_seconds // 86400
    total_seconds %= 86400
    hours = total_seconds // 3600
    total_seconds %= 3600
    minutes = total_seconds // 60
    secs = total_seconds % 60

    # List of (value, unit) tuples in order from longest to shortest
    units = [
        (years, "y"),
        (months, "m"),
        (weeks, "w"),
        (days, "d"),
    ]

    # Find first non-zero unit
    started = False
    parts = []

    for value, unit in units:
        if value > 0:
            started = True
        if started:
            parts.append(f"{value}{unit}")

    # Always show time component (h:m:s) if we've started or there's time left
    if started or hours > 0 or minutes > 0 or secs > 0:
        time_str = f"{hours}h:{minutes:02d}m:{secs:02d}s"
        # If nothing shown yet (only seconds), simplify
        if not started and hours == 0 and minutes == 0:
            return f"{secs}s"
        parts.append(time_str)

    return " ".join(parts) if parts else "0s"

def _build_ap_row(ap: dict, all_devices: list) -> dict:
    """
    Build a display row for a single AP.
    Consolidates all AP display value transformations in one place.
    """
    ap_name = ap.get("name") or ap.get("model", "Unknown AP")
    mac_address = ap.get("mac", "N/A")
    ip_address = ap.get("ip", "N/A")
    version = ap.get("version", "N/A")
    uptime_seconds = ap.get("uptime", 0)

    # Determine connection type (wired vs mesh)
    connection_type_display = "N/A"
    is_wired_status = ap.get('wired')

    if is_wired_status is True:
        connection_type_display = "wired"
    elif is_wired_status is False:
        connection_type_display = "mesh"
    else:
        raw_uplink_type = ap.get('uplink', {}).get('type')
        if raw_uplink_type == 'wire':
            connection_type_display = "wired"
        elif raw_uplink_type in ['mesh', 'wireless']:
            connection_type_display = "mesh"

    # For mesh APs, calculate hop count
    if connection_type_display == "mesh":
        hops = _calculate_mesh_hops(ap, all_devices)
        hop_label = "hop" if hops == 1 else "hops"
        connection_type_display = f"mesh ({hops}-{hop_label})"

    # Determine uplink AP name and MAC for mesh APs
    uplink_ap_name_display = "N/A"
    uplink_ap_mac_display = "N/A"

    if "mesh" in connection_type_display:
        uplink_mac = ap.get('uplink_ap_mac') or ap.get('last_uplink', {}).get('uplink_mac')

        if uplink_mac and uplink_mac != "N/A":
            uplink_ap_mac_display = uplink_mac
            # Look up the uplink AP's name
            for device in all_devices:
                if device.get('mac') == uplink_mac and device.get('type') == 'uap':
                    uplink_ap_name_display = device.get('name') or device.get('model', 'Unknown')
                    break
            else:
                uplink_ap_name_display = "Unknown"
        else:
            uplink_ap_name_display = "No Uplink"
            uplink_ap_mac_display = "No Uplink"

    # Format uptime using the new formatter
    uptime_str = _format_uptime(uptime_seconds)

    # Get AP state (returns string directly)
    state_desc = unifi_utils.get_ap_state(mac_address)

    return {
        "name": ap_name,
        "mac": mac_address,
        "ip": ip_address,
        "version": version,
        "uptime": uptime_str,
        "state": state_desc,
        "connection": connection_type_display,
        "enabled": "Yes" if not ap.get("disabled", False) else "No",
        "uplink_ap_name": uplink_ap_name_display,
        "uplink_ap_mac": uplink_ap_mac_display,
    }

def print_ssid_table(ssids: list, enabled_columns: list, reverse: bool = False):
    """
    Prints a formatted table of SSID data based on enabled columns.
    If reverse is True, sorts in descending order. N/A values always sort to the end.
    """
    # Build the list of columns to display
    display_column_definitions = []
    for col_key in enabled_columns:
        if col_key in SSID_COLUMN_SCHEMA:
            header, default_width = SSID_COLUMN_SCHEMA[col_key]
            display_column_definitions.append((header, col_key, default_width))

    if not display_column_definitions:
        print("Error: No columns are enabled for display.")
        return

    # Build all row data first
    all_row_data = []
    for ssid in ssids:
        all_row_data.append(_build_ssid_row(ssid))

    # Calculate dynamic column widths based on data
    max_widths = {header: max(len(header), default_width) for header, _, default_width in display_column_definitions}

    for row_data in all_row_data:
        for header, key_name, _ in display_column_definitions:
            val = str(row_data.get(key_name, "N/A"))
            max_widths[header] = max(max_widths[header], len(val))

    # Add padding to final widths
    final_widths = {h: w + 2 for h, w in max_widths.items()}
    total_width = sum(final_widths[h] for h, _, _ in display_column_definitions) + (len(display_column_definitions) * 3) - 3

    # Apply sorting when using column switches
    # Sort by first column primarily, with N/A values always at the end
    _apply_sort_with_na_at_end(all_row_data, lambda row: _get_multi_level_sort_key(row, display_column_definitions), reverse)

    # Print header
    print("-" * total_width)
    header_line = ""
    for header, _, _ in display_column_definitions:
        header_line += f"{header:<{final_widths[header]}} | "
    print(header_line.rstrip(" |"))
    print("-" * total_width)

    # Print data rows
    for row_data in all_row_data:
        data_line = ""
        for header, key_name, _ in display_column_definitions:
            val = str(row_data.get(key_name, "N/A"))
            width = final_widths[header]
            data_line += f"{val:<{width}.{width}} | "
        print(data_line.rstrip(" |"))

    print("-" * total_width)

def print_ap_table(aps: list, all_devices: list, enabled_columns: list, reverse: bool = False):
    """
    Prints a formatted table of AP data based on enabled columns.
    Dynamically removes uplink columns if all APs are wired.
    Column widths are set to max(header, longest_data) + 1 space.
    If reverse is True, sorts in descending order. N/A values always sort to the end.
    """
    if not aps:
        print("No APs to display")
        return

    # Check if all APs are wired (no mesh)
    all_wired = all(ap.get('wired') is True or ap.get('uplink', {}).get('type') == 'wire' for ap in aps)

    # Build the list of columns to display
    display_column_definitions = []
    for col_key in enabled_columns:
        # Skip uplink columns if all APs are wired
        if all_wired and col_key in ['uplink_ap_name', 'uplink_ap_mac']:
            continue

        if col_key in AP_COLUMN_SCHEMA:
            header, default_width = AP_COLUMN_SCHEMA[col_key]
            display_column_definitions.append((header, col_key, default_width))

    if not display_column_definitions:
        print("Error: No columns are enabled for display.")
        return

    # Build all row data first
    all_row_data = [_build_ap_row(ap, all_devices) for ap in aps]

    # Calculate dynamic column widths: max of header length and longest data value
    max_widths = {}
    for header, col_key, _ in display_column_definitions:
        header_len = len(header)
        # Find max length of data in this column
        data_len = max(len(str(row.get(col_key, "N/A"))) for row in all_row_data)
        max_widths[header] = max(header_len, data_len)

    # Add 1 space padding to final widths
    final_widths = {h: w + 1 for h, w in max_widths.items()}

    # Calculate total width: sum of column widths + separators (" | ")
    separator = " | "
    total_width = sum(final_widths[h] for h, _, _ in display_column_definitions) + (len(display_column_definitions) - 1) * len(separator)

    # Apply sorting when using column switches
    # Sort by first column primarily, with N/A values always at the end
    _apply_sort_with_na_at_end(all_row_data, lambda row: _get_multi_level_sort_key(row, display_column_definitions), reverse)

    # Print header
    print("-" * total_width)
    header_line = separator.join(f"{header:<{final_widths[header]}}" for header, _, _ in display_column_definitions)
    print(header_line)
    print("-" * total_width)

    # Print data rows
    for row_data in all_row_data:
        data_line = separator.join(
            f"{str(row_data.get(key_name, 'N/A')):<{final_widths[header]}}" 
            for header, key_name, _ in display_column_definitions
        )
        print(data_line)

    print("-" * total_width)

def _build_ap_branch_aps(target_ap: dict, all_devices: list) -> list:
    """
    Returns a list of APs representing the path from the root (wired AP) to the target AP.
    Used for displaying only the relevant branch when filtering a single mesh AP.
    """
    branch_aps = [target_ap]
    current_ap = target_ap

    # Walk up the chain to find all ancestors
    visited = set([current_ap.get('mac')])
    while True:
        uplink_mac = current_ap.get('uplink_ap_mac') or current_ap.get('last_uplink', {}).get('uplink_mac')
        if not uplink_mac or uplink_mac == "N/A":
            break

        # Prevent infinite loops
        if uplink_mac in visited:
            break
        visited.add(uplink_mac)

        # Find the uplink AP
        uplink_ap = None
        for device in all_devices:
            if device.get('mac') == uplink_mac and device.get('type') == 'uap':
                uplink_ap = device
                break

        if not uplink_ap:
            break

        branch_aps.insert(0, uplink_ap)

        # Check if this AP is wired
        is_wired = uplink_ap.get('wired') is True or uplink_ap.get('uplink', {}).get('type') == 'wire'
        if is_wired:
            break

        current_ap = uplink_ap

    return branch_aps

def serialize_ap_topology(aps: list) -> list:
    """
    Serialize AP topology to a simple list format for storage/transmission.
    Each entry is a dict with: {mac, uplink_mac, name}
    uplink_mac is None for wired root APs.

    Args:
        aps: List of AP devices from UniFi

    Returns:
        List of dicts: [{"mac": "xx:xx:...", "uplink_mac": "yy:yy:..." or None, "name": "AP Name"}, ...]
    """
    topology = []

    for ap in aps:
        ap_mac = ap.get('mac', '').lower() if ap.get('mac') else None
        if not ap_mac:
            continue

        ap_name = ap.get('name') or ap.get('model', 'Unknown AP')

        # Determine if this is a wired root AP
        is_wired = ap.get('wired') is True or ap.get('uplink', {}).get('type') == 'wire'

        if is_wired:
            uplink_mac = None
        else:
            # Get uplink MAC for mesh APs
            uplink_mac = ap.get('uplink_ap_mac') or ap.get('last_uplink', {}).get('uplink_mac')
            if uplink_mac:
                uplink_mac = uplink_mac.lower()

        topology.append({
            'mac': ap_mac,
            'uplink_mac': uplink_mac,
            'name': ap_name
        })

    return topology

def deserialize_ap_topology(topology: list) -> list:
    """
    Deserialize AP topology from simple list format back to AP objects.
    Each entry should be a dict with: {mac, uplink_mac, name}

    Args:
        topology: List of dicts with AP topology data

    Returns:
        List of AP dicts with minimal structure needed for display_ap_tree
    """
    aps = []

    for entry in topology:
        if not isinstance(entry, dict):
            continue

        mac = entry.get('mac', '').lower() if entry.get('mac') else None
        name = entry.get('name', 'Unknown AP')
        uplink_mac = entry.get('uplink_mac')

        if not mac:
            continue

        # Build minimal AP object for tree display
        ap_obj = {
            'mac': mac,
            'name': name,
            'model': name,  # Fallback to name if no separate model field
            'wired': uplink_mac is None,  # Root if no uplink
            'uplink_ap_mac': uplink_mac,
            'uplink': {
                'type': 'wire' if uplink_mac is None else 'mesh'
            }
        }

        aps.append(ap_obj)

    return aps

def ap_topology_to_json(aps: list) -> str:
    """
    Serialize AP topology to JSON string.

    Args:
        aps: List of AP devices from UniFi

    Returns:
        JSON string representing the topology
    """
    topology = serialize_ap_topology(aps)
    return json.dumps(topology, indent=2)

def ap_topology_from_json(json_str: str) -> list:
    """
    Deserialize AP topology from JSON string back to AP objects.

    Args:
        json_str: JSON string containing AP topology

    Returns:
        List of AP objects ready for display_ap_tree
    """
    try:
        topology = json.loads(json_str)
        if not isinstance(topology, list):
            return []
        return deserialize_ap_topology(topology)
    except (json.JSONDecodeError, TypeError):
        return []

def display_ap_tree(aps: list, all_devices: list = None, show_macs: bool = True):
    """
    Displays the AP network as a tree structure showing mesh topology.

    Args:
        aps: List of AP devices. Can be either:
            - Live AP data from UniFi (with fields: mac, name, wired, uplink_ap_mac, etc.)
            - Deserialized AP topology from deserialize_ap_topology()
        all_devices: List of all devices (optional, for reference)
        show_macs: If True, display MAC addresses for each AP (default: True)

    Examples:
        # Display from live UniFi data
        aps = unifi_utils.get_devices()
        display_ap_tree(aps, all_devices=aps)

        # Display from serialized topology
        topology = serialize_ap_topology(live_aps)
        # ... later, restore and display
        deserialized_aps = deserialize_ap_topology(topology)
        display_ap_tree(deserialized_aps, show_macs=True)
    """
    print("\n" + "="*80)
    print("## AP Network Tree View")
    print("="*80 + "\n")

    ap_by_mac = {ap['mac']: ap for ap in aps if 'mac' in ap}
    wired_roots = []
    mesh_children_map = defaultdict(list)
    printed_macs = set()

    # Classify APs as wired roots or mesh children. Some adopted APs are missing
    # an explicit wired marker even though they are clearly roots; however this
    # fallback must not apply to pending-adoption APs because they also lack
    # uplink data before topology is known.
    for ap in aps:
        connection_type = 'N/A'
        is_wired_status = ap.get('wired')
        uplink_mac = ap.get('uplink_ap_mac') or ap.get('last_uplink', {}).get('uplink_mac')
        raw_uplink_type = (
            ap.get('uplink', {}).get('type')
            or ap.get('last_uplink', {}).get('type')
        )
        is_fully_adopted = unifi_utils.is_ap_fully_adopted(ap)

        if is_wired_status is True:
            connection_type = 'wired'
        elif is_wired_status is False:
            connection_type = 'mesh'
        else:
            if raw_uplink_type == 'wire':
                connection_type = 'wired'
            elif raw_uplink_type in ['mesh', 'wireless']:
                connection_type = 'mesh'
            elif is_fully_adopted and (not uplink_mac or uplink_mac == 'N/A'):
                connection_type = 'wired'

        if connection_type == 'wired':
            wired_roots.append(ap)
        elif connection_type == 'mesh':
            if uplink_mac and uplink_mac != 'N/A' and uplink_mac in ap_by_mac:
                mesh_children_map[uplink_mac].append(ap)

    # Recursive function to print tree nodes
    def _print_node_recursive(ap_node, prefix=""):
        if ap_node['mac'] in printed_macs:
            return

        node_name = ap_node.get('name') or ap_node.get('model', 'Unknown AP')
        node_mac = ap_node.get('mac', 'N/A')

        if not prefix:  # Root node
            if show_macs:
                print(f"{node_name} ({node_mac}) - Wired Uplink")
            else:
                print(f"{node_name} (Wired Uplink)")
        else:
            if show_macs:
                print(f"{prefix}{node_name} ({node_mac})")
            else:
                print(f"{prefix}{node_name}")

        printed_macs.add(ap_node['mac'])

        children = mesh_children_map.get(ap_node['mac'], [])
        children.sort(key=lambda x: x.get('name', '').lower())

        for i, child in enumerate(children):
            is_last = (i == len(children) - 1)
            child_prefix_segment = "+-- " if is_last else "|-- "

            new_prefix = ""
            if not prefix:  # Direct children of root
                new_prefix = "  " + child_prefix_segment
            else:
                # Extend parent's prefix
                if prefix.endswith("|-- "):
                    new_prefix = prefix[:-4] + "|   " + child_prefix_segment
                elif prefix.endswith("+-- "):
                    new_prefix = prefix[:-4] + "    " + child_prefix_segment
                else:
                    new_prefix = prefix + child_prefix_segment

            _print_node_recursive(child, new_prefix)

    # Print the tree
    wired_roots.sort(key=lambda x: x.get('name', '').lower())

    if not wired_roots:
        print("No wired APs found. Network topology might be entirely mesh.")
    else:
        for root_ap in wired_roots:
            _print_node_recursive(root_ap)

    # Print orphan mesh APs
    orphan_mesh_aps = [
        ap for ap in aps
        if ap.get('mac') not in printed_macs and ap.get('wired') is False and
           (ap.get('uplink_ap_mac') or ap.get('last_uplink', {}).get('uplink_mac'))
    ]

    if orphan_mesh_aps:
        print("\n---")
        print("## Orphan Mesh APs (Uplink not traceable)")
        print("---")
        orphan_mesh_aps.sort(key=lambda x: x.get('name', '').lower())
        for ap in orphan_mesh_aps:
            ap_name = ap.get('name') or ap.get('model', 'Unknown AP')
            ap_mac = ap.get('mac', 'N/A')
            uplink_mac = ap.get('uplink_ap_mac') or ap.get('last_uplink', {}).get('uplink_mac', 'N/A')
            if show_macs:
                print(f"- {ap_name} ({ap_mac}), Uplink MAC: {uplink_mac}")
            else:
                print(f"- {ap_name} (Uplink MAC: {uplink_mac})")

    print("\n" + "="*80)

def calculate_ap_mesh_depths(aps: list) -> dict:
    """
    Calculate the depth of each AP in the mesh hierarchy (0 = wired root, 1+ = mesh children).
    Returns a dict mapping AP MAC addresses to their depths.
    """
    ap_by_mac = {ap.get('mac'): ap for ap in aps if ap.get('mac')}
    depths = {}

    # First pass: identify wired roots (depth 0)
    for ap in aps:
        is_wired = ap.get('wired')
        uplink_type = (
            ap.get('uplink', {}).get('type')
            or ap.get('last_uplink', {}).get('type')
        )
        uplink_mac = ap.get('uplink_ap_mac') or ap.get('last_uplink', {}).get('uplink_mac')
        is_fully_adopted = unifi_utils.is_ap_fully_adopted(ap)

        is_root = (
            is_wired is True
            or uplink_type == 'wire'
            or (
                is_fully_adopted
                and
                (not uplink_mac or uplink_mac == 'N/A')
                and uplink_type not in ['mesh', 'wireless']
            )
        )

        if is_root:
            depths[ap.get('mac')] = 0

    # Second pass: calculate depths for mesh APs using BFS (breadth-first search)
    # This ensures we get correct depths even in complex multi-layer mesh topologies
    max_iterations = len(aps)  # Prevent infinite loops
    iteration = 0

    while len(depths) < len(aps) and iteration < max_iterations:
        iteration += 1
        for ap in aps:
            ap_mac = ap.get('mac')
            if ap_mac in depths:
                continue  # Already calculated

            # Find parent AP
            uplink_mac = ap.get('uplink_ap_mac') or ap.get('last_uplink', {}).get('uplink_mac')

            if uplink_mac and uplink_mac in depths:
                # Parent depth is known, so this AP's depth is parent's depth + 1
                depths[ap_mac] = depths[uplink_mac] + 1

    # Any remaining APs without known uplink get depth -1 (orphans)
    for ap in aps:
        ap_mac = ap.get('mac')
        if ap_mac not in depths:
            depths[ap_mac] = -1

    return depths

def _wait_for_mesh_topology(desired_topology: list, timeout_minutes: int = 75):
    """
    Wait for mesh topology to rebuild to match desired state.

    Args:
        desired_topology: Target topology (serialized format from serialize_ap_topology)
                         List of dicts: [{"mac": "xx:xx:...", "uplink_mac": "yy:yy:..." or None, "name": "AP Name"}, ...]
        timeout_minutes: Maximum time to wait in minutes (default: 75 minutes)

    Process:
    1. Fetch current APs from UniFi and extract their topology
    2. Verify device list matches (same MACs)
    3. Display initial diff of desired vs current uplinks with parking status
    4. Monitor every 5 seconds for topology changes
    5. Report when APs move to new uplinks with elapsed time and parking status
    6. End when all APs are correctly parked
    7. Every minute with no activity, show parking statistics
    8. Timeout after specified time period
    """
    import time

    if not desired_topology:
        print("Error: No desired topology provided")
        sys.exit(1)

    # Extract desired MAC set from desired topology
    desired_macs = {entry['mac'].lower() if entry['mac'] else None for entry in desired_topology}
    desired_macs.discard(None)

    # Create lookup dicts for desired topology
    desired_by_mac = {}
    desired_names_by_mac = {}
    for entry in desired_topology:
        mac = entry.get('mac', '').lower() if entry.get('mac') else None
        if mac:
            desired_by_mac[mac] = entry.get('uplink_mac', '').lower() if entry.get('uplink_mac') else None
            desired_names_by_mac[mac] = entry.get('name', 'Unknown AP')

    print("\nValidating desired topology...")

    # Do an initial check to validate MAC/name consistency
    current_devices = unifi_utils.get_devices()
    current_aps = [d for d in current_devices if d.get("type") == "uap"]
    current_macs = {ap.get('mac', '').lower() for ap in current_aps if ap.get('mac')}

    # Check MAC set matches
    if current_macs != desired_macs:
        missing_macs = desired_macs - current_macs
        extra_macs = current_macs - desired_macs

        if missing_macs or extra_macs:
            print(f"\n[FAIL] Device list mismatch:")
            if missing_macs:
                print(f"  Missing APs in current system: {', '.join(sorted(missing_macs))}")
            if extra_macs:
                print(f"  Extra APs in current system: {', '.join(sorted(extra_macs))}")
            print("\nAborted: Cannot rebuild to desired topology when device set differs.")
            sys.exit(1)

    # Build current AP lookup with names
    current_names_by_mac = {}
    for ap in current_aps:
        mac = ap.get('mac', '').lower() if ap.get('mac') else None
        if mac:
            current_names_by_mac[mac] = ap.get('name') or ap.get('model', 'Unknown AP')

    # Validate that names match for all common MACs
    name_mismatches = []
    for mac in desired_macs:
        desired_name = desired_names_by_mac.get(mac, 'Unknown AP')
        current_name = current_names_by_mac.get(mac, 'Unknown AP')

        # Normalize names for comparison (case-insensitive comparison)
        if desired_name.lower() != current_name.lower():
            name_mismatches.append({
                'mac': mac,
                'desired': desired_name,
                'current': current_name
            })

    if name_mismatches:
        print(f"\n[FAIL] AP name mismatches detected:")
        for mismatch in name_mismatches:
            print(f"  {mismatch['mac']}: desired='{mismatch['desired']}' vs current='{mismatch['current']}'")
        print("\nAborted: AP names in desired topology do not match current system.")
        print("Please update your topology file to match current AP names.")
        sys.exit(1)

    print("[OK] Topology validation passed (MACs and names match)")

    check_interval = 5  # 5 seconds
    timeout_seconds = timeout_minutes * 60
    max_checks = timeout_seconds // check_interval
    last_activity_check = 0
    start_time = time.time()

    # Track previous topology for detecting changes
    last_topology = {}
    topology_displayed = False
    topology_changed = False

    for check_num in range(1, max_checks + 1):
        # Fetch current APs from UniFi
        current_devices = unifi_utils.get_devices()
        current_aps = [d for d in current_devices if d.get("type") == "uap"]

        # Build lookup for current APs
        current_by_mac = {}
        current_names_by_mac = {}
        for ap in current_aps:
            mac = ap.get('mac', '').lower() if ap.get('mac') else None
            if mac:
                current_names_by_mac[mac] = ap.get('name') or ap.get('model', 'Unknown AP')
                # Determine if wired or mesh
                is_wired = ap.get('wired') is True or ap.get('uplink', {}).get('type') == 'wire'
                if is_wired:
                    current_by_mac[mac] = None
                else:
                    uplink_mac = ap.get('uplink_ap_mac') or ap.get('last_uplink', {}).get('uplink_mac')
                    if uplink_mac:
                        uplink_mac = uplink_mac.lower()
                    current_by_mac[mac] = uplink_mac

        # Display initial diff on first check
        if not topology_displayed:
            topology_displayed = True

            # Categorize APs into correct and incorrect lists
            correct_aps = []
            incorrect_aps = []

            for mac in sorted(desired_by_mac.keys()):
                ap_name = desired_names_by_mac.get(mac, 'Unknown')
                desired_uplink = desired_by_mac[mac]
                current_uplink = current_by_mac.get(mac)
                ap_state = unifi_utils.get_ap_state(mac)

                # Format uplink displays with names
                if desired_uplink is None:
                    desired_uplink_display = 'WIRED'
                else:
                    desired_uplink_name = desired_names_by_mac.get(desired_uplink, 'Unknown')
                    desired_uplink_display = f'{desired_uplink_name} ({desired_uplink})'

                if current_uplink is None:
                    current_uplink_display = 'WIRED'
                else:
                    current_uplink_name = current_names_by_mac.get(current_uplink, 'Unknown')
                    current_uplink_display = f'{current_uplink_name} ({current_uplink})'

                ap_info = {
                    'mac': mac,
                    'name': ap_name,
                    'current': current_uplink_display,
                    'desired': desired_uplink_display,
                    'state': ap_state
                }

                # Categorize based on parking status and AP state
                if desired_uplink == current_uplink and ap_state == "RUNNING":
                    correct_aps.append(ap_info)
                else:
                    incorrect_aps.append(ap_info)

            # Display correct APs
            print(f"Initial parking status: {len(correct_aps)} correct, {len(incorrect_aps)} incorrect")

            if correct_aps:
                print(f"\n[OK] Correctly Parked & Online ({len(correct_aps)}):")
                for ap in correct_aps:
                    print(f"  {ap['name']} ({ap['mac']}): {ap['current']} - [{ap['state']}]")

            if incorrect_aps:
                print(f"\n[FAIL] Incorrectly Parked or Offline ({len(incorrect_aps)}):")
                for ap in incorrect_aps:
                    print(f"  {ap['name']} ({ap['mac']}) [{ap['state']}]")
                    print(f"    Current: {ap['current']}")
                    print(f"    Desired: {ap['desired']}")

            print()

        # Detect changes from last topology and count parking status
        changes = {}
        all_correctly_parked = True
        correctly_parked_count = 0
        incorrectly_parked_count = 0
        running_count = 0
        not_running_count = 0

        for mac in current_by_mac:
            current_uplink = current_by_mac[mac]
            desired_uplink = desired_by_mac.get(mac)

            # Check AP state
            ap_state = unifi_utils.get_ap_state(mac)
            if ap_state == "RUNNING":
                running_count += 1
            else:
                not_running_count += 1
                all_correctly_parked = False

            # Check if correctly parked
            if current_uplink == desired_uplink and ap_state == "RUNNING":
                correctly_parked_count += 1
            else:
                incorrectly_parked_count += 1
                all_correctly_parked = False

            # Check if uplink changed from last check
            if mac in last_topology and last_topology[mac] != current_uplink:
                changes[mac] = {
                    'old': last_topology[mac],
                    'new': current_uplink
                }

        # Report uplink changes
        if changes:
            topology_changed = True
            elapsed = time.time() - start_time
            print(f"[{elapsed:.0f}s] Uplink changes detected:")
            for mac, change in changes.items():
                ap_name = current_names_by_mac.get(mac, 'Unknown')
                old_uplink = change['old']
                new_uplink = change['new']

                # Get old uplink name and MAC display
                if old_uplink is None:
                    old_uplink_display = 'WIRED'
                else:
                    old_uplink_name = current_names_by_mac.get(old_uplink, 'Unknown')
                    old_uplink_display = f'{old_uplink_name} ({old_uplink})'

                # Get new uplink name and MAC display
                if new_uplink is None:
                    new_uplink_display = 'WIRED'
                else:
                    new_uplink_name = current_names_by_mac.get(new_uplink, 'Unknown')
                    new_uplink_display = f'{new_uplink_name} ({new_uplink})'

                # Determine parking status after move
                if new_uplink == desired_by_mac.get(mac):
                    parking_status = "[CORRECTLY PARKED]"
                else:
                    parking_status = "[PARKING VIOLATION]"

                print(f"  {ap_name} ({mac})")
                print(f"    From: {old_uplink_display}")
                print(f"    To:   {new_uplink_display} {parking_status}")

            last_activity_check = check_num

        # Check if all correctly parked
        if all_correctly_parked:
            elapsed = time.time() - start_time
            if topology_changed:
                print(f"\n[OK] Mesh topology fully rebuilt in {elapsed:.0f}s!")
            else:
                print(f"\n[OK] All APs already correctly parked (topology unchanged)")
            print(f"  All {correctly_parked_count} APs correctly parked and in RUNNING state")
            return

        # Report statistics every minute with no activity
        checks_since_activity = check_num - last_activity_check
        if checks_since_activity > 0 and checks_since_activity % 12 == 0:  # Every 60 seconds (12 * 5s)
            elapsed = time.time() - start_time
            print(f"[{elapsed:.0f}s] Status: {correctly_parked_count} correct, {incorrectly_parked_count} incorrect | {running_count} running, {not_running_count} not running")

        # Update last topology
        last_topology = current_by_mac.copy()

        # Sleep before next check (not before first check)
        time.sleep(check_interval)

    # Timeout - build final report
    elapsed = time.time() - start_time
    timeout_minutes_display = timeout_minutes

    # Recalculate current state for final report
    current_devices = unifi_utils.get_devices()
    current_aps = [d for d in current_devices if d.get("type") == "uap"]

    current_names_by_mac = {}
    current_by_mac = {}
    for ap in current_aps:
        mac = ap.get('mac', '').lower() if ap.get('mac') else None
        if mac:
            current_names_by_mac[mac] = ap.get('name') or ap.get('model', 'Unknown AP')
            is_wired = ap.get('wired') is True or ap.get('uplink', {}).get('type') == 'wire'
            if is_wired:
                current_by_mac[mac] = None
            else:
                uplink_mac = ap.get('uplink_ap_mac') or ap.get('last_uplink', {}).get('uplink_mac')
                if uplink_mac:
                    uplink_mac = uplink_mac.lower()
                current_by_mac[mac] = uplink_mac

    # Categorize APs for final report
    correct_aps = []
    incorrect_aps = []

    for mac in sorted(desired_by_mac.keys()):
        ap_name = desired_names_by_mac.get(mac, 'Unknown')
        desired_uplink = desired_by_mac[mac]
        current_uplink = current_by_mac.get(mac)
        ap_state = unifi_utils.get_ap_state(mac)

        # Format uplink displays with names
        if current_uplink is None:
            current_uplink_display = 'WIRED'
        else:
            current_uplink_name = current_names_by_mac.get(current_uplink, 'Unknown')
            current_uplink_display = f'{current_uplink_name} ({current_uplink})'

        if desired_uplink is None:
            desired_uplink_display = 'WIRED'
        else:
            desired_uplink_name = desired_names_by_mac.get(desired_uplink, 'Unknown')
            desired_uplink_display = f'{desired_uplink_name} ({desired_uplink})'

        ap_info = {
            'mac': mac,
            'name': ap_name,
            'current': current_uplink_display,
            'desired': desired_uplink_display,
            'state': ap_state
        }

        # Categorize
        if desired_uplink == current_uplink and ap_state == "RUNNING":
            correct_aps.append(ap_info)
        else:
            incorrect_aps.append(ap_info)

    print(f"\n[WARNING] Timeout after {elapsed:.0f}s ({timeout_minutes_display} minutes)")
    print(f"Final status: {len(correct_aps)} correctly parked, {len(incorrect_aps)} parking violations")
    print(f"AP states: {running_count} running, {not_running_count} not running")

    # Display correctly parked APs
    if correct_aps:
        print(f"\n[OK] Correctly Parked & Online ({len(correct_aps)}):")
        for ap in correct_aps:
            print(f"  {ap['name']} ({ap['mac']}): {ap['current']} - [{ap['state']}]")

    # Display incorrectly parked or offline APs
    if incorrect_aps:
        print(f"\n[FAIL] Incorrectly Parked or Offline ({len(incorrect_aps)}):")
        for ap in incorrect_aps:
            print(f"  {ap['name']} ({ap['mac']}) [{ap['state']}]")
            print(f"    Current: {ap['current']}")
            print(f"    Desired: {ap['desired']}")

    print("\nAborting: Some APs still have parking violations or are not in running state.")
    sys.exit(1)

def handle_forget_action_batch(clients: list):
    """Forgets a batch of clients in a single, efficient API call."""
    if not clients:
        return
    mac_list = [c.get("mac") for c in clients if c.get("mac")]
    if not mac_list:
        return
    print(f"\nSending batch 'forget' command for {len(mac_list)} clients at once...")

    # Use constants from config module
    if not UNIFI_NETWORK_URL:
        print("\nERROR: UNIFI_NETWORK_URL is not defined. Cannot proceed.")
        return

    # Construct the single API call with all MACs.
    try:
        payload = {"cmd": "forget-sta", "macs": [mac.lower() for mac in mac_list]}
        unifi_utils.make_unifi_api_call(
            "POST", 
            f"/api/s/{UNIFI_SITE_ID}/cmd/stamgr",
            headers={"Content-Type": "application/json"},
            body=json.dumps(payload).encode('utf-8')
        )
    except Exception as e:
        print(f"Error during batch forget operation: {e}")
    print("Batch forget command has been issued to the controller.")

def print_action_results_table(clients_data: list, action_type: str, results: dict):
    """
    Prints a formatted table of action results (lock, unlock, reconnect, etc.)

    Args:
        clients_data: List of client dicts
        action_type: Type of action ('reconnect', 'lock', 'unlock', 'block', 'unblock')
        results: Dict mapping MAC address to success (True/False)
    """
    # Build display rows
    rows = []
    success_count = 0
    for client in clients_data:
        mac = client.get("mac", "N/A").lower() if client.get("mac") else "N/A"
        friendly_name = client.get("name") or "Unknown"
        success = results.get(mac, False)
        status_symbol = "OK" if success else "FAIL"
        if success:
            success_count += 1
        rows.append({
            "name": friendly_name,
            "mac": mac,
            "status": status_symbol
        })

    if not rows:
        return

    # Calculate column widths
    name_width = max(len("Device Name"), max(len(row["name"]) for row in rows))
    mac_width = max(len("MAC Address"), 17)
    status_width = max(len("Result"), len("OK"))

    # Print header
    print()
    total_width = name_width + mac_width + status_width + 8
    print("-" * total_width)
    header_line = f"{'Device Name':<{name_width}}  {'MAC Address':<{mac_width}}  {'Result':<{status_width}}"
    print(header_line)
    print("-" * total_width)

    # Print data rows
    for row in rows:
        data_line = f"{row['name']:<{name_width}}  {row['mac']:<{mac_width}}  {row['status']:<{status_width}}"
        print(data_line)

    print("-" * total_width)
    failure_count = len(rows) - success_count
    print(f"Successful: {success_count}/{len(rows)}")
    print(f"Failed:     {failure_count}/{len(rows)}")
    print()


def _validate_custom_upgrade_models(aps: list, firmware_url: str | None = None, firmware_file: str | None = None) -> str | None:
    """
    Ensure custom firmware upgrades only target APs of the same model.
    """
    if not (firmware_url or firmware_file) or len(aps) <= 1:
        return None

    models = sorted({(ap.get("model") or "Unknown") for ap in aps})
    if len(models) > 1:
        return (
            "Custom firmware upgrades require all selected APs to share the same model. "
            f"Selected models: {', '.join(models)}"
        )

    return None


def ping_ap_offline(ap_mac: str, ap_name: str, ap_ip: str, offline_timeout: int = 180) -> dict:
    """
    Verify an AP forget by waiting for it to stop responding to ping.

    Success requires 10 consecutive seconds of failed ping replies within the
    configured timeout window. If that never happens, the forget is treated as
    failed.

    Args:
        ap_mac: MAC address of the AP
        ap_name: Name of the AP
        ap_ip: IP address of the AP
        offline_timeout: Maximum number of seconds to wait for the AP to go
            offline (default: 180 seconds)

    Returns:
        dict with:
            success: True if AP becomes non-pingable for 10 consecutive seconds
            message: Human-readable summary
    """
    if not ap_ip:
        return {'success': False, 'message': 'No IP address available for ping verification'}

    consecutive_failures = 0
    start_time = time.monotonic()
    deadline = start_time + offline_timeout

    while True:
        now = time.monotonic()
        if now >= deadline:
            break

        remaining = max(0.0, deadline - now)
        responded = _ping_host(ap_ip, timeout=min(2, remaining + 0.25) if remaining > 0 else 1)

        if responded:
            consecutive_failures = 0
        else:
            consecutive_failures += 1
            if consecutive_failures >= 10:
                elapsed = int(time.monotonic() - start_time)
                return {'success': True, 'message': f'no ping replies for 10s (by {elapsed}s)'}

        # Poll at roughly 1Hz regardless of how quickly ping returns.
        sleep_until = min(deadline, now + 1.0)
        sleep_for = sleep_until - time.monotonic()
        if sleep_for > 0:
            time.sleep(sleep_for)

    return {'success': False, 'message': f'still pingable or unstable after {offline_timeout}s'}


def _ping_host(host: str, timeout: float = 2.0) -> bool:
    """Return True when a host responds to a single ICMP echo request."""
    if not host:
        return False

    import subprocess

    try:
        result = subprocess.run(
            ['ping', '-c', '1', '-W', '1', host],
            capture_output=True,
            timeout=max(1.0, timeout),
        )
        return result.returncode == 0
    except (subprocess.TimeoutExpired, Exception):
        return False


def _advance_ping_upgrade_monitor(ap_info: dict) -> dict:
    """
    Update single-AP SSH/SCP upgrade ping state.

    Progression:
      waiting_for_offline -> waiting_for_online -> verifying_version
    """
    ap_ip = ap_info.get("ip")
    if not ap_ip:
        return {"event": "error", "message": "No IP address available for ping monitoring"}

    phase = ap_info.get("ping_phase", "waiting_for_offline")
    responded = _ping_host(ap_ip)

    if phase == "waiting_for_offline":
        if responded:
            ap_info["ping_failures"] = 0
            return {"event": "waiting"}

        ap_info["ping_failures"] = ap_info.get("ping_failures", 0) + 1
        if ap_info["ping_failures"] >= 10:
            ap_info["ping_phase"] = "waiting_for_online"
            ap_info["ping_successes"] = 0
            return {"event": "offline", "message": "AP stopped responding to ping; upgrade reboot detected"}
        return {"event": "waiting"}

    if phase == "waiting_for_online":
        if responded:
            ap_info["ping_successes"] = ap_info.get("ping_successes", 0) + 1
            if ap_info["ping_successes"] >= 3:
                ap_info["ping_phase"] = "verifying_version"
                ap_info["verify_ping_failures"] = 0
                ap_info["online_detected_at"] = time.time()
                return {"event": "online", "message": "AP is responding to ping again; verifying firmware version"}
        else:
            ap_info["ping_successes"] = 0
        return {"event": "waiting"}

    if phase == "verifying_version":
        if responded:
            ap_info["verify_ping_failures"] = 0
            return {"event": "waiting"}

        ap_info["verify_ping_failures"] = ap_info.get("verify_ping_failures", 0) + 1
        if ap_info["verify_ping_failures"] >= 3:
            ap_info["ping_phase"] = "waiting_for_online"
            ap_info["ping_successes"] = 0
            ap_info["controller_ready_polls"] = 0
            return {"event": "offline_again", "message": "AP stopped responding to ping again; waiting for it to come back"}
        return {"event": "waiting"}

    return {"event": "waiting"}


def _controller_reports_ssh_upgrade_ready(ap_mac: str, target_version: str | None) -> tuple[bool, str, str | None]:
    """
    Return whether the controller shows an AP as stably back after an SSH/SCP upgrade.

    Success requires:
      - AP present in controller inventory
      - adopted
      - recent last_seen
      - uptime > 0
      - RUNNING state
      - target version visible when one is known
    """
    import time

    device = unifi_utils.get_ap_device(ap_mac, raise_on_error=True)
    if not device:
        return False, "AP not yet visible in controller inventory", None

    current_version = device.get("version")
    if target_version and current_version != target_version:
        return False, f"Controller still reports firmware {current_version or 'unknown'}", current_version

    if not device.get("adopted", False):
        return False, "AP not yet adopted in controller", current_version

    uptime_seconds = device.get("uptime", 0) or 0
    if uptime_seconds <= 0:
        return False, "AP uptime not yet populated in controller", current_version

    last_seen = device.get("last_seen", 0) or 0
    if last_seen and (time.time() - last_seen) >= 30:
        return False, "AP not recently seen by controller", current_version

    current_state = unifi_utils.get_ap_state(ap_mac, raise_on_error=True)
    if current_state not in {"RUNNING", "UPGRADABLE"}:
        return False, f"AP controller state is {current_state}", current_version

    return True, "AP is back and stable in controller", current_version


def _is_mesh_ap(ap: dict) -> bool:
    """Return True when an AP is controller-visible as a mesh/wireless-uplink AP."""
    if ap.get("wired") is False:
        return True

    uplink_type = ap.get("uplink", {}).get("type") or ap.get("last_uplink", {}).get("type")
    if uplink_type in {"mesh", "wireless"}:
        return True

    if ap.get("uplink_ap_mac") or ap.get("last_uplink", {}).get("uplink_mac"):
        return True

    return False


def _get_ssh_upgrade_grace_seconds(ap: dict) -> tuple[int, int]:
    """
    Return (ping_progress_threshold, controller_settle_threshold) for SSH/SCP upgrades.

    Mesh APs may need substantially longer because their uplinks can still be
    rebooting or readopting while they come back.
    """
    if _is_mesh_ap(ap):
        return 300, 300
    return 180, 180


def _has_selected_ap_radio_channels(device: dict) -> bool:
    """
    Return True only when the AP exposes concrete numeric channels for its radios.

    Adoption can appear "done" in some controller fields before the GUI shows
    the AP's selected channels. Restrict readiness to radio_table channel values
    that are actual positive integers and require at least one such channel.
    """
    radio_table = device.get("radio_table")
    if not isinstance(radio_table, list) or not radio_table:
        return False

    found_numeric_channel = False
    for radio in radio_table:
        if not isinstance(radio, dict):
            continue

        channel = radio.get("channel")
        try:
            channel_num = int(str(channel).strip())
        except (TypeError, ValueError):
            return False

        if channel_num <= 0:
            return False

        found_numeric_channel = True

    return found_numeric_channel


def _is_ap_adoption_complete(device: dict, require_parent_link: bool = False) -> bool:
    """Return True only when an AP is fully adopted and operationally ready."""
    if not device or not unifi_utils.is_ap_fully_adopted(device):
        return False

    if not device.get("ip"):
        return False

    if not _has_selected_ap_radio_channels(device):
        return False

    uplink_mac = (
        device.get("uplink_ap_mac")
        or device.get("last_uplink", {}).get("uplink_mac")
        or device.get("uplink", {}).get("uplink_mac")
    )
    uplink_type = (
        device.get("uplink", {}).get("type")
        or device.get("last_uplink", {}).get("type")
    )
    if require_parent_link and not uplink_mac and uplink_type != "wire":
        return False

    return True


def _get_multi_level_sort_key(row_data: dict, display_columns: list) -> tuple:
    """
    Generate a multi-level sort key tuple for a client row.
    Sorts by first column, then second column (as tiebreaker), etc.
    N/A values always sort to the end.

    Args:
        row_data: Dictionary with client display values
        display_columns: List of (header, col_key, default_width) tuples in display order

    Returns:
        Tuple of sort keys for each column in order
    """
    keys = []
    for _, col_key, _ in display_columns:
        keys.append(get_sort_key_value(row_data, col_key))
    return tuple(keys)

def _apply_sort_with_na_at_end(row_data_list: list, sort_key_func, reverse: bool = False):
    """
    Sort a list of rows using the given sort key function,
    ensuring N/A values always sort to the end (or beginning if reverse=True, but after real values).

    The sort key function should return tuples where first element is (is_na, value).
    When reverse=True, we need to handle N/A placement specially.
    """
    if not reverse:
        # Normal ascending sort: N/A values (is_na=1) go to the end
        row_data_list.sort(key=sort_key_func)
    else:
        # Reverse sort: need to reverse the actual values but keep N/A at the end
        # We'll split the list into real values and N/A values, sort real values reverse, then append N/A values

        # First, separate rows into real values and N/A values
        real_rows = []
        na_rows = []

        for row in row_data_list:
            sort_key = sort_key_func(row)
            # Check if first element of first tuple indicates N/A
            first_tuple = sort_key[0] if isinstance(sort_key[0], tuple) else sort_key[0:1]
            if isinstance(first_tuple, tuple) and first_tuple[0] == 1:
                # This is an N/A row
                na_rows.append(row)
            else:
                real_rows.append(row)

        # Sort real rows in reverse
        real_rows.sort(key=sort_key_func, reverse=True)

        # Combine: real rows first (reverse order), then N/A rows
        row_data_list.clear()
        row_data_list.extend(real_rows)
        row_data_list.extend(na_rows)

def _parse_uptime_to_seconds(uptime_str: str) -> int:
    """
    Parse formatted uptime string back to seconds for numeric sorting.
    Handles formats like: "45s", "5m:30s", "2h:30m:45s", "3d 4h:05m:06s", "1y 2m 3d 4h:05m:06s"
    """
    if not uptime_str or uptime_str == "N/A":
        return -1

    try:
        total_seconds = 0

        # Split on spaces to separate major units (y, m, w, d) from time part (h:m:s)
        parts = uptime_str.split()

        for part in parts:
            if ':' in part:
                # This is the time part (h:m:s or m:s)
                time_components = part.split(':')

                # Parse components: remove trailing letters (h, m, s)
                if len(time_components) == 3:
                    # h:mm:ss format (e.g., "4h:05m:06s")
                    hours = int(time_components[0].rstrip('h'))
                    minutes = int(time_components[1].rstrip('m'))
                    secs = int(time_components[2].rstrip('s'))
                    total_seconds += hours * 3600 + minutes * 60 + secs
                elif len(time_components) == 2:
                    # m:s format (e.g., "5m:30s")
                    minutes = int(time_components[0].rstrip('m'))
                    secs = int(time_components[1].rstrip('s'))
                    total_seconds += minutes * 60 + secs
            elif part.endswith('y'):
                # Years
                total_seconds += int(part[:-1]) * 365 * 86400
            elif part.endswith('m'):
                # Months (not minutes, those are in the : format)
                total_seconds += int(part[:-1]) * 30 * 86400
            elif part.endswith('w'):
                # Weeks
                total_seconds += int(part[:-1]) * 7 * 86400
            elif part.endswith('d'):
                # Days
                total_seconds += int(part[:-1]) * 86400
            elif part.endswith('s'):
                # Seconds only (e.g., "45s")
                total_seconds += int(part[:-1])

        return total_seconds
    except (ValueError, IndexError, AttributeError):
        return -1

def get_sort_key_value(row_data: dict, col: str):
    """
    Get a sort key value for a single column from row_data.
    Returns tuple (is_na, sort_value) so N/A values always sort to the end.
    """
    if col == "mac":
        val = row_data.get("mac", "").lower()
        return (0, val) if val else (1, "")
    if col == "hostname":
        val = row_data.get("hostname", "") or ""
        return (0, val) if val else (1, "")
    if col == "vendor":
        val = row_data.get("vendor", "") or ""
        return (0, val) if val and val != "N/A" else (1, "")
    if col == "description":
        val = row_data.get("description", "") or ""
        return (0, val) if val else (1, "")
    if col == "status":
        # "Online" sorts before "Offline"
        val = row_data.get("status", "")
        return (0, 0 if val == "Online" else 1)
    if col == "ip":
        ip_str = row_data.get("ip", "") or ""
        if ip_str == "N/A" or not ip_str:
            return (1, "999.999.999.999")  # Put N/A at end
        # Normalize IP address for numeric sorting: pad each byte to 3 digits
        try:
            parts = ip_str.split(".")
            if len(parts) == 4:
                normalized = ".".join(f"{int(part):03d}" for part in parts)
                return (0, normalized)
        except (ValueError, IndexError):
            pass
        return (1, "999.999.999.999")  # Invalid IP at end
    if col == "dns_name":
        val = row_data.get("dns_name", "") or ""
        return (0, val) if val and val != "N/A" else (1, "")
    if col == "uptime":
        uptime_str = row_data.get("uptime", "N/A")
        if uptime_str == "N/A":
            return (1, 0)
        seconds = _parse_uptime_to_seconds(uptime_str)
        return (0, seconds) if seconds >= 0 else (1, 0)
    if col == "connected_ap_name":
        val = row_data.get("connected_ap_name", "") or ""
        return (0, val) if val and val != "N/A" else (1, "")
    if col == "connected_ap_mac":
        val = row_data.get("connected_ap_mac", "") or ""
        return (0, val) if val and val != "N/A" else (1, "")
    if col == "channel":
        channel_val = row_data.get("channel", "N/A")
        if channel_val == "N/A" or channel_val == "":
            return (1, 0)
        try:
            return (0, int(channel_val))
        except (ValueError, TypeError):
            return (1, 0)
    if col == "band":
        band_val = row_data.get("band", "N/A")
        if band_val == "N/A" or band_val == "":
            return (1, "")
        return (0, band_val)
    if col == "wifi_generation":
        wifi_gen = row_data.get("wifi_generation", "N/A")
        if wifi_gen == "N/A" or wifi_gen == "":
            return (1, 0)
        # Extract numeric part from "WiFi X" format
        try:
            num = int(wifi_gen.split()[-1]) if wifi_gen != "N/A" else 0
            return (0, num)
        except (ValueError, IndexError):
            return (1, 0)
    if col == "ieee_version":
        ieee_val = row_data.get("ieee_version", "N/A")
        if ieee_val == "N/A" or ieee_val == "":
            return (1, "")
        return (0, ieee_val)
    if col == "ssid":
        val = row_data.get("ssid", "") or ""
        return (0, val) if val and val != "N/A" else (1, "")
    if col == "signal":
        # Signal display is numeric value or "N/A"
        signal_str = row_data.get("signal", "N/A")
        if signal_str == "N/A":
            return (1, 0)
        try:
            # Negate so stronger (closer to 0) sorts first
            val = -int(signal_str)
            return (0, val)
        except ValueError:
            return (1, 0)
    if col == "retries":
        retries_str = row_data.get("retries", "N/A")
        if retries_str == "N/A":
            return (1, 0)
        try:
            return (0, int(retries_str))
        except ValueError:
            return (1, 0)
    if col == "locked":
        # "Yes" sorts before "No"
        val = row_data.get("locked", "")
        return (0, 0 if val == "Yes" else 1)
    if col == "locked_ap_name":
        val = row_data.get("locked_ap_name", "") or ""
        return (0, val) if val and val != "N/A" else (1, "")
    if col == "locked_ap_mac":
        val = row_data.get("locked_ap_mac", "") or ""
        return (0, val) if val and val != "N/A" else (1, "")
    if col == "last_seen":
        val = row_data.get("last_seen", "") or ""
        return (0, val) if val and val != "N/A" else (1, "")
    return (1, "")

def print_clients_table(clients_data: list, enabled_columns: list, is_default_columns: bool = False, reverse: bool = False):
    """
    Prints a formatted table of client data based on enabled columns.

    If is_default_columns is True (no +/- column switches used):
    - Omit locked columns if no clients are locked to any AP
    - Omit DNS name column if all clients lack valid DNS names

    If is_default_columns is False (using +/- switches):
    - Sort clients by displayed columns in order (first column primary, second as tiebreaker, etc.)

    If reverse is True, sorts in descending order. N/A values always sort to the end.

    Always strips default domain suffix from DNS names to make them narrower.
    """
    if not clients_data:
        print("No clients to display")
        return

    # Check for locked clients and valid DNS names (only for default columns)
    has_any_locked = False
    has_any_valid_dns = False

    if is_default_columns:
        for client in clients_data:
            if client.get("is_ap_locked", False):
                has_any_locked = True
            dns_name = client.get("dns_name", "N/A")
            if dns_name not in ["N/A", "No reverse DNS"]:
                has_any_valid_dns = True

    # Build the list of columns to display
    display_column_definitions = []
    for col_key in enabled_columns:
        # Skip uplink columns if using defaults and no clients are locked
        if is_default_columns and not has_any_locked and col_key in ['locked', 'locked_ap_name', 'locked_ap_mac']:
            continue
        # Skip DNS name column if using defaults and all DNS names are invalid
        if is_default_columns and not has_any_valid_dns and col_key == 'dns_name':
            continue

        if col_key in COLUMN_SCHEMA:
            header, default_width = COLUMN_SCHEMA[col_key]
            display_column_definitions.append((header, col_key, default_width))

    if not display_column_definitions:
        print("Error: No columns are enabled for display.")
        return

    # Build all row data first to calculate widths
    all_row_data = []
    for client in clients_data:
        row_data = _build_client_row(client)
        # Strip default domain from DNS name
        if DEFAULT_DOMAIN and 'dns_name' in row_data:
            row_data['dns_name'] = _strip_default_domain(row_data['dns_name'], DEFAULT_DOMAIN)
        all_row_data.append(row_data)

    # Calculate dynamic column widths: max of header and longest data value + 1 space
    max_widths = {}
    for header, col_key, _ in display_column_definitions:
        header_len = len(header)
        data_len = max(len(str(row.get(col_key, "N/A"))) for row in all_row_data) if all_row_data else 0
        max_widths[header] = max(header_len, data_len)

    # Add 1 space padding
    final_widths = {h: w + 1 for h, w in max_widths.items()}

    # Ensure "Status" and "Locked" have enough space for their values
    if "Status" in final_widths:
        final_widths["Status"] = max(final_widths["Status"], len("Online") + 1)
    if "Locked" in final_widths:
        final_widths["Locked"] = max(final_widths["Locked"], len("Yes") + 1)

    # Calculate total width with separators
    separator = " | "
    total_width = sum(final_widths[h] for h, _, _ in display_column_definitions) + (len(display_column_definitions) - 1) * len(separator)

    # Print header
    print("-" * total_width)
    header_line = separator.join(f"{header:<{final_widths[header]}}" for header, _, _ in display_column_definitions)
    print(header_line)
    print("-" * total_width)

    # Apply multi-level sorting when using +/- column switches (not default columns)
    if not is_default_columns:
        all_row_data.sort(key=lambda row: _get_multi_level_sort_key(row, display_column_definitions), reverse=reverse)

    # Print data rows
    for row_data in all_row_data:
        data_line = separator.join(
            f"{str(row_data.get(key_name, 'N/A')):<{final_widths[header]}}"
            for header, key_name, _ in display_column_definitions
        )
        print(data_line)

    print("-" * total_width)

def get_sort_key(client: dict, col: str):
    """
    Provides a sort key for client data based on the column name.
    Adjusted to use client dictionary keys as provided by unifi_utils.
    """
    if col == "number":
        return int(client.get("number", 0))
    if col == "mac":
        return client.get("mac", "").lower()
    if col == "hostname":
        return client.get("hostname") or ""
    if col == "description":
        return client.get("description") or ""
    if col == "status":
        return 0 if client.get("is_connected_live", False) else 1 # Online first
    if col == "ip":
        return client.get("display_ip") or ""
    if col == "dns_name":
        return client.get("dns_name") or ""
    if col == "connected_ap_name":
        return client.get("connected_ap_name") or ""
    if col == "connected_ap_mac":
        return client.get("live_ap_mac") or ""
    if col == "signal":
        try:
            # Signal values are negative, so sorting by -sig will put stronger signals (closer to 0) first
            sig = int(client.get("live_signal", -999)) # Default to a very low signal if not available
        except (TypeError, ValueError):
            sig = -999
        return -sig
    if col == "retries":
        try:
            ret = int(client.get("tx_retries", -1)) # Default to -1 if not available
        except (TypeError, ValueError):
            ret = -1
        return ret
    if col == "locked":
        return not client.get("is_ap_locked", False) # Sort 'True' (locked) first
    if col == "locked_ap_name":
        return client.get("locked_ap_name") or ""
    if col == "locked_ap_mac":
        return client.get("locked_ap_mac") or ""
    if col == "last_seen":
        return client.get("last_seen_formatted") or "" # Sort by formatted string
    return ""

def parse_column_switches(args_list: list, column_names: list) -> tuple[list, str | None, bool]:
    """
    Parses column display switches (+column, -column) for a given set of column names.
    Returns a tuple: (list of enabled column keys, error message or None, is_using_defaults: bool)
    Validates that all specified columns are valid for the current action.
    """
    positive_mode = False
    negative_mode = False
    enabled_cols_explicit = []
    disabled_cols_explicit = []

    # Parse ALL column switches to check for mixing and invalid columns
    all_column_switch_args = [
        arg
        for arg in args_list
        if len(arg) > 1 and (arg.startswith('+') or arg.startswith('-'))
    ]

    # First pass: check for mixing positive and negative, and validate columns
    for arg in all_column_switch_args:
        col = arg[1:]
        if arg.startswith("+"):
            positive_mode = True
            if col not in column_names:
                return [], f"Column '{col}' is not valid for this action.", False
            if col in enabled_cols_explicit:
                return [], f"Duplicate +column specified: {col}", False
            enabled_cols_explicit.append(col)
        elif arg.startswith("-"):
            negative_mode = True
            if col not in column_names:
                return [], f"Column '{col}' is not valid for this action.", False
            if col in disabled_cols_explicit:
                return [], f"Duplicate -column specified: {col}", False
            disabled_cols_explicit.append(col)

    if positive_mode and negative_mode:
        return [], "Cannot mix positive (+) and negative (-) switches for column display.", False

    if positive_mode:
        if not enabled_cols_explicit:
            return [], "No +columns specified, but positive mode was indicated.", False
        return enabled_cols_explicit, None, False
    else:
        # Default behavior: all columns enabled, unless explicitly disabled
        is_default = len(all_column_switch_args) == 0

        if is_default and column_names == CLIENT_COLUMN_NAMES:
            # Use predefined default columns for client listing when no switches specified
            enabled_final = DEFAULT_CLIENT_COLUMNS
        else:
            # For other modes or when switches are provided, use all columns minus disabled ones
            enabled_final = [col for col in column_names if col not in disabled_cols_explicit]

        if not enabled_final and (negative_mode or not all_column_switch_args):
            return [], "All columns disabled, nothing to show.", False

        return enabled_final, None, is_default

def add_filter_arguments(parser):
    """Add common filtering arguments to a subparser."""
    filter_group_status = parser.add_mutually_exclusive_group()
    filter_group_status.add_argument(
        "--filter_online",
        action="store_true",
        help="Filter clients currently online."
    )
    filter_group_status.add_argument(
        "--filter_offline",
        action="store_true",
        help="Filter clients currently offline."
    )
    filter_group_locked_status = parser.add_mutually_exclusive_group()
    filter_group_locked_status.add_argument(
        "--filter_locked",
        action="store_true",
        help="Filter clients locked to an AP."
    )
    filter_group_locked_status.add_argument(
        "--filter_unlocked",
        action="store_true",
        help="Filter clients NOT locked to an AP."
    )
    parser.add_argument(
        "--filter_ip",
        type=str,
        help="Filter clients by exact IP address match."
    )
    parser.add_argument(
        "--filter_dns_name",
        type=str,
        help="Filter clients by exact DNS name match."
    )
    parser.add_argument(
        "--filter_hostname",
        type=str,
        help="Filter clients by exact hostname match."
    )
    parser.add_argument(
        "--filter_mac",
        type=str,
        help="Filter clients by MAC address (substring match)."
    )
    parser.add_argument(
        "--filter_by_ssid",
        type=str,
        help="Filter clients by SSID (exact match)."
    )
    parser.add_argument(
        "--filter_signal_above",
        type=int,
        help="Filter clients with signal strength strictly ABOVE this value (e.g., -60 means > -60)."
    )
    parser.add_argument(
        "--filter_signal_below",
        type=int,
        help="Filter clients with signal strength strictly BELOW this value (e.g., -30 means < -30)."
    )

def add_filter_arguments_for_list(parser):
    """Add filtering arguments for list command (supports both clients and APs).

    For clients: All standard filters apply.
    For APs: Only --filter_online, --filter_offline, --filter_ip, --filter_mac apply.
    """
    # Status filters (works for both clients and APs)
    filter_group_status = parser.add_mutually_exclusive_group()
    filter_group_status.add_argument(
        "--filter_online",
        action="store_true",
        help="Filter devices currently online (clients and APs)."
    )
    filter_group_status.add_argument(
        "--filter_offline",
        action="store_true",
        help="Filter devices currently offline (clients and APs)."
    )

    # Locked status filters (clients only)
    filter_group_locked_status = parser.add_mutually_exclusive_group()
    filter_group_locked_status.add_argument(
        "--filter_locked",
        action="store_true",
        help="Filter clients locked to an AP (clients only)."
    )
    filter_group_locked_status.add_argument(
        "--filter_unlocked",
        action="store_true",
        help="Filter clients NOT locked to an AP (clients only)."
    )

    # IP and MAC filters (works for both clients and APs)
    parser.add_argument(
        "--filter_ip",
        type=str,
        help="Filter devices by exact IP address match (clients and APs)."
    )
    parser.add_argument(
        "--filter_mac",
        type=str,
        help="Filter devices by MAC address (substring match - clients and APs)."
    )

    # DNS and hostname filters (clients only)
    parser.add_argument(
        "--filter_dns_name",
        type=str,
        help="Filter clients by exact DNS name match (clients only)."
    )
    parser.add_argument(
        "--filter_hostname",
        type=str,
        help="Filter clients by exact hostname match (clients only)."
    )

    # SSID filter (clients only)
    parser.add_argument(
        "--filter_by_ssid",
        type=str,
        help="Filter clients by SSID (exact match - clients only)."
    )

    # Signal strength filters (clients only)
    parser.add_argument(
        "--filter_signal_above",
        type=int,
        help="Filter clients with signal strength strictly ABOVE this value in dBm (clients only, e.g., -60)."
    )
    parser.add_argument(
        "--filter_signal_below",
        type=int,
        help="Filter clients with signal strength strictly BELOW this value in dBm (clients only, e.g., -30)."
    )

class HelpArgumentParser(argparse.ArgumentParser):
    """Custom ArgumentParser that shows full help page on invalid arguments."""
    def error(self, message):
        """Override error to print help page instead of just error message."""
        sys.stderr.write(f"ERROR: {message}\n\n")
        self.print_help(sys.stderr)
        sys.exit(2)

if __name__ == "__main__":
    # Initialize NSS database at startup (before any HTTPS connections)
    import nss.nss as nss_core
    from pathlib import Path
    import subprocess

    nss_db_dir = Path.home() / ".netcon-sync"

    # Create NSS database if it doesn't exist
    try:
        ensure_nss_db(nss_db_dir)
    except RuntimeError as e:
        print(f"Error initializing NSS database: {e}", file=sys.stderr)
        sys.exit(1)

    # Initialize NSS
    try:
        nss_core.nss_init(str(nss_db_dir))
    except Exception as e:
        print(f"Error initializing NSS: {e}", file=sys.stderr)
        sys.exit(1)

    # Check for config errors from import phase
    if _config_error:
        print(f"ERROR: Configuration Error: {_config_error}", file=sys.stderr)
        print("\nTo fix this, set the required environment variables:", file=sys.stderr)
        print("  export UNIFI_NETWORK_URL='https://your-unifi-host:8443'", file=sys.stderr)
        print("  export UNIFI_USERNAME='your-username'", file=sys.stderr)
        print("  export UNIFI_PASSWORD='your-password'", file=sys.stderr)
        print("  export UNIFI_SITE_ID='default'  # (optional, defaults to 'default')", file=sys.stderr)
        print("\nThen run your command again.", file=sys.stderr)
        sys.exit(1)

    # Reminder about backup before any modifications
    if len(sys.argv) > 1 and sys.argv[1] not in ("--help", "-h", "trust"):
        print("WARNING: Please backup your UniFi configuration before making changes!")
        print("   Use UniFi's built-in backup feature in System Settings > Backup & Restore")
        print()

    # Handle "trust" command first (non-standard argument parsing)
    if len(sys.argv) > 1 and sys.argv[1] == "trust":
        if len(sys.argv) < 3:
            print("Usage: unifi_climgr.py trust (--ca <CERT_PATH> | --server <HTTPS_URL>)")
            print()
            print("Examples:")
            print("  # Trust a CA certificate")
            print("  unifi_climgr.py trust --ca /path/to/rootCA.pem")
            print()
            print("  # Trust a server certificate (with interactive verification)")
            print("  unifi_climgr.py trust --server https://192.168.1.100:8443")
            sys.exit(1)

        # NSS database path for trust operations
        nss_db_dir = Path.home() / ".netcon-sync"

        # Parse trust command options
        if sys.argv[2] == "--ca":
            if len(sys.argv) < 4:
                print("ERROR: --ca requires a certificate path")
                sys.exit(1)
            cert_path = sys.argv[3]
            handle_trust_ca_cert(nss_db_dir, cert_path)
        elif sys.argv[2] == "--server":
            if len(sys.argv) < 4:
                print("ERROR: --server requires a URL")
                sys.exit(1)
            server_url = sys.argv[3]
            handle_trust_server_url(nss_db_dir, server_url)
        else:
            # For backwards compatibility: trust <URL> (without --server flag)
            # Only if it looks like a URL (contains ://)
            if "://" in sys.argv[2]:
                handle_trust_server_url(nss_db_dir, sys.argv[2])
            else:
                print(f"ERROR: Invalid trust option: {sys.argv[2]}")
                print("Use either --ca <CERT_PATH> or --server <HTTPS_URL>")
                sys.exit(1)

    # Separate column switches from other arguments BEFORE passing to argparse
    # Accept CLIENT, AP, and SSID columns, validation happens per-action later
    all_args = sys.argv[1:]

    argparse_args = []
    column_control_args = []
    all_valid_columns = set(CLIENT_COLUMN_NAMES) | set(AP_COLUMN_NAMES) | set(SSID_COLUMN_NAMES)

    for arg in all_args:
        is_column_control = False
        if len(arg) > 1 and (arg.startswith('+') or arg.startswith('-')):
            column_name = arg[1:]
            if column_name in all_valid_columns:
                is_column_control = True
        if is_column_control:
            column_control_args.append(arg)
        else:
            argparse_args.append(arg)

    parser = HelpArgumentParser(
        description="UniFi Network Manager - Manage clients, access points, and SSIDs.",
        formatter_class=argparse.RawTextHelpFormatter,
        allow_abbrev=False,
        epilog="""
AVAILABLE ACTIONS:

  list        List clients, SSIDs, and/or access points
              Usage: list (--clients | --ssids | --aps) [column switches] [filters]
              Options:
                --clients              List all connected clients
                --ssids                List all wireless networks (SSIDs)
                --aps                  List all access points with mesh topology tree
              Column Switches: +column, -column (e.g., +mac +hostname -description)

              CLIENT COLUMNS (for --clients):
                number                 Sequential numbering
                mac                    MAC address
                hostname               Device hostname
                description            Device description
                status                 Online/Offline status
                ip                     IP address
                dns_name               DNS name
                uptime                 Client connection uptime
                connected_ap_name      Name of currently connected AP
                connected_ap_mac       MAC of currently connected AP
                channel                WiFi channel number
                band                   WiFi frequency band (2.4 GHz, 5 GHz, 6 GHz)
                wifi_generation        WiFi generation (WiFi 1-7)
                ieee_version           802.11 Version (802.11a/b/g/n/ac/ax/be)
                ssid                   Network SSID name
                signal                 Signal strength (dBm)
                retries                TX retries count
                locked                 AP lock status (Yes/No)
                locked_ap_name         Name of locked AP
                locked_ap_mac          MAC of locked AP
                last_seen              Last seen timestamp

              SSID COLUMNS (for --ssids):
                name                   SSID name
                enabled                Enabled/Disabled status (Yes/No)
                security               Security type (Open, WPA, WPA2, WPA3, WPA2/WPA3)
                band                   Frequency band (2.4GHz, 5GHz, 6GHz, or combinations)

              AP COLUMNS (for --aps):
                name                   AP device name
                mac                    AP MAC address
                ip                     AP IP address
                version                Firmware version
                uptime                 System uptime
                connection             Connection type (wired/mesh)
                uplink_ap_name         Name of uplink AP (for mesh)
                uplink_ap_mac          MAC of uplink AP (for mesh)

              CLIENT FILTERS (for --clients):
                --filter_online, --filter_offline (show online/offline clients)
                --filter_locked, --filter_unlocked (show locked/unlocked clients)
                --filter_ip <IP>, --filter_mac <MAC> (exact/substring match)
                --filter_dns_name <DNS>, --filter_hostname <NAME> (exact match)
                --filter_signal_above <dBm>, --filter_signal_below <dBm> (signal range)

              SSID FILTERS (for --ssids):
                --filter_name <NAME>   Filter by SSID name (substring match)

              AP FILTERS (for --aps):
                --filter_online, --filter_offline (show online/offline APs)
                --filter_ip <IP>, --filter_mac <MAC> (substring match)

  lock_client Lock clients to a specific access point
              Usage: lock_client (--ap_mac <MAC> | --ap_name <NAME> | --connected_ap) [filters]
              Options:
                --ap_mac <MAC>         Lock to AP by MAC address
                --ap_name <NAME>       Lock to AP by name
                --connected_ap         Lock each client to its currently connected AP
              Filters: --filter_online, --filter_offline, --filter_locked, --filter_unlocked,
                       --filter_ip, --filter_dns_name, --filter_hostname, --filter_mac,
                       --filter_signal_above, --filter_signal_below

  unlock_client Unlock clients from access points
              Usage: unlock_client [filters]
              Filters: --filter_online, --filter_offline, --filter_locked, --filter_unlocked,
                       --filter_ip, --filter_dns_name, --filter_hostname, --filter_mac,
                       --filter_signal_above, --filter_signal_below

  reconnect_client Force clients to reconnect
              Usage: reconnect_client [filters]
              Filters: --filter_online, --filter_offline, --filter_locked, --filter_unlocked,
                       --filter_ip, --filter_dns_name, --filter_hostname, --filter_mac,
                       --filter_signal_above, --filter_signal_below

  forget      Forget clients or access points from the controller
              Usage: forget --clients [filters] | forget --aps [filters]
              Options:
                --clients              Forget clients (use with --filter_* flags)
                --aps                  Forget access points (mesh order, with offline verification)
                --actual_forget        Actually perform the forget (default is dry run)
                --verify_offline       Verify APs are offline before next layer (default)
                --no_verify_offline    Skip offline verification
                --offline_timeout <S>  Wait up to S seconds for 10s of no ping replies (default: 180)
              CLIENT FILTERS (for --clients):
                --filter_online, --filter_offline    Online/offline status
                --filter_locked, --filter_unlocked   Locked/unlocked status
                --filter_ip <IP>                     Exact IP address match
                --filter_dns_name <DNS>              Exact DNS name match
                --filter_hostname <NAME>             Exact hostname match
                --filter_mac <MAC>                   MAC address substring match
                --filter_by_ssid <SSID>              Exact SSID match
                --filter_signal_above <dBm>          Signal strength > value
                --filter_signal_below <dBm>          Signal strength < value
              AP FILTERS (for --aps):
                --filter_online, --filter_offline    Online/offline status
                --filter_ip <IP>                     IP address substring match
                --filter_mac <MAC>                   MAC address substring match
                --filter_name <NAME>                 Name or model substring match

  block_client Block clients (prevents connection)
              Usage: block_client [filters]
              Filters: --filter_online, --filter_offline, --filter_locked, --filter_unlocked,
                       --filter_ip, --filter_dns_name, --filter_hostname, --filter_mac,
                       --filter_signal_above, --filter_signal_below

  unblock_client Unblock clients (allows connection)
              Usage: unblock_client [filters]
              Filters: --filter_online, --filter_offline, --filter_locked, --filter_unlocked,
                       --filter_ip, --filter_dns_name, --filter_hostname, --filter_mac,
                       --filter_signal_above, --filter_signal_below

  add_client  Add or update a client
              Usage: add_client <MAC_ADDRESS> [--name <NAME>] [--note <NOTE>]
              Arguments:
                <MAC_ADDRESS>          MAC address of client (required, positional)
              Options:
                --name <NAME>          Client name (optional)
                --note <NOTE>          Client note/description (optional)

  restart_ap  Restart access points
              Usage: restart_ap [--ap_mac <MAC> | --ap_name <NAME>] [--verify_offline | --no_verify_offline] [--offline_timeout <S>]
              Options:
                --ap_mac <MAC>         Restart AP by MAC address
                --ap_name <NAME>       Restart AP by name
                --verify_offline       Verify APs are offline before next layer (default)
                --no_verify_offline    Skip offline verification
                --offline_timeout <S>  Wait up to S seconds for 10s of no ping replies (default: 180)
              If neither --ap_mac nor --ap_name is specified, restarts all APs (use with caution!)
              APs restart in mesh order (leaf to parent), and each layer must go offline
              before the next layer is processed unless verification is disabled.

  adopt_ap    Adopt access points to the controller
              Usage: adopt_ap [--ap_mac <MAC> | --ap_name <NAME>]
              Options:
                --ap_mac <MAC>         Adopt AP by MAC address
                --ap_name <NAME>       Adopt AP by name
                --sequence_timeout <S> Wait for mesh APs to appear for up to S seconds (default: 900)
              If neither --ap_mac nor --ap_name is specified, adopts all visible APs
              by issuing wired AP adoptions first, then polling for mesh APs
              to appear and adopting them sequentially.
              After adoption, AP names are automatically set from reverse DNS if the AP
              doesn't already have a custom name. A custom name may have been set by:
                - pfsense2unifi sync (from pfSense DHCP reservations)
                - A restored UniFi configuration backup
                - Manual configuration in the UniFi UI

  upgrade_ap  Upgrade AP firmware to latest available version on configured channel
              Usage: upgrade_ap [--ap_mac <MAC> | --ap_name <NAME>] [--firmware_url <URL> | --firmware_file <PATH>] [--reflash] [--actual_upgrade]
              Options:
                --ap_mac <MAC>         Upgrade AP by MAC address
                --ap_name <NAME>       Upgrade AP by name
                --actual_upgrade       Actually perform the upgrade (default is dry run)
              If neither --ap_mac nor --ap_name is specified, upgrades all APs!
              For mesh networks, APs upgrade in mesh order (leaf to parent) with 5s delay between layers
              Default behavior is DRY RUN (shows what would be upgraded without making changes)

  enable      Enable wireless networks (SSIDs) or access points (APs)
              Usage: enable (--ssids | --aps) [<NAME> | --filter_name <NAME>] [--filter_mac <MAC>]
              Options:
                --ssids                Enable SSID(s)
                --aps                  Enable AP(s)
                <NAME>                 Name of the SSID or AP to enable (optional, positional)
                --filter_name <NAME>   Enable SSIDs/APs matching this name (substring match)
                --filter_mac <MAC>     Enable AP by MAC address (substring match, APs only)
              Note: Omit filters to enable ALL SSIDs or APs
              For SSIDs, this sets the enabled=true flag in the WLAN configuration.

  disable     Disable wireless networks (SSIDs) or access points (APs)
              Usage: disable (--ssids | --aps) [<NAME> | --filter_name <NAME>] [--filter_mac <MAC>]
              Options:
                --ssids                Disable SSID(s)
                --aps                  Disable AP(s)
                <NAME>                 Name of the SSID or AP to disable (optional, positional)
                --filter_name <NAME>   Disable SSIDs/APs matching this name (substring match)
                --filter_mac <MAC>     Disable AP by MAC address (substring match, APs only)
              Note: Omit filters to disable ALL SSIDs or APs
              For SSIDs, this sets the enabled=false flag in the WLAN configuration.

  backup      Backup controller data
              Usage: backup --clients [--backup_location <DIR>] [client filters]
              Options:
                --clients                Backup UniFi clients to XML
                --backup_location <DIR>  Backup directory (default: ~/.netcon-sync/unifi_backups)
                --filter_online          Only backup online clients
                --filter_offline         Only backup offline clients
                --filter_locked          Only backup locked clients
                --filter_unlocked        Only backup unlocked clients
                --filter_ip <IP>         Only backup clients with IP containing this string
                --filter_mac <MAC>       Only backup clients with MAC containing this string
                --filter_dns_name <DNS>  Only backup clients with DNS name containing this string
                --filter_hostname <NAME> Only backup clients with hostname containing this string
              Backups are saved as XML files with timestamp-based names (unifi_clients_YYYYMMDD_HHMMSS.xml)
              Limitations: client groups and icon metadata are not backed up.

  restore     Restore controller data from backup
              Usage: restore --clients [--backup_file <FILE>] [--backup_location <DIR>] [--actual_restore]
              Options:
                --clients                Restore UniFi clients from XML backup
                --backup_file <FILE>     Backup file to restore (default: latest in backup location)
                --backup_location <DIR>  Backup directory (default: ~/.netcon-sync/unifi_backups)
                --actual_restore         Actually apply changes to UniFi clients (default: dry run)
              Restores client attributes: hostname, name, note, WiFi speed limits, locked status,
              locked AP, fixed IP, and local DNS settings. Gateway-specific attributes (e.g.,
              WiFi speed limits) are gracefully skipped if not supported.
              Limitations: client groups and icon metadata are not restored.

  check_ap    Check AP status and diagnose upgrade issues
              Usage: check_ap (--ap_mac <MAC> | --ap_name <NAME>)
              Options:
                --ap_mac <MAC>         Check AP by MAC address
                --ap_name <NAME>       Check AP by name

  save_mesh_topology Export current AP mesh topology to JSON
              Usage: save_mesh_topology [<FILE>]
              Options:
                <FILE>                 JSON output path (default: ~/.netcon-sync/topology.json)

  wait_for_mesh_topology Wait for mesh topology to match a saved topology
              Usage: wait_for_mesh_topology [<FILE>] [--timeout <MINUTES>]
              Options:
                <FILE>                 JSON topology file (default: ~/.netcon-sync/topology.json)
                --timeout <MINUTES>    Maximum wait time in minutes (default: 75)

  collect_ap_logs Collect diagnostic logs from APs via SSH
              Usage: collect_ap_logs [--output <DIR>] [--parallel <N>] [--timeout <S>]
                                     [--no-controller] [--filter-name <NAME>]
                                     [--filter-ip <IP>] [--filter-mac <MAC>] [--online-only]
              Options:
                --output <DIR>         Output directory (default: ~/ap_logs)
                --parallel <N>         Parallel AP collections (default: 0 = unlimited)
                --timeout <S>          SSH timeout in seconds (default: 60)
                --no-controller        Skip controller support file collection
                --filter-name <NAME>   Filter APs by name (substring match)
                --filter-ip <IP>       Filter APs by IP (substring match)
                --filter-mac <MAC>     Filter APs by MAC (substring match)
                --online-only          Collect only from online APs

  trust       Trust a UniFi certificate or server
              Usage: trust (--ca <CERT_PATH> | --server <HTTPS_URL>)
              Options:
                --ca <CERT_PATH>       Trust a CA/root certificate in the NSS database
                --server <HTTPS_URL>   Fetch and trust a server certificate

EXAMPLES:

  # List all clients
  ./unifi_climgr.py list --clients

  # List only specific columns for clients
  ./unifi_climgr.py list --clients +mac +hostname +status

  # List all SSIDs
  ./unifi_climgr.py list --ssids

  # List SSIDs with only name and security columns
  ./unifi_climgr.py list --ssids +name +security

  # Filter SSIDs by name (substring match)
  ./unifi_climgr.py list --ssids --filter_name "guest"

  # List access points with mesh topology
  ./unifi_climgr.py list --aps

  # Lock all online clients to a specific AP by MAC
  ./unifi_climgr.py lock_client --ap_mac aa:bb:cc:dd:ee:ff --filter_online

  # Lock only offline clients to an AP by name
  ./unifi_climgr.py lock_client --ap_name "Living Room AP" --filter_offline

  # Lock each client to its currently connected AP
  ./unifi_climgr.py lock_client --connected_ap

  # Unlock all locked clients
  ./unifi_climgr.py unlock_client --filter_locked

  # Force all clients with weak signal to reconnect
  ./unifi_climgr.py reconnect_client --filter_signal_below -50

  # Block a specific client by MAC
  ./unifi_climgr.py block_client --filter_mac aa:bb:cc

  # Forget clients matching a hostname pattern
  ./unifi_climgr.py forget --clients --filter_hostname "test-device"

  # Dry run: preview forgetting all APs in mesh order
  ./unifi_climgr.py forget --aps

  # Actually forget all APs in mesh order (with offline verification)
  ./unifi_climgr.py forget --aps --actual_forget

  # Forget APs without offline verification (for testing)
  ./unifi_climgr.py forget --aps --actual_forget --no_verify_offline

  # Forget APs with custom offline timeout
  ./unifi_climgr.py forget --aps --actual_forget --offline_timeout 90

  # Unblock a specific client by MAC
  ./unifi_climgr.py unblock_client --filter_mac aa:bb:cc

  # Add a new client with name and note
  ./unifi_climgr.py add_client aa:bb:cc:dd:ee:ff --name "My Device" --note "Test device"

  # Restart a specific AP by MAC
  ./unifi_climgr.py restart_ap --ap_mac aa:bb:cc:dd:ee:ff

  # Restart a specific AP by name
  ./unifi_climgr.py restart_ap --ap_name "Living Room AP"

  # Restart all APs (WARNING: network disruption! Mesh networks restart in order)
  ./unifi_climgr.py restart_ap

  # Adopt all APs (wired first, then mesh as they appear)
  ./unifi_climgr.py adopt_ap

  # Dry run: preview what firmware updates would be applied (default behavior)
  ./unifi_climgr.py upgrade_ap --ap_mac aa:bb:cc:dd:ee:ff

  # Dry run: preview upgrades for all APs (leaf to parent in mesh order)
  ./unifi_climgr.py upgrade_ap

  # Actually upgrade a specific AP
  ./unifi_climgr.py upgrade_ap --ap_mac aa:bb:cc:dd:ee:ff --actual_upgrade

  # Actually upgrade a specific AP by name
  ./unifi_climgr.py upgrade_ap --ap_name "Living Room AP" --actual_upgrade

  # Actually upgrade all APs (WARNING: network disruption! Mesh networks upgrade in order)
  ./unifi_climgr.py upgrade_ap --actual_upgrade

  # Actually upgrade a specific AP using a custom firmware URL
  ./unifi_climgr.py upgrade_ap --ap_name "Living Room AP" --firmware_url https://example.com/fw.bin --actual_upgrade

  # Reinstall the same custom firmware version anyway
  ./unifi_climgr.py upgrade_ap --ap_name "Living Room AP" --firmware_url https://example.com/fw.bin --reflash --actual_upgrade

  # Enable an SSID
  ./unifi_climgr.py enable --ssids "My WiFi Network"

  # Enable all SSIDs matching a pattern (substring match)
  ./unifi_climgr.py enable --ssids --filter_name "guest"

  # Enable ALL SSIDs
  ./unifi_climgr.py enable --ssids

  # Enable a specific AP by name
  ./unifi_climgr.py enable --aps "Living Room AP"

  # Backup all clients to default location
  ./unifi_climgr.py backup --clients

  # Backup only online clients
  ./unifi_climgr.py backup --clients --filter_online

  # Restore clients from latest backup (dry run)
  ./unifi_climgr.py restore --clients

  # Restore clients from specific backup file
  ./unifi_climgr.py restore --clients --backup_file /path/to/unifi_clients_20240101_120000.xml

  # Check a specific AP
  ./unifi_climgr.py check_ap --ap_mac aa:bb:cc:dd:ee:ff

  # Save current mesh topology
  ./unifi_climgr.py save_mesh_topology

  # Wait for mesh topology to rebuild from a saved file
  ./unifi_climgr.py wait_for_mesh_topology ~/.netcon-sync/topology.json --timeout 75

  # Collect AP logs from online APs only
  ./unifi_climgr.py collect_ap_logs --online-only

  # Enable all APs matching a pattern (substring match)
  ./unifi_climgr.py enable --aps --filter_name "bedroom"

  # Enable all APs with a specific MAC (substring match)
  ./unifi_climgr.py enable --aps --filter_mac aa:bb:cc

  # Enable ALL APs
  ./unifi_climgr.py enable --aps

  # Disable an SSID
  ./unifi_climgr.py disable --ssids "Guest Network"

  # Disable all SSIDs matching a pattern (substring match)
  ./unifi_climgr.py disable --ssids --filter_name "test"

  # Disable ALL SSIDs
  ./unifi_climgr.py disable --ssids

  # Disable a specific AP by name
  ./unifi_climgr.py disable --aps "Garage AP"

  # Disable all APs matching a pattern (substring match)
  ./unifi_climgr.py disable --aps --filter_name "outdoor"

  # Disable all APs with a specific MAC (substring match)
  ./unifi_climgr.py disable --aps --filter_mac aa:bb:cc

  # Disable ALL APs
  ./unifi_climgr.py disable --aps

CERTIFICATE MANAGEMENT:

  # Trust a CA/root certificate
  ./unifi_climgr.py trust --ca /path/to/rootCA.pem

  # Trust a self-signed certificate
  ./unifi_climgr.py trust https://192.168.1.100:8443
        """
    )

    # Create subparsers for actions
    subparsers = parser.add_subparsers(dest='action', required=False)

    # ============================================================================
    # LIST action
    # ============================================================================
    list_parser = subparsers.add_parser(
        'list',
        help='List clients, access points, and SSIDs',
        formatter_class=argparse.RawTextHelpFormatter,
        allow_abbrev=False,
        epilog="""
USAGE:
  list --clients [column switches] [filters]
  list --aps [column switches] [filters]
  list --ssids [column switches] [filters]

FILTERS FOR --clients:
  Status Filters (mutually exclusive):
    --filter_online              Show only online clients
    --filter_offline             Show only offline clients

  Lock Status Filters (mutually exclusive):
    --filter_locked              Show only clients locked to an AP
    --filter_unlocked            Show only clients NOT locked to an AP

  Specific Value Filters:
    --filter_ip <IP>             Exact IP address match
    --filter_mac <MAC>           MAC address substring match
    --filter_dns_name <DNS>      Exact DNS name match
    --filter_hostname <NAME>     Exact hostname match
    --filter_by_ssid <SSID>      SSID exact match

  Signal Strength Filters:
    --filter_signal_above <dBm>  Signal strength > dBm (e.g., -60)
    --filter_signal_below <dBm>  Signal strength < dBm (e.g., -30)

FILTERS FOR --aps:
  Status Filters (mutually exclusive):
    --filter_online              Show only online APs
    --filter_offline             Show only offline APs

  Specific Value Filters:
    --filter_ip <IP>             Exact IP address match
    --filter_mac <MAC>           MAC address substring match

FILTERS FOR --ssids:
  --filter_name <NAME>           SSID name substring match (case-insensitive)

COLUMN SWITCHES (for --clients, --aps, and --ssids):
  +column                        Include column in output
  -column                        Exclude column from output

  Example: list --clients +mac +hostname -description

EXAMPLES:
  # List all clients with default columns
  ./unifi_climgr.py list --clients

  # List all SSIDs
  ./unifi_climgr.py list --ssids

  # Filter SSIDs by name (substring match)
  ./unifi_climgr.py list --ssids --filter_name "guest"

  # List only online clients
  ./unifi_climgr.py list --clients --filter_online

  # List only MAC and hostname for offline clients
  ./unifi_climgr.py list --clients --filter_offline +mac +hostname -ip

  # List locked clients with specific columns
  ./unifi_climgr.py list --clients --filter_locked +hostname +locked_ap_name

  # List clients on a specific SSID
  ./unifi_climgr.py list --clients --filter_by_ssid "MyNetwork"

  # List APs with weak signal clients connected
  ./unifi_climgr.py list --aps

  # List online APs only
  ./unifi_climgr.py list --aps --filter_online

  # List APs on specific IP subnet
  ./unifi_climgr.py list --aps --filter_ip 192.168.1
        """
    )
    list_target = list_parser.add_mutually_exclusive_group(required=True)
    list_target.add_argument('--clients', action='store_true', help='List all connected clients')
    list_target.add_argument('--aps', action='store_true', help='List all access points')
    list_target.add_argument('--ssids', action='store_true', help='List all wireless networks (SSIDs)')
    # Add filter arguments for list command
    add_filter_arguments_for_list(list_parser)
    # Add name filter for SSIDs and APs
    list_parser.add_argument(
        "--filter_name",
        type=str,
        help="Filter SSIDs/APs by name (substring match, case-insensitive)."
    )

    # Add sorting direction flags
    sort_direction = list_parser.add_mutually_exclusive_group()
    sort_direction.add_argument(
        "--ascending",
        action='store_true',
        help="Sort results in ascending order (default)"
    )
    sort_direction.add_argument(
        "--descending",
        action='store_true',
        help="Sort results in descending order"
    )

    # ============================================================================
    # LOCK_CLIENT action
    # ============================================================================
    lock_client_parser = subparsers.add_parser(
        'lock_client',
        help='Lock clients to an access point',
        allow_abbrev=False
    )
    lock_target = lock_client_parser.add_mutually_exclusive_group(required=True)
    lock_target.add_argument('--ap_mac', type=str, help='Lock to AP by MAC address')
    lock_target.add_argument('--ap_name', type=str, help='Lock to AP by name')
    lock_target.add_argument('--connected_ap', action='store_true', help='Lock to currently connected AP')
    add_filter_arguments(lock_client_parser)

    # ============================================================================
    # UNLOCK_CLIENT action
    # ============================================================================
    unlock_client_parser = subparsers.add_parser(
        'unlock_client',
        help='Unlock clients from access points',
        allow_abbrev=False
    )
    add_filter_arguments(unlock_client_parser)
    # ============================================================================
    # RECONNECT_CLIENT action
    # ============================================================================
    reconnect_client_parser = subparsers.add_parser(
        'reconnect_client',
        help='Force clients to reconnect',
        allow_abbrev=False,
        epilog="""
EXAMPLES:
  # Reconnect all online clients (batch mode, no delay)
  ./unifi_climgr.py reconnect_client --filter_online

  # Reconnect all online clients with 1 second delay between each
  ./unifi_climgr.py reconnect_client --filter_online --delay 1000

  # Reconnect clients on specific SSID with 500ms delay
  ./unifi_climgr.py reconnect_client --filter_by_ssid "MyNetwork" --delay 500
        """
    )
    add_filter_arguments(reconnect_client_parser)
    reconnect_client_parser.add_argument(
        "--delay",
        type=int,
        help="Delay in milliseconds between reconnecting clients (default: 0 for batch mode). When specified, clients are reconnected one at a time."
    )

    # ============================================================================
    # FORGET action
    # ============================================================================
    forget_parser = subparsers.add_parser(
        'forget',
        help='Forget clients or access points from the controller',
        allow_abbrev=False
    )
    forget_target = forget_parser.add_mutually_exclusive_group(required=True)
    forget_target.add_argument('--clients', action='store_true', help='Forget clients')
    forget_target.add_argument('--aps', action='store_true', help='Forget access points')
    forget_parser.add_argument(
        '--actual_forget',
        action='store_true',
        help='Actually perform the forget (default is dry run)'
    )
    forget_parser.add_argument(
        '--verify_offline',
        action='store_true',
        default=True,
        help='Verify APs are offline before moving to next depth layer (default: enabled)'
    )
    forget_parser.add_argument(
        '--no_verify_offline',
        action='store_false',
        dest='verify_offline',
        help='Skip offline verification (for testing or when ping is unavailable)'
    )
    forget_parser.add_argument(
        '--offline_timeout',
        type=int,
        default=180,
        help='Maximum seconds to wait for AP to stay offline for 10s (default: 180)'
    )
    add_filter_arguments(forget_parser)
    forget_parser.add_argument(
        "--filter_name",
        type=str,
        help="Filter APs by name or model (substring match, case-insensitive)."
    )

    # ============================================================================
    # BLOCK_CLIENT action
    # ============================================================================
    block_client_parser = subparsers.add_parser(
        'block_client',
        help='Block clients',
        allow_abbrev=False
    )
    add_filter_arguments(block_client_parser)

    # ============================================================================
    # UNBLOCK_CLIENT action
    # ============================================================================
    unblock_client_parser = subparsers.add_parser(
        'unblock_client',
        help='Unblock clients',
        allow_abbrev=False
    )
    add_filter_arguments(unblock_client_parser)

    # ============================================================================
    # ADD_CLIENT action
    # ============================================================================
    add_client_parser = subparsers.add_parser(
        'add_client',
        help='Add or update a client',
        allow_abbrev=False
    )
    add_client_parser.add_argument('mac_address', help='MAC address of the client to add')
    add_client_parser.add_argument('--name', type=str, help='Client name (optional)')
    add_client_parser.add_argument('--note', type=str, help='Client note/description (optional)')

    # ============================================================================
    # RESTART_AP action
    # ============================================================================
    restart_ap_parser = subparsers.add_parser(
        'restart_ap',
        help='Restart access points',
        allow_abbrev=False
    )
    restart_ap_target = restart_ap_parser.add_mutually_exclusive_group(required=False)
    restart_ap_target.add_argument('--ap_mac', type=str, help='Restart AP by MAC address')
    restart_ap_target.add_argument('--ap_name', type=str, help='Restart AP by name')
    restart_ap_parser.add_argument(
        '--verify_offline',
        action='store_true',
        default=True,
        help='Verify APs are offline before moving to the next depth layer (default: enabled)'
    )
    restart_ap_parser.add_argument(
        '--no_verify_offline',
        action='store_false',
        dest='verify_offline',
        help='Skip offline verification'
    )
    restart_ap_parser.add_argument(
        '--offline_timeout',
        type=int,
        default=180,
        help='Maximum seconds to wait for AP to stay offline for 10s (default: 180)'
    )

 
    # ============================================================================
    # ADOPT_AP action
    # ============================================================================
    adopt_ap_parser = subparsers.add_parser(
        'adopt_ap',
        help='Adopt access points to the controller',
        allow_abbrev=False
    )
    adopt_ap_target = adopt_ap_parser.add_mutually_exclusive_group(required=False)
    adopt_ap_target.add_argument('--ap_mac', type=str, help='Adopt AP by MAC address')
    adopt_ap_target.add_argument('--ap_name', type=str, help='Adopt AP by name')
    adopt_ap_parser.add_argument(
        '--sequence_timeout',
        type=int,
        default=900,
        help='Wait for mesh APs to appear for up to this many seconds when adopting all APs (default: 900)'
    )

    # ============================================================================
    # UPGRADE_AP action
    # ============================================================================
    upgrade_ap_parser = subparsers.add_parser(
        'upgrade_ap',
        help='Upgrade AP firmware to latest available version on configured channel',
        allow_abbrev=False
    )
    upgrade_ap_target = upgrade_ap_parser.add_mutually_exclusive_group(required=False)
    upgrade_ap_target.add_argument('--ap_mac', type=str, help='Upgrade AP by MAC address')
    upgrade_ap_target.add_argument('--ap_name', type=str, help='Upgrade AP by name')
    upgrade_ap_source = upgrade_ap_parser.add_mutually_exclusive_group(required=False)
    upgrade_ap_source.add_argument('--firmware_url', type=str, help='Custom firmware URL to pass through the controller API')
    upgrade_ap_source.add_argument('--firmware_file', type=str, help='Custom firmware file path to pass through the controller API')
    upgrade_ap_parser.add_argument('--reflash', action='store_true', help='Allow reinstalling the same parsed custom firmware version')
    upgrade_ap_parser.add_argument('--actual_upgrade', action='store_true', help='Actually perform the upgrade (default is dry run)')
    upgrade_ap_parser.add_argument('--ap_upgrade_delay', type=int, default=10, help='Seconds to wait after each AP upgrade initiation (default: 10)')
    upgrade_ap_parser.add_argument('--layer_upgrade_delay', type=int, default=30, help='Seconds to wait between mesh layers (default: 30)')
    upgrade_ap_parser.add_argument('--upgrade_timeout', type=int, default=900, help='Seconds to monitor upgrade progress before timeout (default: 900 = 15 minutes)')

    # ============================================================================
    # CHECK_AP action (diagnostic)
    # ============================================================================
    check_ap_parser = subparsers.add_parser(
        'check_ap',
        help='Check AP status and diagnose upgrade issues',
        allow_abbrev=False
    )
    check_ap_target = check_ap_parser.add_mutually_exclusive_group(required=True)
    check_ap_target.add_argument('--ap_mac', type=str, help='Check AP by MAC address')
    check_ap_target.add_argument('--ap_name', type=str, help='Check AP by name')

    # ============================================================================
    # SAVE_MESH_TOPOLOGY action (export current mesh topology)
    # ============================================================================
    save_mesh_topology_parser = subparsers.add_parser(
        'save_mesh_topology',
        help='Export current AP mesh topology to JSON file',
        allow_abbrev=False
    )
    save_mesh_topology_parser.add_argument(
        'filename',
        nargs='?',
        default=None,
        help='JSON file to save topology to (default: ~/.netcon-sync/topology.json)'
    )

    # ============================================================================
    # WAIT_FOR_MESH_TOPOLOGY action
    # ============================================================================
    wait_for_mesh_topology_parser = subparsers.add_parser(
        'wait_for_mesh_topology',
        help='Wait for mesh network topology to rebuild to match desired state',
        allow_abbrev=False
    )
    wait_for_mesh_topology_parser.add_argument(
        'filename',
        nargs='?',
        default=None,
        help='JSON file with desired topology (default: ~/.netcon-sync/topology.json)'
    )
    wait_for_mesh_topology_parser.add_argument(
        '--timeout',
        type=int,
        default=75,
        help='Maximum time to wait for topology to rebuild, in minutes (default: 75)'
    )

    # ============================================================================
    # ENABLE action
    # ============================================================================
    enable_parser = subparsers.add_parser(
        'enable',
        help='Enable a wireless network (SSID) or access point (AP)',
        allow_abbrev=False
    )
    enable_target = enable_parser.add_mutually_exclusive_group(required=True)
    enable_target.add_argument('--ssids', action='store_true', help='Enable SSID(s)')
    enable_target.add_argument('--aps', action='store_true', help='Enable AP(s)')
    enable_parser.add_argument('name', nargs='?', default=None, help='Name of the SSID or AP to enable')
    enable_parser.add_argument('--filter_name', type=str, help='Enable SSIDs/APs matching this name (substring match)')
    enable_parser.add_argument('--filter_mac', type=str, help='Enable AP by MAC address (substring match, APs only)')

    # ============================================================================
    # DISABLE action
    # ============================================================================
    disable_parser = subparsers.add_parser(
        'disable',
        help='Disable a wireless network (SSID) or access point (AP)',
        allow_abbrev=False
    )
    disable_target = disable_parser.add_mutually_exclusive_group(required=True)
    disable_target.add_argument('--ssids', action='store_true', help='Disable SSID(s)')
    disable_target.add_argument('--aps', action='store_true', help='Disable AP(s)')
    disable_parser.add_argument('name', nargs='?', default=None, help='Name of the SSID or AP to disable')
    disable_parser.add_argument('--filter_name', type=str, help='Disable SSIDs/APs matching this name (substring match)')
    disable_parser.add_argument('--filter_mac', type=str, help='Disable AP by MAC address (substring match, APs only)')

    # ============================================================================
    # COLLECT_AP_LOGS action
    # ============================================================================
    collect_logs_parser = subparsers.add_parser(
        'collect_ap_logs',
        help='Collect diagnostic logs from Access Points via SSH',
        allow_abbrev=False,
        formatter_class=argparse.RawTextHelpFormatter,
        epilog="""
EXAMPLES:
  # Collect logs from all APs (default: unlimited parallelism)
  ./unifi_climgr.py collect_ap_logs

  # Collect logs with limited parallelism
  ./unifi_climgr.py collect_ap_logs --parallel 5

  # Collect logs to specific directory
  ./unifi_climgr.py collect_ap_logs --output /tmp/ap_logs

  # Collect only from specific APs
  ./unifi_climgr.py collect_ap_logs --filter-name "Office"
  ./unifi_climgr.py collect_ap_logs --filter-ip "192.168.1"

  # Skip controller support file collection
  ./unifi_climgr.py collect_ap_logs --no-controller
        """
    )
    collect_logs_parser.add_argument(
        '--output', '-o',
        type=Path,
        default=Path.home() / 'ap_logs',
        help='Output directory for log files (default: ~/ap_logs)'
    )
    collect_logs_parser.add_argument(
        '--parallel', '-p',
        type=int,
        default=0,
        metavar='N',
        help='Collect from N APs in parallel (default: 0 = unlimited)'
    )
    collect_logs_parser.add_argument(
        '--timeout',
        type=int,
        default=60,
        help='SSH connection timeout in seconds (default: 60)'
    )
    collect_logs_parser.add_argument(
        '--no-controller',
        action='store_true',
        help='Skip controller support file collection'
    )
    collect_logs_parser.add_argument(
        '--filter-name',
        type=str,
        help='Filter APs by name (substring match)'
    )
    collect_logs_parser.add_argument(
        '--filter-ip',
        type=str,
        help='Filter APs by IP address (substring match)'
    )
    collect_logs_parser.add_argument(
        '--filter-mac',
        type=str,
        help='Filter APs by MAC address (substring match)'
    )
    collect_logs_parser.add_argument(
        '--online-only',
        action='store_true',
        help='Collect only from online APs'
    )

    # BACKUP action
    # ============================================================================
    backup_parser = subparsers.add_parser(
        'backup',
        help='Backup controller data',
        allow_abbrev=False,
        formatter_class=argparse.RawTextHelpFormatter,
        epilog="""
EXAMPLES:
  # Backup all clients to default location (~/.netcon-sync/unifi_backups)
  ./unifi_climgr.py backup --clients

  # Backup all clients to custom location
  ./unifi_climgr.py backup --clients --backup_location /path/to/backups

  # Backup only online clients
  ./unifi_climgr.py backup --clients --filter_online

  # Backup clients matching a hostname pattern
  ./unifi_climgr.py backup --clients --filter_hostname "iot-"

LIMITATIONS:
  Client groups and icon metadata are not included in client backups.
        """
    )
    backup_target = backup_parser.add_mutually_exclusive_group(required=True)
    backup_target.add_argument(
        '--clients',
        action='store_true',
        help='Backup UniFi clients to XML'
    )
    backup_parser.add_argument(
        '--backup_location', '-l',
        type=Path,
        default=None,
        help='Backup directory (default: ~/.netcon-sync/unifi_backups)'
    )
    backup_parser.add_argument(
        '--filter_online',
        action='store_true',
        help='Filter: only backup online clients'
    )
    backup_parser.add_argument(
        '--filter_offline',
        action='store_true',
        help='Filter: only backup offline clients'
    )
    backup_parser.add_argument(
        '--filter_locked',
        action='store_true',
        help='Filter: only backup locked clients'
    )
    backup_parser.add_argument(
        '--filter_unlocked',
        action='store_true',
        help='Filter: only backup unlocked clients'
    )
    backup_parser.add_argument(
        '--filter_ip',
        type=str,
        help='Filter: clients with IP containing this string'
    )
    backup_parser.add_argument(
        '--filter_mac',
        type=str,
        help='Filter: clients with MAC containing this string'
    )
    backup_parser.add_argument(
        '--filter_dns_name',
        type=str,
        help='Filter: clients with DNS name containing this string'
    )
    backup_parser.add_argument(
        '--filter_hostname',
        type=str,
        help='Filter: clients with hostname containing this string'
    )

    # RESTORE action
    # ============================================================================
    restore_parser = subparsers.add_parser(
        'restore',
        help='Restore controller data from backup',
        allow_abbrev=False,
        formatter_class=argparse.RawTextHelpFormatter,
        epilog="""
EXAMPLES:
  # Restore all clients from latest backup (dry run - preview only)
  ./unifi_climgr.py restore --clients

  # Restore from specific backup file (dry run - preview only)
  ./unifi_climgr.py restore --clients --backup_file /path/to/unifi_clients_20240101_120000.xml

  # Perform actual restore
  ./unifi_climgr.py restore --clients --actual_restore

  # Restore with custom backup location (dry run)
  ./unifi_climgr.py restore --clients --backup_location /path/to/backups

  # Restore with custom backup location and apply changes
  ./unifi_climgr.py restore --clients --backup_location /path/to/backups --actual_restore

LIMITATIONS:
  Client groups and icon metadata are not restored from backup files.
        """
    )
    restore_target = restore_parser.add_mutually_exclusive_group(required=True)
    restore_target.add_argument(
        '--clients',
        action='store_true',
        help='Restore UniFi clients from XML backup'
    )
    restore_parser.add_argument(
        '--backup_file', '-f',
        type=Path,
        default=None,
        help='Backup file to restore (default: latest in backup location)'
    )
    restore_parser.add_argument(
        '--backup_location', '-l',
        type=Path,
        default=None,
        help='Backup directory (default: ~/.netcon-sync/unifi_backups)'
    )
    restore_parser.add_argument(
        '--actual_restore',
        action='store_true',
        help='Actually apply changes to UniFi clients (default: dry run)'
    )

    # Parse arguments
    args = parser.parse_args(argparse_args)

    # If no action provided, show help
    if not args.action:
        parser.print_help()
        sys.exit(0)

    # Validate that client-only actions still receive a client target flag.
    # `forget` supports both `--clients` and `--aps`, so it is validated by the
    # mutually exclusive target group on its own parser instead of here.
    client_actions_needing_flag = ['block', 'unblock']
    if args.action in client_actions_needing_flag:
        if hasattr(args, 'clients') and not args.clients:
            parser.error("--clients is required for this action")

    # Determine column display mode based on action
    if args.action == 'list':
        if args.aps:
            mode_column_names = AP_COLUMN_NAMES
        elif args.ssids:
            mode_column_names = SSID_COLUMN_NAMES
        else:
            mode_column_names = CLIENT_COLUMN_NAMES
    else:
        # For action commands, default to client columns (but not really used for display)
        mode_column_names = CLIENT_COLUMN_NAMES

    # Handle column switches
    enabled_columns, err, is_default_columns = parse_column_switches(column_control_args, mode_column_names)
    if err:
        if not enabled_columns:
            print(err)
            sys.exit(0)
        else:
            print(f"Error: {err}", file=sys.stderr)
            parser.print_help(sys.stderr)
            sys.exit(1)

    try:
        print("Logging into UniFi controller...")
        unifi_utils.login()
        print("Login successful.")

        # =====================================================================
        # LIST action
        # =====================================================================
        if args.action == 'list':
            if args.aps:
                print("Fetching UniFi devices...")
                all_devices = unifi_utils.get_devices()
                aps = [device for device in all_devices if device.get("type") == "uap"]
                if not aps:
                    print("No Access Points found.")
                    sys.exit(0)

                # Apply AP filters
                filtered_aps = []
                for ap in aps:
                    match = True

                    # Status filters (online/offline)
                    if hasattr(args, 'filter_online') and args.filter_online:
                        if not ap.get("adoptable_when_online", ap.get("state") == "online"):
                            match = False
                    elif hasattr(args, 'filter_offline') and args.filter_offline:
                        if ap.get("adoptable_when_online", ap.get("state") == "online"):
                            match = False

                    # IP filter
                    if hasattr(args, 'filter_ip') and args.filter_ip:
                        ap_ip = ap.get("ip", "")
                        if args.filter_ip.lower() not in ap_ip.lower():
                            match = False

                    # MAC filter
                    if hasattr(args, 'filter_mac') and args.filter_mac:
                        ap_mac = ap.get("mac", "")
                        if args.filter_mac.lower() not in ap_mac.lower():
                            match = False

                    # Name filter (substring match, case-insensitive)
                    if hasattr(args, 'filter_name') and args.filter_name:
                        ap_name = ap.get("name", "")
                        if args.filter_name.lower() not in ap_name.lower():
                            match = False

                    if match:
                        filtered_aps.append(ap)

                if not filtered_aps:
                    print("No Access Points found matching the specified filters.")
                    sys.exit(0)

                print(f"\nFound {len(filtered_aps)} Access Point(s):")
                reverse = getattr(args, 'descending', False)
                print_ap_table(filtered_aps, all_devices, enabled_columns, reverse)

                # Determine whether to show tree view for filtered APs
                show_tree = False
                tree_aps = filtered_aps

                if len(filtered_aps) == 1:
                    # Single AP: show tree only if it's mesh, showing only the branch to that AP
                    ap = filtered_aps[0]
                    is_wired = ap.get('wired') is True or ap.get('uplink', {}).get('type') == 'wire'
                    if not is_wired:
                        show_tree = True
                        tree_aps = _build_ap_branch_aps(ap, all_devices)
                elif len(filtered_aps) > 1:
                    # Multiple APs: show tree only if at least one is mesh, and use full network
                    has_mesh = any(
                        ap.get('wired') is False or ap.get('uplink', {}).get('type') in ['mesh', 'wireless']
                        for ap in filtered_aps
                    )
                    if has_mesh:
                        show_tree = True
                        tree_aps = [d for d in all_devices if d.get("type") == "uap"]  # Use all APs for tree

                if show_tree:
                    display_ap_tree(tree_aps, all_devices)
            elif args.ssids:
                print("Fetching UniFi SSIDs...")
                ssids = unifi_utils.get_ssids()
                if not ssids:
                    print("No SSIDs found.")
                    sys.exit(0)

                # Apply SSID filters
                filtered_ssids = []
                for ssid in ssids:
                    match = True

                    # Name filter (substring match, case-insensitive)
                    if hasattr(args, 'filter_name') and args.filter_name:
                        ssid_name = ssid.get("name", "")
                        if args.filter_name.lower() not in ssid_name.lower():
                            match = False

                    if match:
                        filtered_ssids.append(ssid)

                if not filtered_ssids:
                    print("No SSIDs found matching the specified filters.")
                    sys.exit(0)

                print(f"\nFound {len(filtered_ssids)} SSID(s):")
                if enabled_columns:
                    reverse = getattr(args, 'descending', False)
                    print_ssid_table(filtered_ssids, enabled_columns, reverse)
            elif args.clients:
                # args.clients
                print("Fetching UniFi clients...")
                clients = unifi_utils.get_all_unifi_clients()
                if not clients:
                    print("No clients found.")
                    sys.exit(0)

                # Add "number" key for numbering (before filtering)
                for i, client in enumerate(clients):
                    client["number"] = i + 1

                # Apply client filters
                filtered_clients = []
                for client in clients:
                    match = True

                    # Status filters (online/offline)
                    if hasattr(args, 'filter_online') and args.filter_online and not client.get("is_connected_live", False):
                        match = False
                    elif hasattr(args, 'filter_offline') and args.filter_offline and client.get("is_connected_live", False):
                        match = False

                    # Lock status filters
                    if hasattr(args, 'filter_locked') and args.filter_locked and not client.get("is_ap_locked", False):
                        match = False
                    elif hasattr(args, 'filter_unlocked') and args.filter_unlocked and client.get("is_ap_locked", False):
                        match = False

                    # IP filter
                    if hasattr(args, 'filter_ip') and args.filter_ip:
                        if client.get("display_ip") != args.filter_ip:
                            match = False

                    # MAC filter
                    if hasattr(args, 'filter_mac') and args.filter_mac:
                        client_mac = client.get("mac", "")
                        if args.filter_mac.lower() not in client_mac.lower():
                            match = False

                    # DNS name filter
                    if hasattr(args, 'filter_dns_name') and args.filter_dns_name:
                        if client.get("dns_name") != args.filter_dns_name:
                            match = False

                    # Hostname filter
                    if hasattr(args, 'filter_hostname') and args.filter_hostname:
                        if client.get("hostname") != args.filter_hostname:
                            match = False

                    # SSID filter
                    if hasattr(args, 'filter_by_ssid') and args.filter_by_ssid:
                        if client.get("live_ssid") != args.filter_by_ssid:
                            match = False

                    # Signal strength filters
                    if hasattr(args, 'filter_signal_above') and args.filter_signal_above is not None:
                        signal = client.get("live_signal")
                        if not client.get("is_connected_live", False) or signal is None or signal <= args.filter_signal_above:
                            match = False
                    if hasattr(args, 'filter_signal_below') and args.filter_signal_below is not None:
                        signal = client.get("live_signal")
                        if not client.get("is_connected_live", False) or signal is None or signal >= args.filter_signal_below:
                            match = False

                    if match:
                        filtered_clients.append(client)

                if not filtered_clients:
                    print("No clients found matching the specified filters.")
                    sys.exit(0)

                # Re-number filtered clients
                for i, client in enumerate(filtered_clients):
                    client["number"] = i + 1

                print(f"\nFound {len(filtered_clients)} Client(s):")
                if enabled_columns:
                    reverse = getattr(args, 'descending', False)
                    print_clients_table(filtered_clients, enabled_columns, is_default_columns, reverse)
            sys.exit(0)

        # =====================================================================
        # ADD action
        # =====================================================================
        if args.action == 'add_client':
            mac_to_add = args.mac_address
            client_name = args.name
            client_note = args.note
            print(f"\nAttempting to add/update client {mac_to_add}...")
            if unifi_utils.add_client(mac_to_add, client_name, client_note):
                print(f"Client {mac_to_add} successfully added/updated.")
            else:
                print(f"Failed to add/update client {mac_to_add}. Check logs for details.")
            sys.exit(0)

        # =====================================================================
        # RESTART action
        # =====================================================================
        if args.action == 'restart_ap':
            print("Fetching UniFi devices...")
            all_devices = unifi_utils.get_devices()
            aps = [device for device in all_devices if device.get("type") == "uap"]

            if not aps:
                print("No Access Points found.")
                sys.exit(0)

            aps_to_restart = []

            if args.ap_mac:
                # Restart specific AP by MAC
                target_mac = args.ap_mac.lower()
                matching_aps = [ap for ap in aps if ap.get("mac", "").lower() == target_mac]
                if not matching_aps:
                    print(f"Error: No AP found with MAC {args.ap_mac}")
                    sys.exit(1)
                aps_to_restart = matching_aps
            elif args.ap_name:
                # Restart specific AP by name
                matching_aps = [ap for ap in aps if (ap.get("name") or ap.get("model", "")).lower() == args.ap_name.lower()]
                if not matching_aps:
                    print(f"Error: No AP found with name '{args.ap_name}'")
                    sys.exit(1)
                aps_to_restart = matching_aps
            else:
                # Restart all APs
                aps_to_restart = aps

            # Display the mesh topology before restarting (only if more than one AP)
            if len(aps_to_restart) > 1:
                print()
                display_ap_tree(aps_to_restart, all_devices)

            # Calculate depths against the selected AP inventory so restart sequencing
            # matches the visible mesh topology we are operating on.
            depths = calculate_ap_mesh_depths(aps_to_restart)
            aps_by_depth = defaultdict(list)
            for ap in aps_to_restart:
                ap_mac = ap.get("mac")
                depth = depths.get(ap_mac, -1)
                aps_by_depth[depth].append(ap)

            sorted_depths = sorted(aps_by_depth.keys(), reverse=True)
            verify_str = "WITH OFFLINE VERIFICATION" if args.verify_offline else "NO OFFLINE VERIFICATION"
            print(f"\nRestarting {len(aps_to_restart)} AP(s) in mesh order (leaf to parent)...\n")
            print(f"Offline verification: {verify_str} (wait up to {args.offline_timeout}s for 10s offline)\n")

            ssh_username, ssh_password = None, None

            for i, depth in enumerate(sorted_depths):
                layer_aps = aps_by_depth[depth]

                if depth == -1:
                    depth_label = "Orphan"
                elif depth == 0:
                    depth_label = "Wired Root"
                else:
                    depth_label = f"Mesh Depth {depth}"

                print(f"Layer {i+1}: {depth_label} ({len(layer_aps)} AP{'s' if len(layer_aps) != 1 else ''})")
                for ap in layer_aps:
                    ap_name = ap.get("name") or ap.get("model", "Unknown AP")
                    ap_mac = ap.get("mac")
                    ap_ip = ap.get("ip")

                    if not ap_mac:
                        print(f"  {ap_name}... [FAIL] missing MAC address")
                        continue

                    print(f"  {ap_name}... ", end="", flush=True)
                    result = unifi_utils.restart_ap(ap_mac)
                    if result['success']:
                        print(f"[OK] restart request accepted via {result['method']}")
                        continue

                    print(f"[FAIL] via controller ({result.get('error', 'unknown error')})")
                    if ap_ip:
                        print(f"    Trying SSH fallback to {ap_ip}... ", end="", flush=True)
                        if ssh_username is None:
                            ssh_username, ssh_password = get_ssh_credentials()
                        if ssh_username and ssh_password:
                            ssh_result = unifi_utils.restart_ap_via_ssh(ap_ip, ssh_username, ssh_password)
                            if ssh_result['success']:
                                print(f"[OK] restart request accepted via {ssh_result['method']}")
                            else:
                                print(f"[FAIL] {ssh_result.get('error', 'unknown error')}")
                        else:
                            print("[FAIL] No SSH credentials available")
                    else:
                        print("    No IP address available for SSH fallback")

                if args.verify_offline:
                    print(f"\n  Verifying all {len(layer_aps)} AP(s) in this layer are offline...")
                    all_offline = True
                    verify_targets = [ap for ap in layer_aps if ap.get("mac")]
                    max_workers = min(len(verify_targets), 8) if verify_targets else 1
                    with ThreadPoolExecutor(max_workers=max_workers) as executor:
                        future_to_ap = {
                            executor.submit(
                                ping_ap_offline,
                                ap.get("mac"),
                                ap.get("name") or ap.get("model", "Unknown AP"),
                                ap.get("ip"),
                                args.offline_timeout,
                            ): ap
                            for ap in verify_targets
                        }
                        verification_results = {}
                        for future in as_completed(future_to_ap):
                            ap = future_to_ap[future]
                            ap_mac = ap.get("mac", "").lower()
                            try:
                                verification_results[ap_mac] = future.result()
                            except Exception as e:
                                verification_results[ap_mac] = {
                                    'success': False,
                                    'message': f'ping verification error: {e}',
                                }

                    for ap in layer_aps:
                        ap_mac = ap.get("mac", "").lower()
                        ap_name = ap.get("name") or ap.get("model", "Unknown AP")
                        ap_ip = ap.get("ip")
                        result = verification_results.get(ap_mac, {
                            'success': False,
                            'message': 'verification did not run',
                        })
                        ip_label = f" ({ap_ip})" if ap_ip else ""
                        status = "OK" if result.get('success') else "FAIL"
                        print(f"    {ap_name}{ip_label}... [{status}] {result.get('message', 'unknown result')}")
                        if not result.get('success'):
                            all_offline = False

                    if all_offline:
                        if i < len(sorted_depths) - 1:
                            print("  All APs confirmed offline after restart. Proceeding to next layer...\n")
                        else:
                            print("  All APs confirmed offline after restart.\n")
                    else:
                        print("  Layer verification failed. Stopping restart_ap.\n")
                        sys.exit(1)
                else:
                    print()

            print("\nAll APs processed for restart_ap.")
            sys.exit(0)

        # =====================================================================
        # FORGET action (clients or APs)
        # =====================================================================
        if args.action == 'forget':
            # Handle forget --clients
            if args.clients:
                print("Fetching UniFi clients...")
                all_clients = unifi_utils.get_all_unifi_clients()

                if not all_clients:
                    print("No clients found.")
                    sys.exit(0)

                # Warn about AP-only filters when using --clients
                ap_only_filters = [
                    ("--filter_name", "name"),
                ]
                for filter_arg, filter_desc in ap_only_filters:
                    filter_value = getattr(args, filter_arg.strip('--').replace('-', '_'), None)
                    if filter_value is not None and filter_value is not False:
                        print(f"  [WARN] {filter_arg} is an AP-only filter and will be ignored for --clients")

                # Apply client-specific filters
                filtered_clients = all_clients
                # Status filters
                if args.filter_online:
                    filtered_clients = [c for c in filtered_clients if c.get("is_connected_live")]
                if args.filter_offline:
                    filtered_clients = [c for c in filtered_clients if not c.get("is_connected_live")]
                # Locked status filters
                if args.filter_locked:
                    filtered_clients = [c for c in filtered_clients if c.get("is_ap_locked")]
                if args.filter_unlocked:
                    filtered_clients = [c for c in filtered_clients if not c.get("is_ap_locked")]
                # IP filter
                if args.filter_ip:
                    filtered_clients = [c for c in filtered_clients if args.filter_ip in c.get("display_ip", "")]
                # DNS name filter
                if args.filter_dns_name:
                    filtered_clients = [c for c in filtered_clients if args.filter_dns_name.lower() in c.get("hostname", "").lower()]
                # Hostname filter
                if args.filter_hostname:
                    filtered_clients = [c for c in filtered_clients if args.filter_hostname.lower() in c.get("hostname", "").lower()]
                # MAC filter (substring match)
                if args.filter_mac:
                    filter_mac = args.filter_mac.lower().replace(":", "").replace("-", "")
                    filtered_clients = [c for c in filtered_clients if filter_mac in c.get("mac", "").lower().replace(":", "").replace("-", "")]
                # SSID filter
                if args.filter_by_ssid:
                    filtered_clients = [c for c in filtered_clients if args.filter_by_ssid in c.get("ssid", "")]
                # Signal strength filters
                if args.filter_signal_above:
                    filtered_clients = [c for c in filtered_clients if c.get("signal", float('-inf')) > args.filter_signal_above]
                if args.filter_signal_below:
                    filtered_clients = [c for c in filtered_clients if c.get("signal", float('inf')) < args.filter_signal_below]

                if not filtered_clients:
                    print("No clients match the specified filters.")
                    sys.exit(0)

                mode_str = "ACTUAL:" if args.actual_forget else "DRY RUN:"
                print(f"\n{mode_str} Forgetting {len(filtered_clients)} client(s)...\n")

                if not args.actual_forget:
                    print("Dry run complete. Re-run with --actual_forget to perform the forget.")
                    sys.exit(0)

                handle_forget_action_batch(filtered_clients)
                sys.exit(0)

            # Handle forget --aps
            elif args.aps:
                print("Fetching UniFi devices...")
                all_devices = unifi_utils.get_devices()
                aps = [device for device in all_devices if device.get("type") == "uap"]

                if not aps:
                    print("No Access Points found.")
                    sys.exit(0)

                # Warn about client-only filters when using --aps
                client_only_filters = [
                    ("--filter_locked", "locked"),
                    ("--filter_unlocked", "unlocked"),
                    ("--filter_dns_name", "DNS name"),
                    ("--filter_hostname", "hostname"),
                    ("--filter_by_ssid", "SSID"),
                    ("--filter_signal_above", "signal strength (above)"),
                    ("--filter_signal_below", "signal strength (below)"),
                ]
                for filter_arg, filter_desc in client_only_filters:
                    filter_value = getattr(args, filter_arg.strip('--').replace('-', '_'), None)
                    if filter_value is not None and filter_value is not False:
                        print(f"  [WARN] {filter_arg} is a client-only filter and will be ignored for --aps")

                # Apply AP-specific filters
                # Status filters (online/offline)
                if args.filter_online:
                    aps = [ap for ap in aps if ap.get("state") == 1]
                if args.filter_offline:
                    aps = [ap for ap in aps if ap.get("state") != 1]

                # IP filter (substring match)
                if args.filter_ip:
                    aps = [ap for ap in aps if args.filter_ip in (ap.get("ip") or "")]

                # MAC filter (substring match)
                if args.filter_mac:
                    filter_mac = args.filter_mac.lower().replace(":", "").replace("-", "")
                    aps = [ap for ap in aps if filter_mac in ap.get("mac", "").lower().replace(":", "").replace("-", "")]

                # Name filter (substring match in name or model)
                if args.filter_name:
                    aps = [ap for ap in aps if args.filter_name.lower() in (ap.get("name") or ap.get("model", "")).lower()]

                if not aps:
                    print("No APs match the specified filters.")
                    sys.exit(0)

                if len(aps) > 1:
                    print()
                    display_ap_tree(aps, all_devices)

                # Calculate depths against the full AP inventory so targeted forgets
                # still retain their real mesh position instead of being mislabeled
                # as orphans when their parent AP is outside the selected subset.
                depths = calculate_ap_mesh_depths(aps)
                aps_by_depth = defaultdict(list)
                for ap in aps:
                    ap_mac = ap.get("mac")
                    depth = depths.get(ap_mac, -1)
                    aps_by_depth[depth].append(ap)

                sorted_depths = sorted(aps_by_depth.keys(), reverse=True)

                mode_str = "ACTUAL:" if args.actual_forget else "DRY RUN:"
                verify_str = "WITH OFFLINE VERIFICATION" if args.verify_offline else "NO OFFLINE VERIFICATION"
                print(f"\n{mode_str} Forgetting {len(aps)} AP(s) in mesh order (leaf to parent)...\n")
                print(f"Offline verification: {verify_str} (wait up to {args.offline_timeout}s for 10s offline)\n")

                for i, depth in enumerate(sorted_depths):
                    layer_aps = aps_by_depth[depth]

                    if depth == -1:
                        depth_label = "Orphan"
                    elif depth == 0:
                        depth_label = "Wired Root"
                    else:
                        depth_label = f"Mesh Depth {depth}"

                    print(f"Layer {i+1}: {depth_label} ({len(layer_aps)} AP{'s' if len(layer_aps) != 1 else ''})")
                    for ap in layer_aps:
                        ap_name = ap.get("name") or ap.get("model", "Unknown AP")
                        ap_mac = ap.get("mac")
                        ap_ip = ap.get("ip")

                        if not ap_mac:
                            print(f"  {ap_name}... [FAIL] missing MAC address")
                            continue

                        if not args.actual_forget:
                            print(f"  {ap_name} ({ap_mac}) [DRY RUN]")
                            continue

                        print(f"  {ap_name}... ", end="", flush=True)
                        result = unifi_utils.forget_ap(ap_mac)
                        if result['success']:
                            print("[OK] forget request accepted")
                        elif result.get('skipped'):
                            print(f"[SKIP] {result.get('error', 'skipped')}")
                        else:
                            print(f"[FAIL] {result.get('error', 'unknown error')}")

                    # Skip offline verification for orphan APs. Once they drop out of
                    # controller inventory we may only have their MAC, not a usable IP.
                    if args.actual_forget and args.verify_offline and depth == -1:
                        print("\n  Skipping offline verification for orphan APs (no reliable IP to probe).\n")
                        continue

                    # After processing this layer, verify APs are offline before moving on.
                    if args.actual_forget and args.verify_offline:
                        print(f"\n  Verifying all {len(layer_aps)} AP(s) in this layer are offline...")
                        all_offline = True
                        verify_targets = [
                            ap for ap in layer_aps
                            if ap.get("mac")
                        ]
                        max_workers = min(len(verify_targets), 8) if verify_targets else 1
                        with ThreadPoolExecutor(max_workers=max_workers) as executor:
                            future_to_ap = {
                                executor.submit(
                                    ping_ap_offline,
                                    ap.get("mac"),
                                    ap.get("name") or ap.get("model", "Unknown AP"),
                                    ap.get("ip"),
                                    args.offline_timeout,
                                ): ap
                                for ap in verify_targets
                            }
                            verification_results = {}
                            for future in as_completed(future_to_ap):
                                ap = future_to_ap[future]
                                ap_mac = ap.get("mac", "").lower()
                                try:
                                    verification_results[ap_mac] = future.result()
                                except Exception as e:
                                    verification_results[ap_mac] = {
                                        'success': False,
                                        'message': f'ping verification error: {e}',
                                    }

                        for ap in layer_aps:
                            ap_mac = ap.get("mac", "").lower()
                            ap_name = ap.get("name") or ap.get("model", "Unknown AP")
                            ap_ip = ap.get("ip")
                            result = verification_results.get(ap_mac, {
                                'success': False,
                                'message': 'verification did not run',
                            })
                            ip_label = f" ({ap_ip})" if ap_ip else ""
                            status = "OK" if result.get('success') else "FAIL"
                            print(f"    {ap_name}{ip_label}... [{status}] {result.get('message', 'unknown result')}")
                            if not result.get('success'):
                                all_offline = False

                        if all_offline:
                            if i < len(sorted_depths) - 1:
                                print("  All APs confirmed forgotten. Proceeding to next layer...\n")
                            else:
                                print("  All APs confirmed forgotten.\n")
                        else:
                            print("  Layer verification failed. Stopping forget --aps.\n")
                            sys.exit(1)

                if args.actual_forget:
                    print("\nAll APs processed for forget --aps.")
                else:
                    print("\nDry run complete. Re-run with --actual_forget to perform the forget.")
                sys.exit(0)

        # =====================================================================
        # ADOPT_AP action
        # =====================================================================
        if args.action == 'adopt_ap':
            print("Fetching UniFi devices...")
            all_devices = unifi_utils.get_devices()
            aps = [device for device in all_devices if device.get("type") == "uap"]

            if not aps:
                print("No Access Points found.")
                sys.exit(0)

            if args.ap_mac:
                target_mac = args.ap_mac.lower()
                matching_aps = [ap for ap in aps if ap.get("mac", "").lower() == target_mac]
                if not matching_aps:
                    print(f"Error: No AP found with MAC {args.ap_mac}")
                    sys.exit(1)
                aps_to_adopt = matching_aps
            elif args.ap_name:
                matching_aps = [ap for ap in aps if (ap.get("name") or ap.get("model", "")).lower() == args.ap_name.lower()]
                if not matching_aps:
                    print(f"Error: No AP found with name '{args.ap_name}'")
                    sys.exit(1)
                aps_to_adopt = matching_aps
            else:
                aps_to_adopt = aps

            if len(aps_to_adopt) > 1:
                print()
                display_ap_tree(aps_to_adopt, all_devices)

            use_default_order = (not args.ap_mac and not args.ap_name)

            def _print_adopt_result(ap, result):
                ap_name = ap.get("name") or ap.get("model", "Unknown AP")
                ap_mac = ap.get("mac", "unknown-mac")
                if result['success']:
                    print(f"  {ap_name} ({ap_mac})... [OK] adoption initiated")
                elif result.get('skipped'):
                    print(f"  {ap_name} ({ap_mac})... [SKIP] {result.get('error', 'skipped')}")
                else:
                    print(f"  {ap_name} ({ap_mac})... [FAIL] {result.get('error', 'unknown error')}")

            def _wait_for_ap_adoption(ap_mac, timeout_seconds, require_parent_link=False):
                deadline = time.time() + timeout_seconds
                target_mac = ap_mac.lower()

                while time.time() < deadline:
                    current_devices = unifi_utils.get_devices()
                    matching_ap = None
                    for device in current_devices:
                        if device.get("type") != "uap":
                            continue
                        device_mac = device.get("mac", "").lower()
                        if device_mac == target_mac:
                            matching_ap = device
                            break

                    if matching_ap and _is_ap_adoption_complete(matching_ap, require_parent_link=require_parent_link):
                        uplink_mac = (
                            matching_ap.get("uplink_ap_mac")
                            or matching_ap.get("last_uplink", {}).get("uplink_mac")
                            or matching_ap.get("uplink", {}).get("uplink_mac")
                        )
                        uplink_type = (
                            matching_ap.get("uplink", {}).get("type")
                            or matching_ap.get("last_uplink", {}).get("type")
                        )
                        readiness = "wired" if uplink_type == "wire" else ("linked" if uplink_mac else "adopted")
                        return True, readiness

                    time.sleep(5)

                final_state = unifi_utils.get_ap_state(ap_mac)
                return False, final_state

            def _maybe_set_ap_name_from_dns(ap_mac):
                """
                Set AP name from reverse DNS if the AP doesn't already have a custom name.
                This function looks up the AP's IP address, performs a reverse DNS lookup,
                and renames the AP to the resolved hostname if it currently has only the
                default model name. APs that already have a custom name will be skipped.
                A custom name may have been set by:
                  - pfsense2unifi sync (from pfSense DHCP reservations)
                  - A restored UniFi configuration backup
                  - Manual configuration in the UniFi UI
                """
                print(f"    Checking reverse DNS for {ap_mac}...", flush=True)
                rename_result = unifi_utils.set_ap_name_from_reverse_dns(ap_mac)
                if rename_result.get('success'):
                    print(f"    [OK] AP name set from reverse DNS: {rename_result.get('name')}")
                elif rename_result.get('skipped'):
                    print(f"    [SKIP] Reverse DNS naming skipped: {rename_result.get('error', 'skipped')}")
                else:
                    print(f"    [WARN] Failed to set AP name from reverse DNS: {rename_result.get('error', 'unknown error')}")
                return rename_result

            def _format_adopt_wait_error(result):
                error = result.get('error', 'not ready yet')
                if result.get('status_code') == 400:
                    return 'not ready for adoption yet'
                return error

            def _attempt_parallel_adoptions(candidate_aps):
                results = {}
                if not candidate_aps:
                    return results

                max_workers = min(len(candidate_aps), 8)
                with ThreadPoolExecutor(max_workers=max_workers) as executor:
                    future_to_ap = {
                        executor.submit(unifi_utils.adopt_ap, ap.get("mac")): ap
                        for ap in candidate_aps
                        if ap.get("mac")
                    }
                    for future in as_completed(future_to_ap):
                        ap = future_to_ap[future]
                        ap_mac = ap.get("mac", "").lower()
                        try:
                            results[ap_mac] = future.result()
                        except Exception as e:
                            results[ap_mac] = {'success': False, 'error': str(e)}

                return results

            if use_default_order:
                adopt_timed_out = False
                unresolved_macs = []
                fully_adopted_aps = [ap for ap in aps_to_adopt if _is_ap_adoption_complete(ap)]
                startup_has_zero_adopted = len(fully_adopted_aps) == 0
                initial_orphan_batch_attempted = False
                processed_macs = {
                    ap.get("mac", "").lower()
                    for ap in fully_adopted_aps
                    if ap.get("mac")
                }
                initiated_adoptions = set()
                in_progress_adoptions = set()
                named_after_adoption = set()
                reported_in_progress = set()
                last_adopt_errors = {}
                all_seen_macs = {
                    ap.get("mac", "").lower()
                    for ap in aps_to_adopt
                    if ap.get("mac")
                }

                if startup_has_zero_adopted:
                    print(
                        f"\nAdopting APs with zero startup topology: initial orphan batch in parallel, "
                        f"then sequential until timeout ({args.sequence_timeout}s)...\n"
                    )
                else:
                    print(f"\nAdopting all APs sequentially until all adopt or timeout ({args.sequence_timeout}s)...\n")
                if fully_adopted_aps:
                    print(f"Already fully adopted: {len(fully_adopted_aps)} AP(s) will be skipped.\n")
                all_known_already_adopted = len(fully_adopted_aps) == len(aps_to_adopt)
                if all_known_already_adopted:
                    print("All currently known APs are already fully adopted.")
                    print("Waiting for any newly appearing mesh APs. Abort manually if no more APs are expected.\n")

                discovery_deadline = time.time() + args.sequence_timeout
                print("New AP discovery/adoption sequence")
                while time.time() < discovery_deadline:
                    current_devices = unifi_utils.get_devices()
                    current_aps = [device for device in current_devices if device.get("type") == "uap"]
                    current_ap_by_mac = {}
                    for ap in current_aps:
                        ap_mac = ap.get("mac", "").lower()
                        if not ap_mac:
                            continue
                        current_ap_by_mac[ap_mac] = ap
                        all_seen_macs.add(ap_mac)

                    adopted_this_cycle = False
                    for ap_mac, ap in current_ap_by_mac.items():
                        if ap_mac in processed_macs:
                            continue
                        if _is_ap_adoption_complete(ap):
                            ap_name = ap.get("name") or ap.get("model", "Unknown AP")
                            ap_ip = ap.get("ip")
                            if ap_mac in initiated_adoptions or ap_mac in in_progress_adoptions:
                                if ap_ip:
                                    print(f"  {ap_name} ({ap_mac}, {ap_ip})... [OK] adoption completed")
                                else:
                                    print(f"  {ap_name} ({ap_mac})... [OK] adoption completed")
                            processed_macs.add(ap_mac)
                            if (ap_mac in initiated_adoptions or ap_mac in in_progress_adoptions) and ap_mac not in named_after_adoption:
                                rename_result = _maybe_set_ap_name_from_dns(ap_mac)
                                skip_reason = rename_result.get('error', '') if rename_result.get('skipped') else ''
                                if rename_result.get('success') or skip_reason in {
                                    'AP already has a non-default name',
                                    'AP name already matches reverse DNS',
                                }:
                                    named_after_adoption.add(ap_mac)
                            adopted_this_cycle = True

                    candidate_aps = [
                        ap for ap_mac, ap in current_ap_by_mac.items()
                        if ap_mac not in processed_macs
                    ]
                    candidate_aps.sort(key=lambda ap: ap.get("mac", ""))

                    if not candidate_aps:
                        remaining = max(0, int(discovery_deadline - time.time()))
                        if remaining == 0:
                            break
                        if current_ap_by_mac:
                            print(f"  All currently known APs are already adopted or settling. Waiting 15 seconds... ({remaining}s remaining)")
                        else:
                            print(f"  No new APs discovered yet. Waiting 15 seconds... ({remaining}s remaining)")
                        time.sleep(min(15, remaining))
                        continue

                    accepted_this_cycle = False
                    use_initial_parallel_batch = (
                        startup_has_zero_adopted
                        and not initial_orphan_batch_attempted
                    )

                    if use_initial_parallel_batch:
                        initial_orphan_batch_attempted = True
                        print(f"  Initial orphan batch: attempting {len(candidate_aps)} AP(s) in parallel")
                        adopt_results = _attempt_parallel_adoptions(candidate_aps)
                        for ap in candidate_aps:
                            ap_mac = ap.get("mac", "").lower()
                            ap_name = ap.get("name") or ap.get("model", "Unknown AP")
                            result = adopt_results.get(ap_mac)
                            if not result:
                                continue

                            if result.get('success'):
                                initiated_adoptions.add(ap_mac)
                                in_progress_adoptions.discard(ap_mac)
                                last_adopt_errors.pop(ap_mac, None)
                                print(f"  {ap_name} ({ap_mac})... [OK] adoption initiated")
                                accepted_this_cycle = True
                            elif result.get('skipped') and result.get('error') == 'AP is already adopted':
                                if not _is_ap_adoption_complete(ap):
                                    in_progress_adoptions.add(ap_mac)
                                    last_adopt_errors.pop(ap_mac, None)
                                    if ap_mac not in reported_in_progress:
                                        print(f"  {ap_name} ({ap_mac})... [WAIT] adoption already in progress")
                                        reported_in_progress.add(ap_mac)
                                else:
                                    processed_macs.add(ap_mac)
                            else:
                                last_adopt_errors[ap_mac] = _format_adopt_wait_error(result)
                    else:
                        selected_ap = candidate_aps[0]
                        ap_mac = selected_ap.get("mac", "").lower()
                        ap_name = selected_ap.get("name") or selected_ap.get("model", "Unknown AP")
                        result = unifi_utils.adopt_ap(ap_mac)

                        if result.get('success'):
                            initiated_adoptions.add(ap_mac)
                            in_progress_adoptions.discard(ap_mac)
                            last_adopt_errors.pop(ap_mac, None)
                            print(f"  {ap_name} ({ap_mac})... [OK] adoption initiated")
                            accepted_this_cycle = True
                        elif result.get('skipped') and result.get('error') == 'AP is already adopted':
                            if not _is_ap_adoption_complete(selected_ap):
                                in_progress_adoptions.add(ap_mac)
                                last_adopt_errors.pop(ap_mac, None)
                                if ap_mac not in reported_in_progress:
                                    print(f"  {ap_name} ({ap_mac})... [WAIT] adoption already in progress")
                                    reported_in_progress.add(ap_mac)
                            else:
                                processed_macs.add(ap_mac)
                        else:
                            last_adopt_errors[ap_mac] = _format_adopt_wait_error(result)

                    remaining = max(0, int(discovery_deadline - time.time()))
                    if remaining > 0:
                        if adopted_this_cycle or accepted_this_cycle:
                            print("  Waiting 15 seconds before checking for the next AP...\n")
                        else:
                            print("  No AP accepted adoption this cycle. Waiting 15 seconds...\n")
                        time.sleep(min(15, remaining))
                else:
                    pass

                if time.time() >= discovery_deadline:
                    adopt_timed_out = True
                    print(f"\nAdoption sequence timeout reached after {args.sequence_timeout} seconds.")
                    unresolved_macs = sorted(all_seen_macs - processed_macs)
                    if unresolved_macs:
                        print("APs not adopted before timeout:")
                        for ap_mac in unresolved_macs:
                            current_ap = next((ap for ap in current_aps if ap.get("mac", "").lower() == ap_mac), None)
                            ap_name = (
                                (current_ap.get("name") or current_ap.get("model", "Unknown AP"))
                                if current_ap else ap_mac
                            )
                            reason = last_adopt_errors.get(ap_mac, "controller did not accept adoption before timeout")
                            print(f"  {ap_name} ({ap_mac})... [FAIL] {reason}")
            else:
                print(f"\nAdopting {len(aps_to_adopt)} AP(s)...\n")
                for ap in aps_to_adopt:
                    ap_name = ap.get("name") or ap.get("model", "Unknown AP")
                    ap_mac = ap.get("mac")
                    if not ap_mac:
                        print(f"  {ap_name}... [FAIL] missing MAC address")
                        continue

                    print(f"  {ap_name}... ", end="", flush=True)
                    result = unifi_utils.adopt_ap(ap_mac)
                    if result['success']:
                        print("[OK]")
                    elif result.get('skipped'):
                        print(f"[SKIP] {result.get('error', 'skipped')}")
                    else:
                        print(f"[FAIL] {result.get('error', 'unknown error')}")

            print("\nAll APs processed for adopt_ap.")
            if use_default_order and adopt_timed_out and unresolved_macs:
                sys.exit(1)
            sys.exit(0)

        # =====================================================================
        # UPGRADE_AP action
        # =====================================================================
        if args.action == 'upgrade_ap':
            print("Fetching UniFi devices...")
            all_devices = unifi_utils.get_devices()
            aps = [device for device in all_devices if device.get("type") == "uap"]

            if not aps:
                print("No Access Points found.")
                sys.exit(0)

            aps_to_upgrade = []

            if args.ap_mac:
                # Upgrade specific AP by MAC
                target_mac = args.ap_mac.lower()
                matching_aps = [ap for ap in aps if ap.get("mac", "").lower() == target_mac]
                if not matching_aps:
                    print(f"Error: No AP found with MAC {args.ap_mac}")
                    sys.exit(1)
                aps_to_upgrade = matching_aps
            elif args.ap_name:
                # Upgrade specific AP by name
                matching_aps = [ap for ap in aps if (ap.get("name") or ap.get("model", "")).lower() == args.ap_name.lower()]
                if not matching_aps:
                    print(f"Error: No AP found with name '{args.ap_name}'")
                    sys.exit(1)
                aps_to_upgrade = matching_aps
            else:
                # Upgrade all APs
                aps_to_upgrade = aps

            model_validation_error = _validate_custom_upgrade_models(
                aps_to_upgrade,
                firmware_url=getattr(args, 'firmware_url', None),
                firmware_file=getattr(args, 'firmware_file', None),
            )
            if model_validation_error:
                print(f"Error: {model_validation_error}")
                sys.exit(1)

            ssh_username = None
            ssh_password = None
            if getattr(args, 'firmware_file', None) and args.actual_upgrade:
                ssh_username, ssh_password = get_ssh_credentials()
                if not ssh_username or not ssh_password:
                    print("Error: Could not retrieve AP SSH credentials required for --firmware_file upgrades")
                    sys.exit(1)

            # Run pre-upgrade health check (always run to detect already-upgrading APs)
            already_upgrading_aps = []  # Initialize to empty
            health_result = unifi_utils.check_ap_health_before_upgrade(aps_to_upgrade)
            if not health_result['success']:
                print(f"Error: {health_result['message']}")
                print(f"\nTo proceed, wait for the AP(s) to complete initialization, then try again.")
                sys.exit(1)
            print(health_result['message'])

            already_upgrading_aps = health_result['already_upgrading']
            # Use only ready APs for upgrade (already upgrading ones will be monitored but not re-initiated)
            aps_to_upgrade = health_result['ready_aps']

            if not aps_to_upgrade and not already_upgrading_aps:
                print("Error: No APs ready for upgrade")
                sys.exit(1)

            if already_upgrading_aps:
                if args.actual_upgrade:
                    print(f"\nNote: {len(already_upgrading_aps)} AP(s) already upgrading, monitoring only")
                # Add already upgrading APs back to the full list for monitoring, but not for initiation
                # We'll track them separately in the upgrade process

            # Display the mesh topology before upgrading (only if more than one AP)
            # Show topology of all APs (ready + already upgrading)
            aps_for_tree_display = aps_to_upgrade + already_upgrading_aps
            if len(aps_for_tree_display) > 1:
                display_ap_tree(aps_for_tree_display, all_devices)

            # Check if there are any mesh APs (depth >= 1)
            # Calculate depths for ALL APs (ready + already upgrading) so we don't mark upgrading APs as orphans
            all_aps_for_depth = aps_to_upgrade + already_upgrading_aps
            depths = calculate_ap_mesh_depths(all_aps_for_depth)
            has_mesh_aps = any(depth >= 1 for depth in depths.values())

            # Use mesh-ordered upgrade if there are mesh APs and we're upgrading all APs (not a specific one)
            use_mesh_order = (has_mesh_aps and not args.ap_mac and not args.ap_name)

            dry_run = not args.actual_upgrade  # Default is dry run
            mode_str = "[ACTUAL]" if args.actual_upgrade else "[DRY RUN]"

            # Initialize upgrade tracking (unified for both mesh and standard paths)
            import time
            from datetime import datetime

            upgrade_session_start = time.time()
            start_time_str = datetime.now().strftime("%Y-%m-%d %H:%M:%S")

            # Track APs being upgraded (MAC -> target version -> initiation_time)
            aps_upgrading = {}
            ap_initiation_times = {}

            # Pre-populate with already upgrading APs (so they get monitored regardless of path)
            for ap in already_upgrading_aps:
                ap_mac = ap.get("mac")
                ap_name = ap.get("name") or ap.get("model", "Unknown AP")
                upgrade_to = ap.get("upgrade_to_firmware", "Unknown")
                if ap_mac:
                    aps_upgrading[ap_mac] = {
                        'name': ap_name,
                        'target_version': upgrade_to
                    }
                    # Use current time as initiation (they started before this script)
                    ap_initiation_times[ap_mac] = time.time()

            if use_mesh_order and not args.ap_mac and not args.ap_name:
                # Print message including already upgrading APs
                if already_upgrading_aps:
                    print(f"\n{mode_str} Initiating firmware upgrades for {len(aps_to_upgrade)} AP(s), monitoring {len(already_upgrading_aps)} already-upgrading...")
                else:
                    print(f"\n{mode_str} Initiating firmware upgrades for {len(aps_to_upgrade)} AP(s) in mesh order (leaf to parent)...")
                print(f"Started at: {start_time_str}\n")
                print("Note: Upgrades are queued and will be processed by the APs. Monitoring progress...\n")

                # Group APs by depth (include both ready_aps and already_upgrading_aps for display)
                aps_by_depth = defaultdict(list)
                already_upgrading_macs = {ap.get("mac") for ap in already_upgrading_aps if ap.get("mac")}

                # Pre-populate aps_upgrading dict with already-upgrading APs so they're monitored
                # Get fresh device data to get target versions
                all_devices_for_target = unifi_utils.get_devices()
                device_map_for_target = {}
                for device in all_devices_for_target:
                    if device.get("type") == "uap":
                        device_map_for_target[device.get("mac", "").lower()] = device

                for ap in already_upgrading_aps:
                    ap_mac = ap.get("mac")
                    ap_name = ap.get("name") or ap.get("model", "Unknown AP")
                    current_version = unifi_utils.get_ap_current_version(ap_mac)

                    # Get target version from device data
                    device = device_map_for_target.get(ap_mac.lower())
                    target_version = device.get("upgrade_to_firmware", "Unknown") if device else "Unknown"

                    aps_upgrading[ap_mac] = {
                        "name": ap_name,
                        "target_version": target_version,
                        "current_version": current_version,
                        "custom_firmware": False,
                    }
                    # Use current time as start time for already-upgrading APs
                    ap_initiation_times[ap_mac] = time.time()

                for ap in aps_to_upgrade + already_upgrading_aps:
                    ap_mac = ap.get("mac")
                    depth = depths.get(ap_mac, -1)
                    aps_by_depth[depth].append(ap)

                # Sort depths (deepest/highest numbers first, which means leaf to parent)
                sorted_depths = sorted(aps_by_depth.keys(), reverse=True)

                for i, depth in enumerate(sorted_depths):
                    layer_aps = aps_by_depth[depth]

                    if depth == -1:
                        depth_label = "Orphan"
                    elif depth == 0:
                        depth_label = "Wired Root"
                    else:
                        depth_label = f"Mesh Depth {depth}"

                    print(f"Layer {i+1}: {depth_label} ({len(layer_aps)} AP{'s' if len(layer_aps) != 1 else ''})")

                    # Track if any AP in this layer is actually being upgraded
                    layer_has_upgrade = False

                    # Issue upgrade commands to all APs in this layer (concurrent upgrades)
                    for ap in layer_aps:
                        ap_name = ap.get("name") or ap.get("model", "Unknown AP")
                        ap_mac = ap.get("mac")
                        if ap_mac:
                            # Skip APs already upgrading - they're already in aps_upgrading dict
                            if ap_mac in aps_upgrading:
                                print(f"  {ap_name}... [ALREADY UPGRADING]")
                                continue

                            result = unifi_utils.upgrade_ap_firmware(
                                ap_mac,
                                dry_run=dry_run,
                                firmware_url=getattr(args, 'firmware_url', None),
                                firmware_file=getattr(args, 'firmware_file', None),
                                reflash=getattr(args, 'reflash', False),
                                ssh_username=ssh_username,
                                ssh_password=ssh_password,
                            )
                            if result['success']:
                                current = result.get('current_version', 'Unknown')
                                new = result.get('new_version', 'Unknown')
                                target_version = result.get('parsed_version') or new
                                monitor_via_ping = bool(getattr(args, 'firmware_file', None))
                                print(f"  {ap_name}... ", end="", flush=True)

                                # Check if upgrade is already in progress externally (skip_initiation flag)
                                if result.get('skip_initiation'):
                                    print(f"[MONITORING] Already upgrading externally")
                                    if target_version and current != target_version:
                                        aps_upgrading[ap_mac] = {
                                            "name": ap_name,
                                            "target_version": target_version,
                                            "current_version": current,
                                            "custom_firmware": bool(result.get("custom_firmware")),
                                            "monitor_via_ping": monitor_via_ping,
                                            "ip": ap.get("ip"),
                                        }
                                        ap_initiation_times[ap_mac] = time.time()
                                        layer_has_upgrade = True
                                    continue

                                if result.get('skipped'):
                                    print(f"[SKIP] {result.get('message', 'Already on requested firmware; use --reflash to force reinstalling the same version')}")
                                elif result.get('new_version') and current != target_version:
                                    if dry_run:
                                        print(f"[UPGRADABLE] {current} -> {target_version}")
                                    else:
                                        command_issue_time = time.time()
                                        initiation_time_str = datetime.now().strftime("%H:%M:%S")
                                        print(f"[INITIATING] {current} -> {target_version} at {initiation_time_str}")

                                        upgrade_success = False
                                        actual_start_time = None

                                        if monitor_via_ping:
                                            print("  [OK] SSH/SCP transfer completed; skipping controller upgrade-state verification and monitoring by ping.\n", flush=True)
                                            upgrade_success = True
                                            actual_start_time = time.time()
                                        else:
                                            # Get initial state before the upgrade was initiated
                                            try:
                                                initial_state = unifi_utils.get_ap_state(ap_mac, raise_on_error=True)
                                            except Exception as e:
                                                print(f"[FAIL] Controller query failed before verification: {e}\n", flush=True)
                                                continue

                                            # Verify upgrade state change - with retry if initial attempt fails
                                            verify_result = unifi_utils.verify_upgrade_initiated(ap_mac, initial_state)
                                            if verify_result['success']:
                                                print(f"  [OK] Upgrade detected: {verify_result['message']}\n", flush=True)
                                                upgrade_success = True
                                                actual_start_time = time.time()
                                            else:
                                                # Initial attempt failed, retry the upgrade command once
                                                print(f"  [WAIT] No active upgrade in 15s, retrying upgrade command...", flush=True)
                                                retry_result = unifi_utils.upgrade_ap_firmware(
                                                    ap_mac,
                                                    dry_run=False,
                                                    firmware_url=getattr(args, 'firmware_url', None),
                                                    firmware_file=getattr(args, 'firmware_file', None),
                                                    reflash=getattr(args, 'reflash', False),
                                                    ssh_username=ssh_username,
                                                    ssh_password=ssh_password,
                                                )
                                                if retry_result['success'] and not retry_result.get('skip_initiation'):
                                                    # Check for upgrade activity again after retry
                                                    try:
                                                        retry_initial_state = unifi_utils.get_ap_state(ap_mac, raise_on_error=True)
                                                    except Exception as e:
                                                        print(f"  [FAIL] Controller query failed before retry verification: {e}. Skipping this AP.\n", flush=True)
                                                        continue
                                                    retry_verify_result = unifi_utils.verify_upgrade_initiated(ap_mac, retry_initial_state)
                                                    if retry_verify_result['success']:
                                                        print(f"  [OK] Upgrade detected (retry): {retry_verify_result['message']}\n", flush=True)
                                                        upgrade_success = True
                                                        actual_start_time = time.time()
                                                    else:
                                                        print(f"  [FAIL] Upgrade failed to start even after retry. Skipping this AP.\n", flush=True)
                                                else:
                                                    print(f"  [FAIL] Failed to retry upgrade: {retry_result.get('message', 'Unknown error')}. Skipping this AP.\n", flush=True)

                                        # Only track if upgrade was successful
                                        if upgrade_success:
                                            monitor_entry = {
                                                "name": ap_name,
                                                "target_version": target_version,
                                                "current_version": current,
                                                "custom_firmware": bool(result.get("custom_firmware")),
                                                "monitor_via_ping": monitor_via_ping,
                                                "ip": ap.get("ip"),
                                            }
                                            if monitor_via_ping:
                                                ping_threshold, settle_threshold = _get_ssh_upgrade_grace_seconds(ap)
                                                monitor_entry["ping_phase"] = "waiting_for_offline"
                                                monitor_entry["ping_failures"] = 0
                                                monitor_entry["ping_successes"] = 0
                                                monitor_entry["controller_ready_polls"] = 0
                                                monitor_entry["ping_progress_threshold"] = ping_threshold
                                                monitor_entry["controller_settle_threshold"] = settle_threshold
                                            aps_upgrading[ap_mac] = monitor_entry
                                            ap_initiation_times[ap_mac] = actual_start_time
                                            layer_has_upgrade = True
                                else:
                                    print(f"(already latest)")
                            else:
                                print(f"  {ap_name}... [FAIL] {result.get('message', 'Unknown error')}")

                    # Add configurable delay between layers (but not after the last layer or in dry run mode)
                    if i < len(sorted_depths) - 1 and not dry_run and layer_has_upgrade:
                        pass  # No delay between layers for speed

                # Monitor upgrade progress (only in actual mode and if we have APs to monitor)
                if not dry_run and aps_upgrading:
                    print(f"\n{'='*80}")
                    print(f"Monitoring firmware upgrade progress for {len(aps_upgrading)} AP(s)...")
                    timeout_minutes = args.upgrade_timeout // 60
                    print(f"Checking every 5 seconds. Timeout: {timeout_minutes} minute(s)")
                    print(f"{'='*80}\n")

                    completed_aps = {}  # MAC -> completion_time
                    failed_aps = set()  # Set of MAC addresses that failed to upgrade
                    ap_states = {}  # MAC -> last known state (to detect reversions)
                    retry_count = {}  # MAC -> number of retries
                    reversion_times = {}  # MAC -> time when reversion was first detected
                    monitoring_start = time.time()
                    last_progress_time = monitoring_start
                    timeout_seconds = args.upgrade_timeout
                    check_interval = 5  # 5 seconds
                    no_progress_threshold = 60  # 60 seconds
                    no_progress_displayed = False
                    max_retries = 2  # Maximum number of retries per AP
                    retry_delay_seconds = 30  # Wait 30 seconds before retrying after a reversion

                    while len(completed_aps) < len(aps_upgrading):
                        elapsed = time.time() - monitoring_start
                        time_since_progress = time.time() - last_progress_time

                        # Check timeout
                        if elapsed > timeout_seconds:
                            print(f"\n[TIME]  Upgrade monitoring timeout ({timeout_minutes} minute(s) elapsed)")
                            remaining = [mac for mac in aps_upgrading if mac not in completed_aps]
                            if remaining:
                                print(f"The following APs may still be upgrading:")
                                for ap_mac in remaining:
                                    ap_info = aps_upgrading[ap_mac]
                                    print(f"  - {ap_info['name']}: {ap_info['target_version']}")
                            break

                        # Check each AP's current version for completion
                        for ap_mac in list(aps_upgrading.keys()):
                            if ap_mac not in completed_aps:
                                ap_info = aps_upgrading[ap_mac]
                                if ap_info.get("monitor_via_ping"):
                                    ping_result = _advance_ping_upgrade_monitor(ap_info)
                                    if ping_result["event"] == "error":
                                        print(f"[FAIL] {ap_info['name']}: {ping_result['message']}", flush=True)
                                        completed_aps[ap_mac] = time.time()
                                        failed_aps.add(ap_mac)
                                        continue
                                    if ping_result["event"] in {"offline", "online", "offline_again"}:
                                        print(f"[WAIT] {ap_info['name']}: {ping_result['message']}", flush=True)
                                        last_progress_time = time.time()
                                        no_progress_displayed = False
                                    if ap_info.get("ping_phase") != "verifying_version":
                                        continue

                                try:
                                    if ap_info.get("monitor_via_ping"):
                                        target_version = ap_info.get('target_version')
                                        controller_ready, controller_reason, current_version = _controller_reports_ssh_upgrade_ready(
                                            ap_mac,
                                            target_version,
                                        )
                                        current_state = "RUNNING" if controller_ready else "CONNECTING/INITIALIZING"
                                        if not controller_ready:
                                            ap_info["controller_ready_polls"] = 0
                                            continue
                                        ap_info["controller_ready_polls"] = ap_info.get("controller_ready_polls", 0) + 1
                                        if ap_info["controller_ready_polls"] < 2:
                                            continue
                                    else:
                                        current_version = unifi_utils.get_ap_current_version(ap_mac, raise_on_error=True)
                                        current_state = unifi_utils.get_ap_state(ap_mac, raise_on_error=True)
                                except Exception as e:
                                    print(f"[WARN] {ap_info['name']}: Controller query failed during upgrade monitoring: {e}", flush=True)
                                    continue

                                # Detect state reversion: UPGRADING -> UPGRADABLE (upgrade dropped without progress)
                                if not ap_info.get("monitor_via_ping") and ap_mac in ap_states:
                                    prev_state = ap_states[ap_mac]
                                    if prev_state == "UPGRADING" and current_state == "UPGRADABLE":
                                        # First time detecting this reversion
                                        if ap_mac not in reversion_times:
                                            reversion_times[ap_mac] = time.time()

                                        # Check if enough time has passed to retry
                                        time_since_reversion = time.time() - reversion_times[ap_mac]
                                        if time_since_reversion >= retry_delay_seconds:
                                            retries = retry_count.get(ap_mac, 0)
                                            if retries < max_retries:
                                                retry_count[ap_mac] = retries + 1
                                                print(f"[RETRY] {ap_info['name']}: Retrying upgrade (attempt {retries + 1}/{max_retries})", flush=True)

                                                # Retry the upgrade
                                                result = unifi_utils.upgrade_ap_firmware(
                                                    ap_mac,
                                                    skip_health_check=True,
                                                    firmware_url=getattr(args, 'firmware_url', None),
                                                    firmware_file=getattr(args, 'firmware_file', None),
                                                    reflash=getattr(args, 'reflash', False),
                                                    ssh_username=ssh_username,
                                                    ssh_password=ssh_password,
                                                )
                                                if result['success']:
                                                    last_progress_time = time.time()
                                                    no_progress_displayed = False
                                                    # Clear reversion time so we can detect another reversion if needed
                                                    del reversion_times[ap_mac]
                                                else:
                                                    print(f"[FAIL] {ap_info['name']}: Retry failed - {result.get('message', 'Unknown error')}", flush=True)
                                                    completed_aps[ap_mac] = time.time()
                                                    failed_aps.add(ap_mac)
                                            else:
                                                print(f"[FAIL] {ap_info['name']}: Upgrade dropped by controller and max retries ({max_retries}) exceeded", flush=True)
                                                completed_aps[ap_mac] = time.time()
                                                failed_aps.add(ap_mac)

                                # Track current state
                                if not ap_info.get("monitor_via_ping"):
                                    ap_states[ap_mac] = current_state

                                # Check if upgrade completed
                                target_version = ap_info.get('target_version')
                                version_changed = current_version and current_version != ap_info['current_version']
                                if (target_version and current_version == target_version) or (ap_info.get('custom_firmware') and version_changed):
                                    completion_time = time.time()
                                    completed_aps[ap_mac] = completion_time
                                    last_progress_time = completion_time
                                    no_progress_displayed = False

                                    # Calculate duration
                                    initiation_time = ap_initiation_times.get(ap_mac, completion_time)
                                    duration_seconds = completion_time - initiation_time
                                    duration_minutes = int(duration_seconds // 60)
                                    duration_secs = int(duration_seconds % 60)

                                    completion_time_str = datetime.fromtimestamp(completion_time).strftime("%H:%M:%S")
                                    print(f"[OK] Successful upgrade: {ap_info['name']} -> {current_version} at {completion_time_str} (took {duration_minutes}m:{duration_secs:02d}s)", flush=True)

                                # Check if upgrade is actively progressing
                                else:
                                    if ap_info.get("monitor_via_ping"):
                                        continue
                                    try:
                                        actively_upgrading = unifi_utils.is_ap_actively_upgrading(ap_mac, raise_on_error=True)
                                    except Exception as e:
                                        print(f"[WARN] {ap_info['name']}: Controller query failed while checking upgrade activity: {e}", flush=True)
                                        continue

                                    if actively_upgrading:
                                        # Update progress time - active upgrade is progressing
                                        last_progress_time = time.time()
                                        no_progress_displayed = False

                        # Check for stalled upgrades. Controller-driven upgrades use the generic
                        # no-progress threshold; SSH/SCP upgrades use the longer ping/controller
                        # settle thresholds handled below.
                        if time_since_progress > no_progress_threshold and not no_progress_displayed:
                            pending_ping_only = [
                                aps_upgrading[ap_mac]
                                for ap_mac in aps_upgrading
                                if ap_mac not in completed_aps
                                and aps_upgrading[ap_mac].get("monitor_via_ping")
                                and (
                                    (
                                        aps_upgrading[ap_mac].get("ping_phase") != "verifying_version"
                                        and (
                                            time.time() - ap_initiation_times.get(ap_mac, monitoring_start)
                                        ) <= aps_upgrading[ap_mac].get("ping_progress_threshold", 180)
                                    )
                                    or (
                                        aps_upgrading[ap_mac].get("ping_phase") == "verifying_version"
                                        and (
                                            time.time() - aps_upgrading[ap_mac].get("online_detected_at", monitoring_start)
                                        ) <= aps_upgrading[ap_mac].get("controller_settle_threshold", 180)
                                    )
                                )
                            ]
                            if pending_ping_only:
                                continue
                            no_progress_displayed = True
                            only_ping_stalled = all(
                                aps_upgrading[ap_mac].get("monitor_via_ping")
                                for ap_mac in aps_upgrading
                                if ap_mac not in completed_aps
                            )
                            if only_ping_stalled:
                                max_ping_threshold = max(
                                    aps_upgrading[ap_mac].get("ping_progress_threshold", 180)
                                    for ap_mac in aps_upgrading
                                    if ap_mac not in completed_aps and aps_upgrading[ap_mac].get("monitor_via_ping")
                                )
                                print(
                                    f"\n[FAIL] No SSH/SCP upgrade progress detected within {max_ping_threshold} seconds. "
                                    "The following APs failed to upgrade:\n"
                                )
                            else:
                                print(f"\n[FAIL] No progress detected in last {no_progress_threshold} seconds. The following APs failed to upgrade:\n")

                            stalled_aps = []
                            for ap_mac in list(aps_upgrading.keys()):
                                if ap_mac not in completed_aps:
                                    ap_info = aps_upgrading[ap_mac]
                                    if ap_info.get("monitor_via_ping"):
                                        initiation_time = ap_initiation_times.get(ap_mac, monitoring_start)
                                        ping_progress_threshold = ap_info.get("ping_progress_threshold", 180)
                                        if (
                                            ap_info.get("ping_phase") == "waiting_for_offline"
                                            and time.time() - initiation_time > ping_progress_threshold
                                        ):
                                            ap_info["ping_phase"] = "verifying_version"
                                            ap_info["online_detected_at"] = time.time()
                                            ap_info["controller_ready_polls"] = 0
                                            print(
                                                f"  {ap_info['name']}: no ping outage observed within {ping_progress_threshold}s; "
                                                "continuing with controller verification"
                                            )
                                            last_progress_time = time.time()
                                            no_progress_displayed = False
                                        continue
                                    try:
                                        ap_state = unifi_utils.get_ap_state(ap_mac, raise_on_error=True)
                                        current_version = unifi_utils.get_ap_current_version(ap_mac, raise_on_error=True)
                                        is_actively_upgrading = unifi_utils.is_ap_actively_upgrading(ap_mac, raise_on_error=True)
                                    except Exception as e:
                                        print(f"  {ap_info['name']}: controller query failed ({e}) - still monitoring")
                                        continue
                                    state_desc = unifi_utils._get_ap_state_description(ap_state)

                                    # Report as failed if version hasn't changed and upgrade is NOT actively in progress
                                    # (Even if upgrade_to_firmware is queued, if it hasn't started after 60s, it failed)
                                    if current_version == ap_info['current_version'] and not is_actively_upgrading:
                                        print(f"  {ap_info['name']}: {current_version} (stuck at {state_desc}) - upgrade failed to start")
                                        stalled_aps.append(ap_mac)
                                        completed_aps[ap_mac] = time.time()  # Mark as "done" so we stop monitoring it
                                        failed_aps.add(ap_mac)
                                        failed_aps.add(ap_mac)

                            if not stalled_aps:
                                # False alarm - APs are actually progressing, just slowly
                                no_progress_displayed = False
                                last_progress_time = time.time()
                            else:
                                # Report remaining healthy upgrades
                                active_aps = [mac for mac in aps_upgrading if mac not in completed_aps]
                                if active_aps:
                                    print(f"\nContinuing to monitor {len(active_aps)} AP(s) still upgrading...\n")

                        # Show progress countdown
                        if time_since_progress > no_progress_threshold and no_progress_displayed:
                            remaining_timeout = timeout_seconds - elapsed
                            remaining_minutes = int(remaining_timeout // 60)
                            remaining_seconds = int(remaining_timeout % 60)
                            print(f"[WAIT] {remaining_minutes}m:{remaining_seconds:02d}s until timeout...", flush=True)

                        # If all APs upgraded, exit
                        if len(completed_aps) == len(aps_upgrading):
                            successful_count = len(completed_aps) - len(failed_aps)
                            if failed_aps:
                                print(f"\n[PARTIAL] {successful_count} of {len(aps_upgrading)} AP(s) upgraded successfully, {len(failed_aps)} failed.")
                            else:
                                print(f"\n[SUCCESS] All {len(completed_aps)} AP(s) upgraded successfully!")
                            break
                        # Sleep before next check
                        time.sleep(check_interval)
                # Display total execution time
                upgrade_session_end = time.time()
                total_duration = upgrade_session_end - upgrade_session_start
                total_minutes = int(total_duration // 60)
                total_seconds = int(total_duration % 60)
                print(f"\nTotal execution time: {total_minutes}m:{total_seconds:02d}s")
            else:
                # Standard upgrade without mesh ordering
                # Print message including already upgrading APs
                if already_upgrading_aps:
                    print(f"\n{mode_str} Upgrading {len(aps_to_upgrade)} AP(s), monitoring {len(already_upgrading_aps)} already-upgrading...")
                else:
                    print(f"\n{mode_str} Upgrading {len(aps_to_upgrade)} AP(s)...")
                print(f"Started at: {start_time_str}\n")
                print("Note: Upgrades are queued and will be processed by the APs. Monitoring progress...\n")

                for ap in aps_to_upgrade:
                    ap_name = ap.get("name") or ap.get("model", "Unknown AP")
                    ap_mac = ap.get("mac")
                    if ap_mac:
                        # Check if already in upgrade queue (from earlier in this run)
                        if ap_mac in aps_upgrading:
                            print(f"  {ap_name}... [OK] Already queued for upgrade\n")
                            continue
                        # First, check if upgrade is already in progress
                        print(f"  {ap_name}... ", end="", flush=True)
                        ap_already_upgrading = False
                        try:
                            devices = unifi_utils.get_devices()
                            for device in devices:
                                if device.get("mac", "").lower() == ap_mac.lower():
                                    upgrade_progress = device.get("upgrade_progress")

                                    # Check if upgrade is already active (only upgrade_progress is reliable)
                                    if upgrade_progress and upgrade_progress > 0:
                                        print(f"[OK] Upgrade already in progress (detected from controller)\n")
                                        ap_already_upgrading = True
                                        # Track this AP for monitoring
                                        current = device.get("version", "Unknown")
                                        upgrade_to = device.get("upgrade_to_firmware", "Unknown")
                                        aps_upgrading[ap_mac] = {
                                            "name": ap_name,
                                            "target_version": upgrade_to,
                                            "current_version": current,
                                            "custom_firmware": False,
                                        }
                                        ap_initiation_times[ap_mac] = time.time()
                                    break
                        except Exception as e:
                            pass
                        if ap_already_upgrading:
                            continue

                        # If not already upgrading, proceed with upgrade command
                        result = unifi_utils.upgrade_ap_firmware(
                            ap_mac,
                            dry_run=dry_run,
                            firmware_url=getattr(args, 'firmware_url', None),
                            firmware_file=getattr(args, 'firmware_file', None),
                            reflash=getattr(args, 'reflash', False),
                            ssh_username=ssh_username,
                            ssh_password=ssh_password,
                        )
                        if result['success']:
                            current = result.get('current_version', 'Unknown')
                            new = result.get('new_version', 'Unknown')
                            target_version = result.get('parsed_version') or new
                            monitor_via_ping = bool(getattr(args, 'firmware_file', None))

                            # Check if upgrade is already in progress externally (skip_initiation flag)
                            if result.get('skip_initiation'):
                                print(f"[MONITORING] Already upgrading externally\n")
                                if target_version and current != target_version:
                                    aps_upgrading[ap_mac] = {
                                        "name": ap_name,
                                        "target_version": target_version,
                                        "current_version": current,
                                        "custom_firmware": bool(result.get("custom_firmware")),
                                        "monitor_via_ping": monitor_via_ping,
                                        "ip": ap.get("ip"),
                                    }
                                    ap_initiation_times[ap_mac] = time.time()
                                continue

                            if result.get('skipped'):
                                print(f"[SKIP] {result.get('message', 'Already on requested firmware; use --reflash to force reinstalling the same version')}")
                            elif result.get('new_version') and current != target_version:
                                if dry_run:
                                    print(f"[UPGRADABLE] {current} -> {target_version}")
                                else:
                                    command_issue_time = time.time()
                                    initiation_time_str = datetime.now().strftime("%H:%M:%S")
                                    upgrade_success = False
                                    actual_start_time = None

                                    print(f"[INITIATING] {current} -> {target_version} at {initiation_time_str}")

                                    if monitor_via_ping:
                                        print("  [OK] SSH/SCP transfer completed; skipping controller upgrade-state verification and monitoring by ping.\n", flush=True)
                                        upgrade_success = True
                                        actual_start_time = time.time()
                                    else:
                                        try:
                                            initial_state = unifi_utils.get_ap_state(ap_mac, raise_on_error=True)
                                        except Exception as e:
                                            print(f"[FAIL] Controller query failed before verification: {e}\n", flush=True)
                                            continue

                                        # Verify upgrade state change - with one retry if initial attempt fails
                                        verify_result = unifi_utils.verify_upgrade_initiated(ap_mac, initial_state)
                                        if verify_result['success']:
                                            print(f"  [OK] Upgrade detected: {verify_result['message']}\n", flush=True)
                                            upgrade_success = True
                                            actual_start_time = time.time()
                                        else:
                                            # Initial attempt failed, retry the upgrade command once
                                            print(f"  [WAIT] No active upgrade in 15s, retrying upgrade command...", flush=True)
                                            retry_result = unifi_utils.upgrade_ap_firmware(
                                                ap_mac,
                                                dry_run=False,
                                                firmware_url=getattr(args, 'firmware_url', None),
                                                firmware_file=getattr(args, 'firmware_file', None),
                                                reflash=getattr(args, 'reflash', False),
                                                ssh_username=ssh_username,
                                                ssh_password=ssh_password,
                                            )
                                            if retry_result['success'] and not retry_result.get('skip_initiation'):
                                                # Check for upgrade activity again after retry
                                                try:
                                                    retry_initial_state = unifi_utils.get_ap_state(ap_mac, raise_on_error=True)
                                                except Exception as e:
                                                    print(f"  [FAIL] Controller query failed before retry verification: {e}. Skipping this AP.\n", flush=True)
                                                    continue
                                                retry_verify_result = unifi_utils.verify_upgrade_initiated(ap_mac, retry_initial_state)
                                                if retry_verify_result['success']:
                                                    print(f"  [OK] Upgrade detected (retry): {retry_verify_result['message']}\n", flush=True)
                                                    upgrade_success = True
                                                    actual_start_time = time.time()
                                                else:
                                                    print(f"  [FAIL] Upgrade failed to start even after retry. Skipping this AP.\n", flush=True)
                                            else:
                                                print(f"  [FAIL] Failed to retry upgrade: {retry_result.get('message', 'Unknown error')}. Skipping this AP.\n", flush=True)

                                    # Only track if upgrade was successful
                                    if upgrade_success:
                                        monitor_entry = {
                                            "name": ap_name,
                                            "target_version": target_version,
                                            "current_version": current,
                                            "custom_firmware": bool(result.get("custom_firmware")),
                                            "monitor_via_ping": monitor_via_ping,
                                            "ip": ap.get("ip"),
                                        }
                                        if monitor_via_ping:
                                            ping_threshold, settle_threshold = _get_ssh_upgrade_grace_seconds(ap)
                                            monitor_entry["ping_phase"] = "waiting_for_offline"
                                            monitor_entry["ping_failures"] = 0
                                            monitor_entry["ping_successes"] = 0
                                            monitor_entry["controller_ready_polls"] = 0
                                            monitor_entry["ping_progress_threshold"] = ping_threshold
                                            monitor_entry["controller_settle_threshold"] = settle_threshold
                                        aps_upgrading[ap_mac] = monitor_entry
                                        ap_initiation_times[ap_mac] = actual_start_time
                            else:
                                print(f"(already latest)")
                        else:
                            print(f"  {ap_name}... [FAIL] {result.get('message', 'Unknown error')}")

                        # Add configurable delay after each upgrade initiation in actual mode (only if upgrade was attempted and successful)
                        if not dry_run and result.get('success') and result.get('new_version') and result['current_version'] != result['new_version']:
                            time.sleep(args.ap_upgrade_delay)

                # Monitor upgrade progress (only in actual mode and if we have APs to monitor)
                if not dry_run and aps_upgrading:
                    print(f"\n{'='*80}")
                    print(f"Monitoring firmware upgrade progress for {len(aps_upgrading)} AP(s)...")
                    timeout_minutes = args.upgrade_timeout // 60
                    print(f"Checking every 5 seconds. Timeout: {timeout_minutes} minute(s)")
                    print(f"{'='*80}\n")

                    completed_aps = {}  # MAC -> completion_time
                    failed_aps = set()  # Set of MAC addresses that failed to upgrade
                    ap_states = {}  # MAC -> last known state (to detect reversions)
                    retry_count = {}  # MAC -> number of retries
                    reversion_times = {}  # MAC -> time when reversion was first detected
                    monitoring_start = time.time()
                    last_progress_time = monitoring_start
                    timeout_seconds = args.upgrade_timeout
                    check_interval = 5  # 5 seconds
                    no_progress_threshold = 60  # 60 seconds
                    no_progress_displayed = False
                    max_retries = 2  # Maximum number of retries per AP
                    retry_delay_seconds = 30  # Wait 30 seconds before retrying after a reversion

                    while len(completed_aps) < len(aps_upgrading):
                        elapsed = time.time() - monitoring_start
                        time_since_progress = time.time() - last_progress_time

                        # Check timeout
                        if elapsed > timeout_seconds:
                            print(f"\n[TIME]  Upgrade monitoring timeout ({timeout_minutes} minute(s) elapsed)")
                            remaining = [mac for mac in aps_upgrading if mac not in completed_aps]
                            if remaining:
                                print(f"The following APs may still be upgrading:")
                                for ap_mac in remaining:
                                    ap_info = aps_upgrading[ap_mac]
                                    print(f"  - {ap_info['name']}: {ap_info['target_version']}")
                            break

                        # Check each AP's current version for completion
                        for ap_mac in list(aps_upgrading.keys()):
                            if ap_mac not in completed_aps:
                                ap_info = aps_upgrading[ap_mac]
                                if ap_info.get("monitor_via_ping"):
                                    ping_result = _advance_ping_upgrade_monitor(ap_info)
                                    if ping_result["event"] == "error":
                                        print(f"[FAIL] {ap_info['name']}: {ping_result['message']}", flush=True)
                                        completed_aps[ap_mac] = time.time()
                                        failed_aps.add(ap_mac)
                                        continue
                                    if ping_result["event"] in {"offline", "online", "offline_again"}:
                                        print(f"[WAIT] {ap_info['name']}: {ping_result['message']}", flush=True)
                                        last_progress_time = time.time()
                                        no_progress_displayed = False
                                    if ap_info.get("ping_phase") != "verifying_version":
                                        continue
                                try:
                                    if ap_info.get("monitor_via_ping"):
                                        target_version = ap_info.get('target_version')
                                        controller_ready, controller_reason, current_version = _controller_reports_ssh_upgrade_ready(
                                            ap_mac,
                                            target_version,
                                        )
                                        current_state = "RUNNING" if controller_ready else "CONNECTING/INITIALIZING"
                                        if not controller_ready:
                                            ap_info["controller_ready_polls"] = 0
                                            continue
                                        ap_info["controller_ready_polls"] = ap_info.get("controller_ready_polls", 0) + 1
                                        if ap_info["controller_ready_polls"] < 2:
                                            continue
                                    else:
                                        current_state = unifi_utils.get_ap_state(ap_mac, raise_on_error=True)
                                        current_version = unifi_utils.get_ap_current_version(ap_mac, raise_on_error=True)
                                except Exception as e:
                                    print(f"[WARN] {ap_info['name']}: Controller query failed during upgrade monitoring: {e}", flush=True)
                                    continue

                                # Detect state reversion: UPGRADING -> UPGRADABLE (upgrade dropped without progress)
                                if not ap_info.get("monitor_via_ping") and ap_mac in ap_states:
                                    prev_state = ap_states[ap_mac]
                                    if prev_state == "UPGRADING" and current_state == "UPGRADABLE":
                                        # First time detecting this reversion
                                        if ap_mac not in reversion_times:
                                            reversion_times[ap_mac] = time.time()

                                        # Check if enough time has passed to retry
                                        time_since_reversion = time.time() - reversion_times[ap_mac]
                                        if time_since_reversion >= retry_delay_seconds:
                                            retries = retry_count.get(ap_mac, 0)
                                            if retries < max_retries:
                                                retry_count[ap_mac] = retries + 1
                                                print(f"[RETRY] {ap_info['name']}: Retrying upgrade (attempt {retries + 1}/{max_retries})", flush=True)

                                                # Retry the upgrade
                                                result = unifi_utils.upgrade_ap_firmware(
                                                    ap_mac,
                                                    skip_health_check=True,
                                                    firmware_url=getattr(args, 'firmware_url', None),
                                                    firmware_file=getattr(args, 'firmware_file', None),
                                                    reflash=getattr(args, 'reflash', False),
                                                    ssh_username=ssh_username,
                                                    ssh_password=ssh_password,
                                                )
                                                if result['success']:
                                                    last_progress_time = time.time()
                                                    no_progress_displayed = False
                                                    # Clear reversion time so we can detect another reversion if needed
                                                    del reversion_times[ap_mac]
                                                else:
                                                    print(f"[FAIL] {ap_info['name']}: Retry failed - {result.get('message', 'Unknown error')}", flush=True)
                                                    completed_aps[ap_mac] = time.time()
                                                    failed_aps.add(ap_mac)
                                            else:
                                                print(f"[FAIL] {ap_info['name']}: Upgrade dropped by controller and max retries ({max_retries}) exceeded", flush=True)
                                                completed_aps[ap_mac] = time.time()
                                                failed_aps.add(ap_mac)

                                # Track current state
                                if not ap_info.get("monitor_via_ping"):
                                    ap_states[ap_mac] = current_state

                                # Check if upgrade completed
                                target_version = ap_info.get('target_version')
                                version_changed = current_version and current_version != ap_info['current_version']
                                if (target_version and current_version == target_version) or (ap_info.get('custom_firmware') and version_changed):
                                    completion_time = time.time()
                                    completed_aps[ap_mac] = completion_time
                                    last_progress_time = completion_time
                                    no_progress_displayed = False

                                    # Calculate duration
                                    initiation_time = ap_initiation_times.get(ap_mac, completion_time)
                                    duration_seconds = completion_time - initiation_time
                                    duration_minutes = int(duration_seconds // 60)
                                    duration_secs = int(duration_seconds % 60)

                                    completion_time_str = datetime.fromtimestamp(completion_time).strftime("%H:%M:%S")
                                    print(f"[OK] Successful upgrade: {ap_info['name']} -> {current_version} at {completion_time_str} (took {duration_minutes}m:{duration_secs:02d}s)", flush=True)

                                # Check if upgrade is actively progressing (upgrade_progress > 0)
                                else:
                                    if ap_info.get("monitor_via_ping"):
                                        continue
                                    try:
                                        actively_upgrading = unifi_utils.is_ap_actively_upgrading(ap_mac, raise_on_error=True)
                                    except Exception as e:
                                        print(f"[WARN] {ap_info['name']}: Controller query failed while checking upgrade activity: {e}", flush=True)
                                        continue

                                    if actively_upgrading:
                                        # Update progress time - active upgrade is progressing
                                        last_progress_time = time.time()
                                        no_progress_displayed = False

                        # Check for stalled upgrades. Controller-driven upgrades use the generic
                        # no-progress threshold; SSH/SCP upgrades use the longer ping/controller
                        # settle thresholds handled below.
                        if time_since_progress > no_progress_threshold and not no_progress_displayed:
                            pending_ping_only = [
                                aps_upgrading[ap_mac]
                                for ap_mac in aps_upgrading
                                if ap_mac not in completed_aps
                                and aps_upgrading[ap_mac].get("monitor_via_ping")
                                and (
                                    (
                                        aps_upgrading[ap_mac].get("ping_phase") != "verifying_version"
                                        and (
                                            time.time() - ap_initiation_times.get(ap_mac, monitoring_start)
                                        ) <= aps_upgrading[ap_mac].get("ping_progress_threshold", 180)
                                    )
                                    or (
                                        aps_upgrading[ap_mac].get("ping_phase") == "verifying_version"
                                        and (
                                            time.time() - aps_upgrading[ap_mac].get("online_detected_at", monitoring_start)
                                        ) <= aps_upgrading[ap_mac].get("controller_settle_threshold", 180)
                                    )
                                )
                            ]
                            if pending_ping_only:
                                continue
                            no_progress_displayed = True
                            only_ping_stalled = all(
                                aps_upgrading[ap_mac].get("monitor_via_ping")
                                for ap_mac in aps_upgrading
                                if ap_mac not in completed_aps
                            )
                            if only_ping_stalled:
                                max_ping_threshold = max(
                                    aps_upgrading[ap_mac].get("ping_progress_threshold", 180)
                                    for ap_mac in aps_upgrading
                                    if ap_mac not in completed_aps and aps_upgrading[ap_mac].get("monitor_via_ping")
                                )
                                print(
                                    f"\n[FAIL] No SSH/SCP upgrade progress detected within {max_ping_threshold} seconds. "
                                    "The following APs failed to upgrade:\n"
                                )
                            else:
                                print(f"\n[FAIL] No progress detected in last {no_progress_threshold} seconds. The following APs failed to upgrade:\n")

                            stalled_aps = []
                            for ap_mac in list(aps_upgrading.keys()):
                                if ap_mac not in completed_aps:
                                    ap_info = aps_upgrading[ap_mac]
                                    if ap_info.get("monitor_via_ping"):
                                        initiation_time = ap_initiation_times.get(ap_mac, monitoring_start)
                                        ping_progress_threshold = ap_info.get("ping_progress_threshold", 180)
                                        if (
                                            ap_info.get("ping_phase") == "waiting_for_offline"
                                            and time.time() - initiation_time > ping_progress_threshold
                                        ):
                                            ap_info["ping_phase"] = "verifying_version"
                                            ap_info["online_detected_at"] = time.time()
                                            ap_info["controller_ready_polls"] = 0
                                            print(
                                                f"  {ap_info['name']}: no ping outage observed within {ping_progress_threshold}s; "
                                                "continuing with controller verification"
                                            )
                                            last_progress_time = time.time()
                                            no_progress_displayed = False
                                        continue
                                    try:
                                        ap_state = unifi_utils.get_ap_state(ap_mac, raise_on_error=True)
                                        current_version = unifi_utils.get_ap_current_version(ap_mac, raise_on_error=True)
                                        is_actively_upgrading = unifi_utils.is_ap_actively_upgrading(ap_mac, raise_on_error=True)
                                    except Exception as e:
                                        print(f"  {ap_info['name']}: controller query failed ({e}) - still monitoring")
                                        continue
                                    state_desc = unifi_utils._get_ap_state_description(ap_state)

                                    # Report as failed if version hasn't changed and upgrade is NOT actively in progress
                                    # (Even if upgrade_to_firmware is queued, if it hasn't started after 60s, it failed)
                                    if current_version == ap_info['current_version'] and not is_actively_upgrading:
                                        print(f"  {ap_info['name']}: {current_version} (stuck at {state_desc}) - upgrade failed to start")
                                        stalled_aps.append(ap_mac)
                                        completed_aps[ap_mac] = time.time()  # Mark as "done" so we stop monitoring it
                                        failed_aps.add(ap_mac)
                            if not stalled_aps:
                                # False alarm - APs are actually progressing, just slowly
                                no_progress_displayed = False
                                last_progress_time = time.time()
                            else:
                                # Report remaining healthy upgrades
                                active_aps = [mac for mac in aps_upgrading if mac not in completed_aps]
                                if active_aps:
                                    print(f"\nContinuing to monitor {len(active_aps)} AP(s) still upgrading...\n")

                        # Show progress countdown
                        if time_since_progress > no_progress_threshold and no_progress_displayed:
                            remaining_timeout = timeout_seconds - elapsed
                            remaining_minutes = int(remaining_timeout // 60)
                            remaining_seconds = int(remaining_timeout % 60)
                            print(f"[WAIT] {remaining_minutes}m:{remaining_seconds:02d}s until timeout...", flush=True)

                        # If all APs upgraded, exit
                        if len(completed_aps) == len(aps_upgrading):
                            break

                        # Sleep before next check
                        time.sleep(check_interval)

                    # Display all completion results at the end
                    print(f"\n{'='*80}")
                    successful_count = 0
                    for ap_mac in list(aps_upgrading.keys()):
                        if ap_mac in completed_aps and ap_mac not in failed_aps:
                            ap_info = aps_upgrading[ap_mac]
                            completion_time = completed_aps[ap_mac]
                            initiation_time = ap_initiation_times.get(ap_mac, completion_time)
                            duration_seconds = completion_time - initiation_time
                            duration_minutes = int(duration_seconds // 60)
                            duration_secs = int(duration_seconds % 60)
                            completion_time_str = datetime.fromtimestamp(completion_time).strftime("%H:%M:%S")
                            target_display = ap_info.get('target_version') or 'custom firmware'
                            print(f"[OK] Successful upgrade: {ap_info['name']} -> {target_display} at {completion_time_str} (took {duration_minutes}m:{duration_secs:02d}s)")
                            successful_count += 1

                    # Print summary
                    if failed_aps:
                        print(f"\n[PARTIAL] {successful_count} of {len(aps_upgrading)} AP(s) upgraded successfully, {len(failed_aps)} failed.")
                    else:
                        print(f"\n[SUCCESS] All {len(aps_upgrading)} AP(s) upgraded successfully!")
                    print(f"{'='*80}")
                # Display total execution time
                upgrade_session_end = time.time()
                total_duration = upgrade_session_end - upgrade_session_start
                total_minutes = int(total_duration // 60)
                total_seconds = int(total_duration % 60)
                print(f"\nTotal execution time: {total_minutes}m:{total_seconds:02d}s")
            # Exit after upgrade to prevent falling through to client action handlers
            sys.exit(0)

        # =====================================================================
        # CHECK_AP action (diagnostic)
        # =====================================================================
        if args.action == 'check_ap':
            ap_mac = None
            ap_name = None

            if args.ap_mac:
                ap_mac = args.ap_mac
            elif args.ap_name:
                ap_name = args.ap_name

            # Get AP info
            print("Fetching UniFi devices...")
            all_devices = unifi_utils.get_devices()
            aps = [device for device in all_devices if device.get("type") == "uap"]

            matching_ap = None
            if ap_mac:
                # Find by MAC
                target_mac = ap_mac.lower()
                for ap in aps:
                    if ap.get("mac", "").lower() == target_mac:
                        matching_ap = ap
                        break
            elif ap_name:
                # Find by name
                for ap in aps:
                    if (ap.get("name") or ap.get("model", "")).lower() == ap_name.lower():
                        matching_ap = ap
                        break

            if not matching_ap:
                print(f"Error: No AP found with {'MAC' if ap_mac else 'name'} {ap_mac or ap_name}")
                sys.exit(1)

            # Use the diagnostic function
            status = unifi_utils.check_ap_upgrade_status(matching_ap.get("mac"))

            if status.get("found"):
                print(f"\n=== {status.get('name')} Status ===")
                print(f"MAC: {status.get('mac')}")
                print(f"Model: {status.get('model')}")
                print(f"Serial: {status.get('serial')}")
                print(f"Current Version: {status.get('current_version')}")
                print(f"Upgrade Available: {status.get('upgrade_to_firmware')}")
                print(f"Upgradable: {status.get('upgradable')}")
                print(f"State: {status.get('state')} ({status.get('state_description')})")
                print(f"Adopted: {status.get('adopted')}")
                print(f"Uptime: {status.get('uptime_days')} days")
                print(f"Last Seen: {status.get('last_seen')}")

                if status.get("issues"):
                    print(f"\n[WARNING] Issues found:")
                    for issue in status.get("issues"):
                        print(f"  - {issue}")

                    print(f"\n[NOTE] Recommendations:")
                    state = status.get('state')
                    if state == "CONNECTING/INITIALIZING":
                        print(f"  - The AP is in INITIALIZING state, possibly stuck")
                        print(f"  - Try restarting the AP with: ./unifi_climgr.py restart_ap --ap_name 'Office'")
                        print(f"  - Wait for it to fully boot (state should change to RUNNING)")
                        print(f"  - Then retry the upgrade")
                    if not status.get('upgradable'):
                        print(f"  - The AP is marked as not upgradable")
                        print(f"  - This may indicate a hardware issue or incompatibility")
                        print(f"  - Check UniFi controller logs for more details")
                    if not status.get('adopted'):
                        print(f"  - The AP is not adopted by the controller")
                        print(f"  - You need to adopt it first before upgrading")
                else:
                    print("\n[OK] No obvious issues detected")
            else:
                print(f"Error: {status.get('message')}")

            sys.exit(0)

        # =====================================================================
        # SAVE_MESH_TOPOLOGY action (export current mesh topology to JSON)
        # =====================================================================
        if args.action == 'save_mesh_topology':
            # Determine output filename
            if args.filename:
                output_file = os.path.expanduser(args.filename)
            else:
                # Default: ~/.netcon-sync/topology.json
                output_file = os.path.expanduser("~/.netcon-sync/topology.json")

            # Create directory if it doesn't exist
            output_dir = os.path.dirname(output_file)
            if output_dir and not os.path.exists(output_dir):
                try:
                    os.makedirs(output_dir, exist_ok=True)
                except (OSError, PermissionError) as e:
                    print(f"Error: Failed to create directory {output_dir}: {e}")
                    sys.exit(1)

            # Fetch current APs from UniFi
            print("Fetching current AP mesh topology from UniFi controller...")
            all_devices = unifi_utils.get_devices()
            aps = [device for device in all_devices if device.get("type") == "uap"]

            if not aps:
                print("Error: No Access Points found.")
                sys.exit(1)

            # Serialize topology to JSON
            try:
                json_str = ap_topology_to_json(aps)

                # Write to file
                with open(output_file, 'w') as f:
                    f.write(json_str)

                print(f"[OK] Topology saved to: {output_file}")
                print(f"  APs: {len(aps)}\n")

                # Display tree view
                display_ap_tree(aps, show_macs=True)

                sys.exit(0)
            except (IOError, OSError, PermissionError) as e:
                print(f"Error: Failed to write topology file {output_file}: {e}")
                sys.exit(1)
            except Exception as e:
                print(f"Error: Failed to serialize topology: {e}")
                sys.exit(1)

        # =====================================================================
        # WAIT_FOR_MESH_TOPOLOGY action
        # =====================================================================
        if args.action == 'wait_for_mesh_topology':
            # Determine input filename
            if args.filename:
                topology_file = os.path.expanduser(args.filename)
            else:
                # Default: ~/.netcon-sync/topology.json
                topology_file = os.path.expanduser("~/.netcon-sync/topology.json")

            # Load desired topology from JSON file
            if not os.path.exists(topology_file):
                print(f"Error: Topology file not found: {topology_file}")
                print("\nFirst, save a topology using: ./unifi_climgr.py save_mesh_topology")
                sys.exit(1)

            try:
                with open(topology_file, 'r') as f:
                    json_content = f.read()

                # Parse JSON into serialized format (list of dicts)
                topology_list = json.loads(json_content)

                if not topology_list:
                    print(f"Error: Empty topology in {topology_file}")
                    sys.exit(1)

                # Deserialize into AP objects for tree display
                desired_aps = deserialize_ap_topology(topology_list)

                print(f"Loaded desired topology from: {topology_file}")
                print(f"Desired APs: {len(topology_list)}\n")

                # Display as tree
                display_ap_tree(desired_aps, show_macs=True)

                # Wait for mesh topology to rebuild
                _wait_for_mesh_topology(topology_list, timeout_minutes=args.timeout)

            except (IOError, OSError, PermissionError) as e:
                print(f"Error: Failed to read topology file {topology_file}: {e}")
                sys.exit(1)
            except (json.JSONDecodeError, ValueError) as e:
                print(f"Error: Failed to parse topology file as JSON {topology_file}: {e}")
                sys.exit(1)

            sys.exit(0)

        # =====================================================================
        # ENABLE action
        # =====================================================================
        if args.action == 'enable':
            if args.ssids:
                # =====================================================================
                # ENABLE SSID action
                # =====================================================================
                print("Fetching UniFi SSIDs...")
                ssids = unifi_utils.get_ssids()
                if not ssids:
                    print("No SSIDs found.")
                    sys.exit(0)

                # Find matching SSIDs
                matching_ssids = []
                if args.name:
                    # Exact match by name
                    matching_ssids = [ssid for ssid in ssids if ssid.get("name", "").lower() == args.name.lower()]
                elif args.filter_name:
                    # Substring match
                    matching_ssids = [ssid for ssid in ssids if args.filter_name.lower() in ssid.get("name", "").lower()]
                else:
                    # No specific SSID or filter: enable ALL SSIDs
                    matching_ssids = ssids

                if not matching_ssids:
                    print(f"No SSIDs found matching the specified criteria.")
                    sys.exit(0)

                print(f"\nEnabling {len(matching_ssids)} SSID(s)...")
                for ssid in matching_ssids:
                    ssid_name = ssid.get("name", "Unknown")
                    is_enabled_before = "Yes" if ssid.get("enabled", False) else "No"
                    print(f"  {ssid_name} (enabled: {is_enabled_before} -> ", end="", flush=True)
                    if unifi_utils.enable_ssid(ssid_name):
                        print(f"Yes)... [OK]")
                    else:
                        print(f"?)... [FAIL]")
                sys.exit(0)

            elif args.aps:
                # =====================================================================
                # ENABLE AP action
                # =====================================================================
                print("Fetching UniFi devices...")
                all_devices = unifi_utils.get_devices()
                aps = [device for device in all_devices if device.get("type") == "uap"]

                if not aps:
                    print("No Access Points found.")
                    sys.exit(0)

                # Find matching APs
                matching_aps = []
                if args.name:
                    # Exact match by name
                    matching_aps = [ap for ap in aps if (ap.get("name") or ap.get("model", "")).lower() == args.name.lower()]
                elif args.filter_name:
                    # Substring match by name
                    matching_aps = [ap for ap in aps if args.filter_name.lower() in (ap.get("name") or ap.get("model", "")).lower()]
                elif args.filter_mac:
                    # Substring match by MAC
                    filter_mac_lower = args.filter_mac.lower()
                    matching_aps = [ap for ap in aps if filter_mac_lower in ap.get("mac", "").lower()]
                else:
                    # No specific AP or filter: enable ALL APs
                    matching_aps = aps

                if not matching_aps:
                    print(f"No Access Points found matching the specified criteria.")
                    sys.exit(0)

                print(f"\nEnabling {len(matching_aps)} AP(s)...")
                for ap in matching_aps:
                    ap_name = ap.get("name") or ap.get("model", "Unknown AP")
                    ap_mac = ap.get("mac", "N/A")
                    is_enabled_before = "Yes" if not ap.get("disabled", False) else "No"
                    print(f"  {ap_name} (enabled: {is_enabled_before} -> ", end="", flush=True)
                    if unifi_utils.enable_ap(ap_mac):
                        print(f"Yes)... [OK]")
                    else:
                        print(f"?)... [FAIL]")
                sys.exit(0)

        # =====================================================================
        # DISABLE action
        # =====================================================================
        if args.action == 'disable':
            if args.ssids:
                # =====================================================================
                # DISABLE SSID action
                # =====================================================================
                print("Fetching UniFi SSIDs...")
                ssids = unifi_utils.get_ssids()
                if not ssids:
                    print("No SSIDs found.")
                    sys.exit(0)

                # Find matching SSIDs
                matching_ssids = []
                if args.name:
                    # Exact match by name
                    matching_ssids = [ssid for ssid in ssids if ssid.get("name", "").lower() == args.name.lower()]
                elif args.filter_name:
                    # Substring match
                    matching_ssids = [ssid for ssid in ssids if args.filter_name.lower() in ssid.get("name", "").lower()]
                else:
                    # No specific SSID or filter: disable ALL SSIDs
                    matching_ssids = ssids

                if not matching_ssids:
                    print(f"No SSIDs found matching the specified criteria.")
                    sys.exit(0)

                print(f"\nDisabling {len(matching_ssids)} SSID(s)...")
                for ssid in matching_ssids:
                    ssid_name = ssid.get("name", "Unknown")
                    is_enabled_before = "Yes" if ssid.get("enabled", False) else "No"
                    print(f"  {ssid_name} (enabled: {is_enabled_before} -> ", end="", flush=True)
                    if unifi_utils.disable_ssid(ssid_name):
                        print(f"No)... [OK]")
                    else:
                        print(f"?)... [FAIL]")
                sys.exit(0)

            elif args.aps:
                # =====================================================================
                # DISABLE AP action
                # =====================================================================
                print("Fetching UniFi devices...")
                all_devices = unifi_utils.get_devices()
                aps = [device for device in all_devices if device.get("type") == "uap"]

                if not aps:
                    print("No Access Points found.")
                    sys.exit(0)

                # Find matching APs
                matching_aps = []
                if args.name:
                    # Exact match by name
                    matching_aps = [ap for ap in aps if (ap.get("name") or ap.get("model", "")).lower() == args.name.lower()]
                elif args.filter_name:
                    # Substring match by name
                    matching_aps = [ap for ap in aps if args.filter_name.lower() in (ap.get("name") or ap.get("model", "")).lower()]
                elif args.filter_mac:
                    # Substring match by MAC
                    filter_mac_lower = args.filter_mac.lower()
                    matching_aps = [ap for ap in aps if filter_mac_lower in ap.get("mac", "").lower()]
                else:
                    # No specific AP or filter: disable ALL APs
                    matching_aps = aps

                if not matching_aps:
                    print(f"No Access Points found matching the specified criteria.")
                    sys.exit(0)

                print(f"\nDisabling {len(matching_aps)} AP(s)...")
                for ap in matching_aps:
                    ap_name = ap.get("name") or ap.get("model", "Unknown AP")
                    ap_mac = ap.get("mac", "N/A")
                    is_enabled_before = "Yes" if not ap.get("disabled", False) else "No"
                    print(f"  {ap_name} (enabled: {is_enabled_before} -> ", end="", flush=True)
                    if unifi_utils.disable_ap(ap_mac):
                        print(f"No)... [OK]")
                    else:
                        print(f"?)... [FAIL]")
                sys.exit(0)

        # =====================================================================
        # Client action commands (lock, unlock, reconnect, block, unblock)
        # Fetch and filter clients only for actions that actually need them.
        # =====================================================================
        client_filter_actions = {
            'lock_client',
            'unlock_client',
            'reconnect_client',
            'block_client',
            'unblock_client',
        }
        if args.action in client_filter_actions:
            print("Fetching UniFi clients...")
            clients = unifi_utils.get_all_unifi_clients()
            if not clients:
                print("No clients found.")
                sys.exit(0)

            # Add "number" key for numbering (before filtering)
            for i, client in enumerate(clients):
                client["number"] = i + 1

            # Apply filters using hasattr to check for filter arguments
            filtered_clients = []
            for client in clients:
                match = True
                if hasattr(args, 'filter_online') and args.filter_online and not client.get("is_connected_live", False):
                    match = False
                elif hasattr(args, 'filter_offline') and args.filter_offline and client.get("is_connected_live", False):
                    match = False
                if hasattr(args, 'filter_ip') and args.filter_ip:
                    if client.get("display_ip") != args.filter_ip:
                        match = False
                if hasattr(args, 'filter_dns_name') and args.filter_dns_name:
                    if client.get("dns_name") != args.filter_dns_name:
                        match = False
                if hasattr(args, 'filter_hostname') and args.filter_hostname:
                    if client.get("hostname") != args.filter_hostname:
                        match = False
                if hasattr(args, 'filter_by_ssid') and args.filter_by_ssid:
                    if client.get("live_ssid") != args.filter_by_ssid:
                        match = False
                if hasattr(args, 'filter_mac') and args.filter_mac:
                    client_mac = client.get("mac", "")
                    if args.filter_mac.lower() not in client_mac.lower():
                        match = False
                if hasattr(args, 'filter_signal_above') and args.filter_signal_above is not None:
                    signal = client.get("live_signal")
                    if not client.get("is_connected_live", False) or signal is None or signal <= args.filter_signal_above:
                        match = False
                if hasattr(args, 'filter_signal_below') and args.filter_signal_below is not None:
                    signal = client.get("live_signal")
                    if not client.get("is_connected_live", False) or signal is None or signal >= args.filter_signal_below:
                        match = False
                if hasattr(args, 'filter_locked') and args.filter_locked and not client.get("is_ap_locked", False):
                    match = False
                elif hasattr(args, 'filter_unlocked') and args.filter_unlocked and client.get("is_ap_locked", False):
                    match = False
                if match:
                    filtered_clients.append(client)

            # Re-number filtered clients
            for i, client in enumerate(filtered_clients):
                client["number"] = i + 1

            if not filtered_clients:
                print("No clients found matching the specified filters.")
                sys.exit(0)

            print(f"\n{len(filtered_clients)} client(s) matched the filter.")

        # Execute action
        if args.action == 'lock_client':
            if args.ap_mac:
                ap_mac = args.ap_mac.replace(':', '').replace('-', '').lower()
                target_desc = f"AP MAC {ap_mac}"
            elif args.ap_name:
                ap_mac = unifi_utils.get_ap_mac_by_name(args.ap_name)
                if not ap_mac:
                    print(f"Error: Could not find AP with name '{args.ap_name}'.")
                    sys.exit(1)
                target_desc = f"AP {args.ap_name}"
            else:  # connected_ap
                print("Locking each client to its currently connected AP...")
                results = {}
                for client in filtered_clients:
                    mac = client.get("mac")
                    live_ap_mac = client.get("live_ap_mac")
                    if client.get("is_connected_live") and live_ap_mac and mac:
                        results[mac.lower()] = unifi_utils.lock_client_to_ap(mac, live_ap_mac)
                print_action_results_table(filtered_clients, "lock", results)
                sys.exit(0)

            # Lock to specific AP
            print(f"Locking to {target_desc}...")
            results = {}
            for client in filtered_clients:
                mac = client.get("mac")
                if mac:
                    results[mac.lower()] = unifi_utils.lock_client_to_ap(mac, ap_mac)
            print_action_results_table(filtered_clients, "lock", results)

        elif args.action == 'unlock_client':
            print("Unlocking clients...")
            results = {}
            for client in filtered_clients:
                mac = client.get("mac")
                if mac:
                    results[mac.lower()] = unifi_utils.unlock_client_from_ap(mac)
            print_action_results_table(filtered_clients, "unlock", results)

        elif args.action == 'reconnect_client':
            # Check if delay is specified for sequential reconnects
            delay_ms = getattr(args, 'delay', None)

            if delay_ms is not None:
                # Sequential mode with delay
                start_timestamp = time.strftime('%Y-%m-%d %H:%M:%S')
                print(f"[{start_timestamp}] Reconnecting clients sequentially with {delay_ms}ms delay...")
                results = {}
                total = len(filtered_clients)
                for i, client in enumerate(filtered_clients):
                    mac = client.get("mac")
                    if mac:
                        if i > 0:
                            # Display countdown before reconnecting
                            delay_sec = delay_ms / 1000.0
                            print(f"[{i}/{total}] Waiting {delay_ms}ms before next client...", end="", flush=True)
                            time.sleep(delay_sec)
                            print("\r" + " " * 60 + "\r", end="", flush=True)  # Clear the line

                        # Show which client is being reconnected
                        hostname = client.get("hostname", client.get("name", "Unknown"))
                        print(f"[{i+1}/{total}] Reconnecting {hostname} ({mac})...", end="", flush=True)
                        results[mac.lower()] = unifi_utils.reconnect_client(mac)
                        print(" OK")  # Mark complete

                print()  # Blank line before results table
                print_action_results_table(filtered_clients, "reconnect", results)
            else:
                # Batch mode (default) - reconnect all at once
                timestamp = time.strftime('%Y-%m-%d %H:%M:%S')
                print(f"[{timestamp}] Reconnecting clients...")
                results = {}
                for client in filtered_clients:
                    mac = client.get("mac")
                    if mac:
                        results[mac.lower()] = unifi_utils.reconnect_client(mac)
                print_action_results_table(filtered_clients, "reconnect", results)

        elif args.action == 'forget':
            handle_forget_action_batch(filtered_clients)

        elif args.action == 'block_client':
            print("Blocking clients...")
            results = {}
            for client in filtered_clients:
                mac = client.get("mac")
                if mac:
                    results[mac.lower()] = unifi_utils.block_client(mac)
            print_action_results_table(filtered_clients, "block", results)

        elif args.action == 'unblock_client':
            print("Unblocking clients...")
            results = {}
            for client in filtered_clients:
                mac = client.get("mac")
                if mac:
                    results[mac.lower()] = unifi_utils.unblock_client(mac)
            print_action_results_table(filtered_clients, "unblock", results)

        elif args.action == 'collect_ap_logs':
            print("unifi_climgr - AP Log Collection\n")

            # Login to controller
            print("Logging into UniFi controller...")
            unifi_utils.login()
            print("[OK] Login successful\n")

            # Get SSH credentials from controller
            print("Retrieving SSH credentials from controller...")
            ssh_username, ssh_password = get_ssh_credentials()

            if not ssh_username or not ssh_password:
                print("ERROR: Could not retrieve SSH credentials from controller.")
                print("Please ensure SSH is configured in UniFi Settings > System > Advanced.")
                sys.exit(1)

            # Fetch APs from controller
            print("Fetching UniFi devices...")
            devices = unifi_utils.make_unifi_api_call("GET", f"/api/s/{UNIFI_SITE_ID}/stat/device")

            if isinstance(devices, dict) and 'data' in devices:
                devices = devices['data']

            # Filter for Access Points only
            aps = [d for d in devices if d.get('type') == 'uap']

            if not aps:
                print("No Access Points found.")
                sys.exit(0)

            print(f"Found {len(aps)} Access Point(s)")

            # Apply filters
            filtered_aps = aps

            if args.filter_name:
                filtered_aps = [ap for ap in filtered_aps if args.filter_name.lower() in ap.get('name', '').lower()]

            if args.filter_ip:
                filtered_aps = [ap for ap in filtered_aps if args.filter_ip in ap.get('ip', '')]

            if args.filter_mac:
                filter_mac_clean = args.filter_mac.replace(':', '').replace('-', '').lower()
                filtered_aps = [ap for ap in filtered_aps 
                               if filter_mac_clean in ap.get('mac', '').replace(':', '').lower()]

            if args.online_only:
                filtered_aps = [ap for ap in filtered_aps if ap.get('state') == 1]

            if not filtered_aps:
                print("No Access Points match the specified filters.")
                sys.exit(0)

            print(f"Collecting logs from {len(filtered_aps)} AP(s)...\n")

            # Collect logs
            ap_results, controller_result, collection_info = collect_all_ap_logs(
                output_dir=args.output,
                aps=filtered_aps,
                ssh_username=ssh_username,
                ssh_password=ssh_password,
                parallel=args.parallel,
                timeout=args.timeout,
                include_controller=not args.no_controller
            )

            # Print summary
            successful = [r for r in ap_results if r['success']]
            failed = [r for r in ap_results if not r['success']]

            total_files = sum(len(r.get('files', [])) for r in successful)
            total_size = sum(sum(f['size'] for f in r.get('files', [])) for r in successful)

            print(f"\n{'='*60}")
            print(f"COLLECTION SUMMARY")
            print(f"{'='*60}")
            print(f"Collection start: {collection_info['start_timestamp']}")
            print(f"Collection end:   {collection_info['end_timestamp']}")
            print(f"Total collection time: {collection_info['elapsed_time']:.1f}s")
            print(f"\nTotal APs processed: {len(ap_results)}")
            print(f"  [OK] Successful: {len(successful)}")
            print(f"  [FAIL] Failed: {len(failed)}")
            print(f"\nTotal files collected: {total_files}")
            print(f"Total size: {total_size:,} bytes ({total_size / 1024 / 1024:.2f} MB)")

            if total_files > 0:
                avg_size = total_size / total_files
                print(f"Average file size: {avg_size:,.0f} bytes ({avg_size / 1024:.1f} KB)")

            print(f"\nPer-AP breakdown:")
            for r in successful:
                num_files = len(r.get('files', []))
                ap_size = sum(f['size'] for f in r.get('files', []))
                ap_name = r['ap_name']
                ap_mac = r.get('ap_mac', 'unknown')
                elapsed = r.get('elapsed_time', 0)
                start_ts = r.get('start_timestamp', 'N/A')
                end_ts = r.get('end_timestamp', 'N/A')
                safe_ap_name = ap_name.replace('/', '_').replace(' ', '_')
                dir_name = f"{safe_ap_name}_{ap_mac.replace(':', '-')}"
                print(f"  - {dir_name}: {num_files} file(s), {ap_size:,} bytes ({ap_size / 1024:.1f} KB), {elapsed:.1f}s")
                print(f"    Start: {start_ts}  End: {end_ts}")

            if failed:
                print(f"\nFailed APs:")
                for r in failed:
                    print(f"  - {r['ap_name']} ({r['ap_ip']}): {r.get('error', 'Unknown error')}")

            if controller_result and controller_result['success']:
                ctrl_size = controller_result['size']
                ctrl_elapsed = controller_result.get('elapsed_time', 0)
                ctrl_start = controller_result.get('start_timestamp', 'N/A')
                ctrl_end = controller_result.get('end_timestamp', 'N/A')
                size_display = f"{ctrl_size/1024/1024:.1f} MB" if ctrl_size > 1024*1024 else f"{ctrl_size/1024:.1f} KB"
                print(f"\nController support file: {Path(controller_result['file_path']).name} ({size_display}, {ctrl_elapsed:.1f}s)")
                print(f"  Start: {ctrl_start}  End: {ctrl_end}")
            elif controller_result:
                print(f"\nWARNING: Controller support file collection failed: {controller_result.get('error', 'Unknown error')}")

            # Save summary to JSON
            collection_dir = collection_info['collection_dir']
            summary_file = collection_dir / "collection_summary.json"
            summary_data = {
                'timestamp': collection_info['start_timestamp'],
                'total_aps': len(ap_results),
                'successful': len(successful),
                'failed': len(failed),
                'total_files': total_files,
                'total_size_bytes': total_size,
                'controller_support_file': controller_result,
                'results': ap_results
            }

            with open(summary_file, 'w') as f:
                json.dump(summary_data, f, indent=2)

            print(f"\n[OK] Summary saved to: {summary_file}")

            # Create tarball
            print(f"\nCreating tarball...")
            tarball_start_time = time.time()
            tarball_name = f"ap_log_{collection_info['timestamp']}.tgz"
            tarball_path = args.output / tarball_name

            try:
                with tarfile.open(tarball_path, 'w:gz') as tar:
                    tar.add(collection_dir, arcname=collection_dir.name)

                tarball_size = tarball_path.stat().st_size
                size_display = f"{tarball_size/1024/1024:.1f} MB" if tarball_size > 1024*1024 else f"{tarball_size/1024:.1f} KB"

                print(f"[OK] Created {tarball_path} ({size_display})")

                # Clean up collection directory
                shutil.rmtree(collection_dir)
                print(f"[OK] Cleaned up collection directory")

                tarball_elapsed = time.time() - tarball_start_time
                print(f"\nTarball creation took {tarball_elapsed:.1f}s")
            except Exception as e:
                print(f"WARNING: Failed to create tarball: {e}")

            sys.exit(0 if len(failed) == 0 else 1)

        # =====================================================================
        # BACKUP_CLIENTS action
        # =====================================================================
        elif args.action == 'backup':
            print("unifi_climgr - Client Backup\n")

            # Get all clients
            print("Fetching UniFi clients...")
            all_clients = unifi_utils.get_all_unifi_clients()

            if not all_clients:
                print("No clients found.")
                sys.exit(0)

            print(f"Found {len(all_clients)} client(s)\n")

            # Apply filters
            filtered_clients = all_clients

            if args.filter_online:
                filtered_clients = [c for c in filtered_clients if c.get("is_connected_live")]
                print(f"Filter: online only ({len(filtered_clients)} clients)\n")

            if args.filter_offline:
                filtered_clients = [c for c in filtered_clients if not c.get("is_connected_live")]
                print(f"Filter: offline only ({len(filtered_clients)} clients)\n")

            if args.filter_locked:
                filtered_clients = [c for c in filtered_clients if c.get("is_ap_locked")]
                print(f"Filter: locked only ({len(filtered_clients)} clients)\n")

            if args.filter_unlocked:
                filtered_clients = [c for c in filtered_clients if not c.get("is_ap_locked")]
                print(f"Filter: unlocked only ({len(filtered_clients)} clients)\n")

            if args.filter_ip:
                filtered_clients = [c for c in filtered_clients if args.filter_ip in c.get("display_ip", "")]
                print(f"Filter: IP contains '{args.filter_ip}' ({len(filtered_clients)} clients)\n")

            if args.filter_mac:
                filter_mac_clean = args.filter_mac.replace(':', '').replace('-', '').lower()
                filtered_clients = [c for c in filtered_clients if filter_mac_clean in c.get("mac", "").replace(':', '').lower()]
                print(f"Filter: MAC contains '{args.filter_mac}' ({len(filtered_clients)} clients)\n")

            if args.filter_dns_name:
                filtered_clients = [c for c in filtered_clients if args.filter_dns_name.lower() in c.get("dns_name", "").lower()]
                print(f"Filter: DNS name contains '{args.filter_dns_name}' ({len(filtered_clients)} clients)\n")

            if args.filter_hostname:
                filtered_clients = [c for c in filtered_clients if args.filter_hostname.lower() in c.get("hostname", "").lower()]
                print(f"Filter: hostname contains '{args.filter_hostname}' ({len(filtered_clients)} clients)\n")

            if not filtered_clients:
                print("No clients match the specified filters.")
                sys.exit(0)

            # Export clients to XML
            print(f"Exporting {len(filtered_clients)} client(s) to XML...")
            backup_dir = args.backup_location if args.backup_location else None

            # Convert filtered clients to export format
            clients_to_export = []
            for client in filtered_clients:
                mac = client.get("mac")
                if mac:
                    export_data = unifi_utils.export_client_data(mac)
                    if export_data:
                        clients_to_export.append(export_data)

            if not clients_to_export:
                print("No clients could be exported.")
                sys.exit(0)

            try:
                filepath = unifi_utils.export_clients_to_file(clients_to_export, backup_dir)
                print(f"[OK] Backup saved to: {filepath}")
            except Exception as e:
                print(f"[FAIL] Failed to create backup: {e}")
                sys.exit(1)

            sys.exit(0)

        # =====================================================================
        # RESTORE_CLIENTS action
        # =====================================================================
        elif args.action == 'restore':
            print("unifi_climgr - Client Restore\n")

            # Determine backup location
            backup_dir = args.backup_location if args.backup_location else Path.home() / ".netcon-sync" / "unifi_backups"

            # Determine backup file
            backup_file = args.backup_file
            if not backup_file:
                # Find latest backup file
                if not backup_dir.exists():
                    print(f"ERROR: Backup directory does not exist: {backup_dir}")
                    sys.exit(1)

                backup_files = list(backup_dir.glob("unifi_clients_*.xml"))
                if not backup_files:
                    print(f"ERROR: No backup files found in: {backup_dir}")
                    sys.exit(1)

                backup_file = max(backup_files, key=lambda f: f.stat().st_mtime)
                print(f"Using latest backup: {backup_file}\n")
            else:
                if not backup_file.exists():
                    print(f"ERROR: Backup file does not exist: {backup_file}")
                    sys.exit(1)
                print(f"Using backup file: {backup_file}\n")

            # Read backup file
            print("Reading backup file...")
            try:
                with open(backup_file, 'r') as f:
                    xml_content = f.read()
                clients = unifi_utils._xml_to_clients(xml_content)
                print(f"[OK] Loaded {len(clients)} client(s) from backup\n")
            except Exception as e:
                print(f"[FAIL] Failed to read backup file: {e}")
                sys.exit(1)

            # Safety check: require --actual_restore to make changes
            if not args.actual_restore:
                print("[INFO] Running in dry-run mode (default). Use --actual_restore to apply changes.\n")

            # Restore clients
            mode = "APPLYING CHANGES" if args.actual_restore else "DRY RUN (no changes applied)"
            print(f"Mode: {mode}")
            print(f"Processing {len(clients)} client(s)...\n")

            results = {
                "success": 0,
                "failed": 0,
                "skipped": 0
            }

            for client_data in clients:
                mac = client_data.get("mac")
                if not mac:
                    continue

                result = unifi_utils.restore_client_data(client_data, dry_run=not args.actual_restore)

                if result["success"]:
                    if result["applied"]:
                        # Build detailed output with field values
                        output_lines = []
                        for field in result['applied']:
                            if field in result.get("details", {}):
                                value = result["details"][field]
                                output_lines.append(f"{field}: {value}")
                            else:
                                output_lines.append(field)
                        applied_str = ', '.join(output_lines)
                        # Add locked AP MAC info if applicable
                        if result.get("locked_ap_mac"):
                            applied_str += f" (locked to AP: {result['locked_ap_mac']})"
                        # Add previous AP name if client was previously locked
                        if result.get("previous_ap_name"):
                            applied_str += f" (previous AP name: {result['previous_ap_name']})"
                        # Indicate if this is a new client creation or update
                        if result.get("client_type") == "new":
                            print(f"  [{mac}] Created new client: {applied_str}")
                        else:
                            print(f"  [{mac}] Updated existing client: {applied_str}")
                    if result["skipped"]:
                        for skip in result["skipped"]:
                            print(f"  [{mac}] Skipped {skip['attribute']}: {skip['reason']}")
                    results["success"] += 1
                else:
                    if result["failed"]:
                        for fail in result["failed"]:
                            print(f"  [{mac}] Failed: {fail.get('attribute', 'unknown')} - {fail.get('error', fail.get('reason', 'unknown'))}")
                    results["failed"] += 1

            # Print summary
            print(f"\n{'='*60}")
            print("RESTORE SUMMARY")
            print(f"{'='*60}")
            print(f"Total clients processed: {len(clients)}")
            print(f"  [OK] Success: {results['success']}")
            print(f"  [FAIL] Failed: {results['failed']}")

            if not args.actual_restore:
                print("\n[INFO] Dry run only. No changes were applied.")
                print("[INFO] Re-run with --actual_restore to apply the restored client names, notes, and other settings.")

            sys.exit(0 if results["failed"] == 0 else 1)

    except nss.error.NSPRError as e:
        # Certificate validation error - provide helpful guidance
        error_msg = format_nss_error("UniFi Controller", UNIFI_NETWORK_URL, e, sys.argv[0])
        print(error_msg, file=sys.stderr)
        sys.exit(1)
    except Exception as e:
        # Catch any exception and print an informative error message
        print(f"An error occurred: {e}", file=sys.stderr)
        sys.exit(1)
    finally:
        # Ensure the opener is cleaned up on exit
        unifi_utils.cleanup()