@switchbot/openapi-cli 3.4.0 → 3.4.1

package/dist/index.js

@@ -7221,7 +7221,7 @@ function emitJsonError(errorPayload) {
 function emitStreamHeader(opts) {
   console.log(
     JSON.stringify({
-      schemaVersion: SCHEMA_VERSION,
+      schemaVersion: opts.schemaVersion ?? SCHEMA_VERSION,
       stream: true,
       eventKind: opts.eventKind,
       cadence: opts.cadence
@@ -7531,7 +7531,7 @@ var init_output = __esm({
     init_source();
     init_client();
     init_flags();
-    SCHEMA_VERSION = "1.1";
+    SCHEMA_VERSION = "1.2";
     ASCII_BORDER_CHARS = {
       top: "-",
       "top-mid": "+",
@@ -28296,8 +28296,21 @@ function commandToJson(cmd, opts = {}) {
 }
 function resolveTargetCommand(root, argv) {
   let cmd = root;
+  const rootOptions = root.options;
+  let consumeNext = false;
   for (const token of argv) {
-    if (token.startsWith("-")) continue;
+    if (consumeNext) {
+      consumeNext = false;
+      continue;
+    }
+    if (token.startsWith("-")) {
+      if (!token.includes("=")) {
+        const localOpts = cmd.options;
+        const opt = localOpts.find((o) => o.short === token || o.long === token) || rootOptions.find((o) => o.short === token || o.long === token);
+        if (opt && (opt.required || opt.optional)) consumeNext = true;
+      }
+      continue;
+    }
     const sub = cmd.commands.find(
       (c) => c.name() === token || c.aliases().includes(token)
     );
@@ -31763,6 +31776,26 @@ function buildRelaySetMode(opts) {
   }
   return `${ch};${modeInt}`;
 }
+function buildBrightnessSet(opts) {
+  if (!opts.brightness) throw new UsageError("--brightness is required (1-100)");
+  const b2 = parseInt(opts.brightness, 10);
+  if (!Number.isFinite(b2) || b2 < 1 || b2 > 100) {
+    throw new UsageError(`--brightness must be an integer between 1 and 100 (got "${opts.brightness}")`);
+  }
+  return String(b2);
+}
+function buildColorSet(opts) {
+  if (!opts.color) throw new UsageError('--color is required (e.g. "255:0:0", "#FF0000", "red")');
+  const result = validateSetColor(opts.color);
+  if (!result.ok) throw new UsageError(result.error);
+  return result.normalized ?? opts.color;
+}
+function buildColorTemperatureSet(opts) {
+  if (!opts.colorTemp) throw new UsageError("--color-temp is required (2700-6500)");
+  const result = validateSetColorTemperature(opts.colorTemp);
+  if (!result.ok) throw new UsageError(result.error);
+  return result.normalized ?? opts.colorTemp;
+}
 function validateParameter(deviceType, command, raw) {
   if (!deviceType) return { ok: true };
   if (deviceType === "Air Conditioner" && command === "setAll") {
@@ -31783,7 +31816,7 @@ function validateParameter(deviceType, command, raw) {
   if (command === "setColor" && isColorDevice(deviceType)) {
     return validateSetColor(raw);
   }
-  if (command === "setColorTemperature" && isColorDevice(deviceType)) {
+  if (command === "setColorTemperature" && isBrightnessDevice(deviceType)) {
     return validateSetColorTemperature(raw);
   }
   return { ok: true };
@@ -31792,7 +31825,12 @@ function isBrightnessDevice(deviceType) {
   return deviceType === "Color Bulb" || deviceType === "Strip Light" || deviceType === "Strip Light 3" || deviceType === "Ceiling Light" || deviceType === "Ceiling Light Pro" || deviceType === "Floor Lamp" || deviceType === "Light Strip" || deviceType === "Dimmer" || deviceType === "Fill Light";
 }
 function isColorDevice(deviceType) {
-  return deviceType === "Color Bulb" || deviceType === "Strip Light" || deviceType === "Strip Light 3" || deviceType === "Ceiling Light" || deviceType === "Ceiling Light Pro" || deviceType === "Floor Lamp" || deviceType === "Light Strip" || deviceType === "Fill Light";
+  return deviceType === "Color Bulb" || deviceType === "Strip Light" || deviceType === "Strip Light 3" || deviceType === "Floor Lamp" || deviceType === "Light Strip" || deviceType === "Fill Light";
+}
+function isLightingCommandSupported(deviceType, command) {
+  if (command === "setBrightness" || command === "setColorTemperature") return isBrightnessDevice(deviceType);
+  if (command === "setColor") return isColorDevice(deviceType);
+  return false;
 }
 function validateSetBrightness(raw) {
   if (raw === void 0 || raw === "" || raw === "default") {
@@ -32923,10 +32961,11 @@ init_arg_parsers();
 init_output();
 init_cache();
 init_devices();
+init_catalog();
 init_flags();
 init_client();
 function registerExpandCommand(devices) {
-  devices.command("expand").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", stringArg("--name")).option("--name-strategy <s>", `Name match strategy: ${ALL_STRATEGIES.join("|")} (default: require-unique)`, stringArg("--name-strategy")).option("--name-type <type>", 'Narrow --name by device type (e.g. "Curtain", "Air Conditioner")', 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("--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", `
+  devices.command("expand").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), setBrightness/setColor/setColorTemperature (lighting)").option("--name <query>", "Resolve device by fuzzy name instead of deviceId", stringArg("--name")).option("--name-strategy <s>", `Name match strategy: ${ALL_STRATEGIES.join("|")} (default: require-unique)`, stringArg("--name-strategy")).option("--name-type <type>", 'Narrow --name by device type (e.g. "Curtain", "Air Conditioner")', 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("--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("--brightness <percent>", "setBrightness: 1-100 percent", intArg("--brightness", { min: 1, max: 100 })).option("--color <value>", "setColor: R:G:B, #RRGGBB, or named color (red, blue, etc.)", stringArg("--color")).option("--color-temp <kelvin>", "setColorTemperature: 2700-6500 Kelvin", intArg("--color-temp", { min: 2700, max: 6500 })).option("--yes", "Confirm destructive commands").addHelpText("after", `
 Translates semantic flags into the wire parameter format, then sends the command.
 
 Supported expansions:
@@ -32947,12 +32986,25 @@ Supported expansions:
     --channel 1 --mode edge  \u2192  "1;1"
     --mode values: toggle (0) | edge (1) | detached (2) | momentary (3)
 
+  Color Bulb / Strip Light / Ceiling Light \u2014 setBrightness
+    --brightness 80  \u2192  "80"
+
+  Color Bulb / Strip Light / Floor Lamp \u2014 setColor
+    --color "255:0:0"  \u2192  "255:0:0"
+    --color "#FF0000"  \u2192  "255:0:0"
+    --color red        \u2192  "255:0:0"
+
+  Color Bulb / Strip Light / Ceiling Light \u2014 setColorTemperature
+    --color-temp 4000  \u2192  "4000"
+
 Examples:
-  $ switchbot devices expand <acId>      setAll       --temp 26 --mode cool --fan low --power on
-  $ switchbot devices expand <curtainId> setPosition  --position 50 --mode silent
-  $ switchbot devices expand <blindId>   setPosition  --direction up --angle 50
-  $ switchbot devices expand <relayId>   setMode      --channel 1 --mode edge
-  $ switchbot devices expand <acId>      setAll       --temp 22 --mode heat --fan auto --power on --dry-run
+  $ switchbot devices expand <acId>      setAll               --temp 26 --mode cool --fan low --power on
+  $ switchbot devices expand <curtainId> setPosition          --position 50 --mode silent
+  $ switchbot devices expand <blindId>   setPosition          --direction up --angle 50
+  $ switchbot devices expand <relayId>   setMode              --channel 1 --mode edge
+  $ switchbot devices expand <stripId>   setBrightness        --brightness 80
+  $ switchbot devices expand <bulbId>    setColor             --color "#FF0000"
+  $ switchbot devices expand <bulbId>    setColorTemperature  --color-temp 4000
   $ switchbot devices expand --name "Living Room AC" setAll --temp 26 --mode cool --fan low --power on
 `).action(async (deviceIdArg, commandArg, options) => {
     let deviceId = "";
@@ -32970,12 +33022,22 @@ Examples:
         category: options.nameCategory,
         room: options.nameRoom
       });
-      if (!effectiveCommand) throw new UsageError("A command argument is required (setAll, setPosition, setMode).");
+      if (!effectiveCommand) throw new UsageError("A command argument is required (setAll, setPosition, setMode, setBrightness, setColor, setColorTemperature).");
       command = effectiveCommand;
       const cached2 = getCachedDevice(deviceId);
       const deviceType = cached2?.type ?? "";
       let parameter;
       if (command === "setAll") {
+        if (!cached2) {
+          throw new UsageError(
+            `Device ${deviceId} is not in the local cache \u2014 run 'switchbot devices list' first so 'expand' can verify this is an Air Conditioner.`
+          );
+        }
+        if (deviceType !== "Air Conditioner") {
+          throw new UsageError(
+            `"setAll" is only supported on Air Conditioner devices, but "${cached2.type}" was found.`
+          );
+        }
         parameter = buildAcSetAll(options);
       } else if (command === "setPosition") {
         if (!cached2) {
@@ -32983,13 +33045,56 @@ Examples:
             `Device ${deviceId} is not in the local cache \u2014 run 'switchbot devices list' first so 'expand' knows whether this is a Curtain or a Blind Tilt.`
           );
         }
+        const positionTypes = ["Curtain", "Curtain 3", "Roller Shade", "Blind Tilt"];
+        if (!positionTypes.some((t) => deviceType.startsWith(t))) {
+          throw new UsageError(
+            `"setPosition" is only supported on Curtain, Roller Shade, and Blind Tilt devices, but "${cached2.type}" was found.`
+          );
+        }
         const isBlind = deviceType.startsWith("Blind Tilt");
-        parameter = isBlind ? buildBlindTiltSetPosition(options) : buildCurtainSetPosition(options);
+        const isRollerShade = deviceType.startsWith("Roller Shade");
+        if (isBlind) {
+          parameter = buildBlindTiltSetPosition(options);
+        } else if (isRollerShade) {
+          if (!options.position) throw new UsageError("--position is required (0-100)");
+          parameter = options.position;
+        } else {
+          parameter = buildCurtainSetPosition(options);
+        }
       } else if (command === "setMode" && deviceType.startsWith("Relay Switch")) {
         parameter = buildRelaySetMode(options);
+      } else if (command === "setBrightness" || command === "setColor" || command === "setColorTemperature") {
+        if (!cached2) {
+          throw new UsageError(
+            `Device "${deviceId}" is not in the local cache \u2014 run 'switchbot devices list' first so 'expand' can verify this device supports ${command}.`
+          );
+        }
+        const catalogResult = findCatalogEntry(cached2.type);
+        const catalogEntry = Array.isArray(catalogResult) ? catalogResult[0] : catalogResult;
+        const supportedHint = command === "setColor" ? "Color Bulb, Strip Light, Floor Lamp, and similar RGB lighting devices" : "Color Bulb, Strip Light, Ceiling Light, Floor Lamp, and similar lighting devices";
+        if (catalogEntry !== null) {
+          if (!catalogEntry.commands.some((c) => c.command === command)) {
+            throw new UsageError(
+              `Device type "${cached2.type}" does not support ${command}. Supported on: ${supportedHint}.`
+            );
+          }
+        } else {
+          if (!isLightingCommandSupported(cached2.type, command)) {
+            throw new UsageError(
+              `Device type "${cached2.type}" does not support ${command}. Supported on: ${supportedHint}.`
+            );
+          }
+        }
+        if (command === "setBrightness") {
+          parameter = buildBrightnessSet(options);
+        } else if (command === "setColor") {
+          parameter = buildColorSet(options);
+        } else {
+          parameter = buildColorTemperatureSet(options);
+        }
       } else {
         throw new UsageError(
-          `'expand' does not support "${command}" for device type "${deviceType || "unknown"}". Use 'switchbot devices command' to send raw parameters instead.`
+          `'expand' does not support "${command}" for device type "${deviceType || "unknown"}". Supported: setAll (AC), setPosition (Curtain/Blind Tilt), setMode (Relay Switch), setBrightness/setColor/setColorTemperature (lighting). Use 'switchbot devices command' to send raw parameters instead.`
         );
       }
       if (!options.yes && !isDryRun() && isDestructiveCommand(deviceType, command, "command")) {
@@ -33402,7 +33507,7 @@ Examples:
         const results = await Promise.allSettled(ids.map((id) => fetchDeviceStatus(id)));
         const fetchedAt2 = (/* @__PURE__ */ new Date()).toISOString();
         const batch = results.map(
-          (r, i) => r.status === "fulfilled" ? { deviceId: ids[i], ok: true, _fetchedAt: fetchedAt2, ...annotateStatusPayload(ids[i], r.value) } : { deviceId: ids[i], ok: false, error: r.reason?.message ?? String(r.reason) }
+          (r, i) => r.status === "fulfilled" ? { deviceId: ids[i], ok: true, fetchedAt: fetchedAt2, ...annotateStatusPayload(ids[i], r.value) } : { deviceId: ids[i], ok: false, error: r.reason?.message ?? String(r.reason) }
         );
         const batchFmt = resolveFormat();
         if (isJsonMode() || batchFmt === "json") {
@@ -33414,7 +33519,7 @@ Examples:
         } else {
           const rawFields = resolveFields();
           for (const entry of batch) {
-            const { deviceId: deviceId2, ok, error: error48, _fetchedAt: ts, ...status } = entry;
+            const { deviceId: deviceId2, ok, error: error48, fetchedAt: ts, ...status } = entry;
             console.log(`
 \u2500\u2500\u2500 ${String(deviceId2)} \u2500\u2500\u2500`);
             if (!ok) {
@@ -33440,11 +33545,11 @@ Examples:
       const fetchedAt = (/* @__PURE__ */ new Date()).toISOString();
       const fmt = resolveFormat();
       if (fmt === "json" && process.argv.includes("--json")) {
-        printJson({ ...body, _fetchedAt: fetchedAt });
+        printJson({ ...body, fetchedAt });
         return;
       }
       if (fmt !== "table") {
-        const statusWithTs = { ...body, _fetchedAt: fetchedAt };
+        const statusWithTs = { ...body, fetchedAt };
         const allHeaders = Object.keys(statusWithTs);
         const allRows = [Object.values(statusWithTs)];
         const rawFields = resolveFields();
@@ -33773,7 +33878,7 @@ Examples:
       const joinedMatch = findCatalogEntry(joined);
       if (joinedMatch && !Array.isArray(joinedMatch)) {
         if (isJsonMode()) {
-          printJson(normalizeCatalogForJson(joinedMatch));
+          printJson([normalizeCatalogForJson(joinedMatch)]);
         } else {
           renderCatalogEntry(joinedMatch);
         }
@@ -48672,9 +48777,9 @@ var logLevel = process.env.LOG_LEVEL || "warn";
 var logFormat = process.env.LOG_FORMAT || "json";
 var pinoConfig = {
   level: logLevel,
-  transport: logFormat === "pretty" ? { target: "pino-pretty" } : void 0
+  transport: logFormat === "pretty" ? { target: "pino-pretty", options: { destination: 2 } } : void 0
 };
-var log = pino(pinoConfig);
+var log = logFormat === "pretty" ? pino(pinoConfig) : pino(pinoConfig, pino.destination(2));
 
 // src/mcp/device-history.ts
 init_cjs_shim();
@@ -52513,12 +52618,27 @@ function listRegisteredTools(server) {
   if (!internal._registeredTools) return [];
   return Object.keys(internal._registeredTools).sort();
 }
+function listRegisteredToolsWithMeta(server) {
+  const internal = server;
+  if (!internal._registeredTools) return [];
+  return Object.entries(internal._registeredTools).sort(([a], [b2]) => a.localeCompare(b2)).map(([name, reg]) => {
+    const entry = { name };
+    if (reg.description) entry.description = reg.description;
+    if (reg.inputSchema) {
+      try {
+        entry.inputSchema = external_exports.toJSONSchema(reg.inputSchema);
+      } catch {
+      }
+    }
+    return entry;
+  });
+}
 function listRegisteredResources() {
   return ["switchbot://events"];
 }
 function printMcpToolDirectory() {
   const server = createSwitchBotMcpServer();
-  const tools = listRegisteredTools(server).map((name) => ({ name }));
+  const tools = listRegisteredToolsWithMeta(server);
   const resources = listRegisteredResources().map((uri) => ({ uri }));
   if (isJsonMode()) {
     printJson({ tools, resources });
@@ -52526,7 +52646,8 @@ function printMcpToolDirectory() {
   }
   console.log("Tools:");
   for (const tool of tools) {
-    console.log(`  ${tool.name}`);
+    const desc = tool.description ? ` \u2014 ${tool.description.slice(0, 80)}` : "";
+    console.log(`  ${tool.name}${desc}`);
   }
   console.log("");
   console.log("Resources:");
@@ -52538,7 +52659,7 @@ Total: ${tools.length} tool(s), ${resources.length} resource(s)`);
 }
 function registerMcpCommand(program3) {
   const mcp = program3.command("mcp").description("Run as a Model Context Protocol server so AI agents can call SwitchBot tools").addHelpText("after", `
-  The MCP server exposes twenty-one tools:
+  The MCP server exposes twenty-four tools:
   - list_devices            fetch all physical + IR devices
   - get_device_status       live status for a physical device
   - send_command            control a device (destructive commands need confirm:true)
@@ -52561,6 +52682,8 @@ function registerMcpCommand(program3) {
   - audit_stats             aggregate audit counts by kind/result/device/rule
   - rule_notifications      query rule notify action delivery history
   - rules_suggest           draft an automation rule YAML from intent (heuristic, no LLM)
+  - rules_explain           show why a rule evaluation fired or was blocked
+  - rules_simulate          simulate a rule against historical events
   - policy_add_rule         append a rule into automation.rules[] in policy.yaml
 
 Resource (read-only):
@@ -53003,7 +53126,7 @@ Examples:
           throw new UsageError(`"${match.type}" exists in the effective catalog but not in source "${source}".`);
         }
         if (isJsonMode()) {
-          printJson(picked);
+          printJson([picked]);
           return;
         }
         renderEntry(picked);
@@ -53745,7 +53868,7 @@ Examples:
       let matchedCount = 0;
       const ac = new AbortController();
       const forTimer = forMs !== null && forMs > 0 ? setTimeout(() => ac.abort(), forMs) : null;
-      if (isJsonMode()) emitStreamHeader({ eventKind: "event", cadence: "push" });
+      if (isJsonMode()) emitStreamHeader({ eventKind: "event", cadence: "push", schemaVersion: EVENTS_SCHEMA_VERSION });
       await new Promise((resolve2, reject) => {
         let server = null;
         try {
@@ -53897,7 +54020,7 @@ Examples:
       if (!isJsonMode()) {
         console.error("Fetching MQTT credentials from SwitchBot service\u2026");
       }
-      if (isJsonMode()) emitStreamHeader({ eventKind: "event", cadence: "push" });
+      if (isJsonMode()) emitStreamHeader({ eventKind: "event", cadence: "push", schemaVersion: EVENTS_SCHEMA_VERSION });
       if (isJsonMode()) {
         const sessionStartAt = (/* @__PURE__ */ new Date()).toISOString();
         emitJsonStreamRecord({
@@ -55467,7 +55590,7 @@ function runSchemaExport(options) {
       payload.resources = RESOURCE_CATALOG;
       payload.cliAddedFields = [
         {
-          field: "_fetchedAt",
+          field: "fetchedAt",
           appliesTo: ["devices status", "devices describe"],
           type: "string (ISO-8601)",
           description: "CLI-synthesized timestamp indicating when this status response was fetched or served from the cache. Not part of the upstream SwitchBot API."
@@ -55530,7 +55653,7 @@ Common top-level fields:
   schemaVersion             CLI schema version (stable for agent contracts)
   data.version              Catalog schema version
   data.types                Array of SchemaEntry (or CompactSchemaEntry with --compact)
-  data._fetchedAt           CLI-added; present on live-query responses ('devices status'),
+  data.fetchedAt            CLI-added; present on live-query responses ('devices status'),
                             not on this offline export.
 
 Examples:
@@ -56841,13 +56964,12 @@ function registerRun(rules) {
     const loaded = loadAutomation(pathArg);
     if (!loaded) return;
     if (loaded.automation?.enabled !== true) {
-      const msg = "automation.enabled is not true \u2014 nothing to run.";
-      if (isJsonMode()) {
-        printJson({ kind: "control", controlKind: "disabled", message: msg });
-      } else {
-        console.error(msg);
-      }
-      process.exit(0);
+      exitWithError({
+        code: 1,
+        kind: "runtime",
+        message: "automation.enabled is not true \u2014 set it to true in your policy file to start the daemon.",
+        hint: "Set automation.enabled: true in your policy file, then re-run."
+      });
     }
     const lint = lintRules(loaded.automation);
     if (!lint.valid) {
@@ -59658,7 +59780,7 @@ The daemon reads the same policy file as \`switchbot rules run\`.
       }
     }
     const thisFile = fileURLToPath3(import.meta.url);
-    const cliEntry = path28.resolve(path28.dirname(thisFile), "..", "index.js");
+    const cliEntry = path28.basename(thisFile) === "index.js" ? thisFile : path28.resolve(path28.dirname(thisFile), "..", "index.js");
     const args = ["rules", "run"];
     if (opts.policy) args.push(opts.policy);
     fs32.mkdirSync(path28.dirname(DAEMON_PID_FILE), { recursive: true, mode: 448 });
@@ -60015,17 +60137,32 @@ try {
 } catch (err) {
   if (err instanceof CommanderError) {
     if (err.code === "commander.helpDisplayed") {
+      const helpRequested = process.argv.includes("--help") || process.argv.includes("-h") || process.argv.includes("help");
+      if (helpRequested) {
+        if (isJsonMode()) {
+          const target = resolveTargetCommand(program2, process.argv.slice(2));
+          printJson(commandToJson(target, { includeIdentity: target === program2 }));
+        }
+        process.exit(0);
+      }
       if (isJsonMode()) {
         const target = resolveTargetCommand(program2, process.argv.slice(2));
-        printJson(commandToJson(target, { includeIdentity: target === program2 }));
+        const subNames = target.commands.map((c) => c.name()).join(", ");
+        const usefulMessage = subNames ? `${target.name()}: a subcommand is required. Available: ${subNames}` : err.message;
+        emitJsonError({ code: 2, kind: "usage", message: usefulMessage });
       }
-      process.exit(0);
+      process.exit(2);
     }
     if (err.code === "commander.version") {
       process.exit(0);
     }
     if (isJsonMode()) {
-      emitJsonError({ code: 2, kind: "usage", message: err.message });
+      const errorMessage = err.code === "commander.help" ? (() => {
+        const target = resolveTargetCommand(program2, process.argv.slice(2));
+        const subNames = target.commands.map((c) => c.name()).join(", ");
+        return subNames ? `${target.name()}: a subcommand is required. Available: ${subNames}` : err.message;
+      })() : err.message;
+      emitJsonError({ code: 2, kind: "usage", message: errorMessage });
     }
     process.exit(2);
   }

package/package.json

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