@switchbot/openapi-cli 2.6.2 → 2.6.4

package/README.md

@@ -184,7 +184,10 @@ switchbot devices command --help
 
 Intercepts every non-GET request: the CLI prints the URL/body it would have
 sent, then exits `0` without contacting the API. `GET` requests (list, status,
-query) are still executed so you can preview the state involved.
+query) are still executed so you can preview the state involved. Dry-run also
+validates command names against the device catalog and rejects unknown commands
+(exit 2) when the device type has a known catalog entry. Commands sent to
+read-only sensors (e.g. Meter) are likewise rejected.
 
 ```bash
 switchbot devices command ABC123 turnOn --dry-run
@@ -305,7 +308,7 @@ Generic parameter shapes (which one applies is decided by the device — see the
 
 Parameters for `setAll` (Air Conditioner), `setPosition` (Curtain / Blind Tilt), `setMode` (Relay Switch), `setBrightness` (dimmable lights), and `setColor` (Color Bulb / Strip Light / Ceiling Light) are validated client-side before the request — malformed shapes, out-of-range values, and JSON for CSV fields all fail fast with exit 2. `setColor` accepts `R:G:B`, `R,G,B`, `#RRGGBB`, `#RGB`, and CSS named colors (`red`, `blue`, …); all normalize to `R:G:B` before hitting the API. Pass `--skip-param-validation` to bypass (escape hatch — prefer fixing the argument). Command names are also case-normalized against the catalog (e.g. `turnon` is auto-corrected to `turnOn` with a stderr warning); unknown names still exit 2 with the supported-commands list.
 
-Unknown deviceIds (not in the local cache) exit 2 by default so `--dry-run` is a reliable pre-flight gate. Run `switchbot devices list` first, or pass `--allow-unknown-device` for scripted pass-through.
+Unknown deviceIds (not in the local cache) exit 2 by default so `--dry-run` is a reliable pre-flight gate. Unknown command names and commands on read-only sensors are also rejected during dry-run when the device type has a catalog entry. Run `switchbot devices list` first, or pass `--allow-unknown-device` for scripted pass-through.
 
 Negative numeric parameters (e.g. `setBrightness -1` for a probe) are passed through to the command validator instead of being swallowed by the flag parser as an unknown option.
 
@@ -717,7 +720,7 @@ switchbot cache clear --key status
 
 | Code | Meaning                                                                                                                   |
 | ---- | ------------------------------------------------------------------------------------------------------------------------- |
-| `0`  | Success (including `--dry-run` intercept)                                                                                 |
+| `0`  | Success (including `--dry-run` intercept when validation passes)                                                           |
 | `1`  | Runtime error — API error, network failure, missing credentials                                                           |
 | `2`  | Usage error — bad flag, missing/invalid argument, unknown subcommand, unknown device type, invalid URL, conflicting flags |
 

package/dist/commands/batch.js

@@ -1,5 +1,5 @@
 import { intArg, enumArg, stringArg } from '../utils/arg-parsers.js';
-import { printJson, isJsonMode, handleError, buildErrorPayload, UsageError, emitJsonError } from '../utils/output.js';
+import { printJson, isJsonMode, handleError, buildErrorPayload, UsageError, emitJsonError, exitWithError } from '../utils/output.js';
 import { fetchDeviceList, executeCommand, isDestructiveCommand, buildHubLocationMap, } from '../lib/devices.js';
 import { createClient } from '../api/client.js';
 import { parseFilter, applyFilter, FilterSyntaxError } from '../utils/filter.js';
@@ -166,22 +166,10 @@ Examples:
         }
         catch (error) {
             if (error instanceof FilterSyntaxError) {
-                if (isJsonMode()) {
-                    emitJsonError({ code: 2, kind: 'usage', message: error.message });
-                }
-                else {
-                    console.error(`Error: ${error.message}`);
-                }
-                process.exit(2);
+                exitWithError(`Error: ${error.message}`);
             }
             if (error instanceof Error && error.message.startsWith('No target devices')) {
-                if (isJsonMode()) {
-                    emitJsonError({ code: 2, kind: 'usage', message: error.message });
-                }
-                else {
-                    console.error(`Error: ${error.message}`);
-                }
-                process.exit(2);
+                exitWithError(`Error: ${error.message}`);
             }
             handleError(error);
         }

package/dist/commands/catalog.js

@@ -74,6 +74,14 @@ Examples:
         .description("Show the effective catalog (or one entry). Alias: 'list'. Defaults to 'effective' source.")
         .argument('[type...]', 'Optional device type/alias (case-insensitive, partial match)')
         .option('--source <source>', 'Which catalog to show: built-in | overlay | effective (default)', enumArg('--source', SOURCES), 'effective')
