meross-cli 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+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).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-01-10
+
+### Added
+- Initial release of Meross CLI tool
+- Interactive command-line interface for Meross device management
+- Device listing and discovery
+- Device information and status commands
+- Device control commands with interactive menus
+- Support for various device types (switches, lights, thermostats, sensors, etc.)
+- Hub device and subdevice support
+- MQTT event monitoring
+- Device testing functionality
+- Statistics tracking and display
+- Environment variable support for credentials
+- Token caching and reuse
+
+### Known Issues
+- This is an initial, pre-stable release. Please expect bugs.
+- Some edge cases may not be fully handled yet.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Abe Haverkamp
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,110 @@
+# Meross CLI
+
+![npm version (alpha)](https://img.shields.io/npm/v/meross-cli/alpha)
+![GitHub release](https://img.shields.io/github/v/release/Doekse/merossiot?include_prerelease)
+![npm downloads](https://img.shields.io/npm/dm/meross-cli)
+![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)
+![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)
+![alpha](https://img.shields.io/badge/status-alpha-red.svg)
+
+Command-line interface for controlling and managing Meross smart home devices.
+
+**⚠️ Pre-release**: This is currently an unstable pre-release. Use with caution.
+
+## Requirements
+
+- Node.js >= 18
+- `meross-iot` library (installed automatically as a dependency)
+
+## Installation
+
+```bash
+# Install alpha version globally
+npm install -g meross-cli@alpha
+
+# Or install specific version
+npm install -g meross-cli@0.1.0
+```
+
+Or use via npx:
+
+```bash
+npx meross-cli@alpha
+```
+
+## Usage & Documentation
+
+The CLI provides interactive commands for:
+- Listing devices
+- Getting device status and information
+- Testing device functionality
+- Listening to device events
+- Viewing statistics
+- Controlling devices
+
+### Quick Start
+
+```bash
+# List all devices
+meross-cli list --email user@example.com --password mypass
+
+# Get device information
+meross-cli info <uuid> --email user@example.com --password mypass
+
+# Get device status
+meross-cli status --email user@example.com --password mypass
+
+# Control a device
+meross-cli control <uuid> setToggleX --channel 0 --on
+
+# Start interactive menu mode
+meross-cli
+```
+
+### Environment Variables
+
+You can set these environment variables instead of using command-line options:
+
+- `MEROSS_EMAIL` - Meross account email
+- `MEROSS_PASSWORD` - Meross account password
+- `MEROSS_MFA_CODE` - Multi-factor authentication code
+- `MEROSS_TOKEN_DATA` - Path to token data JSON file
+- `MEROSS_API_URL` - Meross API base URL (optional)
+
+## Supported Devices
+
+The CLI supports all devices that are supported by the underlying `meross-iot` library. See the [meross-iot README](../meross-iot/README.md) for a list of supported devices.
+
+## Changelog
+
+### [0.1.0] - 2026-01-10
+
+#### Added
+- Initial release of Meross CLI tool
+- Interactive command-line interface for Meross device management
+- Device listing and discovery
+- Device information and status commands
+- Device control commands with interactive menus
+- Support for various device types (switches, lights, thermostats, sensors, etc.)
+- Hub device and subdevice support
+- MQTT event monitoring
+- Device testing functionality
+- Statistics tracking and display
+- Environment variable support for credentials
+- Token caching and reuse
+
+#### Known Issues
+- 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
+
+**All product and company names or logos are trademarks™ or registered® trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them or any associated subsidiaries! This personal project is maintained in spare time and has no business goal.**
+**MEROSS is a trademark of Chengdu Meross Technology Co., Ltd.**

package/cli/commands/control/execute.js

@@ -0,0 +1,23 @@
+'use strict';
+
+async function executeControlCommand(manager, uuid, methodName, params) {
+    const device = manager.getDevice(uuid);
+
+    if (!device) {
+        throw new Error(`Device not found: ${uuid}`);
+    }
+
+    if (!device.deviceConnected) {
+        throw new Error('Device is not connected. Please wait for device to connect.');
+    }
+
+    if (typeof device[methodName] !== 'function') {
+        throw new Error(`Control method not available: ${methodName}`);
+    }
+
+    // All methods now use unified options pattern, so we can call directly with params
+    return await device[methodName](params);
+}
+
+module.exports = { executeControlCommand };
+

package/cli/commands/control/index.js

@@ -0,0 +1,12 @@
+'use strict';
+
+const { controlDeviceMenu } = require('./menu');
+const { executeControlCommand } = require('./execute');
+const { collectControlParameters } = require('./params');
+
+module.exports = {
+    controlDeviceMenu,
+    executeControlCommand,
+    collectControlParameters
+};
+

package/cli/commands/control/menu.js

@@ -0,0 +1,193 @@
+'use strict';
+
+const chalk = require('chalk');
+const inquirer = require('inquirer');
+const ora = require('ora');
+const { MerossSubDevice, createDebugUtils, TransportMode } = require('meross-iot');
+const { formatDevice } = require('../../utils/display');
+const { clearScreen, renderSimpleHeader, clearMenuArea, SIMPLE_CONTENT_START_LINE } = require('../../utils/terminal');
+const { detectControlMethods } = require('../../control-registry');
+const { collectControlParameters } = require('./params');
+const { executeControlCommand } = require('./execute');
+
+// Helper function for backward compatibility
+async function question(rl, query) {
+    // For backward compatibility, use inquirer for better UX
+    const result = await inquirer.prompt([{
+        type: 'input',
+        name: 'value',
+        message: query.replace(/:\s*$/, '')
+    }]);
+    return result.value;
+}
+
+/**
+ * Interactive device control menu.
+ * @param {Object} manager - MerossManager instance
+ * @param {Object} rl - Readline interface
+ * @param {string|null} currentUser - Current logged in user name
+ */
+async function controlDeviceMenu(manager, rl, currentUser = null) {
+    const devices = manager.getAllDevices().filter(d => !(d instanceof MerossSubDevice));
+    if (devices.length === 0) {
+        console.log('\nNo devices found.');
+        return;
+    }
+
+    // Select device
+    const deviceChoices = devices.map((device) => {
+        const info = formatDevice(device);
+        return {
+            name: `${info.name} (${info.uuid})`,
+            value: info.uuid
+        };
+    });
+
+    const { uuid } = await inquirer.prompt([{
+        type: 'list',
+        name: 'uuid',
+        message: 'Select device to control:',
+        choices: deviceChoices
+    }]);
+
+    const device = manager.getDevice(uuid);
+
+    // Wait for device to connect if needed
+    if (!device.deviceConnected) {
+        console.log(chalk.yellow('\nWaiting for device to connect...'));
+        const spinner = ora('Connecting').start();
+        let connected = false;
+        for (let i = 0; i < 30; i++) {
+            await new Promise(resolve => setTimeout(resolve, 500));
+            if (device.deviceConnected) {
+                connected = true;
+                break;
+            }
+        }
+        spinner.stop();
+        if (!connected) {
+            console.log(chalk.red('\nDevice did not connect in time. Please try again.'));
+            return;
+        }
+    }
+
+    // Abilities are already loaded at device creation (single-phase initialization)
+    // Detect available control methods (filtered by device capabilities)
+    const availableMethods = detectControlMethods(device);
+    if (availableMethods.length === 0) {
+        console.log(chalk.yellow('\nNo control methods available for this device.'));
+        return;
+    }
+
+    // Group methods by category
+    const methodsByCategory = {};
+    for (const method of availableMethods) {
+        const category = method.category || 'Other';
+        if (!methodsByCategory[category]) {
+            methodsByCategory[category] = [];
+        }
+        methodsByCategory[category].push(method);
+    }
+
+    // Control loop
+    while (true) {
+        clearScreen();
+        const deviceCount = manager.getAllDevices().filter(d => !(d instanceof MerossSubDevice)).length;
+        renderSimpleHeader(currentUser, deviceCount);
+        clearMenuArea(SIMPLE_CONTENT_START_LINE);
+
+        const info = formatDevice(manager.getDevice(uuid));
+        console.log(chalk.bold(`=== Control Device: ${info.name} ===\n`));
+
+        // Build choices grouped by category
+        const choices = [];
+        for (const [category, methods] of Object.entries(methodsByCategory)) {
+            choices.push(new inquirer.Separator(chalk.bold(category)));
+            for (const method of methods) {
+                choices.push({
+                    name: `${method.name} - ${method.description}`,
+                    value: method.methodName
+                });
+            }
+        }
+        choices.push(new inquirer.Separator());
+        choices.push({ name: 'Back to main menu', value: 'back' });
+
+        const { methodName } = await inquirer.prompt([{
+            type: 'list',
+            name: 'methodName',
+            message: 'Select control method:',
+            choices
+        }]);
+
+        if (methodName === 'back') {
+            break;
+        }
+
+        // Get method metadata
+        const method = availableMethods.find(m => m.methodName === methodName);
+        if (!method) {
+            console.log(chalk.red('\nMethod not found.'));
+            await question(rl, '\nPress Enter to continue...');
+            continue;
+        }
+
+        try {
+            // Collect parameters
+            const params = await collectControlParameters(methodName, method, device);
+
+            // Ensure stats are enabled (they should be, but verify)
+            const debug = createDebugUtils(manager);
+            if (!debug.isStatsEnabled()) {
+                console.log(chalk.yellow('\nNote: Statistics tracking is disabled. Enable it in Settings to track control commands.'));
+            }
+
+            // Check error budget if using LAN HTTP transport modes
+            const transportMode = manager.defaultTransportMode;
+            const usesLanHttp = transportMode === TransportMode.LAN_HTTP_FIRST ||
+                                transportMode === TransportMode.LAN_HTTP_FIRST_ONLY_GET;
+            if (usesLanHttp) {
+                const debug = createDebugUtils(manager);
+                const budget = debug.getErrorBudget(uuid);
+                if (budget < 1) {
+                    console.log(chalk.yellow(`\n⚠ Device is out of error budget (${budget} remaining). HTTP requests will be blocked and fallback to MQTT will be used.`));
+                    console.log(chalk.dim('   You can reset the error budget in Settings > Error Budget Management.\n'));
+                }
+            }
+
+            // Execute command
+            console.log(chalk.cyan(`\nExecuting ${method.name}...`));
+            const spinner = ora('Sending command').start();
+
+            const result = await executeControlCommand(manager, uuid, methodName, params);
+
+            spinner.stop();
+            console.log(chalk.green('\n✓ Command executed successfully!'));
+
+            if (result) {
+                console.log(chalk.dim('\nResponse:'));
+                console.log(JSON.stringify(result, null, 2));
+            }
+
+        } catch (error) {
+            console.log(chalk.red(`\n✗ Error: ${error.message}`));
+            if (error.stack && process.env.MEROSS_VERBOSE) {
+                console.error(error.stack);
+            }
+        }
+
+        const { continueControl } = await inquirer.prompt([{
+            type: 'confirm',
+            name: 'continueControl',
+            message: '\nControl this device again?',
+            default: true
+        }]);
+
+        if (!continueControl) {
+            break;
+        }
+    }
+}
+
+module.exports = { controlDeviceMenu };
+

package/cli/commands/control/params/generic.js

@@ -0,0 +1,229 @@
+'use strict';
+
+const inquirer = require('inquirer');
+
+/**
+ * Validates a number value against parameter constraints.
+ */
+function _validateNumber(value, paramDef) {
+    if (paramDef.required && (value === null || value === undefined)) {
+        return `${paramDef.label || paramDef.name} is required`;
+    }
+    if (value !== null && value !== undefined) {
+        if (paramDef.min !== undefined && value < paramDef.min) {
+            return `Value must be at least ${paramDef.min}`;
+        }
+        if (paramDef.max !== undefined && value > paramDef.max) {
+            return `Value must be at most ${paramDef.max}`;
+        }
+    }
+    return true;
+}
+
+/**
+ * Validates a string value.
+ */
+function _validateString(value, paramDef) {
+    if (paramDef.required && (!value || value.trim() === '')) {
+        return `${paramDef.label || paramDef.name} is required`;
+    }
+    return true;
+}
+
+/**
+ * Validates an RGB color value.
+ */
+function _validateRgb(value, paramDef) {
+    if (paramDef.required && (!value || value.trim() === '')) {
+        return 'RGB color is required';
+    }
+    if (value && value.trim() !== '') {
+        const parts = value.split(',');
+        if (parts.length !== 3) {
+            return 'RGB must be in format: r,g,b (e.g., 255,0,0)';
+        }
+        for (const part of parts) {
+            const num = parseInt(part.trim(), 10);
+            if (isNaN(num) || num < 0 || num > 255) {
+                return 'Each RGB value must be between 0 and 255';
+            }
+        }
+    }
+    return true;
+}
+
+/**
+ * Builds a number type question for inquirer.
+ */
+function _buildNumberQuestion(paramDef) {
+    return {
+        type: 'number',
+        name: paramDef.name,
+        message: paramDef.label || paramDef.name,
+        default: paramDef.default,
+        validate: (value) => _validateNumber(value, paramDef),
+        when: paramDef.when || (() => true)
+    };
+}
+
+/**
+ * Builds a boolean type question for inquirer.
+ */
+function _buildBooleanQuestion(paramDef) {
+    if (paramDef.choices) {
+        return {
+            type: 'list',
+            name: paramDef.name,
+            message: paramDef.label || paramDef.name,
+            choices: paramDef.choices,
+            required: paramDef.required || false
+        };
+    }
+    return {
+        type: 'confirm',
+        name: paramDef.name,
+        message: paramDef.label || paramDef.name,
+        default: paramDef.default
+    };
+}
+
+/**
+ * Builds an enum type question for inquirer.
+ */
+function _buildEnumQuestion(paramDef) {
+    return {
+        type: 'list',
+        name: paramDef.name,
+        message: paramDef.label || paramDef.name,
+        choices: paramDef.choices,
+        required: paramDef.required || false
+    };
+}
+
+/**
+ * Builds a string type question for inquirer.
+ */
+function _buildStringQuestion(paramDef) {
+    return {
+        type: 'input',
+        name: paramDef.name,
+        message: paramDef.label || paramDef.name,
+        default: paramDef.default,
+        validate: (value) => _validateString(value, paramDef)
+    };
+}
+
+/**
+ * Builds an RGB type question for inquirer.
+ */
+function _buildRgbQuestion(paramDef) {
+    return {
+        type: 'input',
+        name: paramDef.name,
+        message: paramDef.label || 'RGB Color (r,g,b)',
+        default: paramDef.default,
+        validate: (value) => _validateRgb(value, paramDef),
+        filter: (value) => {
+            if (!value || value.trim() === '') {return null;}
+            const parts = value.split(',').map(p => parseInt(p.trim(), 10));
+            return parts;
+        }
+    };
+}
+
+/**
+ * Collects object properties interactively.
+ */
+async function _collectObjectProperties(paramDef) {
+    const objectParams = {};
+    if (!paramDef.properties) {
+        return objectParams;
+    }
+
+    for (const prop of paramDef.properties) {
+        if (prop.type === 'number') {
+            const propValue = await inquirer.prompt([{
+                type: 'number',
+                name: 'value',
+                message: prop.label || prop.name,
+                default: prop.default,
+                validate: (value) => _validateNumber(value, prop)
+            }]);
+            objectParams[prop.name] = propValue.value;
+        } else if (prop.type === 'boolean') {
+            const propValue = await inquirer.prompt([{
+                type: 'confirm',
+                name: 'value',
+                message: prop.label || prop.name,
+                default: prop.default
+            }]);
+            objectParams[prop.name] = propValue.value ? 1 : 0;
+        } else if (prop.type === 'string') {
+            const propValue = await inquirer.prompt([{
+                type: 'input',
+                name: 'value',
+                message: prop.label || prop.name,
+                default: prop.default,
+                validate: (value) => _validateString(value, prop)
+            }]);
+            objectParams[prop.name] = propValue.value;
+        }
+    }
+    return objectParams;
+}
+
+/**
+ * Builds a question for a parameter definition based on its type.
+ */
+function _buildQuestionForType(paramDef) {
+    switch (paramDef.type) {
+    case 'number':
+        return _buildNumberQuestion(paramDef);
+    case 'boolean':
+        return _buildBooleanQuestion(paramDef);
+    case 'enum':
+        return _buildEnumQuestion(paramDef);
+    case 'string':
+        return _buildStringQuestion(paramDef);
+    case 'rgb':
+        return _buildRgbQuestion(paramDef);
+    default:
+        return null;
+    }
+}
+
+/**
+ * Generic parameter collection based on methodMetadata.params.
+ * Handles all standard parameter types: number, boolean, enum, string, rgb, object.
+ */
+async function collectGenericParams(methodMetadata) {
+    const params = {};
+    const questions = [];
+
+    if (!methodMetadata || !methodMetadata.params) {
+        return params;
+    }
+
+    for (const paramDef of methodMetadata.params) {
+        if (paramDef.type === 'object') {
+            const objectParams = await _collectObjectProperties(paramDef);
+            params[paramDef.name] = objectParams;
+            continue;
+        }
+
+        const question = _buildQuestionForType(paramDef);
+        if (question) {
+            questions.push(question);
+        }
+    }
+
+    if (questions.length > 0) {
+        const answers = await inquirer.prompt(questions);
+        Object.assign(params, answers);
+    }
+
+    return params;
+}
+
+module.exports = { collectGenericParams };
+

package/cli/commands/control/params/index.js

@@ -0,0 +1,56 @@
+'use strict';
+
+const { collectThermostatModeParams } = require('./thermostat');
+const { collectSetTimerXParams, collectDeleteTimerXParams } = require('./timer');
+const { collectSetTriggerXParams, collectDeleteTriggerXParams } = require('./trigger');
+const { collectSetLightColorParams } = require('./light');
+const { collectGenericParams } = require('./generic');
+
+/**
+ * Main entry point for collecting control parameters.
+ * Routes to feature-specific handlers or falls back to generic collection.
+ */
+async function collectControlParameters(methodName, methodMetadata, device) {
+    if (!methodMetadata || !methodMetadata.params) {
+        return {};
+    }
+
+    // Route to feature-specific handlers
+    switch (methodName) {
+    case 'setThermostatMode':
+        return await collectThermostatModeParams(methodMetadata, device);
+
+    case 'setLightColor':
+        return await collectSetLightColorParams(methodMetadata, device);
+
+    case 'setTimerX':
+        return await collectSetTimerXParams(methodMetadata, device);
+
+    case 'deleteTimerX': {
+        const result = await collectDeleteTimerXParams(methodMetadata, device);
+        if (result !== null) {
+            return result;
+        }
+        // Fall through to generic collection if no timers found
+        break;
+    }
+
+    case 'setTriggerX':
+        return await collectSetTriggerXParams(methodMetadata, device);
+
+    case 'deleteTriggerX': {
+        const result = await collectDeleteTriggerXParams(methodMetadata, device);
+        if (result !== null) {
+            return result;
+        }
+        // Fall through to generic collection if no triggers found
+        break;
+    }
+    }
+
+    // Default to generic parameter collection
+    return await collectGenericParams(methodMetadata);
+}
+
+module.exports = { collectControlParameters };
+