meross-cli 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -5,6 +5,30 @@ 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
+- **BREAKING**: Updated to use simplified device API from `meross-iot` v0.4.0
+  - Updated to use `initializeDevices()` instead of `getDevices()`
+  - Updated to use direct device properties instead of `cachedHttpInfo`
+  - Updated to use camelCase property names consistently
+  - Updated all tests and commands to use new API patterns
+
 ## [0.2.0] - 2026-01-15
 
 ### 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.2.0
+npm install -g meross-cli@0.4.0
 ```
 
 Or use via npx:
@@ -77,6 +77,33 @@ 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
+- **BREAKING**: Updated to use simplified device API from `meross-iot` v0.4.0
+  - Updated to use `initializeDevices()` instead of `getDevices()`
+  - Updated to use direct device properties instead of `cachedHttpInfo`
+  - Updated to use camelCase property names consistently
+  - Updated all tests and commands to use new API patterns
+
 ### [0.2.0] - 2026-01-15
 
 #### Changed
@@ -107,11 +134,6 @@ The CLI supports all devices that are supported by the underlying `meross-iot` l
 - This is an initial, pre-stable release. Please expect bugs.
 - Some edge cases may not be fully handled yet.
 
-<details>
-<summary>Older</summary>
-
-<!-- Older changelog entries will appear here -->
-
 </details>
 
 ## Disclaimer

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;
 }
@@ -84,35 +84,41 @@ function _displayChannels(device) {
 }
 
 /**
- * Builds HTTP device info data array.
+ * Extracts HTTP device info properties for display.
+ *
+ * Collects HTTP metadata properties (domain, reservedDomain, subType, region, etc.)
+ * that are now directly accessible on the device instance for formatting in the CLI output.
+ *
+ * @param {Object} device - MerossDevice instance
+ * @returns {Array<Array<string>>} Array of [label, value] pairs for display
  */
-function _buildHttpInfoData(httpInfo) {
+function _buildHttpInfoData(device) {
     const httpInfoData = [];
 
-    if (httpInfo.domain) {
-        httpInfoData.push(['MQTT Domain', httpInfo.domain]);
+    if (device.domain) {
+        httpInfoData.push(['MQTT Domain', device.domain]);
     }
-    if (httpInfo.reservedDomain) {
-        httpInfoData.push(['Reserved Domain', httpInfo.reservedDomain]);
+    if (device.reservedDomain) {
+        httpInfoData.push(['Reserved Domain', device.reservedDomain]);
     }
-    if (httpInfo.subType) {
-        httpInfoData.push(['Sub Type', httpInfo.subType]);
+    if (device.subType) {
+        httpInfoData.push(['Sub Type', device.subType]);
     }
-    if (httpInfo.region) {
-        httpInfoData.push(['Region', httpInfo.region]);
+    if (device.region) {
+        httpInfoData.push(['Region', device.region]);
     }
-    if (httpInfo.skillNumber) {
-        httpInfoData.push(['Skill Number', httpInfo.skillNumber]);
+    if (device.skillNumber) {
+        httpInfoData.push(['Skill Number', device.skillNumber]);
     }
-    if (httpInfo.devIconId) {
-        httpInfoData.push(['Icon ID', httpInfo.devIconId]);
+    if (device.devIconId) {
+        httpInfoData.push(['Icon ID', device.devIconId]);
     }
-    if (httpInfo.bindTime) {
-        httpInfoData.push(['Bind Time', httpInfo.bindTime.toLocaleString()]);
+    if (device.bindTime) {
+        httpInfoData.push(['Bind Time', device.bindTime.toLocaleString()]);
     }
-    if (httpInfo.onlineStatus !== undefined) {
-        const onlineStatusText = httpInfo.onlineStatus === OnlineStatus.ONLINE ? chalk.green('Online') :
-            httpInfo.onlineStatus === OnlineStatus.OFFLINE ? chalk.red('Offline') :
+    if (device.onlineStatus !== undefined) {
+        const onlineStatusText = device.onlineStatus === OnlineStatus.ONLINE ? chalk.green('Online') :
+            device.onlineStatus === OnlineStatus.OFFLINE ? chalk.red('Offline') :
                 chalk.yellow('Unknown');
         httpInfoData.push(['Online Status', onlineStatusText]);
     }
@@ -121,15 +127,12 @@ function _buildHttpInfoData(httpInfo) {
 }
 
 /**
- * Displays HTTP device info if available.
+ * Displays HTTP device info section if properties are available.
+ *
+ * @param {Object} device - MerossDevice instance
  */
 function _displayHttpInfo(device) {
-    if (!device.cachedHttpInfo) {
-        return;
-    }
-
-    const httpInfo = device.cachedHttpInfo;
-    const httpInfoData = _buildHttpInfoData(httpInfo);
+    const httpInfoData = _buildHttpInfoData(device);
 
     if (httpInfoData.length === 0) {
         return;

package/cli/control-registry.js

@@ -762,10 +762,10 @@ function getMethodsByCategory() {
  * @returns {boolean} True if device supports the namespace
  */
 function deviceSupportsNamespace(device, namespace) {
-    if (!device._abilities || typeof device._abilities !== 'object') {
+    if (!device.abilities || typeof device.abilities !== 'object') {
         return false;
     }
-    return !!device._abilities[namespace];
+    return !!device.abilities[namespace];
 }
 
 /**

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)',