@switchbot/openapi-cli 3.6.0 → 3.6.1

package/README.md

@@ -63,7 +63,7 @@ Under the hood every surface shares the same catalog, cache, and HMAC client —
 - 🎨 **Dual output modes** — colorized tables by default; `--json` passthrough for `jq` and scripting
 - 🔐 **Secure credentials** — HMAC-SHA256 signed requests; config file written with `0600`; env-var override for CI
 - 🔍 **Dry-run mode** — preview every mutating request before it hits the API
-- 🧪 **Fully tested** — 2370 Vitest tests, mocked axios, zero network in CI
+- 🧪 **Fully tested** — 2391 Vitest tests, mocked axios, zero network in CI
 - ⚡ **Shell completion** — Bash / Zsh / Fish / PowerShell
 
 ## Requirements
@@ -633,7 +633,7 @@ switchbot doctor
 switchbot doctor --json
 ```
 
-Runs local checks (Node version, credentials, profiles, catalog, catalog-schema, cache, quota, clock, MQTT, policy, MCP, keychain, path, inventory, audit, daemon, health, notify-connectivity, release-notes) and exits 1 if any check fails. `warn` results exit 0. The MQTT check reports `ok` when REST credentials are configured (auto-provisioned on first use). The `notify-connectivity` check probes webhook URLs declared in `type: notify` actions. Use this to diagnose connectivity or config issues before running automation.
+Runs local checks (Node version, credentials, profiles, catalog, catalog-schema, catalog-coverage, cache, quota, clock, MQTT, policy, MCP, keychain, path, inventory, audit, daemon, health, notify-connectivity, release-notes) and exits 1 if any check fails. `warn` results exit 0. The MQTT check reports `ok` when REST credentials are configured (auto-provisioned on first use). The `notify-connectivity` check probes webhook URLs declared in `type: notify` actions. Use this to diagnose connectivity or config issues before running automation.
 
 `--json` output includes `maturityScore` (0–100) and `maturityLabel` (`production-ready` / `mostly-ready` / `needs-work` / `not-ready`) to give an at-a-glance readiness rating:
 
@@ -807,7 +807,7 @@ npm install
 
 npm run dev -- <args>       # Run from TypeScript sources via tsx
 npm run build               # Compile to dist/
-npm test                    # Run the Vitest suite (2370 tests)
+npm test                    # Run the Vitest suite (2391 tests)
 npm run test:watch          # Watch mode
 npm run test:coverage       # Coverage report (v8, HTML + text)
 ```

package/dist/index.js

