@switchbot/openapi-cli 2.2.0 → 2.3.0

package/dist/commands/expand.js

@@ -1,86 +1,11 @@
+import { intArg, stringArg } from '../utils/arg-parsers.js';
 import { handleError, isJsonMode, printJson, UsageError } from '../utils/output.js';
 import { getCachedDevice } from '../devices/cache.js';
 import { executeCommand, isDestructiveCommand, getDestructiveReason } from '../lib/devices.js';
 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
@@ -88,15 +13,15 @@ export function registerExpandCommand(devices) {
         .description('Send a command with semantic flags instead of raw positional parameters')
         .argument('[deviceId]', 'Target device ID from "devices list" (or use --name)')
         .argument('[command]', 'Command name: setAll (AC), setPosition (Curtain/Blind Tilt), setMode (Relay Switch 2)')
-        .option('--name <query>', 'Resolve device by fuzzy name instead of deviceId')
-        .option('--temp <celsius>', 'AC setAll: temperature in Celsius (16-30)')
-        .option('--mode <mode>', 'AC: auto|cool|dry|fan|heat  Curtain: default|performance|silent  Relay: toggle|edge|detached|momentary')
-        .option('--fan <speed>', 'AC setAll: fan speed auto|low|mid|high')
-        .option('--power <state>', 'AC setAll: on|off')
-        .option('--position <percent>', 'Curtain setPosition: 0-100 (0=open, 100=closed)')
-        .option('--direction <dir>', 'Blind Tilt setPosition: up|down')
-        .option('--angle <percent>', 'Blind Tilt setPosition: 0-100 (0=closed, 100=open)')
-        .option('--channel <n>', 'Relay Switch 2 setMode: channel 1 or 2')
+        .option('--name <query>', 'Resolve device by fuzzy name instead of deviceId', stringArg('--name'))
+        .option('--temp <celsius>', 'AC setAll: temperature in Celsius (16-30)', intArg('--temp', { min: 16, max: 30 }))
+        .option('--mode <mode>', 'AC: auto|cool|dry|fan|heat  Curtain: default|performance|silent  Relay: toggle|edge|detached|momentary', stringArg('--mode'))
+        .option('--fan <speed>', 'AC setAll: fan speed auto|low|mid|high', stringArg('--fan'))
+        .option('--power <state>', 'AC setAll: on|off', stringArg('--power'))
+        .option('--position <percent>', 'Curtain setPosition: 0-100 (0=open, 100=closed)', intArg('--position', { min: 0, max: 100 }))
+        .option('--direction <dir>', 'Blind Tilt setPosition: up|down', stringArg('--direction'))
+        .option('--angle <percent>', 'Blind Tilt setPosition: 0-100 (0=closed, 100=open)', intArg('--angle', { min: 0, max: 100 }))
+        .option('--channel <n>', 'Relay Switch 2 setMode: channel 1 or 2', intArg('--channel', { min: 1, max: 2 }))
         .option('--yes', 'Confirm destructive commands')
         .addHelpText('after', `
 Translates semantic flags into the wire parameter format, then sends the command.

package/dist/commands/history.js

@@ -1,5 +1,6 @@
 import path from 'node:path';
 import os from 'node:os';
+import { intArg, stringArg } from '../utils/arg-parsers.js';
 import { printJson, isJsonMode, handleError } from '../utils/output.js';
 import { readAudit } from '../utils/audit.js';
 import { executeCommand } from '../lib/devices.js';
@@ -21,8 +22,8 @@ Examples:
     history
         .command('show')
         .description('Print recent audit entries')
-        .option('--file <path>', `Path to the audit log (default ${DEFAULT_AUDIT})`)
-        .option('--limit <n>', 'Show only the last N entries')
+        .option('--file <path>', `Path to the audit log (default ${DEFAULT_AUDIT})`, stringArg('--file'))
+        .option('--limit <n>', 'Show only the last N entries', intArg('--limit', { min: 1 }))
         .action((options) => {
         const file = options.file ?? DEFAULT_AUDIT;
         const entries = readAudit(file);
@@ -52,7 +53,7 @@ Examples:
         .command('replay')
         .description('Re-run a recorded command by its 1-indexed position')
         .argument('<index>', 'Entry index (1 = oldest; as shown by "history show")')
-        .option('--file <path>', `Path to the audit log (default ${DEFAULT_AUDIT})`)
+        .option('--file <path>', `Path to the audit log (default ${DEFAULT_AUDIT})`, stringArg('--file'))
         .addHelpText('after', `
 Dry-run-honouring: pass --dry-run on the parent command to preview without
 sending the actual call. Errors from the recorded entry are NOT replayed —

package/dist/commands/mcp.js

@@ -2,6 +2,7 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 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 } from '../utils/output.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';
@@ -489,11 +490,11 @@ Inspect locally:
     mcp
         .command('serve')
         .description('Start the MCP server on stdio (default) or HTTP (--port)')
-        .option('--port <n>', 'Listen on HTTP instead of stdio (Streamable HTTP transport)')
-        .option('--bind <host>', 'IP address to bind (default 127.0.0.1; use 0.0.0.0 to accept external connections)', '127.0.0.1')
-        .option('--auth-token <token>', 'Bearer token for HTTP requests (required for --bind 0.0.0.0; falls back to SWITCHBOT_MCP_TOKEN env var)')
-        .option('--cors-origin <url>', 'Allowed CORS origin(s) for HTTP (repeatable)')
-        .option('--rate-limit <n>', 'Max requests per minute per profile (default 60)', '60')
+        .option('--port <n>', 'Listen on HTTP instead of stdio (Streamable HTTP transport)', intArg('--port', { min: 1, max: 65535 }))
+        .option('--bind <host>', 'IP address to bind (default 127.0.0.1; use 0.0.0.0 to accept external connections)', stringArg('--bind'), '127.0.0.1')
+        .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')
         .action(async (options) => {
         try {
             if (options.port) {

package/dist/commands/schema.js

@@ -1,3 +1,4 @@
+import { enumArg, stringArg } from '../utils/arg-parsers.js';
 import { printJson } from '../utils/output.js';
 import { getEffectiveCatalog } from '../devices/catalog.js';
 function toSchemaEntry(e) {
@@ -24,15 +25,17 @@ function toSchemaCommand(c) {
     };
 }
 export function registerSchemaCommand(program) {
+    const ROLES = ['lighting', 'security', 'sensor', 'climate', 'media', 'cleaning', 'curtain', 'fan', 'power', 'hub', 'other'];
+    const CATEGORIES = ['physical', 'ir'];
     const schema = program
         .command('schema')
         .description('Export the device catalog as structured JSON (for agent prompts / tooling)');
     schema
         .command('export')
         .description('Print the full catalog as structured JSON (one object per type)')
-        .option('--type <type>', 'Restrict to a single device type (e.g. "Strip Light")')
-        .option('--role <role>', 'Restrict to a functional role: lighting, security, sensor, climate, media, cleaning, curtain, fan, power, hub, other')
-        .option('--category <cat>', 'Restrict to "physical" or "ir"')
+        .option('--type <type>', 'Restrict to a single device type (e.g. "Strip Light")', stringArg('--type'))
+        .option('--role <role>', 'Restrict to a functional role: lighting, security, sensor, climate, media, cleaning, curtain, fan, power, hub, other', enumArg('--role', ROLES))
+        .option('--category <cat>', 'Restrict to "physical" or "ir"', enumArg('--category', CATEGORIES))
         .addHelpText('after', `
 Output is always JSON (this command ignores --format). The output is a
 catalog export — not a formal JSON Schema standard document — suitable for

package/dist/commands/watch.js

@@ -2,6 +2,7 @@ import { printJson, isJsonMode, handleError, UsageError } from '../utils/output.
 import { fetchDeviceStatus } from '../lib/devices.js';
 import { getCachedDevice } from '../devices/cache.js';
 import { parseDurationToMs, getFields } from '../utils/flags.js';
+import { intArg, durationArg, stringArg } from '../utils/arg-parsers.js';
 import { createClient } from '../api/client.js';
 import { resolveDeviceId } from '../utils/name-resolver.js';
 const DEFAULT_INTERVAL_MS = 30_000;
@@ -57,9 +58,9 @@ export function registerWatchCommand(devices) {
         .command('watch')
         .description('Poll device status on an interval and emit field-level changes (JSONL)')
         .argument('[deviceId...]', 'One or more deviceIds to watch (or use --name for one device)')
-        .option('--name <query>', 'Resolve one device by fuzzy name (combined with any positional IDs)')
-        .option('--interval <dur>', `Polling interval: "30s", "1m", "500ms", ... (default 30s, min ${MIN_INTERVAL_MS / 1000}s)`, '30s')
-        .option('--max <n>', 'Stop after N ticks (default: run until Ctrl-C)')
+        .option('--name <query>', 'Resolve one device by fuzzy name (combined with any positional IDs)', stringArg('--name'))
+        .option('--interval <dur>', `Polling interval: "30s", "1m", "500ms", ... (default 30s, min ${MIN_INTERVAL_MS / 1000}s)`, durationArg('--interval'), '30s')
+        .option('--max <n>', 'Stop after N ticks (default: run until Ctrl-C)', intArg('--max', { min: 1 }))
         .option('--include-unchanged', 'Emit a tick even when no field changed')
         .addHelpText('after', `
 Each poll emits one JSON line per deviceId with the shape:

package/dist/commands/webhook.js

@@ -1,3 +1,4 @@
+import { stringArg } from '../utils/arg-parsers.js';
 import { createClient } from '../api/client.js';
 import { printKeyValue, printJson, isJsonMode, handleError, UsageError } from '../utils/output.js';
 import chalk from 'chalk';
@@ -54,7 +55,7 @@ Example:
     webhook
         .command('query')
         .description('Query webhook configuration')
-        .option('--details <url>', 'Query detailed configuration (enable/deviceList/timestamps) for a specific URL')
+        .option('--details <url>', 'Query detailed configuration (enable/deviceList/timestamps) for a specific URL', stringArg('--details'))
         .addHelpText('after', `
 Without --details, lists all configured webhook URLs.
 With --details, prints enable/deviceList/createTime/lastUpdateTime for the given URL.

package/dist/config.js

@@ -99,7 +99,7 @@ export function showConfig() {
     const envSecret = process.env.SWITCHBOT_SECRET;
     if (envToken && envSecret) {
         console.log('Credential source: environment variables');
-        console.log(`token : ${envToken}`);
+        console.log(`token : ${maskCredential(envToken)}`);
         console.log(`secret: ${maskSecret(envSecret)}`);
         return;
     }
@@ -112,13 +112,18 @@ export function showConfig() {
         const raw = fs.readFileSync(file, 'utf-8');
         const cfg = JSON.parse(raw);
         console.log(`Credential source: ${file}`);
-        console.log(`token : ${cfg.token}`);
+        console.log(`token : ${maskCredential(cfg.token)}`);
         console.log(`secret: ${maskSecret(cfg.secret)}`);
     }
     catch {
         console.error('Failed to read config file');
     }
 }
+function maskCredential(token) {
+    if (token.length <= 8)
+        return '*'.repeat(Math.max(4, token.length));
+    return token.slice(0, 4) + '*'.repeat(token.length - 8) + token.slice(-4);
+}
 function maskSecret(secret) {
     if (secret.length <= 4)
         return '****';

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/index.js

@@ -1,6 +1,8 @@
 #!/usr/bin/env node
-import { Command, CommanderError } from 'commander';
+import { Command, CommanderError, InvalidArgumentError } from 'commander';
 import { createRequire } from 'node:module';
+import { intArg, stringArg, enumArg } from './utils/arg-parsers.js';
+import { parseDurationToMs } from './utils/flags.js';
 import { registerConfigCommand } from './commands/config.js';
 import { registerDevicesCommand } from './commands/devices.js';
 import { registerScenesCommand } from './commands/scenes.js';
@@ -19,26 +21,44 @@ import { registerCapabilitiesCommand } from './commands/capabilities.js';
 const require = createRequire(import.meta.url);
 const { version: pkgVersion } = require('../package.json');
 const program = new Command();
+// 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 = [
+    'config', 'devices', 'scenes', 'webhook', 'completion', 'mcp',
+    'quota', 'catalog', 'cache', 'events', 'doctor', 'schema',
+    'history', 'plan', 'capabilities',
+];
+const cacheModeArg = (value) => {
+    if (value.startsWith('-')) {
+        throw new InvalidArgumentError(`--cache requires a mode value, got "${value}". ` +
+            `Valid: "off", "auto", or a duration like "5m", "1h". Use --cache=<mode> if needed.`);
+    }
+    if (value === 'off' || value === 'auto')
+        return value;
+    if (parseDurationToMs(value) !== null)
+        return value;
+    throw new InvalidArgumentError(`--cache must be "off", "auto", or a duration like "30s"/"5m"/"1h" (got "${value}")`);
+};
 program
     .name('switchbot')
     .description('Command-line tool for SwitchBot API v1.1')
     .version(pkgVersion)
     .option('--json', 'Output raw JSON response (disables tables; useful for pipes/scripts)')
-    .option('--format <type>', 'Output format: table (default), json, jsonl, tsv, yaml, id')
-    .option('--fields <csv>', 'Comma-separated list of columns to include (e.g. --fields=id,name,type)')
+    .option('--format <type>', 'Output format: table (default), json, jsonl, tsv, yaml, id', enumArg('--format', ['table', 'json', 'jsonl', 'tsv', 'yaml', 'id']))
+    .option('--fields <csv>', 'Comma-separated list of columns to include (e.g. --fields=id,name,type)', stringArg('--fields', { disallow: TOP_LEVEL_COMMANDS }))
     .option('-v, --verbose', 'Log HTTP request/response details to stderr')
     .option('--dry-run', 'Print mutating requests without sending them (GETs still execute)')
-    .option('--timeout <ms>', 'HTTP request timeout in milliseconds (default: 30000)')
-    .option('--retry-on-429 <n>', 'Max 429 retries before surfacing the error (default: 3)')
-    .option('--backoff <strategy>', 'Backoff strategy for retries: "linear" or "exponential" (default)')
+    .option('--timeout <ms>', 'HTTP request timeout in milliseconds (default: 30000)', intArg('--timeout', { min: 1 }))
+    .option('--retry-on-429 <n>', 'Max 429 retries before surfacing the error (default: 3)', intArg('--retry-on-429', { min: 0 }))
+    .option('--backoff <strategy>', 'Backoff strategy for retries: "linear" or "exponential" (default)', enumArg('--backoff', ['linear', 'exponential']))
     .option('--no-retry', 'Disable 429 retries entirely (equivalent to --retry-on-429 0)')
     .option('--no-quota', 'Disable the local ~/.switchbot/quota.json counter for this run')
-    .option('--cache <mode>', 'Cache mode: "off" | "auto" (default: list 1h, status off) | duration like 5m, 1h, 30s (enables both stores)')
+    .option('--cache <mode>', 'Cache mode: "off" | "auto" (default: list 1h, status off) | duration like 5m, 1h, 30s (enables both stores)', cacheModeArg)
     .option('--no-cache', 'Disable cache reads (equivalent to --cache off)')
-    .option('--config <path>', 'Override credential file location (default: ~/.switchbot/config.json)')
-    .option('--profile <name>', 'Use a named profile: ~/.switchbot/profiles/<name>.json')
+    .option('--config <path>', 'Override credential file location (default: ~/.switchbot/config.json)', stringArg('--config', { disallow: TOP_LEVEL_COMMANDS }))
+    .option('--profile <name>', 'Use a named profile: ~/.switchbot/profiles/<name>.json', stringArg('--profile', { disallow: TOP_LEVEL_COMMANDS }))
     .option('--audit-log', 'Append every mutating command to JSONL audit log (default path: ~/.switchbot/audit.log)')
-    .option('--audit-log-path <path>', 'Custom audit log file path; use together with --audit-log')
+    .option('--audit-log-path <path>', 'Custom audit log file path; use together with --audit-log', stringArg('--audit-log-path', { disallow: TOP_LEVEL_COMMANDS }))
     .showHelpAfterError('(run with --help to see usage)')
     .showSuggestionAfterError();
 registerConfigCommand(program);
@@ -95,24 +115,33 @@ Discovery:
 
 Docs: https://github.com/OpenWonderLabs/SwitchBotAPI
 `);
-// Map commander usage errors (unknown option, missing argument, etc.) to exit code 2.
-program.exitOverride((err) => {
-    // --help and --version print to stdout and exit 0
+// Map commander usage errors (unknown option, missing argument, argParser
+// InvalidArgumentError, etc.) to exit code 2. Commander's exitOverride is
+// 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);
     }
-    // Everything else from commander (unknown option, missing argument,
-    // invalid choice, conflicting options, unknown command) is a usage error.
     process.exit(2);
-});
+};
+function applyExitOverride(cmd) {
+    cmd.exitOverride(usageExitHandler);
+    cmd.commands.forEach(applyExitOverride);
+}
+applyExitOverride(program);
 try {
     await program.parseAsync();
 }
 catch (err) {
-    // exitOverride already handled CommanderErrors; anything that escapes is a
-    // runtime error (should be rare since actions use handleError).
+    // Subcommand-level CommanderErrors (e.g. InvalidArgumentError from an
+    // argParser on a subcommand option) don't always hit the root exitOverride.
+    // Mirror the root mapping so all usage errors surface as exit 2.
     if (err instanceof CommanderError) {
-        process.exit(err.exitCode ?? 2);
+        if (err.code === 'commander.helpDisplayed' || err.code === 'commander.version') {
+            process.exit(0);
+        }
+        process.exit(2);
     }
     throw err;
 }