@switchbot/openapi-cli 2.2.1 → 2.3.0

package/README.md

@@ -278,6 +278,8 @@ Generic parameter shapes (which one applies is decided by the device — see the
 | `<json object>`     | `'{"action":"sweep","param":{"fanLevel":2,"times":1}}'`  |
 | Custom IR button    | `devices command <id> MyButton --type customize`         |
 
+Parameters for `setAll` (Air Conditioner), `setPosition` (Curtain / Blind Tilt), and `setMode` (Relay Switch) are validated client-side before the request — malformed shapes, out-of-range values, and JSON for CSV fields all fail fast with exit 2. 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.
+
 For the complete per-device command reference, see the [SwitchBot API docs](https://github.com/OpenWonderLabs/SwitchBotAPI#send-device-control-commands).
 
 #### `devices expand` — named flags for packed parameters

package/dist/commands/devices.js

@@ -6,6 +6,7 @@ import { getCachedDevice } from '../devices/cache.js';
 import { loadDeviceMeta } from '../devices/device-meta.js';
 import { resolveDeviceId } from '../utils/name-resolver.js';
 import { fetchDeviceList, fetchDeviceStatus, executeCommand, describeDevice, validateCommand, isDestructiveCommand, getDestructiveReason, buildHubLocationMap, DeviceNotFoundError, } from '../lib/devices.js';
+import { validateParameter } from '../devices/param-validator.js';
 import { registerBatchCommand } from './batch.js';
 import { registerWatchCommand } from './watch.js';
 import { registerExplainCommand } from './explain.js';
@@ -341,19 +342,22 @@ Examples:
 `)
         .action(async (deviceIdArg, cmdArg, parameter, options) => {
         try {
-            // BUG-FIX: When --name is provided, Commander misassigns the first positional
-            // to [deviceId] instead of [cmd]. Detect and shift positionals accordingly.
+            // BUG-FIX: When --name is provided, Commander fills positionals left-to-right
+            // starting at [deviceId]. Shift them back to their semantic slots.
             let cmd;
             let effectiveDeviceIdArg;
             if (options.name) {
-                if (deviceIdArg && cmdArg) {
-                    throw new UsageError('Provide either a deviceId argument or --name, not both.');
-                }
-                if (!deviceIdArg && !cmdArg) {
+                // `--name "x" <cmd> [parameter]` → Commander binds deviceIdArg=<cmd>, cmdArg=[parameter].
+                if (!deviceIdArg) {
                     throw new UsageError('Command name is required (e.g. turnOn, turnOff, setAll).');
                 }
-                // --name "x" turnOn  →  deviceIdArg="turnOn", cmdArg=undefined → shift
-                cmd = (deviceIdArg ?? cmdArg);
+                cmd = deviceIdArg;
+                if (cmdArg !== undefined) {
+                    if (parameter !== undefined) {
+                        throw new UsageError('Too many positional arguments after --name. Expected: --name <query> <cmd> [parameter].');
+                    }
+                    parameter = cmdArg;
+                }
                 effectiveDeviceIdArg = undefined;
             }
             else {
@@ -391,6 +395,37 @@ Examples:
                 }
                 process.exit(2);
             }
+            // Case-only mismatch: emit a warning and continue with the canonical name.
+            if (validation.caseNormalizedFrom && validation.normalized) {
+                console.error(`Note: '${validation.caseNormalizedFrom}' normalized to '${validation.normalized}' (case mismatch). Use exact casing to silence this warning.`);
+                cmd = validation.normalized;
+            }
+            else if (validation.normalized) {
+                cmd = validation.normalized;
+            }
+            // Raw-parameter validation (runs for known (deviceType, command) pairs only).
+            const cachedForParam = getCachedDevice(deviceId);
+            if (cachedForParam && options.type === 'command') {
+                const paramCheck = validateParameter(cachedForParam.type, cmd, parameter);
+                if (!paramCheck.ok) {
+                    if (isJsonMode()) {
+                        console.error(JSON.stringify({
+                            error: {
+                                code: 2,
+                                kind: 'usage',
+                                message: paramCheck.error,
+                                context: { command: cmd, deviceType: cachedForParam.type, deviceId },
+                            },
+                        }));
+                    }
+                    else {
+                        console.error(`Error: ${paramCheck.error}`);
+                    }
+                    process.exit(2);
+                }
+                if (paramCheck.normalized !== undefined)
+                    parameter = paramCheck.normalized;
+            }
             const cachedForGuard = getCachedDevice(deviceId);
             if (!options.yes &&
                 !isDryRun() &&

package/dist/commands/expand.js

@@ -5,83 +5,7 @@ import { executeCommand, isDestructiveCommand, getDestructiveReason } from '../l
 import { isDryRun } from '../utils/flags.js';
 import { resolveDeviceId } from '../utils/name-resolver.js';
 import { DryRunSignal } from '../api/client.js';
-// ---- Mapping tables --------------------------------------------------------
-const AC_MODE_MAP = { auto: 1, cool: 2, dry: 3, fan: 4, heat: 5 };
-const AC_FAN_MAP = { auto: 1, low: 2, mid: 3, high: 4 };
-const CURTAIN_MODE_MAP = { default: 'ff', performance: '0', silent: '1' };
-const RELAY_MODE_MAP = { toggle: 0, edge: 1, detached: 2, momentary: 3 };
-const BLIND_DIRECTION = new Set(['up', 'down']);
-// ---- Translators -----------------------------------------------------------
-function buildAcSetAll(opts) {
-    if (!opts.temp)
-        throw new UsageError('--temp is required for setAll (e.g. --temp 26)');
-    if (!opts.mode)
-        throw new UsageError('--mode is required for setAll (auto|cool|dry|fan|heat)');
-    if (!opts.fan)
-        throw new UsageError('--fan is required for setAll (auto|low|mid|high)');
-    if (!opts.power)
-        throw new UsageError('--power is required for setAll (on|off)');
-    const temp = parseInt(opts.temp, 10);
-    if (!Number.isFinite(temp) || temp < 16 || temp > 30) {
-        throw new UsageError(`--temp must be an integer between 16 and 30 (got "${opts.temp}")`);
-    }
-    const modeInt = AC_MODE_MAP[opts.mode.toLowerCase()];
-    if (modeInt === undefined) {
-        throw new UsageError(`--mode must be one of: auto, cool, dry, fan, heat (got "${opts.mode}")`);
-    }
-    const fanInt = AC_FAN_MAP[opts.fan.toLowerCase()];
-    if (fanInt === undefined) {
-        throw new UsageError(`--fan must be one of: auto, low, mid, high (got "${opts.fan}")`);
-    }
-    const power = opts.power.toLowerCase();
-    if (power !== 'on' && power !== 'off') {
-        throw new UsageError(`--power must be "on" or "off" (got "${opts.power}")`);
-    }
-    return `${temp},${modeInt},${fanInt},${power}`;
-}
-function buildCurtainSetPosition(opts) {
-    if (!opts.position)
-        throw new UsageError('--position is required (0-100)');
-    const pos = parseInt(opts.position, 10);
-    if (!Number.isFinite(pos) || pos < 0 || pos > 100) {
-        throw new UsageError(`--position must be an integer between 0 and 100 (got "${opts.position}")`);
-    }
-    const modeStr = opts.mode ? CURTAIN_MODE_MAP[opts.mode.toLowerCase()] : 'ff';
-    if (modeStr === undefined) {
-        throw new UsageError(`--mode must be one of: default, performance, silent (got "${opts.mode}")`);
-    }
-    return `0,${modeStr},${pos}`;
-}
-function buildBlindTiltSetPosition(opts) {
-    if (!opts.direction)
-        throw new UsageError('--direction is required (up|down)');
-    if (!opts.angle)
-        throw new UsageError('--angle is required (0-100)');
-    const dir = opts.direction.toLowerCase();
-    if (!BLIND_DIRECTION.has(dir)) {
-        throw new UsageError(`--direction must be "up" or "down" (got "${opts.direction}")`);
-    }
-    const angle = parseInt(opts.angle, 10);
-    if (!Number.isFinite(angle) || angle < 0 || angle > 100) {
-        throw new UsageError(`--angle must be an integer between 0 and 100 (got "${opts.angle}")`);
-    }
-    return `${dir};${angle}`;
-}
-function buildRelaySetMode(opts) {
-    if (!opts.channel)
-        throw new UsageError('--channel is required (1 or 2)');
-    if (!opts.mode)
-        throw new UsageError('--mode is required (toggle|edge|detached|momentary)');
-    const ch = parseInt(opts.channel, 10);
-    if (ch !== 1 && ch !== 2) {
-        throw new UsageError(`--channel must be 1 or 2 (got "${opts.channel}")`);
-    }
-    const modeInt = RELAY_MODE_MAP[opts.mode.toLowerCase()];
-    if (modeInt === undefined) {
-        throw new UsageError(`--mode must be one of: toggle, edge, detached, momentary (got "${opts.mode}")`);
-    }
-    return `${ch};${modeInt}`;
-}
+import { buildAcSetAll, buildCurtainSetPosition, buildBlindTiltSetPosition, buildRelaySetMode, } from '../devices/param-validator.js';
 // ---- Registration ----------------------------------------------------------
 export function registerExpandCommand(devices) {
     devices

package/dist/devices/param-validator.js

@@ -0,0 +1,263 @@
+import { UsageError } from '../utils/output.js';
+export const AC_MODE_MAP = { auto: 1, cool: 2, dry: 3, fan: 4, heat: 5 };
+export const AC_FAN_MAP = { auto: 1, low: 2, mid: 3, high: 4 };
+export const CURTAIN_MODE_MAP = { default: 'ff', performance: '0', silent: '1' };
+export const RELAY_MODE_MAP = { toggle: 0, edge: 1, detached: 2, momentary: 3 };
+const BLIND_DIRECTION = new Set(['up', 'down']);
+// ---- Semantic-flag builders (used by `devices expand`) --------------------
+export function buildAcSetAll(opts) {
+    if (!opts.temp)
+        throw new UsageError('--temp is required for setAll (e.g. --temp 26)');
+    if (!opts.mode)
+        throw new UsageError('--mode is required for setAll (auto|cool|dry|fan|heat)');
+    if (!opts.fan)
+        throw new UsageError('--fan is required for setAll (auto|low|mid|high)');
+    if (!opts.power)
+        throw new UsageError('--power is required for setAll (on|off)');
+    const temp = parseInt(opts.temp, 10);
+    if (!Number.isFinite(temp) || temp < 16 || temp > 30) {
+        throw new UsageError(`--temp must be an integer between 16 and 30 (got "${opts.temp}")`);
+    }
+    const modeInt = AC_MODE_MAP[opts.mode.toLowerCase()];
+    if (modeInt === undefined) {
+        throw new UsageError(`--mode must be one of: auto, cool, dry, fan, heat (got "${opts.mode}")`);
+    }
+    const fanInt = AC_FAN_MAP[opts.fan.toLowerCase()];
+    if (fanInt === undefined) {
+        throw new UsageError(`--fan must be one of: auto, low, mid, high (got "${opts.fan}")`);
+    }
+    const power = opts.power.toLowerCase();
+    if (power !== 'on' && power !== 'off') {
+        throw new UsageError(`--power must be "on" or "off" (got "${opts.power}")`);
+    }
+    return `${temp},${modeInt},${fanInt},${power}`;
+}
+export function buildCurtainSetPosition(opts) {
+    if (!opts.position)
+        throw new UsageError('--position is required (0-100)');
+    const pos = parseInt(opts.position, 10);
+    if (!Number.isFinite(pos) || pos < 0 || pos > 100) {
+        throw new UsageError(`--position must be an integer between 0 and 100 (got "${opts.position}")`);
+    }
+    const modeStr = opts.mode ? CURTAIN_MODE_MAP[opts.mode.toLowerCase()] : 'ff';
+    if (modeStr === undefined) {
+        throw new UsageError(`--mode must be one of: default, performance, silent (got "${opts.mode}")`);
+    }
+    return `0,${modeStr},${pos}`;
+}
+export function buildBlindTiltSetPosition(opts) {
+    if (!opts.direction)
+        throw new UsageError('--direction is required (up|down)');
+    if (!opts.angle)
+        throw new UsageError('--angle is required (0-100)');
+    const dir = opts.direction.toLowerCase();
+    if (!BLIND_DIRECTION.has(dir)) {
+        throw new UsageError(`--direction must be "up" or "down" (got "${opts.direction}")`);
+    }
+    const angle = parseInt(opts.angle, 10);
+    if (!Number.isFinite(angle) || angle < 0 || angle > 100) {
+        throw new UsageError(`--angle must be an integer between 0 and 100 (got "${opts.angle}")`);
+    }
+    return `${dir};${angle}`;
+}
+export function buildRelaySetMode(opts) {
+    if (!opts.channel)
+        throw new UsageError('--channel is required (1 or 2)');
+    if (!opts.mode)
+        throw new UsageError('--mode is required (toggle|edge|detached|momentary)');
+    const ch = parseInt(opts.channel, 10);
+    if (ch !== 1 && ch !== 2) {
+        throw new UsageError(`--channel must be 1 or 2 (got "${opts.channel}")`);
+    }
+    const modeInt = RELAY_MODE_MAP[opts.mode.toLowerCase()];
+    if (modeInt === undefined) {
+        throw new UsageError(`--mode must be one of: toggle, edge, detached, momentary (got "${opts.mode}")`);
+    }
+    return `${ch};${modeInt}`;
+}
+/**
+ * Validate a raw wire-format parameter string for (deviceType, command)
+ * combos where the shape is well-defined. Unknown combos pass through so
+ * `devices command` remains a usable escape hatch for types/commands the
+ * CLI hasn't modelled yet.
+ *
+ * On passthrough, `normalized` is left undefined so the caller keeps the
+ * original parameter value (preserving the `undefined → "default"` default
+ * for no-arg commands).
+ */
+export function validateParameter(deviceType, command, raw) {
+    if (!deviceType)
+        return { ok: true };
+    if (deviceType === 'Air Conditioner' && command === 'setAll') {
+        return validateAcSetAll(raw);
+    }
+    if (deviceType.startsWith('Curtain') && command === 'setPosition') {
+        return validateCurtainSetPosition(raw);
+    }
+    if (deviceType.startsWith('Blind Tilt') && command === 'setPosition') {
+        return validateBlindTiltSetPosition(raw);
+    }
+    if (deviceType.startsWith('Relay Switch') && command === 'setMode') {
+        return validateRelaySetMode(raw);
+    }
+    return { ok: true };
+}
+function validateAcSetAll(raw) {
+    if (raw === undefined || raw === '' || raw === 'default') {
+        return {
+            ok: false,
+            error: `setAll requires a parameter "<temp>,<mode>,<fan>,<on|off>". Example: "26,2,2,on".`,
+        };
+    }
+    if (raw.startsWith('{') || raw.startsWith('[')) {
+        return {
+            ok: false,
+            error: `setAll parameter must be a CSV string like "26,2,2,on", not JSON (got ${JSON.stringify(raw)}).`,
+        };
+    }
+    const parts = raw.split(',');
+    if (parts.length !== 4) {
+        return {
+            ok: false,
+            error: `setAll expects 4 comma-separated fields "<temp>,<mode>,<fan>,<on|off>", got ${parts.length} (${JSON.stringify(raw)}). Example: "26,2,2,on".`,
+        };
+    }
+    const [tempStr, modeStr, fanStr, powerStr] = parts.map((s) => s.trim());
+    const temp = Number(tempStr);
+    if (!Number.isInteger(temp) || temp < 16 || temp > 30) {
+        return {
+            ok: false,
+            error: `setAll field 1 (temp) must be an integer 16-30, got "${tempStr}". Example: "26,2,2,on".`,
+        };
+    }
+    const mode = Number(modeStr);
+    if (!Number.isInteger(mode) || mode < 1 || mode > 5) {
+        return {
+            ok: false,
+            error: `setAll field 2 (mode) must be 1-5 (1=auto 2=cool 3=dry 4=fan 5=heat), got "${modeStr}". Example: "26,2,2,on".`,
+        };
+    }
+    const fan = Number(fanStr);
+    if (!Number.isInteger(fan) || fan < 1 || fan > 4) {
+        return {
+            ok: false,
+            error: `setAll field 3 (fan) must be 1-4 (1=auto 2=low 3=mid 4=high), got "${fanStr}". Example: "26,2,2,on".`,
+        };
+    }
+    const power = powerStr.toLowerCase();
+    if (power !== 'on' && power !== 'off') {
+        return {
+            ok: false,
+            error: `setAll field 4 (power) must be "on" or "off", got "${powerStr}". Example: "26,2,2,on".`,
+        };
+    }
+    return { ok: true, normalized: `${temp},${mode},${fan},${power}` };
+}
+function validateCurtainSetPosition(raw) {
+    if (raw === undefined || raw === '' || raw === 'default') {
+        return {
+            ok: false,
+            error: `setPosition requires a parameter. Expected: "<0-100>" or "<index>,<ff|0|1>,<0-100>". Example: "50" or "0,ff,50".`,
+        };
+    }
+    if (!raw.includes(',')) {
+        const pos = Number(raw);
+        if (!Number.isInteger(pos) || pos < 0 || pos > 100) {
+            return {
+                ok: false,
+                error: `setPosition must be an integer 0-100, got "${raw}". Example: "50".`,
+            };
+        }
+        return { ok: true, normalized: String(pos) };
+    }
+    const parts = raw.split(',').map((s) => s.trim());
+    if (parts.length !== 3) {
+        return {
+            ok: false,
+            error: `setPosition tuple form expects 3 comma-separated fields "<index>,<ff|0|1>,<0-100>", got ${parts.length} (${JSON.stringify(raw)}).`,
+        };
+    }
+    const [idxStr, modeStr, posStr] = parts;
+    const idx = Number(idxStr);
+    if (!Number.isInteger(idx) || idx < 0) {
+        return {
+            ok: false,
+            error: `setPosition field 1 (index) must be a non-negative integer, got "${idxStr}".`,
+        };
+    }
+    const modeLower = modeStr.toLowerCase();
+    if (!['ff', '0', '1'].includes(modeLower)) {
+        return {
+            ok: false,
+            error: `setPosition field 2 (mode) must be "ff", "0", or "1", got "${modeStr}". (ff=default, 0=performance, 1=silent)`,
+        };
+    }
+    const pos = Number(posStr);
+    if (!Number.isInteger(pos) || pos < 0 || pos > 100) {
+        return {
+            ok: false,
+            error: `setPosition field 3 (position) must be an integer 0-100, got "${posStr}".`,
+        };
+    }
+    return { ok: true, normalized: `${idx},${modeLower},${pos}` };
+}
+function validateBlindTiltSetPosition(raw) {
+    if (raw === undefined || raw === '' || raw === 'default') {
+        return {
+            ok: false,
+            error: `Blind Tilt setPosition requires a parameter. Expected: "<up|down>;<0-100>". Example: "up;50".`,
+        };
+    }
+    const parts = raw.split(';');
+    if (parts.length !== 2) {
+        return {
+            ok: false,
+            error: `Blind Tilt setPosition expects "<up|down>;<angle>", got ${JSON.stringify(raw)}. Example: "up;50".`,
+        };
+    }
+    const dir = parts[0].toLowerCase();
+    if (!BLIND_DIRECTION.has(dir)) {
+        return {
+            ok: false,
+            error: `Blind Tilt setPosition direction must be "up" or "down", got "${parts[0]}".`,
+        };
+    }
+    const angle = Number(parts[1]);
+    if (!Number.isInteger(angle) || angle < 0 || angle > 100) {
+        return {
+            ok: false,
+            error: `Blind Tilt setPosition angle must be an integer 0-100, got "${parts[1]}".`,
+        };
+    }
+    return { ok: true, normalized: `${dir};${angle}` };
+}
+function validateRelaySetMode(raw) {
+    if (raw === undefined || raw === '' || raw === 'default') {
+        return {
+            ok: false,
+            error: `Relay Switch setMode requires a parameter. Expected: "<1|2>;<0|1|2|3>". Example: "1;1" (channel 1, edge mode).`,
+        };
+    }
+    const parts = raw.split(';');
+    if (parts.length !== 2) {
+        return {
+            ok: false,
+            error: `Relay Switch setMode expects "<channel>;<mode>", got ${JSON.stringify(raw)}. Example: "1;1".`,
+        };
+    }
+    const ch = Number(parts[0]);
+    if (ch !== 1 && ch !== 2) {
+        return {
+            ok: false,
+            error: `Relay Switch setMode channel must be 1 or 2, got "${parts[0]}".`,
+        };
+    }
+    const mode = Number(parts[1]);
+    if (!Number.isInteger(mode) || mode < 0 || mode > 3) {
+        return {
+            ok: false,
+            error: `Relay Switch setMode mode must be 0-3 (0=toggle 1=edge 2=detached 3=momentary), got "${parts[1]}".`,
+        };
+    }
+    return { ok: true, normalized: `${ch};${mode}` };
+}

package/dist/lib/devices.js

@@ -129,8 +129,10 @@ export async function executeCommand(deviceId, cmd, parameter, commandType, clie
 /**
  * Validate a command against the locally-cached device → catalog mapping.
  * Returns `{ ok: true }` when validation passes or is skipped (unknown device,
- * custom IR button, etc.); returns `{ ok: false, error }` when the caller
- * should refuse the call.
+ * custom IR button, etc.). On a case-only mismatch the canonical command name
+ * is returned via `normalized` along with a `caseNormalizedFrom` field so the
+ * caller can emit a warning and continue with the canonical name.
+ * Returns `{ ok: false, error }` only when the caller should refuse the call.
  */
 export function validateCommand(deviceId, cmd, parameter, commandType) {
     if (commandType === 'customize')
@@ -144,24 +146,34 @@ export function validateCommand(deviceId, cmd, parameter, commandType) {
     const builtinCommands = match.commands.filter((c) => c.commandType !== 'customize');
     if (builtinCommands.length === 0)
         return { ok: true };
-    const spec = builtinCommands.find((c) => c.command === cmd);
+    let spec = builtinCommands.find((c) => c.command === cmd);
+    let caseNormalizedFrom;
+    let normalizedCmd = cmd;
     if (!spec) {
         const unique = [...new Set(builtinCommands.map((c) => c.command))];
         const caseMatch = unique.find((c) => c.toLowerCase() === cmd.toLowerCase());
-        const hint = caseMatch
-            ? `Did you mean "${caseMatch}"? Supported commands: ${unique.join(', ')}`
-            : `Supported commands: ${unique.join(', ')}`;
-        return {
-            ok: false,
-            error: new CommandValidationError(`"${cmd}" is not a supported command for ${cached.name} (${cached.type}).`, 'unknown-command', hint),
-        };
+        if (caseMatch) {
+            // Case-only mismatch: normalize and continue.
+            caseNormalizedFrom = cmd;
+            normalizedCmd = caseMatch;
+            spec = builtinCommands.find((c) => c.command === caseMatch);
+        }
+        else {
+            const hint = `Supported commands: ${unique.join(', ')}`;
+            return {
+                ok: false,
+                error: new CommandValidationError(`"${cmd}" is not a supported command for ${cached.name} (${cached.type}).`, 'unknown-command', hint),
+            };
+        }
     }
+    if (!spec)
+        return { ok: true, normalized: normalizedCmd, caseNormalizedFrom };
     const noParamExpected = spec.parameter === '—';
     const userProvidedParam = parameter !== undefined && parameter !== 'default';
     if (noParamExpected && userProvidedParam) {
         return {
             ok: false,
-            error: new CommandValidationError(`"${cmd}" takes no parameter, but one was provided: "${parameter}".`, 'unexpected-parameter', `Try: switchbot devices command ${deviceId} ${cmd}`),
+            error: new CommandValidationError(`"${normalizedCmd}" takes no parameter, but one was provided: "${parameter}".`, 'unexpected-parameter', `Try: switchbot devices command ${deviceId} ${normalizedCmd}`),
         };
     }
     // Warn when a parameter is required but the user omitted it
@@ -170,12 +182,12 @@ export function validateCommand(deviceId, cmd, parameter, commandType) {
         const example = spec.exampleParams?.[0];
         return {
             ok: false,
-            error: new CommandValidationError(`"${cmd}" requires a parameter (${spec.parameter}).`, 'missing-parameter', example
-                ? `Example: switchbot devices command <deviceId> ${cmd} "${example}"`
+            error: new CommandValidationError(`"${normalizedCmd}" requires a parameter (${spec.parameter}).`, 'missing-parameter', example
+                ? `Example: switchbot devices command <deviceId> ${normalizedCmd} "${example}"`
                 : `See: switchbot devices commands ${cached.type}`),
         };
     }
-    return { ok: true };
+    return { ok: true, normalized: normalizedCmd, caseNormalizedFrom };
 }
 /**
  * Inspect catalog annotations to decide whether a command is destructive,

package/dist/utils/arg-parsers.js

@@ -9,7 +9,10 @@ import { parseDurationToMs } from './flags.js';
  */
 export function intArg(flagName, opts) {
     return (value) => {
-        if (value.startsWith('-')) {
+        // Flag-like tokens (`--something`, `-x`) are rejected up-front.
+        // Pure negative integers (`-1`, `-42`) fall through to min/max so the
+        // error classifies as a range error rather than "requires a numeric value".
+        if (value.startsWith('-') && !/^-\d+$/.test(value)) {
             throw new InvalidArgumentError(`${flagName} requires a numeric value, got "${value}". ` +
                 `Did you forget a value? Use ${flagName}=<n> if the value really starts with "-".`);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@switchbot/openapi-cli",
-  "version": "2.2.1",
+  "version": "2.3.0",
   "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",