@@ -7797,7 +7797,9 @@ var init_catalog = __esm({
       moveDetected: "Motion detected (boolean)",
       openState: "Contact sensor open/closed",
       status: "Device-specific status word",
-      lightLevel: "Ambient light level"
+      lightLevel: "Ambient light level",
+      detected: "Presence detected (boolean)",
+      hubDeviceId: "Hub device identifier for hub-bound devices"
     };
     onOff = [
       { command: "turnOn", parameter: "\u2014", description: "Power on", idempotent: true },
@@ -7918,12 +7920,12 @@ var init_catalog = __esm({
       {
         type: "Relay Switch 2PM",
         category: "physical",
-        description: "Dual-channel relay switch with per-channel on/off/toggle and optional roller-shade mode.",
+        description: 'Dual-channel relay switch with per-channel on/off/toggle and optional roller-shade mode. IMPORTANT: turnOn/turnOff/toggle require a channel parameter ("1" or "2") \u2014 omitting it is a usage error.',
         role: "power",
         commands: [
-          { command: "turnOn", parameter: "1 | 2 (channel)", description: "Turn on channel 1 or 2", idempotent: true, exampleParams: ["1", "2"] },
-          { command: "turnOff", parameter: "1 | 2 (channel)", description: "Turn off channel 1 or 2", idempotent: true, exampleParams: ["1", "2"] },
-          { command: "toggle", parameter: "1 | 2 (channel)", description: "Toggle channel 1 or 2", idempotent: false, exampleParams: ["1", "2"] },
+          { command: "turnOn", parameter: "1 | 2 (channel \u2014 required)", description: "Turn on channel 1 or 2", idempotent: true, exampleParams: ["1", "2"] },
+          { command: "turnOff", parameter: "1 | 2 (channel \u2014 required)", description: "Turn off channel 1 or 2", idempotent: true, exampleParams: ["1", "2"] },
+          { command: "toggle", parameter: "1 | 2 (channel \u2014 required)", description: "Toggle channel 1 or 2", idempotent: false, exampleParams: ["1", "2"] },
           { command: "setMode", parameter: '"<channel>;<mode>" e.g. "1;0"', description: "Per-channel mode (see Relay Switch 1 modes)", idempotent: true, exampleParams: ["1;0", "2;3"] },
           { command: "setPosition", parameter: "0-100 (roller percentage)", description: "Roller-shade-pair mode only", idempotent: true, exampleParams: ["0", "50", "100"] }
         ],
@@ -7945,7 +7947,7 @@ var init_catalog = __esm({
         category: "physical",
         description: "Evaporative humidifier with multiple speed/auto/sleep/humidity modes and child lock.",
         role: "climate",
-        aliases: ["Evaporative Humidifier"],
+        aliases: ["Evaporative Humidifier", "Evaporative Humidifier (Auto-refill)"],
         commands: [
           ...onOff,
           { command: "setMode", parameter: `'{"mode":1-8,"targetHumidify":0-100}'`, description: "mode: 1=lv4 2=lv3 3=lv2 4=lv1 5=humidity 6=sleep 7=auto 8=drying", idempotent: true, exampleParams: ['{"mode":7,"targetHumidify":50}'] },
@@ -8064,7 +8066,7 @@ var init_catalog = __esm({
         category: "physical",
         description: "Entry-level robot vacuum with start/stop/dock and four suction power levels.",
         role: "cleaning",
-        aliases: ["Robot Vacuum", "Robot Vacuum Cleaner S1 Plus", "K10+", "K10+ Pro"],
+        aliases: ["Robot Vacuum", "S1", "S1 Plus", "Robot Vacuum Cleaner S1 Plus", "K10+", "K10+ Pro"],
         commands: [
           { command: "start", parameter: "\u2014", description: "Start cleaning", idempotent: true },
           { command: "stop", parameter: "\u2014", description: "Stop cleaning", idempotent: true },
@@ -8078,7 +8080,7 @@ var init_catalog = __esm({
         category: "physical",
         description: "Compact robot vacuum and mop combo with sweep/mop sessions, fan level, and water level.",
         role: "cleaning",
-        aliases: ["K10+ Pro Combo", "K20+ Pro", "K11+", "Robot Vacuum Cleaner K11+"],
+        aliases: ["K10+ Pro Combo", "K20+ Pro", "Robot Vacuum Cleaner K20 Plus Pro", "K11+", "Robot Vacuum Cleaner K11+"],
         commands: [
           { command: "startClean", parameter: `'{"action":"sweep"|"mop","param":{"fanLevel":1-4,"times":1-2639999}}'`, description: "Begin a cleaning session", idempotent: false, exampleParams: ['{"action":"sweep","param":{"fanLevel":2,"times":1}}'] },
           { command: "pause", parameter: "\u2014", description: "Pause cleaning", idempotent: true },
@@ -8093,7 +8095,7 @@ var init_catalog = __esm({
         category: "physical",
         description: "Advanced floor cleaning robot with sweep/mop modes, self-wash dock, and humidifier refill.",
         role: "cleaning",
-        aliases: ["Robot Vacuum Cleaner S10", "Robot Vacuum Cleaner S20", "S20"],
+        aliases: ["S10", "Robot Vacuum Cleaner S10", "Robot Vacuum Cleaner S20", "S20"],
         commands: [
           { command: "startClean", parameter: `'{"action":"sweep"|"sweep_mop","param":{"fanLevel":1-4,"waterLevel":1-2,"times":1-2639999}}'`, description: "Begin a cleaning session", idempotent: false, exampleParams: ['{"action":"sweep","param":{"fanLevel":2,"waterLevel":1,"times":1}}'] },
           { command: "pause", parameter: "\u2014", description: "Pause cleaning", idempotent: true },
@@ -8208,7 +8210,18 @@ var init_catalog = __esm({
         description: "Battery-powered temperature and humidity sensor; read-only, no control commands.",
         role: "sensor",
         readOnly: true,
-        aliases: ["Meter Plus", "MeterPro", "MeterPro(CO2)", "WoIOSensor"],
+        aliases: [
+          "MeterPlus",
+          "Meter Plus",
+          "Meter Plus (JP)",
+          "Meter Plus (US)",
+          "Outdoor Meter",
+          "MeterPro",
+          "Meter Pro",
+          "MeterPro(CO2)",
+          "Meter Pro (CO2 Monitor)",
+          "WoIOSensor"
+        ],
         commands: [],
         statusFields: ["temperature", "humidity", "battery", "version"]
       },
@@ -8221,6 +8234,16 @@ var init_catalog = __esm({
         commands: [],
         statusFields: ["battery", "version", "moveDetected", "brightness", "openState"]
       },
+      {
+        type: "Presence Sensor",
+        category: "physical",
+        description: "Presence detector that reports occupancy and ambient light through a paired hub; read-only.",
+        role: "sensor",
+        readOnly: true,
+        aliases: ["Human Presence Sensor", "Prensence Sensor"],
+        commands: [],
+        statusFields: ["version", "battery", "lightLevel", "detected", "hubDeviceId"]
+      },
       {
         type: "Contact Sensor",
         category: "physical",
@@ -8256,7 +8279,7 @@ var init_catalog = __esm({
         description: "IR hub that bridges BLE devices to the cloud and learns IR remotes; no direct control commands.",
         role: "hub",
         readOnly: true,
-        aliases: ["Hub Mini2"],
+        aliases: ["Hub", "Hub Plus", "Hub Mini2"],
         commands: [],
         statusFields: ["version"]
       },
@@ -8305,6 +8328,41 @@ var init_catalog = __esm({
         commands: [],
         statusFields: ["battery", "version"]
       },
+      {
+        type: "Indoor Cam",
+        category: "physical",
+        description: "Indoor security camera; listed by the cloud API but exposes no cloud status or control commands.",
+        role: "security",
+        readOnly: true,
+        commands: []
+      },
+      {
+        type: "Pan/Tilt Cam",
+        category: "physical",
+        description: "Pan/tilt indoor security camera; listed by the cloud API but exposes no cloud status or control commands.",
+        role: "security",
+        readOnly: true,
+        aliases: ["Pan/Tilt Cam 2K"],
+        commands: []
+      },
+      {
+        type: "Pan/Tilt Cam Plus 3K",
+        category: "physical",
+        description: "Pan/tilt indoor security camera; listed by the cloud API but exposes no cloud status or control commands.",
+        role: "security",
+        readOnly: true,
+        aliases: ["Pan/Tilt Cam Plus 2K", "Pan/Tilt Cam Plus", "Pan Tilt Cam Plus 3K"],
+        commands: []
+      },
+      {
+        type: "Remote",
+        category: "physical",
+        description: "Bluetooth wireless button remote paired to a hub or device; listed by the cloud API but exposes no cloud status or control commands.",
+        role: "other",
+        readOnly: true,
+        aliases: ["SwitchBot Remote", "Remote Button", "Wireless Remote"],
+        commands: []
+      },
       // ---------- Virtual IR remotes ----------
       {
         type: "Air Conditioner",
@@ -32221,15 +32279,15 @@ function validateSetBrightness(raw, deviceType) {
       error: `setBrightness requires an integer ${min}-${max} (percent). Example: "50".`
     };
   }
-  const trimmed = stripQuotes(raw.trim());
-  if (!/^-?\d+$/.test(trimmed)) {
+  const parsed = parseStrictInt(raw);
+  if (!parsed.ok) {
     return {
       ok: false,
       error: `setBrightness must be an integer ${min}-${max}, got ${JSON.stringify(raw)}. ${hintBrightnessRetry(min, max)}`
     };
   }
-  const n = Number(trimmed);
-  if (!Number.isInteger(n) || n < min || n > max) {
+  const n = parsed.value;
+  if (n < min || n > max) {
     return {
       ok: false,
       error: `setBrightness must be an integer ${min}-${max}, got "${raw}". ${hintBrightnessRetry(min, max)}`
@@ -32321,15 +32379,15 @@ function validateSetColorTemperature(raw) {
       error: `setColorTemperature requires an integer Kelvin value 2700-6500. Example: "4000".`
     };
   }
-  const trimmed = stripQuotes(raw.trim());
-  if (!/^-?\d+$/.test(trimmed)) {
+  const parsed = parseStrictInt(raw);
+  if (!parsed.ok) {
     return {
       ok: false,
       error: `setColorTemperature must be an integer 2700-6500, got ${JSON.stringify(raw)}.`
     };
   }
-  const n = Number(trimmed);
-  if (!Number.isInteger(n) || n < 2700 || n > 6500) {
+  const n = parsed.value;
+  if (n < 2700 || n > 6500) {
     return {
       ok: false,
       error: `setColorTemperature must be an integer 2700-6500, got "${raw}".`
@@ -32359,27 +32417,30 @@ function validateAcSetAll(raw) {
     };
   }
   const [tempStr, modeStr, fanStr, powerStr] = parts.map((s2) => s2.trim());
-  const temp = Number(tempStr);
-  if (!Number.isInteger(temp) || temp < 16 || temp > 30) {
+  const tempP = parseStrictInt(tempStr);
+  if (!tempP.ok || tempP.value < 16 || tempP.value > 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) {
+  const temp = tempP.value;
+  const modeP = parseStrictInt(modeStr);
+  if (!modeP.ok || modeP.value < 1 || modeP.value > 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) {
+  const mode = modeP.value;
+  const fanP = parseStrictInt(fanStr);
+  if (!fanP.ok || fanP.value < 1 || fanP.value > 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 fan = fanP.value;
   const power = powerStr.toLowerCase();
   if (power !== "on" && power !== "off") {
     return {
@@ -32398,14 +32459,14 @@ function validateCurtainSetPosition(raw) {
   }
   const stripped = stripQuotes(raw.trim());
   if (!stripped.includes(",")) {
-    const pos2 = Number(stripped);
-    if (!Number.isInteger(pos2) || pos2 < 0 || pos2 > 100) {
+    const posP2 = parseStrictInt(stripped);
+    if (!posP2.ok || posP2.value < 0 || posP2.value > 100) {
       return {
         ok: false,
         error: `setPosition must be an integer 0-100, got "${raw}". Example: "50".`
       };
     }
-    return { ok: true, normalized: String(pos2) };
+    return { ok: true, normalized: String(posP2.value) };
   }
   const parts = stripped.split(",").map((s2) => s2.trim());
   if (parts.length !== 3) {
@@ -32415,13 +32476,14 @@ function validateCurtainSetPosition(raw) {
     };
   }
   const [idxStr, modeStr, posStr] = parts;
-  const idx = Number(idxStr);
-  if (!Number.isInteger(idx) || idx < 0) {
+  const idxP = parseStrictInt(idxStr);
+  if (!idxP.ok || idxP.value < 0) {
     return {
       ok: false,
       error: `setPosition field 1 (index) must be a non-negative integer, got "${idxStr}".`
     };
   }
+  const idx = idxP.value;
   const modeLower = modeStr.toLowerCase();
   if (!["ff", "0", "1"].includes(modeLower)) {
     return {
@@ -32429,13 +32491,14 @@ function validateCurtainSetPosition(raw) {
       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) {
+  const posP = parseStrictInt(posStr);
+  if (!posP.ok || posP.value < 0 || posP.value > 100) {
     return {
       ok: false,
       error: `setPosition field 3 (position) must be an integer 0-100, got "${posStr}".`
     };
   }
+  const pos = posP.value;
   return { ok: true, normalized: `${idx},${modeLower},${pos}` };
 }
 function validateBlindTiltSetPosition(raw) {
@@ -32460,13 +32523,14 @@ function validateBlindTiltSetPosition(raw) {
       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) {
+  const angleP = parseStrictInt(parts[1]);
+  if (!angleP.ok || angleP.value < 0 || angleP.value > 100) {
     return {
       ok: false,
       error: `Blind Tilt setPosition angle must be an integer 0-100, got "${parts[1]}".`
     };
   }
+  const angle = angleP.value;
   if (angle % 2 !== 0) {
     return {
       ok: false,
@@ -32490,21 +32554,22 @@ function validateRelay2PmSetMode(raw) {
       error: `Relay Switch setMode expects "<channel>;<mode>", got ${JSON.stringify(raw)}. Example: "1;1".`
     };
   }
-  const ch = Number(parts[0]);
-  if (ch !== 1 && ch !== 2) {
+  const chP = parseStrictInt(parts[0]);
+  if (!chP.ok || chP.value !== 1 && chP.value !== 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) {
+  const ch = chP.value;
+  const modeP = parseStrictInt(parts[1]);
+  if (!modeP.ok || modeP.value < 0 || modeP.value > 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}` };
+  return { ok: true, normalized: `${ch};${modeP.value}` };
 }
 function validateRelayChannel(raw) {
   if (raw === void 0 || raw === "" || raw === "default") {
@@ -32528,6 +32593,11 @@ function stripQuotes(s2) {
   }
   return s2;
 }
+function parseStrictInt(raw) {
+  const cleaned = stripQuotes(raw);
+  if (!/^[+-]?(?:0|[1-9]\d*)$/.test(cleaned)) return { ok: false };
+  return { ok: true, value: Number(cleaned) };
+}
 function validateIntRange(raw, command, min, max, label) {
   if (raw === void 0 || raw === "" || raw === "default") {
     return {
@@ -32535,14 +32605,14 @@ function validateIntRange(raw, command, min, max, label) {
       error: `${command} requires an integer ${min}-${max} (${label}). Example: "${Math.round((min + max) / 2)}".`
     };
   }
-  const trimmed = stripQuotes(raw.trim());
-  if (!/^-?\d+$/.test(trimmed)) {
+  const parsed = parseStrictInt(raw);
+  if (!parsed.ok) {
     return {
       ok: false,
       error: `${command} must be an integer ${min}-${max} (${label}), got ${JSON.stringify(raw)}.`
     };
   }
-  const n = Number(trimmed);
+  const n = parsed.value;
   if (n < min || n > max) {
     return {
       ok: false,
@@ -33205,9 +33275,9 @@ Examples:
         printJson(result);
       } else {
         if (dryRunned.length > 0) {
-          console.log(`
+          console.error(`
 Planned (dry-run): ${dryRunned.length} device(s)`);
-          for (const d of dryRunned) console.log(`  - ${d.deviceId}`);
+          for (const d of dryRunned) console.error(`  - ${d.deviceId}`);
         }
         if (preSkipped.length > 0) {
           console.log(`
@@ -33842,7 +33912,7 @@ Examples:
         if (isJsonMode()) {
           printJson({ ok: true, dryRun: true, command, deviceId });
         } else {
-          console.log(`\u25E6 dry-run: ${command} would be sent to ${deviceId}`);
+          console.error(`\u25E6 dry-run: ${command} would be sent to ${deviceId}`);
         }
         return;
       }
@@ -34204,7 +34274,7 @@ Total: ${totalLabel}`);
       handleError(error48);
     }
   });
-  devices.command("status").description("Query the real-time status of a specific device").argument("[deviceId]", 'Device ID from "devices list" (or use --name or --ids)').option("--name <query>", "Resolve device by fuzzy name instead of deviceId", stringArg("--name")).option("--name-strategy <s>", `Name match strategy: ${ALL_STRATEGIES.join("|")} (default: fuzzy)`, stringArg("--name-strategy")).option("--name-type <type>", 'Narrow --name by device type (e.g. "Bot", "Color Bulb")', stringArg("--name-type")).option("--name-category <cat>", "Narrow --name by category: physical|ir", enumArg("--name-category", ["physical", "ir"])).option("--name-room <room>", "Narrow --name by room name (substring match)", stringArg("--name-room")).option("--ids <list>", "Comma-separated device IDs for batch status (incompatible with --name)", stringArg("--ids")).addHelpText("after", `
+  devices.command("status").description("Query the real-time status of a specific device").argument("[deviceId...]", 'Device ID(s) from "devices list" (or use --name or --ids)').option("--name <query>", "Resolve device by fuzzy name instead of deviceId", stringArg("--name")).option("--name-strategy <s>", `Name match strategy: ${ALL_STRATEGIES.join("|")} (default: fuzzy)`, stringArg("--name-strategy")).option("--name-type <type>", 'Narrow --name by device type (e.g. "Bot", "Color Bulb")', stringArg("--name-type")).option("--name-category <cat>", "Narrow --name by category: physical|ir", enumArg("--name-category", ["physical", "ir"])).option("--name-room <room>", "Narrow --name by room name (substring match)", stringArg("--name-room")).option("--ids <list>", "Comma-separated device IDs for batch status (incompatible with --name)", stringArg("--ids")).addHelpText("after", `
 Status fields vary by device type. To discover them without a live call:
 
   switchbot devices commands <type>    (prints the "Status fields" section)
@@ -34214,6 +34284,7 @@ all field names returned by your specific device, then narrow with --fields.
 
 Examples:
   $ switchbot devices status ABC123DEF456
+  $ switchbot devices status ABC123 DEF456 GHI789
   $ switchbot devices status --name "Living Room AC"
   $ switchbot devices status ABC123DEF456 --json
   $ switchbot devices status ABC123DEF456 --format yaml
@@ -34221,12 +34292,13 @@ Examples:
   $ switchbot devices status ABC123DEF456 --json | jq '.data.battery'
   $ switchbot devices status --ids ABC123,DEF456,GHI789
   $ switchbot devices status --ids ABC123,DEF456 --fields power,battery
-`).action(async (deviceIdArg, options) => {
+`).action(async (deviceIdArgs, options) => {
     try {
-      if (options.ids) {
+      const batchIds = options.ids ? options.ids.split(",").map((s2) => s2.trim()).filter(Boolean) : deviceIdArgs.length > 1 ? deviceIdArgs : void 0;
+      if (batchIds) {
         if (options.name) throw new UsageError("--ids and --name cannot be used together.");
-        const ids = options.ids.split(",").map((s2) => s2.trim()).filter(Boolean);
-        if (ids.length === 0) throw new UsageError("--ids requires at least one device ID.");
+        if (batchIds.length === 0) throw new UsageError("--ids requires at least one device ID.");
+        const ids = batchIds;
         const results = await Promise.allSettled(ids.map((id) => fetchDeviceStatus(id)));
         const fetchedAt2 = (/* @__PURE__ */ new Date()).toISOString();
         const batch = results.map(
@@ -34258,7 +34330,7 @@ Examples:
         }
         return;
       }
-      const deviceId = resolveDeviceId(deviceIdArg, options.name, {
+      const deviceId = resolveDeviceId(deviceIdArgs[0], options.name, {
         strategy: options.nameStrategy ?? "fuzzy",
         type: options.nameType,
         category: options.nameCategory,
@@ -34536,7 +34608,7 @@ ${extra}` : extra;
         if (isJsonMode()) {
           printJson({ dryRun: true, wouldSend });
         } else {
-          console.log(`\u25E6 dry-run intercepted for ${_cmd} on ${_deviceId}; see stderr preview for the HTTP request.`);
+          console.error(`\u25E6 dry-run intercepted for ${_cmd} on ${_deviceId}; see stderr preview for the HTTP request.`);
         }
         return;
       }
@@ -34787,12 +34859,15 @@ function renderCatalogEntry(entry) {
   console.log(`Type:     ${entry.type}`);
   console.log(`Category: ${entry.category === "ir" ? "IR remote" : "Physical device"}`);
   if (entry.role) console.log(`Role:     ${entry.role}`);
-  if (entry.readOnly) console.log(`ReadOnly: yes (status-only device, no control commands)`);
+  const hasStatusFields = (entry.statusFields?.length ?? 0) > 0;
+  if (entry.readOnly) {
+    console.log(hasStatusFields ? `ReadOnly: yes (status-only device, no control commands)` : `ReadOnly: yes (no cloud control commands cataloged)`);
+  }
   if (entry.aliases && entry.aliases.length > 0) {
     console.log(`Aliases:  ${entry.aliases.join(", ")}`);
   }
   if (entry.commands.length === 0) {
-    console.log("\nCommands: (none \u2014 status-only device)");
+    console.log(hasStatusFields ? "\nCommands: (none \u2014 status-only device)" : "\nCommands: (none \u2014 no cloud control commands cataloged)");
   } else {
     console.log("\nCommands:");
     const hasExamples = entry.commands.some((c) => c.exampleParams && c.exampleParams.length > 0);
@@ -34897,7 +34972,7 @@ Example:
         if (isJsonMode()) {
           printJson({ dryRun: true, wouldSend });
         } else {
-          console.log(`[dry-run] Would POST /v1.1/scenes/${sceneId}/execute (${found.sceneName})`);
+          console.error(`[dry-run] Would POST /v1.1/scenes/${sceneId}/execute (${found.sceneName})`);
         }
         return;
       }
@@ -35055,7 +35130,7 @@ Example:
       console.log(`idempotent: unknown (scene steps not exposed by API)`);
       console.log(`toExecute:  ${explanation.toExecute}`);
       if (explanation.dryRun) {
-        console.log(`dryRun:     true  (pass --dry-run to execute would be a no-op)`);
+        console.error(`dryRun:     true  (pass --dry-run to execute would be a no-op)`);
       }
       console.log(`note:       ${explanation.note}`);
     } catch (error48) {
@@ -50545,7 +50620,7 @@ async function executePlanSteps(plan, planId, options) {
       if (err instanceof Error && err.name === "DryRunSignal") {
         out.results.push({ step: idx, type: "command", deviceId: resolvedDeviceId, command: step.command, status: "dry-run" });
         out.summary.dryRun++;
-        if (!isJsonMode()) console.log(`  ${idx}. \u25E6 dry-run ${step.command} on ${resolvedDeviceId}`);
+        if (!isJsonMode()) console.error(`  ${idx}. \u25E6 dry-run ${step.command} on ${resolvedDeviceId}`);
         continue;
       }
       const msg = err instanceof Error ? err.message : String(err);
@@ -53515,21 +53590,21 @@ Example Claude Desktop config (~/Library/Application Support/Claude/claude_deskt
 Inspect locally:
   $ npx @modelcontextprotocol/inspector switchbot mcp serve
 `);
-  mcp.command("tools").description("Print the registered MCP tools in human or JSON form").option("--tools <profile>", "Tool profile: default, readonly, all (default: all)", stringArg("--tools"), "all").action((opts) => {
+  mcp.command("tools").description("Print the registered MCP tools in human or JSON form").option("--tools <profile>", 'Tool profile: "default" (13 tools), "readonly" (10), or "all" (24). Lists all when omitted', stringArg("--tools"), "all").action((opts) => {
     try {
       printMcpToolDirectory(resolveToolProfile(opts.tools));
     } catch (e) {
       handleError(e);
     }
   });
-  mcp.command("list-tools").description("Alias of `mcp tools`").option("--tools <profile>", "Tool profile: default, readonly, all (default: all)", stringArg("--tools"), "all").action((opts) => {
+  mcp.command("list-tools").description("Alias of `mcp tools`").option("--tools <profile>", 'Tool profile: "default" (13 tools), "readonly" (10), or "all" (24). Lists all when omitted', stringArg("--tools"), "all").action((opts) => {
     try {
       printMcpToolDirectory(resolveToolProfile(opts.tools));
     } catch (e) {
       handleError(e);
     }
   });
-  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)", 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").option("--tools <profile>", "Tool profile: default, readonly, all (default: default)", stringArg("--tools"), "default").addHelpText("after", `
+  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)", 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").option("--tools <profile>", 'Tool profile: "default" (13 tools), "readonly" (10), or "all" (24)', stringArg("--tools"), "default").addHelpText("after", `
 Examples:
   $ switchbot mcp serve
   $ switchbot mcp serve --tools all
@@ -53977,6 +54052,7 @@ Total: ${entries.length} device type(s)  (source: ${source})`);
   });
   catalog.command("search").description("Fuzzy search the effective catalog by type name, alias, role, or command name").argument("<keyword>", "Substring to match (case-insensitive) against type, alias, role, or command").option("--strict", "Only return entries whose type name matches (skip alias/role/command fallbacks)").action((keyword, options) => {
     try {
+      if (!keyword.trim()) throw new UsageError("catalog search requires a non-empty keyword.");
       const q = keyword.toLowerCase();
       const entries = getEffectiveCatalog();
       const strict = options.strict === true;
@@ -55541,6 +55617,25 @@ function checkCatalog() {
     detail: `${catalog.length} types loaded${missingRole > 0 ? `, ${missingRole} missing role` : ""}`
   };
 }
+function checkCatalogCoverage() {
+  const cache2 = loadCache();
+  if (!cache2) {
+    return { name: "catalog-coverage", status: "ok", detail: 'no device cache \u2014 run "switchbot devices list" first' };
+  }
+  const catalog = getEffectiveCatalog();
+  const catalogTypes = new Set(catalog.map((e) => e.type.toLowerCase()));
+  const aliases = new Set(catalog.flatMap((e) => (e.aliases ?? []).map((a) => a.toLowerCase())));
+  const deviceTypes = [...new Set(Object.values(cache2.devices).map((d) => d.type))];
+  const missing = deviceTypes.filter((t) => !catalogTypes.has(t.toLowerCase()) && !aliases.has(t.toLowerCase()));
+  if (missing.length === 0) {
+    return { name: "catalog-coverage", status: "ok", detail: `all ${deviceTypes.length} device types have catalog entries` };
+  }
+  return {
+    name: "catalog-coverage",
+    status: "warn",
+    detail: { missing, message: `${missing.length} device type(s) without catalog entry` }
+  };
+}
 function checkCache() {
   try {
     const info = describeCache();
@@ -55642,6 +55737,7 @@ function checkInventoryConsistency() {
     status: "warn",
     detail: {
       message: `${dangling.length} device(s) reference a hubDeviceId that is not present in the current inventory`,
+      hint: "This usually means the hub was removed or replaced. Re-pair affected devices in the SwitchBot app, or ignore if the devices still work.",
       dangling: dangling.slice(0, 10)
     }
   };
@@ -56143,6 +56239,7 @@ var CHECK_REGISTRY = [
   { name: "keychain", description: "OS keychain backend availability and usage", run: () => checkKeychain() },
   { name: "profiles", description: "profile definitions valid", run: () => checkProfiles() },
   { name: "catalog", description: "catalog loads", run: () => checkCatalog() },
+  { name: "catalog-coverage", description: "all cached device types have catalog entries", run: () => checkCatalogCoverage() },
   { name: "catalog-schema", description: "catalog vs agent-bootstrap version aligned", run: () => checkCatalogSchema() },
   { name: "inventory", description: "cached inventory graph consistency (hubDeviceId references)", run: () => checkInventoryConsistency() },
   { name: "cache", description: "device cache state", run: () => checkCache() },
@@ -56204,7 +56301,7 @@ function applyFixes(checks, writeOk) {
   return results;
 }
 function registerDoctorCommand(program3) {
-  program3.command("doctor").description("Self-check the SwitchBot CLI setup: credentials, catalog, cache, quota, MQTT, daemon, health, MCP").option("--section <names>", "Comma-separated list of checks to run (see --list for names)").option("--list", "Print the registered check names and exit 0 without running any check").option("--fix", "Apply safe, reversible remediations for failing checks (e.g. clear stale cache)").option("--yes", "Required together with --fix to confirm write actions").option("--probe", "Perform live-probe variant of checks that support it (mqtt)").addHelpText("after", `
+  program3.command("doctor").description("Self-check the SwitchBot CLI setup: credentials, catalog, cache, quota, MQTT, daemon, health, MCP").option("--section <names>", "Comma-separated list of checks to run (see --list for names)").option("--list", "Print the registered check names and exit 0 without running any check").option("--fix", "Apply safe, reversible remediations for failing checks (e.g. clear stale cache)").option("--yes", "Required together with --fix to confirm write actions").option("--probe", "Perform live-probe variant of checks that support it (mqtt)").option("-q, --quiet", "Only show warn/fail checks, hide passing checks").addHelpText("after", `
 Runs a battery of local sanity checks and exits with code 0 only when every
 check is 'ok'. 'warn' \u2192 exit 0 (informational); 'fail' \u2192 exit 1.
 
@@ -56281,7 +56378,9 @@ Examples:
       if (fixes !== void 0) payload.fixes = fixes;
       printJson(payload);
     } else {
+      const quiet = Boolean(opts.quiet);
       for (const c of checks) {
+        if (quiet && c.status === "ok") continue;
         const icon2 = c.status === "ok" ? "\u2713" : c.status === "warn" ? "!" : "\u2717";
         const detailStr = typeof c.detail === "string" ? c.detail : typeof c.detail.message === "string" ? c.detail.message : JSON.stringify(c.detail);
         console.log(`${icon2} ${c.name.padEnd(12)} ${detailStr}`);
@@ -57114,8 +57213,8 @@ Examples:
     if (opts.dryRun) {
       if (isJsonMode()) printJson(finalPayload);
       else {
-        console.log(`\u2022 dry-run: would upgrade ${policyPath} (v${plan.fromVersion} \u2192 v${plan.toVersion})`);
-        console.log(`  bytes: ${bytesWritten}`);
+        console.error(`\u2022 dry-run: would upgrade ${policyPath} (v${plan.fromVersion} \u2192 v${plan.toVersion})`);
+        console.error(`  bytes: ${bytesWritten}`);
         console.log(`  precheck: valid against v${target}`);
       }
       return;
@@ -57232,7 +57331,7 @@ Reads rule YAML from stdin. Combine with 'rules suggest' for a full pipeline:
         if (result.written) {
           console.log(`\u2713 rule "${result.ruleName}" added to ${policyPath}`);
         } else {
-          console.log(`\u2022 dry-run: rule "${result.ruleName}" not written`);
+          console.error(`\u2022 dry-run: rule "${result.ruleName}" not written`);
         }
       }
     } catch (err) {
@@ -59312,18 +59411,18 @@ function printDryRun(steps, ctx) {
     });
     return;
   }
-  console.log(source_default.bold("switchbot install \u2014 dry run"));
-  console.log(`  profile: ${ctx.profile}`);
-  console.log(`  agent:   ${ctx.agent}`);
-  console.log(`  skill:   ${ctx.skillPath ?? "(none \u2014 recipe will be printed)"}`);
-  console.log(`  policy:  ${ctx.policyPath}`);
-  console.log("");
-  console.log(source_default.bold("Steps that would run (in order):"));
+  console.error(source_default.bold("switchbot install \u2014 dry run"));
+  console.error(`  profile: ${ctx.profile}`);
+  console.error(`  agent:   ${ctx.agent}`);
+  console.error(`  skill:   ${ctx.skillPath ?? "(none \u2014 recipe will be printed)"}`);
+  console.error(`  policy:  ${ctx.policyPath}`);
+  console.error("");
+  console.error(source_default.bold("Steps that would run (in order):"));
   for (const s2 of steps) {
-    console.log(`  \u2022 ${s2.name}${s2.description ? `  \u2014 ${s2.description}` : ""}`);
+    console.error(`  \u2022 ${s2.name}${s2.description ? `  \u2014 ${s2.description}` : ""}`);
   }
-  console.log("");
-  console.log(source_default.dim("No changes made. Re-run without --dry-run to apply."));
+  console.error("");
+  console.error(source_default.dim("No changes made. Re-run without --dry-run to apply."));
 }
 function registerInstallCommand(program3) {
   program3.command("install").description("One-command bootstrap: credentials + policy + skill link (rolls back on failure)").option("--agent <name>", `target agent: ${AGENT_VALUES.join(" | ")} (default: claude-code)`).option("--skill-path <dir>", "local clone of openclaw-switchbot-skill (enables auto-link)").option("--token-file <path>", "two-line credential file (token, secret); read once and deleted on success").option("--skip <names>", 'comma-separated list of step names to skip (e.g. "scaffold-policy,symlink-skill")').option("--force", "replace an existing skill symlink pointing at a different path; allow link even without SKILL.md").option("--verify", "after a successful install, run `switchbot doctor --json` as a warn-only post-check").addHelpText(
@@ -59618,14 +59717,14 @@ Examples:
           plan: plan.map(({ action, detail }) => ({ action, detail }))
         });
       } else {
-        console.log(source_default.bold("switchbot uninstall \u2014 dry run"));
-        console.log(`  profile: ${profile}`);
-        console.log(`  agent:   ${agent}`);
-        console.log("");
-        console.log(source_default.bold("Would run:"));
-        for (const p2 of plan) console.log(`  \u2022 ${p2.action}  \u2014 ${p2.detail}`);
-        console.log("");
-        console.log(source_default.dim("No changes made. Re-run without --dry-run (add --yes to skip prompts)."));
+        console.error(source_default.bold("switchbot uninstall \u2014 dry run"));
+        console.error(`  profile: ${profile}`);
+        console.error(`  agent:   ${agent}`);
+        console.error("");
+        console.error(source_default.bold("Would run:"));
+        for (const p2 of plan) console.error(`  \u2022 ${p2.action}  \u2014 ${p2.detail}`);
+        console.error("");
+        console.error(source_default.dim("No changes made. Re-run without --dry-run (add --yes to skip prompts)."));
       }
       return;
     }
@@ -60201,7 +60300,7 @@ function getHealthReport(auditPath = DEFAULT_AUDIT_PATH3) {
     const breakdown = {};
     let expectedErrors = 0;
     for (const e of errorEntries) {
-      const code = e.statusCode !== void 0 ? String(e.statusCode) : "unknown";
+      const code = e.statusCode !== void 0 ? String(e.statusCode) : "client";
       breakdown[code] = (breakdown[code] ?? 0) + 1;
       if (e.statusCode !== void 0 && EXPECTED_ERROR_CODES.has(e.statusCode)) {
         expectedErrors++;
@@ -60268,38 +60367,46 @@ function runHealthCheck(opts) {
     process.stdout.write(toPrometheusText(report));
     return;
   }
-  if (isJsonMode()) {
+  const fmt = resolveFormat();
+  if (fmt === "json" || isJsonMode()) {
     printJson(report);
     return;
   }
+  const headers = ["Component", "Status", "Detail"];
+  const rows = [
+    [
+      "quota",
+      report.quota.status,
+      `${report.quota.used}/${report.quota.limit} (${report.quota.percentUsed}% used, ${report.quota.remaining} remaining)`
+    ],
+    [
+      "audit",
+      report.audit.status,
+      report.audit.present ? `${report.audit.recentErrors}/${report.audit.recentTotal} errors in 24h (${report.audit.errorRatePercent}%)` : "log not present"
+    ],
+    [
+      "circuit",
+      report.circuit.status,
+      `${report.circuit.name}: ${report.circuit.state} (failures: ${report.circuit.failures})`
+    ],
+    [
+      "process",
+      "ok",
+      `pid ${report.process.pid} \xB7 uptime ${report.process.uptimeSeconds}s \xB7 mem ${report.process.memoryMb}MB`
+    ]
+  ];
+  if (fmt !== "table") {
+    if (fmt === "id") {
+      handleError(new UsageError("--format=id is not supported for health check (no deviceId column). Use --format json, yaml, tsv, jsonl, or markdown."));
+    }
+    renderRows(headers, rows, fmt);
+    if (report.overall !== "ok") process.exit(1);
+    return;
+  }
   const statusEmoji = report.overall === "ok" ? "\u2713" : report.overall === "degraded" ? "\u26A0" : "\u2717";
   console.log(`${statusEmoji} overall: ${report.overall}  (${report.generatedAt})`);
   console.log("");
-  printTable(
-    ["Component", "Status", "Detail"],
-    [
-      [
-        "quota",
-        report.quota.status,
-        `${report.quota.used}/${report.quota.limit} (${report.quota.percentUsed}% used, ${report.quota.remaining} remaining)`
-      ],
-      [
-        "audit",
-        report.audit.status,
-        report.audit.present ? `${report.audit.recentErrors}/${report.audit.recentTotal} errors in 24h (${report.audit.errorRatePercent}%)` : "log not present"
-      ],
-      [
-        "circuit",
-        report.circuit.status,
-        `${report.circuit.name}: ${report.circuit.state} (failures: ${report.circuit.failures})`
-      ],
-      [
-        "process",
-        "ok",
-        `pid ${report.process.pid} \xB7 uptime ${report.process.uptimeSeconds}s \xB7 mem ${report.process.memoryMb}MB`
-      ]
-    ]
-  );
+  printTable(headers, rows);
   if (report.overall !== "ok") process.exit(1);
 }
 function createHealthHandler(auditLogPath) {
@@ -60853,6 +60960,7 @@ if (process.argv.includes("--no-color") || Boolean(process.env.NO_COLOR)) {
   source_default.level = 0;
 }
 var program2 = new Command();
+program2.allowExcessArguments(false);
 if (isJsonMode()) {
   program2.configureOutput({ writeErr: () => {
   } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@switchbot/openapi-cli",
-  "version": "3.6.0",
+  "version": "3.6.1",
   "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",
@@ -42,6 +42,7 @@
     "hooks:install": "node scripts/install-git-hooks.mjs",
     "lint:md": "markdownlint \"**/*.md\"",
     "lint:md:changelog": "markdownlint CHANGELOG.md",
+    "lint:stdout": "bash scripts/lint-stdout.sh",
     "prepare": "node scripts/install-git-hooks.mjs",
     "start": "node dist/index.js",
     "smoke:pack-install": "node scripts/smoke-pack-install.mjs",
@@ -51,6 +52,7 @@
     "test:release-smoke:manual": "npm test -- tests/commands/policy.test.ts tests/commands/devices.test.ts tests/commands/explain.test.ts tests/commands/doctor.test.ts tests/commands/mcp.test.ts tests/commands/health-check.test.ts tests/commands/quota.test.ts tests/commands/status-sync.test.ts tests/status-sync/smoke.test.ts tests/commands/watch.test.ts tests/commands/events.test.ts tests/devices/catalog-fidelity.test.ts tests/commands/schema.test.ts tests/commands/auth.test.ts tests/commands/config.test.ts tests/commands/scenes.test.ts tests/commands/batch.test.ts tests/commands/history.test.ts tests/commands/expand.test.ts tests/commands/webhook.test.ts tests/commands/daemon.test.ts tests/commands/upgrade-check.test.ts tests/commands/install.test.ts tests/commands/uninstall.test.ts tests/commands/rules.test.ts tests/commands/plan.test.ts",
     "verify:pre-commit": "npm run build && npm test -- tests/version.test.ts",
     "verify:pre-push": "npm run build && npm test -- tests/version.test.ts && npm run smoke:pack-install",
+    "verify:release": "node scripts/verify-release.mjs",
     "prepublishOnly": "npm test && npm run build && npm run smoke:pack-install"
   },
   "dependencies": {