+        .addHelpText('after', `
+Examples:
+  $ switchbot catalog show
+  $ switchbot catalog show Bot
+  $ switchbot catalog show Robot Vacuum
+  $ switchbot catalog show --source built-in
+  $ switchbot catalog show --json
+`)
         .action((typeParts, options) => {
         try {
             const source = options.source;

package/dist/commands/config.js

@@ -3,7 +3,7 @@ import readline from 'node:readline';
 import { execFileSync } from 'node:child_process';
 import { stringArg } from '../utils/arg-parsers.js';
 import { intArg } from '../utils/arg-parsers.js';
-import { saveConfig, showConfig, listProfiles, readProfileMeta } from '../config.js';
+import { saveConfig, showConfig, getConfigSummary, listProfiles, readProfileMeta } from '../config.js';
 import { isJsonMode, printJson, emitJsonError } from '../utils/output.js';
 import chalk from 'chalk';
 function parseEnvFile(file) {
@@ -237,6 +237,10 @@ Files are written with mode 0600. Profiles live under ~/.switchbot/profiles/<nam
         .command('show')
         .description('Show the current credential source and a masked secret')
         .action(() => {
+        if (isJsonMode()) {
+            printJson(getConfigSummary());
+            return;
+        }
         showConfig();
     });
     config

package/dist/commands/devices.js

@@ -1,5 +1,5 @@
 import { enumArg, stringArg } from '../utils/arg-parsers.js';
-import { printTable, printKeyValue, printJson, isJsonMode, handleError, UsageError, StructuredUsageError, emitJsonError } from '../utils/output.js';
+import { printTable, printKeyValue, printJson, isJsonMode, handleError, UsageError, StructuredUsageError, emitJsonError, exitWithError } from '../utils/output.js';
 import { resolveFormat, resolveFields, renderRows } from '../utils/format.js';
 import { findCatalogEntry, getEffectiveCatalog } from '../devices/catalog.js';
 import { getCachedDevice, loadCache } from '../devices/cache.js';
@@ -15,6 +15,14 @@ import { registerExpandCommand } from './expand.js';
 import { registerDevicesMetaCommand } from './device-meta.js';
 import { isDryRun } from '../utils/flags.js';
 import { DryRunSignal } from '../api/client.js';
+import { resolveField, listSupportedFieldInputs } from '../schema/field-aliases.js';
+const EXPAND_HINTS = {
+    'Air Conditioner': { command: 'setAll', flags: '--temp 26 --mode cool --fan low --power on' },
+    'Curtain': { command: 'setPosition', flags: '--position 50 --mode silent' },
+    'Curtain 3': { command: 'setPosition', flags: '--position 50' },
+    'Blind Tilt': { command: 'setPosition', flags: '--direction up --angle 50' },
+    'Relay Switch 2PM': { command: 'setMode', flags: '--channel 1 --mode edge' },
+};
 export function registerDevicesCommand(program) {
     const COMMAND_TYPES = ['command', 'customize'];
     const devices = program
@@ -80,7 +88,7 @@ Examples:
 `)
         .option('--wide', 'Show all columns (controlType, family, roomID, room, hub, cloud)')
         .option('--show-hidden', 'Include devices hidden via "devices meta set --hide"')
-        .option('--filter <expr>', 'Filter devices: comma-separated clauses. Each clause is "key=value" (substring; exact for category), "key!=value" (negated substring), "key~value" (explicit substring), or "key=/regex/" (case-insensitive regex). Supported keys: type, name, category, room.', stringArg('--filter'))
+        .option('--filter <expr>', 'Filter devices: comma-separated clauses. Each clause is "key=value" (substring; exact for category), "key!=value" (negated substring), "key~value" (explicit substring), or "key=/regex/" (case-insensitive regex). Supported keys: deviceId/id, deviceName/name, deviceType/type, controlType, roomName/room, category.', stringArg('--filter'))
         .action(async (options) => {
         try {
             const body = await fetchDeviceList();
@@ -90,11 +98,26 @@ Examples:
             const hubLocation = buildHubLocationMap(deviceList);
             // Parse --filter into a list of clauses. Shared grammar across
             // `devices list`, `devices batch`, and `events tail` / `mqtt-tail`.
-            const LIST_KEYS = ['type', 'name', 'category', 'room'];
+            const LIST_KEYS = ['deviceId', 'type', 'name', 'category', 'room', 'controlType'];
+            const LIST_FILTER_CANONICAL = ['deviceId', 'deviceName', 'deviceType', 'controlType', 'roomName', 'category'];
+            const LIST_FILTER_TO_RUNTIME = {
+                deviceId: 'deviceId',
+                deviceName: 'name',
+                deviceType: 'type',
+                controlType: 'controlType',
+                roomName: 'room',
+                category: 'category',
+            };
             let listClauses = null;
             if (options.filter) {
                 try {
-                    listClauses = parseFilterExpr(options.filter, LIST_KEYS);
+                    listClauses = parseFilterExpr(options.filter, LIST_KEYS, {
+                        resolveKey: (input) => {
+                            const canonical = resolveField(input, LIST_FILTER_CANONICAL);
+                            return LIST_FILTER_TO_RUNTIME[canonical];
+                        },
+                        supportedKeys: listSupportedFieldInputs(LIST_FILTER_CANONICAL),
+                    });
                 }
                 catch (err) {
                     if (err instanceof FilterSyntaxError)
@@ -114,10 +137,10 @@ Examples:
             };
             if (fmt === 'json' && process.argv.includes('--json')) {
                 if (listClauses) {
-                    const filteredDeviceList = deviceList.filter((d) => matchesFilter({ type: d.deviceType || '', name: d.deviceName, category: 'physical', room: d.roomName || '' }));
+                    const filteredDeviceList = deviceList.filter((d) => matchesFilter({ deviceId: d.deviceId, type: d.deviceType || '', name: d.deviceName, category: 'physical', room: d.roomName || '', controlType: d.controlType || '' }));
                     const filteredIrList = infraredRemoteList.filter((d) => {
                         const inherited = hubLocation.get(d.hubDeviceId);
-                        return matchesFilter({ type: d.remoteType, name: d.deviceName, category: 'ir', room: inherited?.room || '' });
+                        return matchesFilter({ deviceId: d.deviceId, type: d.remoteType, name: d.deviceName, category: 'ir', room: inherited?.room || '', controlType: d.controlType || '' });
                     });
                     printJson({ ok: true, deviceList: filteredDeviceList, infraredRemoteList: filteredIrList });
                 }
@@ -134,7 +157,7 @@ Examples:
             for (const d of deviceList) {
                 if (!options.showHidden && deviceMeta.devices[d.deviceId]?.hidden)
                     continue;
-                if (!matchesFilter({ type: d.deviceType || '', name: d.deviceName, category: 'physical', room: d.roomName || '' }))
+                if (!matchesFilter({ deviceId: d.deviceId, type: d.deviceType || '', name: d.deviceName, category: 'physical', room: d.roomName || '', controlType: d.controlType || '' }))
                     continue;
                 rows.push([
                     d.deviceId,
@@ -154,7 +177,7 @@ Examples:
                 if (!options.showHidden && deviceMeta.devices[d.deviceId]?.hidden)
                     continue;
                 const inherited = hubLocation.get(d.hubDeviceId);
-                if (!matchesFilter({ type: d.remoteType, name: d.deviceName, category: 'ir', room: inherited?.room || '' }))
+                if (!matchesFilter({ deviceId: d.deviceId, type: d.remoteType, name: d.deviceName, category: 'ir', room: inherited?.room || '', controlType: d.controlType || '' }))
                     continue;
                 rows.push([
                     d.deviceId,
@@ -177,9 +200,19 @@ Examples:
             const defaultFields = options.wide ? undefined : narrowHeaders;
             // Accept API field names and short aliases alongside canonical column names
             const DEVICE_LIST_ALIASES = {
-                id: 'deviceId', name: 'deviceName', deviceType: 'type', type: 'type',
-                roomName: 'room', familyName: 'family',
-                hubDeviceId: 'hub', enableCloudService: 'cloud',
+                id: 'deviceId',
+                name: 'deviceName',
+                deviceType: 'type',
+                type: 'type',
+                roomName: 'room',
+                familyName: 'family',
+                hubDeviceId: 'hub',
+                enableCloudService: 'cloud',
+                controlType: 'controlType',
+                deviceName: 'deviceName',
+                deviceId: 'deviceId',
+                category: 'category',
+                alias: 'alias',
             };
             renderRows(wideHeaders, rows, fmt, userFields ?? defaultFields, DEVICE_LIST_ALIASES);
             if (fmt === 'table') {
@@ -454,18 +487,10 @@ Examples:
             if (cachedForParam && options.type === 'command' && !options.skipParamValidation) {
                 const paramCheck = validateParameter(cachedForParam.type, cmd, parameter);
                 if (!paramCheck.ok) {
-                    if (isJsonMode()) {
-                        emitJsonError({
-                            code: 2,
-                            kind: 'usage',
-                            message: paramCheck.error,
-                            context: { command: cmd, deviceType: cachedForParam.type, deviceId, humanHint: paramCheck.error },
-                        });
-                    }
-                    else {
-                        console.error(`Error: ${paramCheck.error}`);
-                    }
-                    process.exit(2);
+                    exitWithError({
+                        message: `Error: ${paramCheck.error}`,
+                        context: { command: cmd, deviceType: cachedForParam.type, deviceId, humanHint: paramCheck.error },
+                    });
                 }
                 if (paramCheck.normalized !== undefined)
                     parameter = paramCheck.normalized;
@@ -476,24 +501,14 @@ Examples:
                 isDestructiveCommand(cachedForGuard?.type, cmd, options.type)) {
                 const typeLabel = cachedForGuard?.type ?? 'unknown';
                 const reason = getDestructiveReason(cachedForGuard?.type, cmd, options.type);
-                if (isJsonMode()) {
-                    emitJsonError({
-                        code: 2,
-                        kind: 'guard',
-                        message: `"${cmd}" on ${typeLabel} is destructive and requires --yes.`,
-                        hint: reason
-                            ? `Re-run with --yes to confirm. Reason: ${reason}`
-                            : 'Re-run with --yes to confirm, or --dry-run to preview without sending.',
-                        context: { command: cmd, deviceType: typeLabel, deviceId, ...(reason ? { destructiveReason: reason } : {}) },
-                    });
-                }
-                else {
-                    console.error(`Refusing to run destructive command "${cmd}" on ${typeLabel} without --yes.`);
-                    if (reason)
-                        console.error(`Reason: ${reason}`);
-                    console.error(`Re-run with --yes to confirm, or --dry-run to preview without sending.`);
-                }
-                process.exit(2);
+                exitWithError({
+                    kind: 'guard',
+                    message: `Refusing to run destructive command "${cmd}" on ${typeLabel} without --yes.`,
+                    hint: reason
+                        ? `Re-run with --yes to confirm. Reason: ${reason}`
+                        : 'Re-run with --yes to confirm, or --dry-run to preview without sending.',
+                    context: { command: cmd, deviceType: typeLabel, deviceId, ...(reason ? { destructiveReason: reason } : {}) },
+                });
             }
             // Warn when --yes is given but the command is not destructive (no-op flag)
             if (options.yes && !isDestructiveCommand(cachedForGuard?.type, cmd, options.type) && !isDryRun()) {
@@ -702,7 +717,8 @@ JSON output shape (--json):
       liveStatus: <status payload when --live was passed>
     },
     source: "catalog" | "live" | "catalog+live" | "none",
-    suggestedActions: [{command, parameter?, description}]
+    suggestedActions: [{command, parameter?, description}],
+    expandHint?: {command, flags, example}  // present when the type supports 'devices expand'
   }
 
 Examples:
@@ -722,6 +738,7 @@ Examples:
             const result = await describeDevice(deviceId, options);
             const { device, isPhysical, typeName, controlType, catalog, capabilities, source, suggestedActions: picks } = result;
             if (isJsonMode()) {
+                const expandHint = catalog ? EXPAND_HINTS[catalog.type] : undefined;
                 printJson({
                     device,
                     controlType,
@@ -729,6 +746,7 @@ Examples:
                     capabilities,
                     source,
                     suggestedActions: picks,
+                    ...(expandHint ? { expandHint: { command: expandHint.command, flags: expandHint.flags, example: `switchbot devices expand ${deviceId} ${expandHint.command} ${expandHint.flags}` } } : {}),
                 });
                 return;
             }
@@ -785,20 +803,12 @@ Examples:
         catch (error) {
             if (error instanceof DeviceNotFoundError) {
                 const message = `${error.message} Try 'switchbot devices list' to see the full list.`;
-                if (isJsonMode()) {
-                    emitJsonError({
-                        code: 1,
-                        kind: 'runtime',
-                        message,
-                        errorClass: 'runtime',
-                        transient: false,
-                    });
-                }
-                else {
-                    console.error(error.message);
-                    console.error(`Try 'switchbot devices list' to see the full list.`);
-                }
-                process.exit(1);
+                exitWithError({
+                    code: 1,
+                    kind: 'runtime',
+                    message,
+                    extra: { errorClass: 'runtime', transient: false },
+                });
             }
             handleError(error);
         }
@@ -853,4 +863,8 @@ function renderCatalogEntry(entry) {
         console.log('\nStatus fields (from "devices status"):');
         console.log('  ' + entry.statusFields.join(', '));
     }
+    const expandHint = EXPAND_HINTS[entry.type];
+    if (expandHint) {
+        console.log(`\nTip: Use 'devices expand <id> ${expandHint.command} ${expandHint.flags}' for semantic flags instead of raw parameters.`);
+    }
 }

package/dist/commands/mcp.js

@@ -3,7 +3,7 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { z } from 'zod';
 import { intArg, stringArg } from '../utils/arg-parsers.js';
-import { handleError, isJsonMode, buildErrorPayload, emitJsonError } from '../utils/output.js';
+import { handleError, buildErrorPayload, exitWithError } from '../utils/output.js';
 import { VERSION } from '../version.js';
 import { fetchDeviceList, fetchDeviceStatus, executeCommand, describeDevice, validateCommand, isDestructiveCommand, getDestructiveReason, searchCatalog, DeviceNotFoundError, toMcpDescribeShape, toMcpDeviceListShape, toMcpIrDeviceShape, } from '../lib/devices.js';
 import { fetchScenes, executeScene } from '../lib/scenes.js';
@@ -274,6 +274,7 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`,
         },
     }, async ({ deviceId, command, parameter, commandType, confirm, idempotencyKey, dryRun }) => {
         const effectiveType = commandType ?? 'command';
+        let effectiveCommand = command;
         let effectiveParameter = parameter;
         // stringifiedParam mirrors the CLI form that validateCommand /
         // validateParameter expect — B-1 runs on the string representation.
@@ -291,30 +292,37 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`,
                     context: { deviceId },
                 });
             }
+            const dryValidation = validateCommand(deviceId, effectiveCommand, stringifiedParam, effectiveType);
+            if (!dryValidation.ok) {
+                return mcpError('usage', 2, dryValidation.error.message, {
+                    hint: dryValidation.error.hint,
+                    context: {
+                        validationKind: dryValidation.error.kind,
+                        deviceType: cached.type,
+                        command: effectiveCommand,
+                    },
+                });
+            }
+            if (dryValidation.normalized) {
+                effectiveCommand = dryValidation.normalized;
+            }
             // R-2: run B-1 param validation in dry-run too, so dry-run doesn't
             // falsely accept inputs the live API would reject.
             if (effectiveType !== 'customize') {
-                const pv = validateParameter(cached.type, command, stringifiedParam);
+                const pv = validateParameter(cached.type, effectiveCommand, stringifiedParam);
                 if (!pv.ok) {
                     return mcpError('usage', 2, pv.error, {
                         hint: 'Dry-run rejected the parameter client-side; the API would reject it too.',
-                        context: { deviceType: cached.type, command, parameter: stringifiedParam },
+                        context: { deviceType: cached.type, command: effectiveCommand, parameter: stringifiedParam },
                     });
                 }
                 if (pv.normalized !== undefined) {
                     effectiveParameter = pv.normalized;
                 }
             }
-            const cmdVal = validateCommand(deviceId, command, stringifiedParam, effectiveType);
-            if (!cmdVal.ok) {
-                return mcpError('usage', 2, cmdVal.error.message, {
-                    hint: cmdVal.error.hint,
-                    context: { validationKind: cmdVal.error.kind },
-                });
-            }
             const wouldSend = {
                 deviceId,
-                command,
+                command: effectiveCommand,
                 parameter: effectiveParameter ?? 'default',
                 commandType: effectiveType,
             };
@@ -339,19 +347,19 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`,
             }
             typeName = physical ? physical.deviceType : ir.remoteType;
         }
-        if (isDestructiveCommand(typeName, command, effectiveType) && !confirm) {
-            const reason = getDestructiveReason(typeName, command, effectiveType);
+        if (isDestructiveCommand(typeName, effectiveCommand, effectiveType) && !confirm) {
+            const reason = getDestructiveReason(typeName, effectiveCommand, effectiveType);
             const entry = typeName ? findCatalogEntry(typeName) : null;
             const spec = entry && !Array.isArray(entry)
-                ? entry.commands.find((c) => c.command === command)
+                ? entry.commands.find((c) => c.command === effectiveCommand)
                 : undefined;
             const hint = reason
                 ? `Re-issue with confirm:true after confirming with the user. Reason: ${reason}`
                 : 'Re-issue the call with confirm:true to proceed.';
-            return mcpError('guard', 3, `Command "${command}" on device type "${typeName}" is destructive and requires confirm:true.`, {
+            return mcpError('guard', 3, `Command "${effectiveCommand}" on device type "${typeName}" is destructive and requires confirm:true.`, {
                 hint,
                 context: {
-                    command,
+                    command: effectiveCommand,
                     deviceType: typeName,
                     description: spec?.description ?? null,
                     ...(reason ? { destructiveReason: reason } : {}),
@@ -361,18 +369,24 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`,
         // validateCommand covers command existence + required/unexpected-parameter.
         // stringifiedParam was computed once at the top of the handler so dry-run
         // and live paths share the same shape.
-        const validation = validateCommand(deviceId, command, stringifiedParam, effectiveType);
+        const validation = validateCommand(deviceId, effectiveCommand, stringifiedParam, effectiveType);
         if (!validation.ok) {
-            return mcpError('usage', 2, validation.error.message, { hint: validation.error.hint, context: { validationKind: validation.error.kind } });
+            return mcpError('usage', 2, validation.error.message, {
+                hint: validation.error.hint,
+                context: { validationKind: validation.error.kind, deviceType: typeName, command: effectiveCommand },
+            });
+        }
+        if (validation.normalized) {
+            effectiveCommand = validation.normalized;
         }
         // R-2: run B-1 client-side parameter validator (range/format checks).
         // Customize commands (user-defined IR buttons) opt out — the catalog
         // cannot know their expected shape.
         if (effectiveType !== 'customize') {
-            const pv = validateParameter(typeName, command, stringifiedParam);
+            const pv = validateParameter(typeName, effectiveCommand, stringifiedParam);
             if (!pv.ok) {
                 return mcpError('usage', 2, pv.error, {
-                    context: { deviceType: typeName, command, parameter: stringifiedParam, validationKind: 'param-out-of-range' },
+                    context: { deviceType: typeName, command: effectiveCommand, parameter: stringifiedParam, validationKind: 'param-out-of-range' },
                 });
             }
             if (pv.normalized !== undefined) {
@@ -381,7 +395,7 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`,
         }
         let result;
         try {
-            result = await executeCommand(deviceId, command, effectiveParameter, effectiveType, undefined, {
+            result = await executeCommand(deviceId, effectiveCommand, effectiveParameter, effectiveType, undefined, {
                 idempotencyKey,
             });
         }
@@ -398,7 +412,7 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`,
             return apiErrorToMcpError(err);
         }
         const isIr = getCachedDevice(deviceId)?.category === 'ir';
-        const structured = { ok: true, command, deviceId, result };
+        const structured = { ok: true, command: effectiveCommand, deviceId, result };
         if (isIr) {
             structured.verification = {
                 verifiable: false,
@@ -764,19 +778,19 @@ Inspect locally:
         .option('--auth-token <token>', 'Bearer token for HTTP requests (required for --bind 0.0.0.0; falls back to SWITCHBOT_MCP_TOKEN env var)', stringArg('--auth-token'))
         .option('--cors-origin <url>', 'Allowed CORS origin(s) for HTTP (repeatable)', stringArg('--cors-origin'))
         .option('--rate-limit <n>', 'Max requests per minute per profile (default 60)', intArg('--rate-limit', { min: 1 }), '60')
+        .addHelpText('after', `
+Examples:
+  $ switchbot mcp serve
+  $ switchbot mcp serve --port 8787
+  $ switchbot mcp serve --port 8787 --bind 127.0.0.1 --auth-token your-token
+  $ switchbot mcp serve --port 8787 --bind 0.0.0.0 --auth-token your-token
+`)
         .action(async (options) => {
         try {
             if (options.port) {
                 const port = Number(options.port);
                 if (!Number.isFinite(port) || port < 1 || port > 65535) {
-                    const msg = `Invalid --port "${options.port}". Must be 1-65535.`;
-                    if (isJsonMode()) {
-                        emitJsonError({ code: 2, kind: 'usage', message: msg });
-                    }
-                    else {
-                        console.error(msg);
-                    }
-                    process.exit(2);
+                    exitWithError(`Invalid --port "${options.port}". Must be 1-65535.`);
                 }
                 const bind = options.bind ?? '127.0.0.1';
                 const authToken = options.authToken ?? process.env.SWITCHBOT_MCP_TOKEN;
@@ -785,14 +799,7 @@ Inspect locally:
                 // Guard: refuse to bind non-localhost without auth
                 const isLocalhost = bind === '127.0.0.1' || bind === 'localhost' || bind === '::1';
                 if (!isLocalhost && !authToken) {
-                    const msg = 'Refusing to listen on 0.0.0.0 without --auth-token. Pass --auth-token <token> or bind to localhost (default).';
-                    if (isJsonMode()) {
-                        emitJsonError({ code: 2, kind: 'usage', message: msg });
-                    }
-                    else {
-                        console.error(msg);
-                    }
-                    process.exit(2);
+                    exitWithError('Refusing to listen on 0.0.0.0 without --auth-token. Pass --auth-token <token> or bind to localhost (default).');
                 }
                 const { createServer } = await import('node:http');
                 const rateLimitMap = new Map();
@@ -1011,6 +1018,29 @@ process_uptime_seconds ${Math.floor(process.uptime())}
             const server = createSwitchBotMcpServer({ eventManager });
             const transport = new StdioServerTransport();
             await server.connect(transport);
+            let isShuttingDown = false;
+            const gracefulShutdown = async () => {
+                if (isShuttingDown)
+                    return;
+                isShuttingDown = true;
+                console.error('Shutting down...');
+                // Force exit after 30s if shutdown hangs (e.g. stuck MQTT disconnect).
+                const forceExit = setTimeout(() => {
+                    console.error('Force exiting after 30s timeout');
+                    process.exit(1);
+                }, 30000);
+                forceExit.unref();
+                try {
+                    await eventManager.shutdown();
+                }
+                catch (err) {
+                    console.error('Error during shutdown:', err instanceof Error ? err.message : String(err));
+                }
+                process.exit(0);
+            };
+            process.on('SIGTERM', gracefulShutdown);
+            process.on('SIGINT', gracefulShutdown);
+            process.stdin.on('end', gracefulShutdown);
         }
         catch (error) {
             handleError(error);

package/dist/config.js

@@ -3,6 +3,7 @@ import path from 'node:path';
 import os from 'node:os';
 import { getConfigPath } from './utils/flags.js';
 import { getActiveProfile } from './lib/request-context.js';
+import { emitJsonError, isJsonMode } from './utils/output.js';
 function sanitizeOptionalString(v) {
     if (typeof v !== 'string')
         return undefined;
@@ -51,20 +52,36 @@ export function loadConfig() {
         const hint = profile
             ? `No credentials configured for profile "${profile}". Run: switchbot --profile ${profile} config set-token <token> <secret>`
             : 'No credentials configured. Run: switchbot config set-token <token> <secret>';
-        console.error(`${hint}\nOr set SWITCHBOT_TOKEN and SWITCHBOT_SECRET environment variables.`);
+        const msg = `${hint}\nOr set SWITCHBOT_TOKEN and SWITCHBOT_SECRET environment variables.`;
+        if (isJsonMode()) {
+            emitJsonError({ code: 1, kind: 'runtime', message: hint });
+        }
+        else {
+            console.error(msg);
+        }
         process.exit(1);
     }
     try {
         const raw = fs.readFileSync(file, 'utf-8');
         const cfg = JSON.parse(raw);
         if (!cfg.token || !cfg.secret) {
-            console.error('Invalid config format. Please re-run: switchbot config set-token');
+            if (isJsonMode()) {
+                emitJsonError({ code: 1, kind: 'runtime', message: 'Invalid config format. Please re-run: switchbot config set-token' });
+            }
+            else {
+                console.error('Invalid config format. Please re-run: switchbot config set-token');
+            }
             process.exit(1);
         }
         return cfg;
     }
     catch {
-        console.error('Failed to read config file. Please re-run: switchbot config set-token');
+        if (isJsonMode()) {
+            emitJsonError({ code: 1, kind: 'runtime', message: 'Failed to read config file. Please re-run: switchbot config set-token' });
+        }
+        else {
+            console.error('Failed to read config file. Please re-run: switchbot config set-token');
+        }
         process.exit(1);
     }
 }
@@ -156,36 +173,63 @@ export function readProfileMeta(profile) {
     }
 }
 export function showConfig() {
+    const summary = getConfigSummary();
+    if (summary.source === 'env') {
+        console.log('Credential source: environment variables');
+        console.log(`token : ${summary.token ?? ''}`);
+        console.log(`secret: ${summary.secret ?? ''}`);
+        return;
+    }
+    if (summary.source === 'none') {
+        console.log('No credentials configured');
+        return;
+    }
+    if (summary.source === 'invalid') {
+        console.error('Failed to read config file');
+        return;
+    }
+    console.log(`Credential source: ${summary.path}`);
+    if (summary.label)
+        console.log(`label : ${summary.label}`);
+    if (summary.description)
+        console.log(`desc  : ${summary.description}`);
+    console.log(`token : ${summary.token ?? ''}`);
+    console.log(`secret: ${summary.secret ?? ''}`);
+    if (summary.dailyCap)
+        console.log(`limits: dailyCap=${summary.dailyCap}`);
+    if (summary.defaultFlags?.length)
+        console.log(`defaults: ${summary.defaultFlags.join(' ')}`);
+}
+export function getConfigSummary() {
     const envToken = process.env.SWITCHBOT_TOKEN;
     const envSecret = process.env.SWITCHBOT_SECRET;
     if (envToken && envSecret) {
-        console.log('Credential source: environment variables');
-        console.log(`token : ${maskCredential(envToken)}`);
-        console.log(`secret: ${maskSecret(envSecret)}`);
-        return;
+        return {
+            source: 'env',
+            token: maskCredential(envToken),
+            secret: maskSecret(envSecret),
+        };
     }
     const file = configFilePath();
     if (!fs.existsSync(file)) {
-        console.log('No credentials configured');
-        return;
+        return { source: 'none' };
     }
     try {
         const raw = fs.readFileSync(file, 'utf-8');
         const cfg = JSON.parse(raw);
-        console.log(`Credential source: ${file}`);
-        if (cfg.label)
-            console.log(`label : ${cfg.label}`);
-        if (cfg.description)
-            console.log(`desc  : ${cfg.description}`);
-        console.log(`token : ${maskCredential(cfg.token)}`);
-        console.log(`secret: ${maskSecret(cfg.secret)}`);
-        if (cfg.limits?.dailyCap)
-            console.log(`limits: dailyCap=${cfg.limits.dailyCap}`);
-        if (cfg.defaults?.flags?.length)
-            console.log(`defaults: ${cfg.defaults.flags.join(' ')}`);
+        return {
+            source: 'file',
+            path: file,
+            label: cfg.label,
+            description: cfg.description,
+            token: maskCredential(cfg.token),
+            secret: maskSecret(cfg.secret),
+            dailyCap: cfg.limits?.dailyCap,
+            defaultFlags: cfg.defaults?.flags,
+        };
     }
     catch {
-        console.error('Failed to read config file');
+        return { source: 'invalid', path: file };
     }
 }
 function maskCredential(token) {

package/dist/devices/catalog.js

@@ -219,7 +219,7 @@ export const DEVICE_CATALOG = [
         category: 'physical',
         description: 'Entry-level robot vacuum with start/stop/dock and four suction power levels.',
         role: 'cleaning',
-        aliases: ['Robot Vacuum Cleaner S1 Plus', 'K10+'],
+        aliases: ['Robot Vacuum', 'Robot Vacuum Cleaner S1 Plus', 'K10+'],
         commands: [
             { command: 'start', parameter: '—', description: 'Start cleaning', idempotent: true },
             { command: 'stop', parameter: '—', description: 'Stop cleaning', idempotent: true },

package/dist/index.js

@@ -4,6 +4,7 @@ import { createRequire } from 'node:module';
 import chalk from 'chalk';
 import { intArg, stringArg, enumArg } from './utils/arg-parsers.js';
 import { parseDurationToMs } from './utils/flags.js';
+import { emitJsonError, isJsonMode } from './utils/output.js';
 import { registerConfigCommand } from './commands/config.js';
 import { registerDevicesCommand } from './commands/devices.js';
 import { registerScenesCommand } from './commands/scenes.js';
@@ -28,6 +29,11 @@ if (process.argv.includes('--no-color') || Boolean(process.env.NO_COLOR)) {
     chalk.level = 0;
 }
 const program = new Command();
+if (isJsonMode()) {
+    // In --json mode, commander writes plain-text usage errors by default.
+    // Silence that channel and emit a single structured error in the catch block.
+    program.configureOutput({ writeErr: () => { } });
+}
 // Top-level subcommand names. Used by stringArg to produce clearer errors when
 // a value is omitted and the next argv token turns out to be a subcommand name.
 const TOP_LEVEL_COMMANDS = [
@@ -130,10 +136,7 @@ Docs: https://github.com/OpenWonderLabs/SwitchBotAPI
 // per-command: subcommand errors won't bubble to the root override, so walk
 // every registered command and apply the same handler.
 const usageExitHandler = (err) => {
-    if (err.code === 'commander.helpDisplayed' || err.code === 'commander.version') {
-        process.exit(0);
-    }
-    process.exit(2);
+    throw err;
 };
 function applyExitOverride(cmd) {
     cmd.exitOverride(usageExitHandler);
@@ -158,6 +161,9 @@ catch (err) {
         if (err.code === 'commander.helpDisplayed' || err.code === 'commander.version') {
             process.exit(0);
         }
+        if (isJsonMode()) {
+            emitJsonError({ code: 2, kind: 'usage', message: err.message });
+        }
         process.exit(2);
     }
     throw err;

package/dist/lib/devices.js

@@ -151,8 +151,12 @@ export function validateCommand(deviceId, cmd, parameter, commandType) {
     if (!match || Array.isArray(match))
         return { ok: true };
     const builtinCommands = match.commands.filter((c) => c.commandType !== 'customize');
-    if (builtinCommands.length === 0)
-        return { ok: true };
+    if (match.readOnly || builtinCommands.length === 0) {
+        return {
+            ok: false,
+            error: new CommandValidationError(`${cached.name} (${cached.type}) is a read-only sensor — it has no control commands.`, 'read-only-device', `Use 'switchbot devices status ${deviceId}' to read this device instead.`),
+        };
+    }
     let spec = builtinCommands.find((c) => c.command === cmd);
     let caseNormalizedFrom;
     let normalizedCmd = cmd;

package/dist/schema/field-aliases.js

@@ -0,0 +1,36 @@
+import { UsageError } from '../utils/output.js';
+export const FIELD_ALIASES = {
+    deviceId: ['id'],
+    deviceName: ['name'],
+    deviceType: ['type'],
+    controlType: ['control'],
+    roomName: ['room'],
+    roomID: ['roomid'],
+    familyName: ['family'],
+    hubDeviceId: ['hub'],
+    enableCloudService: ['cloud'],
+    alias: ['alias'],
+};
+export function resolveField(input, allowedCanonical) {
+    const normalized = input.trim().toLowerCase();
+    if (!normalized) {
+        throw new UsageError('Field name cannot be empty.');
+    }
+    for (const canonical of allowedCanonical) {
+        if (canonical.toLowerCase() === normalized)
+            return canonical;
+        const aliases = FIELD_ALIASES[canonical] ?? [];
+        if (aliases.some((a) => a.toLowerCase() === normalized))
+            return canonical;
+    }
+    throw new UsageError(`Unknown field "${input}". Supported: ${listSupportedFieldInputs(allowedCanonical).join(', ')}`);
+}
+export function listSupportedFieldInputs(allowedCanonical) {
+    const out = new Set();
+    for (const canonical of allowedCanonical) {
+        out.add(canonical);
+        for (const alias of FIELD_ALIASES[canonical] ?? [])
+            out.add(alias);
+    }
+    return [...out];
+}

package/dist/utils/filter.js

@@ -20,7 +20,7 @@ export class FilterSyntaxError extends Error {
  * {type,name,category,room}; `devices batch` uses {type,family,room,category};
  * `events tail` uses {deviceId,type}.
  */
-export function parseFilterExpr(expr, allowedKeys) {
+export function parseFilterExpr(expr, allowedKeys, options) {
     if (!expr)
         return [];
     const parts = expr.split(',').map((p) => p.trim()).filter((p) => p.length > 0);
@@ -72,10 +72,23 @@ export function parseFilterExpr(expr, allowedKeys) {
         if (!raw) {
             throw new FilterSyntaxError(`Empty value for filter clause "${part}"`);
         }
-        if (!allowedKeys.includes(key)) {
-            throw new FilterSyntaxError(`Unknown filter key "${key}" — supported: ${allowedKeys.join(', ')}`);
+        let resolvedKey = key;
+        if (options?.resolveKey) {
+            try {
+                resolvedKey = options.resolveKey(key);
+            }
+            catch (err) {
+                if (err instanceof Error) {
+                    throw new FilterSyntaxError(err.message);
+                }
+                throw err;
+            }
+        }
+        if (!allowedKeys.includes(resolvedKey)) {
+            const printableKeys = options?.supportedKeys ?? allowedKeys;
+            throw new FilterSyntaxError(`Unknown filter key "${key}" – supported: ${printableKeys.join(', ')}`);
         }
-        clauses.push({ key, op, raw, regex });
+        clauses.push({ key: resolvedKey, op, raw, regex });
     }
     return clauses;
 }

package/dist/utils/output.js

@@ -28,6 +28,26 @@ export function emitJsonError(errorPayload) {
         console.error(chalk.red(msg));
     }
 }
+export function exitWithError(messageOrOpts) {
+    const opts = typeof messageOrOpts === 'string' ? { message: messageOrOpts } : messageOrOpts;
+    const { message, kind = 'usage', code = 2, hint, context, extra } = opts;
+    if (isJsonMode()) {
+        const payload = { code, kind, message };
+        if (hint)
+            payload.hint = hint;
+        if (context)
+            payload.context = context;
+        if (extra)
+            Object.assign(payload, extra);
+        emitJsonError(payload);
+    }
+    else {
+        console.error(message);
+        if (hint)
+            console.error(hint);
+    }
+    process.exit(code);
+}
 function escapeMarkdownCell(s) {
     // Pipes break markdown table layout; backslash-escape them. Collapse
     // newlines into <br> so each row stays on one line.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@switchbot/openapi-cli",
-  "version": "2.6.2",
+  "version": "2.6.4",
   "description": "SwitchBot smart home CLI — control devices, run scenes, stream real-time events, and integrate AI agents via MCP. Full API v1.1 coverage.",
   "keywords": [
     "switchbot",