mmrelay 1.2.0__py3-none-any.whl → 1.2.2__py3-none-any.whl

mmrelay/cli.py

@@ -7,6 +7,9 @@ import importlib.resources
 import os
 import shutil
 import sys
+from collections.abc import Mapping
+
+import yaml
 
 # Import version from package
 from mmrelay import __version__
@@ -131,6 +134,11 @@ def parse_arguments():
         help="Validate configuration file",
         description="Check configuration file syntax and completeness",
     )
+    config_subparsers.add_parser(
+        "diagnose",
+        help="Diagnose configuration system issues",
+        description="Test config generation capabilities and troubleshoot platform-specific issues",
+    )
 
     # AUTH group
     auth_parser = subparsers.add_parser(
@@ -141,11 +149,24 @@ def parse_arguments():
     auth_subparsers = auth_parser.add_subparsers(
         dest="auth_command", help="Auth commands"
     )
-    auth_subparsers.add_parser(
+    login_parser = auth_subparsers.add_parser(
         "login",
         help="Authenticate with Matrix",
         description="Set up Matrix authentication for E2EE support",
     )
+    login_parser.add_argument(
+        "--homeserver",
+        help="Matrix homeserver URL (e.g., https://matrix.org). If provided, --username and --password are also required.",
+    )
+    login_parser.add_argument(
+        "--username",
+        help="Matrix username (with or without @ and :server). If provided, --homeserver and --password are also required.",
+    )
+    login_parser.add_argument(
+        "--password",
+        metavar="PWD",
+        help="Matrix password (can be empty). If provided, --homeserver and --username are also required. For security, prefer interactive mode.",
+    )
 
     auth_subparsers.add_parser(
         "status",
@@ -189,9 +210,10 @@ def parse_arguments():
 
     # Use parse_known_args to handle unknown arguments gracefully (e.g., pytest args)
     args, unknown = parser.parse_known_args()
-    # If there are unknown arguments and we're not in a test environment, warn about them
-    if unknown and not any("pytest" in arg or "test" in arg for arg in sys.argv):
-        print(f"Warning: Unknown arguments ignored: {unknown}")
+    # If there are unknown arguments and we're not in a test invocation, warn about them
+    # Heuristic: suppress warning when pytest appears in argv (unit tests may pass extra args)
+    if unknown and not any("pytest" in arg or "py.test" in arg for arg in sys.argv):
+        print(f"Warning: Unknown arguments ignored: {unknown}", file=sys.stderr)
 
     return args
 
@@ -215,14 +237,16 @@ def print_version():
 
 def _validate_e2ee_dependencies():
     """
-    Check whether end-to-end encryption (E2EE) runtime dependencies are available.
-
-    Performs a platform check and attempts to import required packages (python-olm, nio.crypto.OlmDevice,
-    and nio.store.SqliteStore). Prints a short user-facing status message and guidance.
-
+    Check whether end-to-end encryption (E2EE) is usable on the current platform.
+    
     Returns:
-        bool: True if the platform supports E2EE and all required dependencies can be imported;
-              False if running on an unsupported platform (Windows) or if any dependency is missing.
+        bool: True if the platform is supported and required E2EE libraries can be imported;
+        False otherwise.
+    
+    Notes:
+        - This function performs only local checks (platform and importability) and does not perform
+          network I/O.
+        - It emits user-facing messages to indicate missing platform support or missing dependencies.
     """
     if sys.platform == WINDOWS_PLATFORM:
         print("❌ Error: E2EE is not supported on Windows")
@@ -239,42 +263,34 @@ def _validate_e2ee_dependencies():
         print("✅ E2EE dependencies are installed")
         return True
     except ImportError:
-        print("❌ Error: E2EE enabled but dependencies not installed")
+        print("❌ Error: E2EE dependencies not installed")
+        print("   End-to-end encryption features require additional dependencies")
         print("   Install E2EE support: pipx install 'mmrelay[e2e]'")
         return False
 
 
 def _validate_credentials_json(config_path):
     """
-    Validate that a credentials.json file exists next to the given config and contains the required Matrix authentication fields.
+    Validate that a credentials.json file exists (adjacent to config_path or in the base directory) and contains the required Matrix session fields.
 
-    Searches for credentials.json in the same directory as config_path, then falls back to the application's base directory. If found, the file is parsed as JSON and must include non-empty values for: "homeserver", "access_token", "user_id", and "device_id".
+    Checks for a credentials.json via _find_credentials_json_path(config_path). If found, the file is parsed as JSON and must include non-empty string values for the keys "homeserver", "access_token", "user_id", and "device_id". On validation failure the function prints a brief error and guidance to run the auth login flow.
 
     Parameters:
         config_path (str): Path to the configuration file used to determine the primary search directory for credentials.json.
 
     Returns:
-        bool: True if a valid credentials.json was found and contains all required fields; False otherwise. When invalid or missing fields are detected the function prints a short error and guidance to run the auth login flow.
+        bool: True if a credentials.json was found and contains all required non-empty fields; False otherwise.
     """
     try:
         import json
 
-        # Look for credentials.json in the same directory as the config file
-        config_dir = os.path.dirname(config_path)
-        credentials_path = os.path.join(config_dir, "credentials.json")
-
-        if not os.path.exists(credentials_path):
-            # Also try the standard location
-            from mmrelay.config import get_base_dir
-
-            standard_credentials_path = os.path.join(get_base_dir(), "credentials.json")
-            if os.path.exists(standard_credentials_path):
-                credentials_path = standard_credentials_path
-            else:
-                return False
+        # Look for credentials.json using helper function
+        credentials_path = _find_credentials_json_path(config_path)
+        if not credentials_path:
+            return False
 
         # Load and validate credentials
-        with open(credentials_path, "r") as f:
+        with open(credentials_path, "r", encoding="utf-8") as f:
             credentials = json.load(f)
 
         # Check for required fields
@@ -282,7 +298,7 @@ def _validate_credentials_json(config_path):
         missing_fields = [
             field
             for field in required_fields
-            if field not in credentials or not credentials[field]
+            if not _is_valid_non_empty_string((credentials or {}).get(field))
         ]
 
         if missing_fields:
@@ -298,6 +314,52 @@ def _validate_credentials_json(config_path):
         return False
 
 
+def _is_valid_non_empty_string(value) -> bool:
+    """
+    Return True if value is a string containing non-whitespace characters.
+
+    Checks that the input is an instance of `str` and that stripping whitespace
+    does not produce an empty string.
+
+    Returns:
+        bool: True when value is a non-empty, non-whitespace-only string; otherwise False.
+    """
+    return isinstance(value, str) and value.strip() != ""
+
+
+def _has_valid_password_auth(matrix_section):
+    """
+    Return True if the given Matrix config section contains valid password-based authentication settings.
+
+    The function expects matrix_section to be a dict-like mapping from configuration keys to values.
+    It validates that:
+    - `homeserver` and `bot_user_id` are present and are non-empty strings (after trimming),
+    - `password` is present and is a string (it may be an empty string, which is accepted).
+
+    If matrix_section is not a dict, the function returns False.
+
+    Parameters:
+        matrix_section: dict-like Matrix configuration section (may be the parsed "matrix" config).
+
+    Returns:
+        bool: True when password-based authentication is correctly configured as described above; otherwise False.
+    """
+    if not isinstance(matrix_section, Mapping):
+        return False
+
+    pwd = matrix_section.get("password")
+    homeserver = matrix_section.get(CONFIG_KEY_HOMESERVER)
+    bot_user_id = matrix_section.get(CONFIG_KEY_BOT_USER_ID)
+
+    # Allow empty password strings (some environments legitimately use empty passwords).
+    # Homeserver and bot_user_id must still be valid non-empty strings.
+    return (
+        isinstance(pwd, str)
+        and _is_valid_non_empty_string(homeserver)
+        and _is_valid_non_empty_string(bot_user_id)
+    )
+
+
 def _validate_matrix_authentication(config_path, matrix_section):
     """
     Determine whether Matrix authentication is configured and usable.
@@ -323,7 +385,10 @@ def _validate_matrix_authentication(config_path, matrix_section):
           and whether E2EE support is available.
     """
     has_valid_credentials = _validate_credentials_json(config_path)
-    has_access_token = matrix_section and "access_token" in matrix_section
+    token = (matrix_section or {}).get(CONFIG_KEY_ACCESS_TOKEN)
+    has_access_token = _is_valid_non_empty_string(token)
+
+    has_password = _has_valid_password_auth(matrix_section)
 
     if has_valid_credentials:
         print("✅ Using credentials.json for Matrix authentication")
@@ -331,8 +396,16 @@ def _validate_matrix_authentication(config_path, matrix_section):
             print("   E2EE support available (if enabled)")
         return True
 
+    elif has_password:
+        print(
+            "✅ Using password in config for initial authentication (credentials.json will be created on first run)"
+        )
+        print(f"   {msg_for_e2ee_support()}")
+        return True
     elif has_access_token:
-        print("✅ Using access_token for Matrix authentication")
+        print(
+            "✅ Using access_token for Matrix authentication (deprecated — consider 'mmrelay auth login' to create credentials.json)"
+        )
         print(f"   {msg_for_e2ee_support()}")
         return True
 
@@ -388,7 +461,7 @@ def _validate_e2ee_config(config, matrix_section, config_path):
         )
         if store_path:
             expanded_path = os.path.expanduser(store_path)
-            if not os.path.exists(os.path.dirname(expanded_path)):
+            if not os.path.exists(expanded_path):
                 print(f"ℹ️  Note: E2EE store directory will be created: {expanded_path}")
 
         print("✅ E2EE configuration is valid")
@@ -470,19 +543,9 @@ def _analyze_e2ee_setup(config, config_path):
             "Enable E2EE in config.yaml under matrix section: e2ee: enabled: true"
         )
 
-    # Check credentials (same logic as _validate_credentials_json)
-    config_dir = os.path.dirname(config_path)
-    credentials_path = os.path.join(config_dir, "credentials.json")
-
-    if not os.path.exists(credentials_path):
-        # Also try the standard location
-        from mmrelay.config import get_base_dir
-
-        standard_credentials_path = os.path.join(get_base_dir(), "credentials.json")
-        if os.path.exists(standard_credentials_path):
-            credentials_path = standard_credentials_path
-
-    analysis["credentials_available"] = os.path.exists(credentials_path)
+    # Check credentials file existence
+    credentials_path = _find_credentials_json_path(config_path)
+    analysis["credentials_available"] = bool(credentials_path)
 
     if not analysis["credentials_available"]:
         analysis["recommendations"].append(
@@ -506,54 +569,89 @@ def _analyze_e2ee_setup(config, config_path):
     return analysis
 
 
+def _find_credentials_json_path(config_path: str | None) -> str | None:
+    """
+    Return the filesystem path to a credentials.json file if one can be found, otherwise None.
+
+    Search order:
+    1. A credentials.json file located in the same directory as the provided config_path.
+    2. A credentials.json file in the application's base directory (get_base_dir()).
+
+    Parameters:
+        config_path (str | None): Path to the configuration file used to derive the adjacent credentials.json location.
+
+    Returns:
+        str | None: Absolute path to the discovered credentials.json, or None if no file is found.
+    """
+    if not config_path:
+        from mmrelay.config import get_base_dir
+
+        standard = os.path.join(get_base_dir(), "credentials.json")
+        return standard if os.path.exists(standard) else None
+
+    config_dir = os.path.dirname(config_path)
+    candidate = os.path.join(config_dir, "credentials.json")
+    if os.path.exists(candidate):
+        return candidate
+    from mmrelay.config import get_base_dir
+
+    standard = os.path.join(get_base_dir(), "credentials.json")
+    return standard if os.path.exists(standard) else None
+
+
 def _print_unified_e2ee_analysis(e2ee_status):
     """
-    Print a concise, user-facing analysis of E2EE readiness from a centralized status object.
+    Print a concise, user-facing analysis of E2EE readiness.
 
-    This formats and prints the platform support, dependency availability, configuration enabled state,
-    authentication (credentials.json) presence, and the overall status. If the overall status is not
-    "ready", prints actionable fix instructions obtained from mmrelay.e2ee_utils.get_e2ee_fix_instructions.
+    Given a status dictionary produced by the E2EE analysis routines, prints platform support,
+    dependency availability, whether E2EE is enabled in configuration, whether credentials.json
+    is available, and the overall status. If the overall status is not "ready", prints actionable
+    fix instructions.
 
     Parameters:
-        e2ee_status (dict): Status dictionary as returned by get_e2ee_status(config, config_path).
-            Expected keys:
-                - platform_supported (bool)
-                - dependencies_installed (bool)
-                - enabled (bool)
-                - credentials_available (bool)
-                - overall_status (str)
+        e2ee_status (dict): Status dictionary with (at least) the following keys:
+            - platform_supported (bool): whether the current OS/platform supports E2EE.
+            - dependencies_installed or dependencies_available (bool): whether required E2EE
+              Python packages and runtime dependencies are present.
+            - enabled or config_enabled (bool): whether E2EE is enabled in the configuration.
+            - credentials_available (bool): whether a usable credentials.json is present.
+            - overall_status (str): high-level status ("ready", "disabled", "incomplete", etc.).
     """
     print("\n🔐 E2EE Configuration Analysis:")
 
     # Platform support
-    if e2ee_status["platform_supported"]:
+    if e2ee_status.get("platform_supported", True):
         print("✅ Platform: E2EE supported")
     else:
         print("❌ Platform: E2EE not supported on Windows")
 
     # Dependencies
-    if e2ee_status["dependencies_installed"]:
+    if e2ee_status.get(
+        "dependencies_installed", e2ee_status.get("dependencies_available", False)
+    ):
         print("✅ Dependencies: E2EE dependencies installed")
     else:
         print("❌ Dependencies: E2EE dependencies not fully installed")
 
     # Configuration
-    if e2ee_status["enabled"]:
+    if e2ee_status.get("enabled", e2ee_status.get("config_enabled", False)):
         print("✅ Configuration: E2EE enabled")
     else:
         print("❌ Configuration: E2EE disabled")
 
     # Authentication
-    if e2ee_status["credentials_available"]:
+    if e2ee_status.get("credentials_available", False):
         print("✅ Authentication: credentials.json found")
     else:
         print("❌ Authentication: credentials.json not found")
 
     # Overall status
-    print(f"\n📊 Overall Status: {e2ee_status['overall_status'].upper()}")
+    print(
+        f"\n📊 Overall Status: {e2ee_status.get('overall_status', 'unknown').upper()}"
+    )
 
     # Show fix instructions if needed
-    if e2ee_status["overall_status"] != "ready":
+    if e2ee_status.get("overall_status") != "ready":
         from mmrelay.e2ee_utils import get_e2ee_fix_instructions
 
         instructions = get_e2ee_fix_instructions(e2ee_status)
@@ -682,23 +780,18 @@ def check_config(args=None):
     """
     Validate the application's YAML configuration file and its required sections.
 
-    Performs these checks:
-    - Locates the first existing config file from get_config_paths(args) (parses CLI args if args is None).
-    - Verifies YAML syntax and reports syntax errors or style warnings.
-    - Ensures the config is non-empty.
-    - Validates Matrix authentication: accepts credentials supplied via credentials.json or requires a matrix section with homeserver, access_token, and bot_user_id when credentials.json is absent.
-    - Validates end-to-end-encryption (E2EE) configuration and dependencies.
-    - Ensures matrix_rooms exists, is a non-empty list, and each room is a dict containing an id.
-    - Validates the meshtastic section: requires connection_type and the connection-specific fields (serial_port for serial, host for tcp/network, ble_address for ble). Warns about deprecated connection types.
-    - Validates optional meshtastic fields and types (broadcast_enabled, detection_sensor, message_delay >= 2.0, meshnet_name) and reports missing optional settings as guidance.
-    - Warns if a deprecated db section is present.
-    - Prints a short environment summary on success.
+    Performs these checks: locates the first existing config file from get_config_paths(args),
+    validates YAML syntax and non-empty content, verifies Matrix authentication (prefers
+    credentials.json but accepts access_token or password in the matrix section), performs
+    E2EE configuration and dependency checks, validates matrix_rooms and meshtastic sections
+    (including connection-specific requirements), checks a set of optional meshtastic settings
+    (and value constraints), and warns about deprecated sections.
 
     Side effects:
-    - Prints errors, warnings, and status messages to stdout.
+    - Prints human-readable errors, warnings, and status messages to stdout.
 
     Parameters:
-        args (argparse.Namespace | None): Parsed CLI arguments. If None, CLI arguments will be parsed internally.
+        args (argparse.Namespace | None): Parsed CLI arguments; if None, CLI arguments are parsed internally.
 
     Returns:
         bool: True if a configuration file was found and passed all checks; False otherwise.
@@ -717,7 +810,7 @@ def check_config(args=None):
             config_path = path
             print(f"Found configuration file at: {config_path}")
             try:
-                with open(config_path, "r") as f:
+                with open(config_path, "r", encoding="utf-8") as f:
                     config_content = f.read()
 
                 # Validate YAML syntax first
@@ -748,6 +841,9 @@ def check_config(args=None):
                         # Create empty matrix section if missing - no fields required
                         config[CONFIG_SECTION_MATRIX] = {}
                     matrix_section = config[CONFIG_SECTION_MATRIX]
+                    if not isinstance(matrix_section, dict):
+                        print("Error: 'matrix' section must be a mapping (YAML object)")
+                        return False
                     required_matrix_fields = (
                         []
                     )  # No fields required from config when using credentials.json
@@ -756,22 +852,37 @@ def check_config(args=None):
                     if CONFIG_SECTION_MATRIX not in config:
                         print("Error: Missing 'matrix' section in config")
                         print(
-                            "   Either add matrix section with access_token and bot_user_id,"
+                            "   Either add matrix section with access_token or password and bot_user_id,"
                         )
                         print(f"   {msg_or_run_auth_login()}")
                         return False
 
                     matrix_section = config[CONFIG_SECTION_MATRIX]
+                    if not isinstance(matrix_section, dict):
+                        print("Error: 'matrix' section must be a mapping (YAML object)")
+                        return False
+
                     required_matrix_fields = [
                         CONFIG_KEY_HOMESERVER,
-                        CONFIG_KEY_ACCESS_TOKEN,
                         CONFIG_KEY_BOT_USER_ID,
                     ]
+                    token = matrix_section.get(CONFIG_KEY_ACCESS_TOKEN)
+                    pwd = matrix_section.get("password")
+                    has_token = _is_valid_non_empty_string(token)
+                    # Allow explicitly empty password strings; require the value to be a string
+                    # (reject unquoted numeric types)
+                    has_password = isinstance(pwd, str)
+                    if not (has_token or has_password):
+                        print(
+                            "Error: Missing authentication in 'matrix' section: provide 'access_token' or 'password'"
+                        )
+                        print(f"   {msg_or_run_auth_login()}")
+                        return False
 
                 missing_matrix_fields = [
                     field
                     for field in required_matrix_fields
-                    if field not in matrix_section
+                    if not _is_valid_non_empty_string(matrix_section.get(field))
                 ]
 
                 if missing_matrix_fields:
@@ -929,7 +1040,8 @@ def check_config(args=None):
                         # Special validation for message_delay
                         if option == "message_delay" and value < 2.0:
                             print(
-                                f"Error: 'message_delay' must be at least 2.0 seconds (firmware limitation), got: {value}"
+                                f"Error: 'message_delay' must be at least 2.0 seconds (firmware limitation), got: {value}",
+                                file=sys.stderr,
                             )
                             return False
                     else:
@@ -943,16 +1055,23 @@ def check_config(args=None):
                 # Check for deprecated db section
                 if "db" in config:
                     print(
-                        "\nWarning: 'db' section is deprecated. Please use 'database' instead."
+                        "\nWarning: 'db' section is deprecated. Please use 'database' instead.",
+                        file=sys.stderr,
                     )
                     print(
-                        "This option still works but may be removed in future versions.\n"
+                        "This option still works but may be removed in future versions.\n",
+                        file=sys.stderr,
                     )
 
                 print("\n✅ Configuration file is valid!")
                 return True
+            except (OSError, ValueError, UnicodeDecodeError) as e:
+                print(
+                    f"Error checking configuration: {e.__class__.__name__}: {e}",
+                    file=sys.stderr,
+                )
             except Exception as e:
-                print(f"Error checking configuration: {e}")
+                print(f"Error checking configuration: {e}", file=sys.stderr)
                 return False
 
     print("Error: No configuration file found in any of the following locations:")
@@ -977,8 +1096,27 @@ def main():
         int: Exit code (0 on success, non-zero on failure).
     """
     try:
+        # Set up Windows console for better compatibility
+        try:
+            from mmrelay.windows_utils import setup_windows_console
+
+            setup_windows_console()
+        except (ImportError, OSError, AttributeError):
+            # windows_utils not available or Windows console setup failed
+            # This is intentional - we want to continue if Windows utils fail
+            pass
+
         args = parse_arguments()
 
+        # Handle the --data-dir option
+        if args and args.data_dir:
+            import mmrelay.config
+
+            # Set the global custom_data_dir variable
+            mmrelay.config.custom_data_dir = os.path.abspath(args.data_dir)
+            # Create the directory if it doesn't exist
+            os.makedirs(mmrelay.config.custom_data_dir, exist_ok=True)
+
         # Handle subcommands first (modern interface)
         if hasattr(args, "command") and args.command:
             return handle_subcommand(args)
@@ -1019,20 +1157,33 @@ def main():
             print(f"Error importing main module: {e}")
             return 1
 
+    except (OSError, PermissionError, KeyboardInterrupt) as e:
+        # Handle common system-level errors
+        print(f"System error: {e.__class__.__name__}: {e}", file=sys.stderr)
+        return 1
     except Exception as e:
-        print(f"Unexpected error: {e}")
+        # Default error message
+        error_msg = f"Unexpected error: {e.__class__.__name__}: {e}"
+        # Provide Windows-specific error guidance if available
+        try:
+            from mmrelay.windows_utils import get_windows_error_message, is_windows
+
+            if is_windows():
+                error_msg = f"Error: {get_windows_error_message(e)}"
+        except ImportError:
+            pass  # Use default message
+        print(error_msg, file=sys.stderr)
         return 1
 
 
 def handle_subcommand(args):
     """
-    Dispatch the modern grouped CLI subcommand to its handler and return an exit code.
-
-    Parameters:
-        args (argparse.Namespace): Parsed CLI arguments (as produced by parse_arguments()). Must have a `command` attribute with one of: "config", "auth", or "service".
+    Dispatch the modern grouped CLI subcommand to the appropriate handler and return an exit code.
 
-    Returns:
-        int: Process exit code — 0 on success, non-zero on error or unknown command.
+    The function expects an argparse.Namespace from parse_arguments() with a `command`
+    attribute set to one of: "config", "auth", or "service". Delegates to the
+    corresponding handler and returns its exit code. If `command` is unknown,
+    prints an error and returns 1.
     """
     if args.command == "config":
         return handle_config_command(args)
@@ -1040,6 +1191,7 @@ def handle_subcommand(args):
         return handle_auth_command(args)
     elif args.command == "service":
         return handle_service_command(args)
+
     else:
         print(f"Unknown command: {args.command}")
         return 1
@@ -1047,21 +1199,25 @@ def handle_subcommand(args):
 
 def handle_config_command(args):
     """
-    Dispatch the 'config' subgroup commands: "generate" and "check".
+    Dispatch the "config" command group to the selected subcommand handler.
 
-    If `args.config_command` is "generate", writes a sample config to the default location.
-    If "check", validates the configuration referenced by `args` (see check_config).
+    Supported subcommands:
+    - "generate": create or update the sample configuration file at the preferred location.
+    - "check": validate the resolved configuration file (delegates to check_config).
+    - "diagnose": run a sequence of non-destructive diagnostics and print a report (delegates to handle_config_diagnose).
 
     Parameters:
-        args (argparse.Namespace): Parsed CLI namespace with a `config_command` attribute.
+        args (argparse.Namespace): CLI namespace containing `config_command` (one of "generate", "check", "diagnose") and any subcommand-specific options.
 
     Returns:
-        int: Process exit code (0 on success, 1 on failure or unknown subcommand).
+        int: Exit code (0 on success, 1 on failure or for unknown subcommands).
     """
     if args.config_command == "generate":
         return 0 if generate_sample_config() else 1
     elif args.config_command == "check":
         return 0 if check_config(args) else 1
+    elif args.config_command == "diagnose":
+        return handle_config_diagnose(args)
     else:
         print(f"Unknown config command: {args.config_command}")
         return 1
@@ -1096,24 +1252,97 @@ def handle_auth_command(args):
 
 def handle_auth_login(args):
     """
-    Run the interactive Matrix bot login flow and return a CLI-style exit code.
+    Run the Matrix bot login flow and return a CLI-style exit code.
+
+    Performs Matrix bot authentication either interactively (prompts the user) or non-interactively
+    when all three parameters (--homeserver, --username, --password) are provided on the command line.
+    For non-interactive mode, --homeserver and --username must be non-empty strings; --password may be
+    an empty string (some flows will prompt). Supplying some but not all of the three parameters
+    is treated as an error and the function exits with a non-zero status.
 
-    Runs the login_matrix_bot coroutine to perform authentication for the Matrix/E2EE bot and prints a short header. Returns 0 on successful authentication; returns 1 if the login fails, is cancelled by the user (KeyboardInterrupt), or an unexpected error occurs.
+    Returns:
+        int: 0 on successful authentication, 1 on failure, cancellation (KeyboardInterrupt), or unexpected errors.
 
     Parameters:
-        args: Parsed command-line arguments (not used by this handler).
+        args: Parsed CLI namespace; may contain attributes `homeserver`, `username`, and `password`.
     """
     import asyncio
 
     from mmrelay.matrix_utils import login_matrix_bot
 
-    # Show header
-    print("Matrix Bot Authentication for E2EE")
-    print("===================================")
+    # Extract arguments
+    homeserver = getattr(args, "homeserver", None)
+    username = getattr(args, "username", None)
+    password = getattr(args, "password", None)
+
+    # Count provided parameters (empty strings count as provided)
+    provided_params = [p for p in [homeserver, username, password] if p is not None]
+
+    # Determine mode based on parameters provided
+    if len(provided_params) == 3:
+        # All parameters provided - validate required non-empty fields
+        if not _is_valid_non_empty_string(homeserver) or not _is_valid_non_empty_string(
+            username
+        ):
+            print(
+                "❌ Error: --homeserver and --username must be non-empty for non-interactive login."
+            )
+            return 1
+        # Password may be empty (flows may prompt)
+    elif len(provided_params) > 0:
+        # Some but not all parameters provided - show error
+        missing_params = []
+        if homeserver is None:
+            missing_params.append("--homeserver")
+        if username is None:
+            missing_params.append("--username")
+        if password is None:
+            missing_params.append("--password")
+
+        error_message = f"""❌ Error: All authentication parameters are required when using command-line options.
+   Missing: {', '.join(missing_params)}
+
+💡 Options:
+   • For secure interactive authentication: mmrelay auth login
+   • For automated authentication: provide all three parameters
+
+⚠️  Security Note: Command-line passwords may be visible in process lists and shell history.
+   Interactive mode is recommended for manual use."""
+        print(error_message)
+        return 1
+    else:
+        # No parameters provided - run in interactive mode
+        # Check if E2EE is actually configured before mentioning it
+        # Use silent checking to avoid warnings during initial setup
+        try:
+            from mmrelay.config import check_e2ee_enabled_silently
+
+            e2ee_enabled = check_e2ee_enabled_silently(args)
+
+            if e2ee_enabled:
+                print("Matrix Bot Authentication for E2EE")
+                print("===================================")
+            else:
+                print("\nMatrix Bot Authentication")
+                print("=========================")
+        except (OSError, PermissionError, ImportError, ValueError) as e:
+            # Fallback if silent checking fails due to config file or import issues
+            from mmrelay.log_utils import get_logger
+
+            logger = get_logger("CLI")
+            logger.debug(f"Failed to silently check E2EE status: {e}")
+            print("\nMatrix Bot Authentication")
+            print("=========================")
 
     try:
-        # For now, use the existing login function
-        result = asyncio.run(login_matrix_bot())
+        result = asyncio.run(
+            login_matrix_bot(
+                homeserver=homeserver,
+                username=username,
+                password=password,
+                logout_others=False,
+            )
+        )
         return 0 if result else 1
     except KeyboardInterrupt:
         print("\nAuthentication cancelled by user.")
@@ -1125,38 +1354,66 @@ def handle_auth_login(args):
 
 def handle_auth_status(args):
     """
-    Show Matrix authentication status by locating and reading a credentials.json file.
+    Print the Matrix authentication status by locating and reading a credentials.json file.
 
-    Searches candidate config directories derived from the provided parsed-arguments namespace for a credentials.json file. If found and readable, prints the file path and the homeserver, user_id, and device_id values. If the file is unreadable or not found, prints guidance to run the authentication flow.
+    Searches for credentials.json next to each discovered config file (in preference order),
+    then falls back to the application's base directory. If a readable credentials.json is
+    found, prints its path and the homeserver, user_id, and device_id values.
 
     Parameters:
-        args (argparse.Namespace): Parsed CLI arguments used to determine the list of config paths to search.
+        args: argparse.Namespace
+            Parsed CLI arguments (used to locate config file paths).
 
     Returns:
-        int: Exit code — 0 if a readable credentials.json was found, 1 otherwise.
+        int: Exit code — 0 if a valid credentials.json was found and read, 1 otherwise.
+
+    Side effects:
+        Writes human-readable status messages to stdout.
     """
     import json
-    import os
 
-    from mmrelay.config import get_config_paths
+    from mmrelay.config import get_base_dir, get_config_paths
 
     print("Matrix Authentication Status")
     print("============================")
 
-    # Check for credentials.json
     config_paths = get_config_paths(args)
-    for config_path in config_paths:
-        config_dir = os.path.dirname(config_path)
-        credentials_path = os.path.join(config_dir, "credentials.json")
+
+    # Developer note: Build a de-duplicated sequence of candidate locations,
+    # preserving preference order: each config-adjacent credentials.json first,
+    # then the standard base-dir fallback.
+    seen = set()
+    candidate_paths = []
+    for p in (
+        os.path.join(os.path.dirname(cp), "credentials.json") for cp in config_paths
+    ):
+        if p not in seen:
+            candidate_paths.append(p)
+            seen.add(p)
+    base_candidate = os.path.join(get_base_dir(), "credentials.json")
+    if base_candidate not in seen:
+        candidate_paths.append(base_candidate)
+
+    for credentials_path in candidate_paths:
         if os.path.exists(credentials_path):
             try:
-                with open(credentials_path, "r") as f:
+                with open(credentials_path, "r", encoding="utf-8") as f:
                     credentials = json.load(f)
 
+                required = ("homeserver", "access_token", "user_id", "device_id")
+                if not all(
+                    isinstance(credentials.get(k), str) and credentials.get(k).strip()
+                    for k in required
+                ):
+                    print(
+                        f"❌ Error: credentials.json at {credentials_path} is missing required fields"
+                    )
+                    print(f"Run '{get_command('auth_login')}' to authenticate")
+                    return 1
                 print(f"✅ Found credentials.json at: {credentials_path}")
-                print(f"   Homeserver: {credentials.get('homeserver', 'Unknown')}")
-                print(f"   User ID: {credentials.get('user_id', 'Unknown')}")
-                print(f"   Device ID: {credentials.get('device_id', 'Unknown')}")
+                print(f"   Homeserver: {credentials.get('homeserver')}")
+                print(f"   User ID: {credentials.get('user_id')}")
+                print(f"   Device ID: {credentials.get('device_id')}")
                 return 0
             except Exception as e:
                 print(f"❌ Error reading credentials.json: {e}")
@@ -1169,15 +1426,21 @@ def handle_auth_status(args):
 
 def handle_auth_logout(args):
     """
-    Log out the bot from Matrix and remove local session artifacts.
+    Log out the Matrix bot and remove local session artifacts.
 
-    Prompts for a verification password (unless provided via args.password), warns if the password was supplied on the command line, asks for confirmation unless args.yes is True, and then performs the logout by calling the logout_matrix_bot routine. On success the function returns 0; on failure or cancellation it returns 1. KeyboardInterrupt is treated as a cancellation and returns 1.
+    Prompts for a verification password (unless a non-empty password is provided via args.password),
+    optionally asks for interactive confirmation (skipped if args.yes is True), and attempts to clear
+    local session data (credentials, E2EE store) and invalidate the bot's access token.
 
     Parameters:
-        args (argparse.Namespace): CLI arguments. Relevant attributes:
-            password (str | None): If provided and non-empty, used as the verification password.
-                If provided as an empty string or omitted, the function will prompt securely.
-            yes (bool): If True, skip the interactive confirmation prompt.
+        args (argparse.Namespace): CLI arguments with the following relevant attributes:
+            password (str | None): If a non-empty string is provided, it will be used as the
+                verification password. If None or an empty string, the function prompts securely.
+            yes (bool): If True, skip the confirmation prompt.
+
+    Returns:
+        int: 0 on successful logout, 1 on failure or if the operation is cancelled (including
+             KeyboardInterrupt).
     """
     import asyncio
 
@@ -1197,7 +1460,11 @@ def handle_auth_logout(args):
         # Handle password input
         password = getattr(args, "password", None)
 
-        if password is None or password == "":
+        if (
+            password is None
+            or password
+            == ""  # nosec B105 (user-entered secret; prompting securely via getpass)
+        ):
             # No --password flag or --password with no value, prompt securely
             import getpass
 
@@ -1231,10 +1498,16 @@ def handle_auth_logout(args):
 
 def handle_service_command(args):
     """
-    Handle service-related CLI subcommands.
-
-    Currently supports the "install" subcommand which attempts to import and run mmrelay.setup_utils.install_service.
-    Returns 0 on success, 1 on failure or for unknown subcommands. Prints an error message if setup utilities cannot be imported.
+    Dispatch service-related subcommands.
+    
+    Currently supports the "install" subcommand which imports and runs mmrelay.setup_utils.install_service().
+    Returns 0 on successful installation, 1 on failure or for unknown subcommands.
+    
+    Parameters:
+        args: argparse.Namespace with a `service_command` attribute indicating the requested action.
+    
+    Returns:
+        int: Exit code (0 on success, 1 on error).
     """
     if args.service_command == "install":
         try:
@@ -1249,6 +1522,259 @@ def handle_service_command(args):
         return 1
 
 
+def _diagnose_config_paths(args):
+    """
+    Print a diagnostic summary of resolved configuration file search paths and their directory accessibility.
+    
+    Uses get_config_paths(args) to compute the ordered list of candidate config file locations, then prints each path with a concise directory status icon:
+    - ✅ directory exists and is writable
+    - ⚠️ directory exists but is not writable
+    - ❌ directory does not exist
+    
+    Parameters:
+        args (argparse.Namespace): Parsed CLI arguments used to determine the config search order.
+    """
+    print("1. Testing configuration paths...")
+    from mmrelay.config import get_config_paths
+
+    paths = get_config_paths(args)
+    print(f"   Config search paths: {len(paths)} locations")
+    for i, path in enumerate(paths, 1):
+        dir_path = os.path.dirname(path)
+        dir_exists = os.path.exists(dir_path)
+        dir_writable = os.access(dir_path, os.W_OK) if dir_exists else False
+        status = "✅" if dir_exists and dir_writable else "⚠️" if dir_exists else "❌"
+        print(f"   {i}. {path} {status}")
+    print()
+
+
+def _diagnose_sample_config_accessibility():
+    """
+    Check availability of the bundled sample configuration and print a short diagnostic.
+    
+    Performs two non-destructive checks and prints human-readable results:
+    1) Verifies whether the sample config file exists at the path returned by mmrelay.tools.get_sample_config_path().
+    2) Attempts to read the embedded resource "sample_config.yaml" from the mmrelay.tools package via importlib.resources and reports success and the content length.
+    
+    Returns:
+        bool: True if a filesystem sample config exists at the resolved path; False otherwise.
+    """
+    print("2. Testing sample config accessibility...")
+    from mmrelay.tools import get_sample_config_path
+
+    sample_path = get_sample_config_path()
+    sample_exists = os.path.exists(sample_path)
+    print(f"   Sample config path: {sample_path}")
+    print(f"   Sample config exists: {'✅' if sample_exists else '❌'}")
+
+    # Test importlib.resources fallback
+    try:
+        import importlib.resources
+
+        content = (
+            importlib.resources.files("mmrelay.tools")
+            .joinpath("sample_config.yaml")
+            .read_text()
+        )
+        print(f"   importlib.resources fallback: ✅ ({len(content)} chars)")
+    except (FileNotFoundError, ImportError, OSError) as e:
+        print(f"   importlib.resources fallback: ❌ ({e})")
+    print()
+
+    return sample_exists
+
+
+def _diagnose_platform_specific(args):
+    """
+    Run platform-specific diagnostic checks.
+    
+    On Windows, imports and runs Windows-specific requirement checks and a configuration-generation
+    test from mmrelay.windows_utils, printing per-component results and any warnings. On non-Windows
+    platforms this reports that platform-specific tests are not required.
+    
+    Parameters:
+        args (argparse.Namespace): Parsed CLI arguments; passed through to the Windows
+            config-generation test when running on Windows.
+    
+    Returns:
+        bool: True if the platform is Windows (Windows checks were executed), False otherwise.
+    """
+    print("3. Platform-specific diagnostics...")
+    import sys
+
+    from mmrelay.constants.app import WINDOWS_PLATFORM
+
+    on_windows = sys.platform == WINDOWS_PLATFORM
+    print(f"   Platform: {sys.platform}")
+    print(f"   Windows: {'Yes' if on_windows else 'No'}")
+
+    if on_windows:
+        try:
+            from mmrelay.windows_utils import (
+                check_windows_requirements,
+                test_config_generation_windows,
+            )
+
+            # Check Windows requirements
+            warnings = check_windows_requirements()
+            if warnings:
+                print("   Windows warnings: ⚠️")
+                for line in warnings.split("\n"):
+                    if line.strip():
+                        print(f"     {line}")
+            else:
+                print("   Windows compatibility: ✅")
+
+            # Run Windows-specific tests
+            print("\n   Windows config generation test:")
+            results = test_config_generation_windows(args)
+
+            for component, result in results.items():
+                if component == "overall_status":
+                    continue
+                if isinstance(result, dict):
+                    status_icon = (
+                        "✅"
+                        if result["status"] == "ok"
+                        else "❌" if result["status"] == "error" else "⚠️"
+                    )
+                    print(f"     {component}: {status_icon}")
+
+            overall = results.get("overall_status", "unknown")
+            print(
+                f"   Overall Windows status: {'✅' if overall == 'ok' else '⚠️' if overall == 'partial' else '❌'}"
+            )
+
+        except ImportError:
+            print("   Windows utilities: ❌ (not available)")
+    else:
+        print("   Platform-specific tests: ✅ (Unix-like system)")
+
+    print()
+    return on_windows
+
+
+def _get_minimal_config_template():
+    """
+    Return a minimal MMRelay YAML configuration template used as a fallback when the packaged sample_config.yaml cannot be located.
+
+    The template contains a small, functional configuration (matrix connection hints, a serial meshtastic connection, one room entry, and basic logging) that users can edit to create a working config file.
+
+    Returns:
+        str: A YAML-formatted minimal configuration template.
+    """
+    return """# MMRelay Configuration File
+# This is a minimal template created when the full sample config was unavailable
+# For complete configuration options, visit:
+# https://github.com/jeremiah-k/meshtastic-matrix-relay/wiki
+
+matrix:
+  homeserver: https://matrix.example.org
+  # Use 'mmrelay auth login' to set up authentication
+  # access_token: your_access_token_here
+  # bot_user_id: '@your_bot:matrix.example.org'
+
+meshtastic:
+  connection_type: serial
+  serial_port: /dev/ttyUSB0  # Windows: COM3, macOS: /dev/cu.usbserial-*
+  # host: meshtastic.local  # For network connection
+  # ble_address: "your_device_address"  # For BLE connection
+
+matrix_rooms:
+  - id: '#your-room:matrix.example.org'
+    meshtastic_channel: 0
+
+logging:
+  level: info
+
+# Uncomment and configure as needed:
+# database:
+#   msg_map:
+#     msgs_to_keep: 100
+
+# plugins:
+#   ping:
+#     active: true
+#   weather:
+#     active: true
+#     units: metric
+"""
+
+
+def _diagnose_minimal_config_template():
+    """
+    Validate the built-in minimal YAML configuration template and print a concise pass/fail status.
+    
+    Attempts to parse the string returned by _get_minimal_config_template() using yaml.safe_load. Prints a single-line result showing a ✅ with the template character length when the template is valid YAML, or a ❌ with the YAML parsing error when invalid. This is a non-destructive diagnostic helper that prints output and does not return a value.
+    """
+    print("4. Testing minimal config template fallback...")
+    try:
+        template = _get_minimal_config_template()
+        yaml.safe_load(template)
+        print(f"   Minimal template: ✅ ({len(template)} chars, valid YAML)")
+    except yaml.YAMLError as e:
+        print(f"   Minimal template: ❌ ({e})")
+
+    print()
+
+
+def handle_config_diagnose(args):
+    """
+    Run non-destructive diagnostics for the MMRelay configuration subsystem and print a human-readable report.
+    
+    Performs four checks: resolves candidate config paths and reports directory accessibility; verifies packaged sample config availability (filesystem and importlib.resources fallback); runs platform-specific diagnostics (Windows-focused where applicable); and validates the built-in minimal YAML template. Prints findings and suggested next steps to stdout/stderr.
+    
+    Parameters:
+        args (argparse.Namespace): Parsed CLI arguments used to resolve config search paths and to control platform-specific checks.
+    
+    Returns:
+        int: Exit code (0 on success, 1 on failure).
+    """
+    print("MMRelay Configuration System Diagnostics")
+    print("=" * 40)
+    print()
+
+    try:
+        # Test 1: Basic config path resolution
+        _diagnose_config_paths(args)
+
+        # Test 2: Sample config accessibility
+        sample_exists = _diagnose_sample_config_accessibility()
+
+        # Test 3: Platform-specific diagnostics
+        on_windows = _diagnose_platform_specific(args)
+
+        # Test 4: Minimal config template
+        _diagnose_minimal_config_template()
+
+        print("=" * 40)
+        print("Diagnostics complete!")
+
+        # Provide guidance based on results
+        if on_windows and not sample_exists:
+            print("\n💡 Windows Troubleshooting Tips:")
+            print("   • Try: pip install --upgrade --force-reinstall mmrelay")
+            print("   • Use: python -m mmrelay config generate")
+            print("   • Check antivirus software for quarantined files")
+
+        return 0
+
+    except Exception as e:
+        print(f"❌ Diagnostics failed: {e}", file=sys.stderr)
+
+        # Provide platform-specific guidance
+        try:
+            from mmrelay.windows_utils import get_windows_error_message, is_windows
+
+            if is_windows():
+                error_msg = get_windows_error_message(e)
+                print(f"\nWindows-specific guidance: {error_msg}", file=sys.stderr)
+        except ImportError:
+            pass
+
+        return 1
+
+
 if __name__ == "__main__":
     import sys
 
@@ -1311,7 +1837,8 @@ def generate_sample_config():
     If an existing config file is found in any candidate path (from get_config_paths()), this function aborts and prints its location. Otherwise it creates a sample config at the first candidate path. Sources tried, in order, are:
     - the path returned by get_sample_config_path(),
     - the packaged resource mmrelay.tools:sample_config.yaml via importlib.resources,
-    - a set of fallback filesystem locations relative to the package and current working directory.
+    - a set of fallback filesystem locations relative to the package and current working directory,
+    - a minimal configuration template as a last resort.
 
     On success the sample is written to disk and (on Unix-like systems) secure file permissions are applied (owner read/write, 0o600). Returns True when a sample config is successfully generated and False on any error or if a config already exists.
     """
@@ -1356,7 +1883,17 @@ def generate_sample_config():
             )
             return True
         except (IOError, OSError) as e:
-            print(f"Error copying sample config file: {e}")
+            # Provide Windows-specific error guidance if available
+            try:
+                from mmrelay.windows_utils import get_windows_error_message, is_windows
+
+                if is_windows():
+                    error_msg = get_windows_error_message(e)
+                    print(f"Error copying sample config file: {error_msg}")
+                else:
+                    print(f"Error copying sample config file: {e}")
+            except ImportError:
+                print(f"Error copying sample config file: {e}")
             return False
 
     # If the helper function failed, try using importlib.resources directly
@@ -1369,7 +1906,7 @@ def generate_sample_config():
         )
 
         # Write the sample config to the target path
-        with open(target_path, "w") as f:
+        with open(target_path, "w", encoding="utf-8") as f:
             f.write(sample_config_content)
 
         # Set secure permissions on Unix systems (600 - owner read/write)
@@ -1381,7 +1918,17 @@ def generate_sample_config():
         )
         return True
     except (FileNotFoundError, ImportError, OSError) as e:
-        print(f"Error accessing sample_config.yaml: {e}")
+        print(f"Error accessing sample_config.yaml via importlib.resources: {e}")
+
+        # Provide Windows-specific guidance if needed
+        try:
+            from mmrelay.windows_utils import is_windows
+
+            if is_windows():
+                print("This may be due to Windows installer packaging differences.")
+                print("Trying alternative methods...")
+        except ImportError:
+            pass
 
         # Fallback to traditional file paths if importlib.resources fails
         # First, check in the package directory
@@ -1409,8 +1956,61 @@ def generate_sample_config():
                     )
                     return True
                 except (IOError, OSError) as e:
-                    print(f"Error copying sample config file from {path}: {e}")
+                    # Provide Windows-specific error guidance if available
+                    try:
+                        from mmrelay.windows_utils import (
+                            get_windows_error_message,
+                            is_windows,
+                        )
+
+                        if is_windows():
+                            error_msg = get_windows_error_message(e)
+                            print(
+                                f"Error copying sample config file from {path}: {error_msg}"
+                            )
+                        else:
+                            print(f"Error copying sample config file from {path}: {e}")
+                    except ImportError:
+                        print(f"Error copying sample config file from {path}: {e}")
                     return False
 
-        print("Error: Could not find sample_config.yaml")
+        print("Error: Could not find sample_config.yaml in any location")
+
+        # Last resort: create a minimal config template
+        print("\nAttempting to create minimal config template...")
+        try:
+            minimal_config = _get_minimal_config_template()
+            with open(target_path, "w", encoding="utf-8") as f:
+                f.write(minimal_config)
+
+            # Set secure permissions on Unix systems
+            set_secure_file_permissions(target_path)
+
+            print(f"Created minimal config template at: {target_path}")
+            print(
+                "\n⚠️  This is a minimal template. Please refer to documentation for full configuration options."
+            )
+            print("Visit: https://github.com/jeremiah-k/meshtastic-matrix-relay/wiki")
+            return True
+
+        except (IOError, OSError) as e:
+            print(f"Failed to create minimal config template: {e}")
+
+        # Provide Windows-specific troubleshooting guidance
+        try:
+            from mmrelay.windows_utils import is_windows
+
+            if is_windows():
+                print("\nWindows Troubleshooting:")
+                print("1. Check if MMRelay was installed correctly")
+                print("2. Try reinstalling with: pipx install --force mmrelay")
+                print(
+                    "3. Use alternative entry point: python -m mmrelay config generate"
+                )
+                print("4. Check antivirus software - it may have quarantined files")
+                print("5. Run diagnostics: python -m mmrelay config diagnose")
+                print("6. Manually create config file using documentation")
+        except ImportError:
+            pass
+
         return False