meross-cli 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -5,6 +5,21 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.0] - 2026-01-19
+
+### Changed
+- **BREAKING**: Updated to use new manager module structure from `meross-iot` v0.5.0
+  - Updated to use manager properties (`manager.devices`, `manager.mqtt`, `manager.http`, etc.) instead of direct methods
+  - Updated all commands and helpers to use new property-based access patterns
+- **BREAKING**: Updated to use standardized error handling from `meross-iot` v0.5.0
+  - Updated to use new `MerossError*` error class names
+  - Replaced inline error handling with centralized `handleError()` function
+  - All error handling now uses the new error handler utility for consistent, user-friendly formatted messages
+
+### Added
+- Centralized error handler utility (`cli/utils/error-handler.js`) with formatted error messages
+- Enhanced error display with better context and user-friendly formatting
+
 ## [0.3.0] - 2026-01-16
 
 ### Changed

package/README.md

@@ -23,7 +23,7 @@ Command-line interface for controlling and managing Meross smart home devices.
 npm install -g meross-cli@alpha
 
 # Or install specific version
-npm install -g meross-cli@0.3.0
+npm install -g meross-cli@0.4.0
 ```
 
 Or use via npx:
@@ -77,6 +77,24 @@ The CLI supports all devices that are supported by the underlying `meross-iot` l
 
 ## Changelog
 
+### [0.4.0] - 2026-01-19
+
+#### Changed
+- **BREAKING**: Updated to use new manager module structure from `meross-iot` v0.5.0
+  - Updated to use manager properties (`manager.devices`, `manager.mqtt`, `manager.http`, etc.) instead of direct methods
+  - Updated all commands and helpers to use new property-based access patterns
+- **BREAKING**: Updated to use standardized error handling from `meross-iot` v0.5.0
+  - Updated to use new `MerossError*` error class names
+  - Replaced inline error handling with centralized `handleError()` function
+  - All error handling now uses the new error handler utility for consistent, user-friendly formatted messages
+
+#### Added
+- Centralized error handler utility (`cli/utils/error-handler.js`) with formatted error messages
+- Enhanced error display with better context and user-friendly formatting
+
+<details>
+<summary>Older</summary>
+
 ### [0.3.0] - 2026-01-16
 
 #### Changed
@@ -86,9 +104,6 @@ The CLI supports all devices that are supported by the underlying `meross-iot` l
   - Updated to use camelCase property names consistently
   - Updated all tests and commands to use new API patterns
 
-<details>
-<summary>Older</summary>
-
 ### [0.2.0] - 2026-01-15
 
 #### Changed

package/cli/commands/control/execute.js

@@ -1,18 +1,31 @@
 'use strict';
 
+const ManagerMeross = require('meross-iot');
+
 async function executeControlCommand(manager, uuid, methodName, params) {
     const device = manager.devices.get(uuid);
 
     if (!device) {
-        throw new Error(`Device not found: ${uuid}`);
+        throw new ManagerMeross.MerossErrorNotFound(
+            `Device not found: ${uuid}`,
+            'device',
+            uuid
+        );
     }
 
     if (!device.deviceConnected) {
-        throw new Error('Device is not connected. Please wait for device to connect.');
+        throw new ManagerMeross.MerossErrorUnconnected(
+            'Device is not connected. Please wait for device to connect.',
+            uuid
+        );
     }
 
     if (typeof device[methodName] !== 'function') {
-        throw new Error(`Control method not available: ${methodName}`);
+        throw new ManagerMeross.MerossErrorUnsupported(
+            `Control method not available: ${methodName}`,
+            methodName,
+            'Method not supported by this device'
+        );
     }
 
     // All methods now use unified options pattern, so we can call directly with params

package/cli/commands/control/menu.js

@@ -143,7 +143,7 @@ async function controlDeviceMenu(manager, rl, currentUser = null) {
             }
 
             // Check error budget if using LAN HTTP transport modes
-            const transportMode = manager.defaultTransportMode;
+            const transportMode = manager.transport.defaultMode;
             const usesLanHttp = transportMode === TransportMode.LAN_HTTP_FIRST ||
                                 transportMode === TransportMode.LAN_HTTP_FIRST_ONLY_GET;
             if (usesLanHttp) {
@@ -170,10 +170,8 @@ async function controlDeviceMenu(manager, rl, currentUser = null) {
             }
 
         } catch (error) {
-            console.log(chalk.red(`\n✗ Error: ${error.message}`));
-            if (error.stack && process.env.MEROSS_VERBOSE) {
-                console.error(error.stack);
-            }
+            const { handleError } = require('../../utils/error-handler');
+            handleError(error, { verbose: process.env.MEROSS_VERBOSE === 'true' });
         }
 
         const { continueControl } = await inquirer.prompt([{

package/cli/commands/info.js

@@ -34,7 +34,7 @@ function _buildBasicDeviceInfo(device, manager) {
 
     info.push(['Connected', status]);
     info.push(['Online', onlineStatus]);
-    info.push(['Transport', getTransportModeName(manager.defaultTransportMode)]);
+    info.push(['Transport', getTransportModeName(manager.transport.defaultMode)]);
 
     return info;
 }

package/cli/helpers/client.js

@@ -2,6 +2,7 @@
 
 const fs = require('fs');
 const { MerossHttpClient, TransportMode } = require('meross-iot');
+const { handleError } = require('../utils/error-handler');
 
 async function processOptionsAndCreateHttpClient(opts) {
     const email = opts.email || process.env.MEROSS_EMAIL || null;
@@ -33,16 +34,21 @@ async function processOptionsAndCreateHttpClient(opts) {
             maxStatsSamples: 1000
         });
     } else if (email && password) {
-        httpClient = await MerossHttpClient.fromUserPassword({
-            email,
-            password,
-            mfaCode,
-            logger: verbose ? console.log : null,
-            timeout,
-            autoRetryOnBadDomain: true,
-            enableStats,
-            maxStatsSamples: 1000
-        });
+        try {
+            httpClient = await MerossHttpClient.fromUserPassword({
+                email,
+                password,
+                mfaCode,
+                logger: verbose ? console.log : null,
+                timeout,
+                autoRetryOnBadDomain: true,
+                enableStats,
+                maxStatsSamples: 1000
+            });
+        } catch (error) {
+            // Re-throw with better context for MFA/auth errors
+            throw error;
+        }
     } else {
         throw new Error('Email and password are required (or provide token data).\nUse --email and --password options or set MEROSS_EMAIL and MEROSS_PASSWORD environment variables.');
     }

package/cli/helpers/meross.js

@@ -3,6 +3,7 @@
 const ManagerMeross = require('meross-iot');
 const { MerossHttpClient, TransportMode } = require('meross-iot');
 const ora = require('ora');
+const { handleError } = require('../utils/error-handler');
 
 async function createMerossInstance(optionsOrEmail, password, mfaCode, transportMode, timeout, enableStats, verbose) {
     let httpClient;
@@ -29,16 +30,21 @@ async function createMerossInstance(optionsOrEmail, password, mfaCode, transport
         finalVerbose = verbose || false;
 
         // Create HTTP client
-        httpClient = await MerossHttpClient.fromUserPassword({
-            email,
-            password,
-            mfaCode,
-            logger: finalVerbose ? console.log : null,
-            timeout: finalTimeout,
-            autoRetryOnBadDomain: true,
-            enableStats: finalEnableStats,
-            maxStatsSamples: 1000
-        });
+        try {
+            httpClient = await MerossHttpClient.fromUserPassword({
+                email,
+                password,
+                mfaCode,
+                logger: finalVerbose ? console.log : null,
+                timeout: finalTimeout,
+                autoRetryOnBadDomain: true,
+                enableStats: finalEnableStats,
+                maxStatsSamples: 1000
+            });
+        } catch (error) {
+            // Re-throw to let caller handle with proper error formatting
+            throw error;
+        }
     }
 
     const instance = new ManagerMeross({
@@ -79,10 +85,8 @@ async function connectMeross(manager) {
         await new Promise(resolve => setTimeout(resolve, 2000));
         return true;
     } catch (error) {
-        spinner.fail(`Connection error: ${error.message}`);
-        if (error.stack && process.env.MEROSS_VERBOSE) {
-            console.error(error.stack);
-        }
+        spinner.stop();
+        handleError(error, { verbose: process.env.MEROSS_VERBOSE === 'true' });
         return false;
     }
 }

package/cli/menu/main.js

@@ -2,13 +2,14 @@
 
 const chalk = require('chalk');
 const inquirer = require('inquirer');
+const ora = require('ora');
 const { MerossHubDevice, MerossSubDevice, createDebugUtils, TransportMode } = require('meross-iot');
 const testRunner = require('../tests/test-runner');
 const { clearScreen, renderLogoAtTop, renderSimpleHeader, clearMenuArea, CONTENT_START_LINE, SIMPLE_CONTENT_START_LINE, createRL, question, promptForPassword } = require('../utils/terminal');
 const { formatDevice } = require('../utils/display');
 const { listDevices, showStats, dumpRegistry, listMqttConnections, getDeviceStatus, showDeviceInfo, controlDeviceMenu, runTestCommand, snifferMenu } = require('../commands');
 const { addUser, getUser, listUsers } = require('../config/users');
-const { createMerossInstance, connectMeross, disconnectMeross } = require('../helpers/meross');
+const { createMerossInstance, disconnectMeross } = require('../helpers/meross');
 const { showSettingsMenu } = require('./settings');
 
 // Helper functions
@@ -169,6 +170,164 @@ async function _saveCredentialsPrompt(rl, currentCredentials) {
     return null;
 }
 
+/**
+ * Prompts user to select devices and subdevices to initialize.
+ *
+ * Discovers available devices and subdevices, presents them in a hierarchical
+ * selection UI with subdevices indented under their hubs, and initializes
+ * only the selected items.
+ *
+ * @param {ManagerMeross} manager - Meross manager instance
+ * @returns {Promise<boolean>} True if initialization succeeded, false otherwise
+ * @private
+ */
+async function _selectDevicesToInitialize(manager) {
+    const spinner = ora('Discovering available devices...').start();
+    try {
+        const [baseDevices, subdevices] = await Promise.all([
+            manager.devices.discover({ onlineOnly: true }),
+            manager.devices.discoverSubdevices({ onlineOnly: true })
+        ]);
+        spinner.stop();
+
+        if ((!baseDevices || baseDevices.length === 0) && (!subdevices || subdevices.length === 0)) {
+            console.log(chalk.yellow('\nNo online devices or subdevices found.'));
+            return false;
+        }
+
+        // Group subdevices by hub UUID to display them hierarchically
+        const subdevicesByHub = new Map();
+        if (subdevices && subdevices.length > 0) {
+            for (const subdevice of subdevices) {
+                const hubUuid = subdevice.hubUuid;
+                if (!subdevicesByHub.has(hubUuid)) {
+                    subdevicesByHub.set(hubUuid, []);
+                }
+                subdevicesByHub.get(hubUuid).push(subdevice);
+            }
+        }
+
+        const deviceChoices = [];
+        const deviceUuids = new Set();
+
+        if (baseDevices && baseDevices.length > 0) {
+            for (const device of baseDevices) {
+                const hasSubdevices = subdevicesByHub.has(device.uuid);
+                if (hasSubdevices) {
+                    deviceUuids.add(device.uuid);
+                }
+
+                deviceChoices.push({
+                    name: `${device.devName || 'Unknown'} (${device.deviceType}) - ${chalk.grey(device.uuid)}`,
+                    value: `device:${device.uuid}`,
+                    checked: true
+                });
+
+                // Display subdevices indented under their hub for visual hierarchy
+                if (hasSubdevices) {
+                    const hubSubdevices = subdevicesByHub.get(device.uuid);
+                    for (const subdevice of hubSubdevices) {
+                        deviceChoices.push({
+                            name: `  └─ ${subdevice.subdeviceName || 'Unknown'} (${subdevice.subdeviceType}) - ${chalk.grey(subdevice.subdeviceId)}`,
+                            value: `subdevice:${subdevice.hubUuid}:${subdevice.subdeviceId}`,
+                            checked: true
+                        });
+                    }
+                }
+            }
+        }
+
+        // Handle edge case where subdevices exist but their hub isn't in base device list
+        for (const [hubUuid, hubSubdevices] of subdevicesByHub) {
+            if (!deviceUuids.has(hubUuid)) {
+                for (const subdevice of hubSubdevices) {
+                    deviceChoices.push({
+                        name: `  └─ ${subdevice.subdeviceName || 'Unknown'} (${subdevice.subdeviceType}) - ${chalk.grey(subdevice.subdeviceId)} [Hub: ${chalk.grey(subdevice.hubUuid)}]`,
+                        value: `subdevice:${subdevice.hubUuid}:${subdevice.subdeviceId}`,
+                        checked: true
+                    });
+                }
+            }
+        }
+
+        if (deviceChoices.length === 0) {
+            console.log(chalk.yellow('\nNo devices or subdevices found.'));
+            return false;
+        }
+
+        const { selectedItems } = await inquirer.prompt([{
+            type: 'checkbox',
+            name: 'selectedItems',
+            message: 'Select devices/subdevices to initialize (use space to toggle, enter to confirm):',
+            choices: deviceChoices,
+            pageSize: 20
+        }]);
+
+        if (!selectedItems || selectedItems.length === 0) {
+            console.log(chalk.yellow('\nNo devices selected. Skipping initialization.'));
+            return false;
+        }
+
+        // Parse selection into base devices and subdevices for different initialization paths
+        const baseDeviceUuids = [];
+        const subdeviceIdentifiers = [];
+
+        for (const item of selectedItems) {
+            if (item.startsWith('device:')) {
+                baseDeviceUuids.push(item.replace('device:', ''));
+            } else if (item.startsWith('subdevice:')) {
+                const parts = item.replace('subdevice:', '').split(':');
+                if (parts.length === 2) {
+                    subdeviceIdentifiers.push({ hubUuid: parts[0], id: parts[1] });
+                }
+            }
+        }
+
+        spinner.start('Initializing selected devices...');
+        try {
+            let totalInitialized = 0;
+
+            if (baseDeviceUuids.length > 0) {
+                const deviceCount = await manager.devices.initialize({ uuids: baseDeviceUuids });
+                totalInitialized += deviceCount;
+            }
+
+            // Initialize subdevices individually since they require hub context
+            for (const subdeviceId of subdeviceIdentifiers) {
+                try {
+                    const subdevice = await manager.devices.initializeDevice(subdeviceId);
+                    if (subdevice) {
+                        totalInitialized++;
+                    }
+                } catch (error) {
+                    if (manager.options && manager.options.logger) {
+                        manager.options.logger(`Failed to initialize subdevice ${subdeviceId.id}: ${error.message}`);
+                    }
+                }
+            }
+
+            spinner.succeed(`Initialized ${totalInitialized} device(s)`);
+
+            // Allow time for MQTT connections to establish
+            await new Promise(resolve => setTimeout(resolve, 2000));
+
+            manager.authenticated = true;
+
+            return true;
+        } catch (error) {
+            spinner.stop();
+            const { handleError } = require('../utils/error-handler');
+            handleError(error, { verbose: process.env.MEROSS_VERBOSE === 'true' });
+            return false;
+        }
+    } catch (error) {
+        spinner.stop();
+        const { handleError } = require('../utils/error-handler');
+        handleError(error, { verbose: process.env.MEROSS_VERBOSE === 'true' });
+        return false;
+    }
+}
+
 async function _selectDevice(manager, message = 'Select device:') {
     const devices = manager.devices.list().filter(d => !(d instanceof MerossSubDevice));
     if (devices.length === 0) {
@@ -384,12 +543,12 @@ function _buildSettingsCallbacks(
                 enableStatsRef.current,
                 verboseRef.current
             );
-            const connected = await connectMeross(managerRef.current, rl);
+            const connected = await _selectDevicesToInitialize(managerRef.current);
             if (connected) {
                 currentUserRef.current = userName;
                 return { success: true };
             }
-            return { success: false, error: 'Failed to connect with new user' };
+            return { success: false, error: 'Failed to initialize devices with new user' };
         },
         onSaveCredentials: async (name) => {
             if (!currentCredentials) {
@@ -408,15 +567,15 @@ function _buildSettingsCallbacks(
 }
 
 async function _handleSettingsCommand(manager, rl, currentUserRef, currentCredentials) {
-    const transportModeRef = { current: manager.defaultTransportMode || TransportMode.MQTT_ONLY };
+    const transportModeRef = { current: manager.transport.defaultMode || TransportMode.MQTT_ONLY };
     const timeoutRef = { current: 10000 };
-    const enableStatsRef = { current: manager._mqttStatsCounter !== null || manager.httpClient._httpStatsCounter !== null };
+    const enableStatsRef = { current: manager.statistics.isEnabled() };
     const verboseRef = { current: manager.options && manager.options.logger !== null };
     const managerRef = { current: manager };
 
     const setTransportMode = (mode) => {
         transportModeRef.current = mode;
-        managerRef.current.defaultTransportMode = mode;
+        managerRef.current.transport.defaultMode = mode;
     };
     const setTimeout = (newTimeout) => {
         timeoutRef.current = newTimeout;
@@ -540,10 +699,10 @@ async function menuMode() {
         currentCredentials = result.credentials;
     }
 
-    // Connect
-    const connected = await connectMeross(currentManager, rl);
+    // Discover and select devices to initialize
+    const connected = await _selectDevicesToInitialize(currentManager);
     if (!connected) {
-        console.error('Failed to connect. Exiting.');
+        console.error('Failed to initialize devices. Exiting.');
         rl.close();
         return;
     }
@@ -622,10 +781,8 @@ async function menuMode() {
                 }
             }
         } catch (error) {
-            console.error(`\nError: ${error.message}`);
-            if (error.stack && process.env.MEROSS_VERBOSE) {
-                console.error(error.stack);
-            }
+            const { handleError } = require('../utils/error-handler');
+            handleError(error, { verbose: process.env.MEROSS_VERBOSE === 'true' });
             await question(rl, '\nPress Enter to return to menu...');
         }
     }

package/cli/menu/settings.js

@@ -32,7 +32,7 @@ async function showSettingsMenu(rl, currentManager, currentUser, timeout, enable
         const debug = currentManager ? createDebugUtils(currentManager) : null;
         const currentStatsEnabled = debug ? debug.isStatsEnabled() : enableStats;
         const currentTransportMode = currentManager
-            ? getTransportModeName(currentManager.defaultTransportMode)
+            ? getTransportModeName(currentManager.transport.defaultMode)
             : getTransportModeName(TransportMode.MQTT_ONLY);
         const currentVerboseState = currentManager && currentManager.options ? (currentManager.options.logger !== null) : verbose;
 
@@ -111,7 +111,7 @@ async function showTransportModeSettings(rl, currentManager, currentUser, setTra
         type: 'list',
         name: 'mode',
         message: 'Transport Mode',
-        default: currentManager.defaultTransportMode,
+        default: currentManager.transport.defaultMode,
         choices: [
             {
                 name: 'MQTT Only (default, works remotely)',

package/cli/meross-cli.js

@@ -16,6 +16,7 @@ const packageJson = require('../package.json');
 // Import from new modules
 const { processOptionsAndCreateHttpClient } = require('./helpers/client');
 const { printLogo, printVersion } = require('./utils/display');
+const { handleError } = require('./utils/error-handler');
 const { listDevices, dumpRegistry, listMqttConnections, getDeviceStatus, showDeviceInfo, executeControlCommand, collectControlParameters, runTestCommand } = require('./commands');
 const { menuMode } = require('./menu');
 
@@ -112,7 +113,8 @@ Examples:
             const deviceCount = await manager.connect();
             spinner.succeed(chalk.green(`Connected to ${deviceCount} device(s)`));
         } catch (error) {
-            spinner.fail(chalk.red(`Connection failed: ${error.message}`));
+            spinner.stop();
+            handleError(error, { verbose: config.verbose });
             throw error;
         }
 
@@ -136,11 +138,7 @@ Examples:
                     console.log('\nLogout response:', JSON.stringify(logoutResponse, null, 2));
                 }
             } catch (error) {
-                console.error(chalk.red(`Error: ${error.message}`));
-                if (opts.verbose) {
-                    console.error(error.stack);
-                }
-                process.exit(1);
+                handleError(error, { verbose: opts.verbose, exit: true });
             }
         });
 
@@ -164,11 +162,7 @@ Examples:
                     console.log('\nLogout response:', JSON.stringify(logoutResponse, null, 2));
                 }
             } catch (error) {
-                console.error(chalk.red(`Error: ${error.message}`));
-                if (opts.verbose) {
-                    console.error(error.stack);
-                }
-                process.exit(1);
+                handleError(error, { verbose: opts.verbose, exit: true });
             }
         });
 
@@ -186,11 +180,7 @@ Examples:
                     console.log('\nLogout response:', JSON.stringify(logoutResponse, null, 2));
                 }
             } catch (error) {
-                console.error(chalk.red(`Error: ${error.message}`));
-                if (opts.verbose) {
-                    console.error(error.stack);
-                }
-                process.exit(1);
+                handleError(error, { verbose: opts.verbose, exit: true });
             }
         });
 
@@ -221,11 +211,7 @@ Examples:
                     console.log('\nLogout response:', JSON.stringify(logoutResponse, null, 2));
                 }
             } catch (error) {
-                console.error(chalk.red(`Error: ${error.message}`));
-                if (opts.verbose) {
-                    console.error(error.stack);
-                }
-                process.exit(1);
+                handleError(error, { verbose: opts.verbose, exit: true });
             }
         });
 
@@ -248,11 +234,7 @@ Examples:
                     console.log('\nLogout response:', JSON.stringify(logoutResponse, null, 2));
                 }
             } catch (error) {
-                console.error(chalk.red(`Error: ${error.message}`));
-                if (opts.verbose) {
-                    console.error(error.stack);
-                }
-                process.exit(1);
+                handleError(error, { verbose: opts.verbose, exit: true });
             }
         });
 
@@ -443,11 +425,7 @@ Examples:
                     console.log('\nLogout response:', JSON.stringify(logoutResponse, null, 2));
                 }
             } catch (error) {
-                console.error(chalk.red(`Error: ${error.message}`));
-                if (opts.verbose) {
-                    console.error(error.stack);
-                }
-                process.exit(1);
+                handleError(error, { verbose: opts.verbose, exit: true });
             }
         });
 
@@ -476,11 +454,7 @@ Examples:
                     console.log('\nLogout response:', JSON.stringify(logoutResponse, null, 2));
                 }
             } catch (error) {
-                console.error(chalk.red(`Error: ${error.message}`));
-                if (opts.verbose) {
-                    console.error(error.stack);
-                }
-                process.exit(1);
+                handleError(error, { verbose: opts.verbose, exit: true });
             }
         });
 
@@ -520,11 +494,7 @@ Examples:
             await menuMode();
             return;
         } catch (error) {
-            console.error(chalk.red(`Error: ${error.message}`));
-            if (error.stack) {
-                console.error(error.stack);
-            }
-            process.exit(1);
+            handleError(error, { verbose: true, exit: true });
         }
     }
 
@@ -535,11 +505,7 @@ Examples:
 // Run if called directly
 if (require.main === module) {
     main().catch(error => {
-        console.error(chalk.red(`Fatal error: ${error.message}`));
-        if (error.stack) {
-            console.error(error.stack);
-        }
-        process.exit(1);
+        handleError(error, { verbose: true, exit: true });
     });
 }
 

package/cli/utils/error-handler.js

@@ -0,0 +1,257 @@
+'use strict';
+
+const chalk = require('chalk');
+const ManagerMeross = require('meross-iot');
+
+/**
+ * Formats error messages for display in the CLI.
+ *
+ * Provides user-friendly error messages based on error type, with specific
+ * guidance for common error scenarios like MFA, authentication, and command failures.
+ *
+ * @param {Error} error - The error to format
+ * @param {boolean} verbose - Whether to show detailed error information
+ * @returns {string} Formatted error message
+ */
+function formatError(error, verbose = false) {
+    if (error instanceof ManagerMeross.MerossErrorMFARequired) {
+        return chalk.red('\n✗ MFA (Multi-Factor Authentication) is required.\n') +
+            chalk.dim(`  Error Code: ${error.code}\n`) +
+            chalk.yellow('  Please provide MFA code using --mfa-code option or set MEROSS_MFA_CODE environment variable.\n');
+    }
+
+    if (error instanceof ManagerMeross.MerossErrorWrongMFA) {
+        return chalk.red('\n✗ MFA code is incorrect.\n') +
+            chalk.dim(`  Error Code: ${error.code}\n`) +
+            chalk.yellow('  Please check your MFA code and try again.\n');
+    }
+
+    if (error instanceof ManagerMeross.MerossErrorAuthentication) {
+        return chalk.red('\n✗ Authentication failed.\n') +
+            chalk.dim(`  Error Code: ${error.code}\n`) +
+            chalk.yellow('  Please check your email and password.\n');
+    }
+
+    if (error instanceof ManagerMeross.MerossErrorTokenExpired) {
+        return chalk.yellow('\n⚠ Authentication token has expired.\n') +
+            chalk.dim(`  Error Code: ${error.code}\n`) +
+            chalk.dim('  The library will automatically attempt to login again.\n');
+    }
+
+    if (error instanceof ManagerMeross.MerossErrorBadDomain) {
+        return chalk.yellow('\n⚠ Bad domain error.\n') +
+            chalk.dim(`  Error Code: ${error.code}\n`) +
+            chalk.dim('  The API domain may be incorrect. Auto-retry is enabled.\n');
+    }
+
+    if (error instanceof ManagerMeross.MerossErrorCommand) {
+        let message = chalk.red('\n✗ Device command failed.\n') +
+            chalk.dim(`  Error Code: ${error.code}\n`);
+        if (error.deviceUuid) {
+            message += chalk.dim(`  Device: ${error.deviceUuid}\n`);
+        }
+        if (error.errorPayload) {
+            message += chalk.dim(`  Device Response: ${JSON.stringify(error.errorPayload, null, 2)}\n`);
+        }
+        return message;
+    }
+
+    if (error instanceof ManagerMeross.MerossErrorCommandTimeout) {
+        let message = chalk.yellow('\n⚠ Command timeout.\n') +
+            chalk.dim(`  Error Code: ${error.code}\n`);
+        if (error.deviceUuid) {
+            message += chalk.dim(`  Device: ${error.deviceUuid}\n`);
+        }
+        if (error.timeout) {
+            message += chalk.dim(`  Timeout: ${error.timeout}ms\n`);
+        }
+        message += chalk.dim('  The device may be offline or experiencing network issues.\n');
+        return message;
+    }
+
+    if (error instanceof ManagerMeross.MerossErrorMqtt) {
+        let message = chalk.red('\n✗ MQTT error.\n') +
+            chalk.dim(`  Error Code: ${error.code}\n`);
+        if (error.topic) {
+            message += chalk.dim(`  Topic: ${error.topic}\n`);
+        }
+        return message;
+    }
+
+    if (error instanceof ManagerMeross.MerossErrorUnauthorized) {
+        return chalk.red('\n✗ Unauthorized access.\n') +
+            chalk.dim(`  Error Code: ${error.code}\n`) +
+            chalk.dim(`  HTTP Status: ${error.httpStatusCode || 401}\n`) +
+            chalk.yellow('  Authentication token may be invalid or expired.\n');
+    }
+
+    if (error instanceof ManagerMeross.MerossErrorHttpApi) {
+        let message = chalk.red('\n✗ HTTP API error.\n') +
+            chalk.dim(`  Error Code: ${error.code}\n`);
+        if (error.httpStatusCode) {
+            message += chalk.dim(`  HTTP Status: ${error.httpStatusCode}\n`);
+        }
+        if (error.cause && verbose) {
+            message += chalk.dim(`  Caused by: ${error.cause.message}\n`);
+        }
+        return message;
+    }
+
+    if (error instanceof ManagerMeross.MerossErrorApiLimitReached) {
+        return chalk.yellow('\n⚠ API rate limit reached.\n') +
+            chalk.dim(`  Error Code: ${error.code}\n`) +
+            chalk.dim('  Please wait before making more requests.\n');
+    }
+
+    if (error instanceof ManagerMeross.MerossErrorResourceAccessDenied) {
+        return chalk.red('\n✗ Resource access denied.\n') +
+            chalk.dim(`  Error Code: ${error.code}\n`) +
+            chalk.yellow('  You may not have permission to access this resource.\n');
+    }
+
+    if (error instanceof ManagerMeross.MerossErrorUnconnected) {
+        return chalk.yellow('\n⚠ Device is not connected.\n') +
+            chalk.dim(`  Error Code: ${error.code}\n`) +
+            chalk.dim('  Please wait for the device to connect before sending commands.\n');
+    }
+
+    if (error instanceof ManagerMeross.MerossErrorValidation) {
+        let message = chalk.red('\n✗ Validation error.\n') +
+            chalk.dim(`  Error Code: ${error.code}\n`);
+        if (error.field) {
+            message += chalk.dim(`  Field: ${error.field}\n`);
+        }
+        return message;
+    }
+
+    if (error instanceof ManagerMeross.MerossErrorNotFound) {
+        let message = chalk.red('\n✗ Resource not found.\n') +
+            chalk.dim(`  Error Code: ${error.code}\n`);
+        if (error.resourceType) {
+            message += chalk.dim(`  Type: ${error.resourceType}\n`);
+        }
+        if (error.resourceId) {
+            message += chalk.dim(`  ID: ${error.resourceId}\n`);
+        }
+        return message;
+    }
+
+    if (error instanceof ManagerMeross.MerossErrorTooManyTokens) {
+        return chalk.red('\n✗ Too many authentication tokens.\n') +
+            chalk.dim(`  Error Code: ${error.code}\n`) +
+            chalk.yellow('  You have issued too many tokens without logging out. Please log out from other sessions.\n');
+    }
+
+    if (error instanceof ManagerMeross.MerossErrorRateLimit) {
+        return chalk.yellow('\n⚠ Request rate limit exceeded.\n') +
+            chalk.dim(`  Error Code: ${error.code}\n`) +
+            chalk.dim('  Please wait before making more requests.\n');
+    }
+
+    if (error instanceof ManagerMeross.MerossErrorOperationLocked) {
+        return chalk.yellow('\n⚠ Operation is locked.\n') +
+            chalk.dim(`  Error Code: ${error.code}\n`) +
+            chalk.dim('  The operation may become available after a delay.\n');
+    }
+
+    if (error instanceof ManagerMeross.MerossErrorUnsupported) {
+        let message = chalk.red('\n✗ Unsupported operation.\n') +
+            chalk.dim(`  Error Code: ${error.code}\n`);
+        if (error.operation) {
+            message += chalk.dim(`  Operation: ${error.operation}\n`);
+        }
+        if (error.reason) {
+            message += chalk.dim(`  Reason: ${error.reason}\n`);
+        }
+        return message;
+    }
+
+    if (error instanceof ManagerMeross.MerossErrorInitialization) {
+        let message = chalk.red('\n✗ Initialization failed.\n') +
+            chalk.dim(`  Error Code: ${error.code}\n`);
+        if (error.component) {
+            message += chalk.dim(`  Component: ${error.component}\n`);
+        }
+        if (error.reason) {
+            message += chalk.dim(`  Reason: ${error.reason}\n`);
+        }
+        return message;
+    }
+
+    if (error instanceof ManagerMeross.MerossErrorNetworkTimeout) {
+        let message = chalk.yellow('\n⚠ Network request timeout.\n') +
+            chalk.dim(`  Error Code: ${error.code}\n`);
+        if (error.timeout) {
+            message += chalk.dim(`  Timeout: ${error.timeout}ms\n`);
+        }
+        if (error.url) {
+            message += chalk.dim(`  URL: ${error.url}\n`);
+        }
+        return message;
+    }
+
+    if (error instanceof ManagerMeross.MerossErrorParse) {
+        let message = chalk.red('\n✗ Parse error.\n') +
+            chalk.dim(`  Error Code: ${error.code}\n`);
+        if (error.format) {
+            message += chalk.dim(`  Format: ${error.format}\n`);
+        }
+        return message;
+    }
+
+    if (error instanceof ManagerMeross.MerossErrorUnknownDeviceType) {
+        let message = chalk.red('\n✗ Unknown or unsupported device type.\n') +
+            chalk.dim(`  Error Code: ${error.code}\n`);
+        if (error.deviceType) {
+            message += chalk.dim(`  Device Type: ${error.deviceType}\n`);
+        }
+        return message;
+    }
+
+    if (error instanceof ManagerMeross.MerossError) {
+        let message = chalk.red(`\n✗ ${error.message}\n`);
+        if (error.code) {
+            message += chalk.dim(`  Error Code: ${error.code}\n`);
+        }
+        if (error.errorCode !== null && error.errorCode !== undefined) {
+            message += chalk.dim(`  API Error Code: ${error.errorCode}\n`);
+        }
+        return message;
+    }
+
+    // Generic error fallback
+    return chalk.red(`\n✗ ${error.message}\n`);
+}
+
+/**
+ * Handles and displays errors with appropriate formatting.
+ *
+ * Formats the error message and optionally displays the stack trace
+ * if verbose mode is enabled.
+ *
+ * @param {Error} error - The error to handle
+ * @param {Object} options - Options for error handling
+ * @param {boolean} [options.verbose=false] - Whether to show stack trace
+ * @param {boolean} [options.exit=false] - Whether to exit the process after displaying error
+ * @param {number} [options.exitCode=1] - Exit code to use if exiting
+ */
+function handleError(error, options = {}) {
+    const { verbose = false, exit = false, exitCode = 1 } = options;
+
+    const formattedMessage = formatError(error, verbose);
+    console.error(formattedMessage);
+
+    if (verbose && error.stack) {
+        console.error(chalk.dim('\nStack trace:'));
+        console.error(chalk.dim(error.stack));
+    }
+
+    if (exit) {
+        process.exit(exitCode);
+    }
+}
+
+module.exports = {
+    formatError,
+    handleError
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "meross-cli",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Command-line interface for controlling Meross smart home devices",
   "author": "Abe Haverkamp",
   "homepage": "https://github.com/Doekse/merossiot#readme",
@@ -24,7 +24,7 @@
     "chalk": "^4.1.2",
     "commander": "^12.1.0",
     "inquirer": "^8.2.6",
-    "meross-iot": "^0.4.0",
+    "meross-iot": "^0.5.0",
     "ora": "^5.4.1"
   },
   "devDependencies": {