@switchbot/openapi-cli 2.5.1 → 2.6.1

package/README.md

@@ -63,6 +63,7 @@ Under the hood every surface shares the same catalog, cache, and HMAC client —
 - [Scripting examples](#scripting-examples)
 - [Development](#development)
 - [Contributing](#contributing)
+- [Roadmap](#roadmap)
 - [License](#license)
 - [References](#references)
 
@@ -237,7 +238,7 @@ switchbot devices status <deviceId>
 switchbot devices status <deviceId> --json
 
 # Resolve device by fuzzy name instead of ID (status, command, describe, expand, watch)
-switchbot devices status --name "客厅空调"
+switchbot devices status --name "Living Room AC"
 switchbot devices command --name "Office Light" turnOn
 switchbot devices describe --name "Kitchen Bot"
 
@@ -263,18 +264,21 @@ switchbot devices commands curtain      # Case-insensitive, substring match
 
 #### Filter expressions — per-command reference
 
-Three commands accept `--filter`. They share one three-operator grammar,
+Three commands accept `--filter`. They share one four-operator grammar,
 but each exposes its own key set:
 
 | Command                             | Operators                                                                                     | Supported keys                        |
 |-------------------------------------|-----------------------------------------------------------------------------------------------|---------------------------------------|
-| `devices list`                      | `=` (substring; **exact** for `category`), `~` (substring), `=/regex/` (case-insensitive regex) | `type`, `name`, `category`, `room`    |
+| `devices list`                      | `=` (substring; **exact** for `category`), `!=` (negated), `~` (substring), `=/regex/` (case-insensitive regex) | `type`, `name`, `category`, `room`    |
 | `devices batch`                     | same                                                                                          | `type`, `family`, `room`, `category`  |
 | `events tail` / `events mqtt-tail`  | same (tail only; mqtt-tail uses `--topic` instead)                                            | `deviceId`, `type`                    |
 
 Clauses are comma-separated and AND-ed. No OR across clauses — use regex
 alternation (`=/A|B/`) for that. `category` is the one key that stays exact
-under `=` to preserve `category=physical` / `category=ir` semantics.
+under `=` / `!=` to preserve `category=physical` / `category!=ir` semantics.
+A clause with an empty value (e.g. `name~`, `type=`) is rejected with exit 2 —
+the parser refuses to guess whether an empty value means "no constraint" or
+"match empty string". Drop the clause outright to remove the constraint.
 
 #### Parameter formats
 
@@ -299,7 +303,9 @@ Generic parameter shapes (which one applies is decided by the device — see the
 | `<json object>`     | `'{"action":"sweep","param":{"fanLevel":2,"times":1}}'`  |
 | Custom IR button    | `devices command <id> MyButton --type customize`         |
 
-Parameters for `setAll` (Air Conditioner), `setPosition` (Curtain / Blind Tilt), and `setMode` (Relay Switch) are validated client-side before the request — malformed shapes, out-of-range values, and JSON for CSV fields all fail fast with exit 2. Command names are also case-normalized against the catalog (e.g. `turnon` is auto-corrected to `turnOn` with a stderr warning); unknown names still exit 2 with the supported-commands list.
+Parameters for `setAll` (Air Conditioner), `setPosition` (Curtain / Blind Tilt), `setMode` (Relay Switch), `setBrightness` (dimmable lights), and `setColor` (Color Bulb / Strip Light / Ceiling Light) are validated client-side before the request — malformed shapes, out-of-range values, and JSON for CSV fields all fail fast with exit 2. `setColor` accepts `R:G:B`, `R,G,B`, `#RRGGBB`, `#RGB`, and CSS named colors (`red`, `blue`, …); all normalize to `R:G:B` before hitting the API. Pass `--skip-param-validation` to bypass (escape hatch — prefer fixing the argument). Command names are also case-normalized against the catalog (e.g. `turnon` is auto-corrected to `turnOn` with a stderr warning); unknown names still exit 2 with the supported-commands list.
+
+Unknown deviceIds (not in the local cache) exit 2 by default so `--dry-run` is a reliable pre-flight gate. Run `switchbot devices list` first, or pass `--allow-unknown-device` for scripted pass-through.
 
 Negative numeric parameters (e.g. `setBrightness -1` for a probe) are passed through to the command validator instead of being swallowed by the flag parser as an unknown option.
 
@@ -313,7 +319,7 @@ Some commands require a packed string like `"26,2,2,on"`. `devices expand` build
 # Air Conditioner — setAll
 switchbot devices expand <acId> setAll --temp 26 --mode cool --fan low --power on
 # Resolve by name
-switchbot devices expand --name "客厅空调" setAll --temp 26 --mode cool --fan low --power on
+switchbot devices expand --name "Living Room AC" setAll --temp 26 --mode cool --fan low --power on
 
 # Curtain / Roller Shade — setPosition
 switchbot devices expand <curtainId> setPosition --position 50 --mode silent
@@ -325,7 +331,7 @@ switchbot devices expand <blindId> setPosition --direction up --angle 50
 switchbot devices expand <relayId> setMode --channel 1 --mode edge
 ```
 
-Run `switchbot devices expand <id> <command> --help` to see the available flags for any device command.
+Run `switchbot devices expand <id> <command> --help` to see the available flags for any device command. `expand` is only meaningful for multi-parameter commands (the four above); single-parameter commands like `setBrightness 50` or `setColor "#FF0000"` are already flag-free at the CLI level.
 
 #### `devices explain` — one-shot device summary
 
@@ -602,7 +608,9 @@ Reads the JSONL audit log (`~/.switchbot/audit.log` by default; override with `-
 
 ```bash
 switchbot catalog show              # all 42 built-in types
+switchbot catalog list              # alias for `show`
 switchbot catalog show Bot          # one type
+switchbot catalog search Hub        # fuzzy match across type / aliases / commands
 switchbot catalog diff              # what a local overlay changes vs built-in
 switchbot catalog path              # location of the local overlay file
 switchbot catalog refresh           # reload local overlay (clears in-process cache)
@@ -624,9 +632,10 @@ Exports the effective catalog in a machine-readable format. Pipe the output into
 
 ```bash
 switchbot capabilities --json
+switchbot capabilities --used --json   # only types seen in the local cache
 ```
 
-Prints a versioned JSON manifest describing available surfaces (CLI, MCP, MQTT, plan runner), commands, and environment variables. Designed for agents and tooling that need to discover the CLI's capabilities programmatically.
+Prints a versioned JSON manifest describing available surfaces (CLI, MCP, MQTT, plan runner), commands, and environment variables. Every subcommand leaf now carries a `{mutating, consumesQuota, idempotencySupported, agentSafetyTier, verifiability, typicalLatencyMs}` block, and the top-level payload publishes a flat `commandMeta` path-keyed lookup so agents don't have to walk the tree. `--used` filters the per-type summary to devices actually present in the local cache (same semantics as `schema export --used`).
 
 ### `cache` — inspect and clear local cache
 
@@ -822,6 +831,21 @@ Bug reports, feature requests, and PRs are welcome.
 3. Run `npm test` and `npm run build` locally — both must pass.
 4. Open a pull request against `main`. CI runs on Node 18/20/22; all three must stay green.
 
+## Roadmap
+
+Tracked for a future v3.x line (OpenClaw B-17 / B-18 / B-19 / B-21) — each is a
+standalone track rather than a bug fix:
+
+- **Daemon mode** — long-running local process with a Unix/named-pipe socket so
+  repeated MCP or plan invocations don't pay fresh-process startup every call.
+- **`npx @switchbot/mcp-server`** — split the MCP server into its own tiny
+  published package so non-CLI users can `npx` it directly without installing
+  the full CLI.
+- **`switchbot self-test`** — scripted end-to-end harness that checks a live
+  token + a representative device and prints a go/no-go report.
+- **Record / replay** — capture raw request/response pairs into a fixture file
+  and replay them offline for deterministic testing and CI.
+
 ## License
 
 [MIT](./LICENSE) © chenliuyun

package/dist/api/client.js

@@ -2,7 +2,7 @@ import axios from 'axios';
 import chalk from 'chalk';
 import { buildAuthHeaders } from '../auth.js';
 import { loadConfig } from '../config.js';
-import { isVerbose, isDryRun, getTimeout, getRetryOn429, getBackoffStrategy, isQuotaDisabled, } from '../utils/flags.js';
+import { isVerbose, isDryRun, getTimeout, getRetryOn429, getRetryOn5xx, getBackoffStrategy, isQuotaDisabled, } from '../utils/flags.js';
 import { nextRetryDelayMs, sleep } from '../utils/retry.js';
 import { recordRequest, checkDailyCap } from '../utils/quota.js';
 import { readProfileMeta } from '../config.js';
@@ -45,6 +45,7 @@ export function createClient() {
     const verbose = isVerbose();
     const dryRun = isDryRun();
     const maxRetries = getRetryOn429();
+    const max5xxRetries = getRetryOn5xx();
     const backoff = getBackoffStrategy();
     const quotaEnabled = !isQuotaDisabled();
     const profile = getActiveProfile();
@@ -110,11 +111,25 @@ export function createClient() {
         if (error instanceof DryRunSignal)
             throw error;
         if (axios.isAxiosError(error)) {
+            const config = error.config;
+            const method = (config?.method ?? 'get').toUpperCase();
+            const isIdempotentRead = method === 'GET';
             if (error.code === 'ECONNABORTED' || error.code === 'ETIMEDOUT') {
-                throw new ApiError(`Request timed out after ${getTimeout()}ms (override with --timeout <ms>)`, 0, { transient: true, retryable: false });
+                // Retry idempotent GETs on timeout up to `max5xxRetries` times.
+                if (isIdempotentRead && config && max5xxRetries > 0) {
+                    const attempt = config.__retryCount ?? 0;
+                    if (attempt < max5xxRetries) {
+                        config.__retryCount = attempt + 1;
+                        const delay = nextRetryDelayMs(attempt, backoff, undefined);
+                        if (verbose) {
+                            process.stderr.write(chalk.grey(`[verbose] timeout — retry ${attempt + 1}/${max5xxRetries} in ${delay}ms\n`));
+                        }
+                        return sleep(delay).then(() => client.request(config));
+                    }
+                }
+                throw new ApiError(`Request timed out after ${getTimeout()}ms (override with --timeout <ms>)`, 0, { transient: true, retryable: isIdempotentRead });
             }
             const status = error.response?.status;
-            const config = error.config;
             // 429 → transparent retry with Retry-After / exponential backoff.
             // Skipped when: no config (shouldn't happen for real axios errors),
             // retries disabled, or we've already used our budget.
@@ -129,6 +144,23 @@ export function createClient() {
                     return sleep(delay).then(() => client.request(config));
                 }
             }
+            // 502/503/504 on idempotent GETs → transparent retry. Mutating calls
+            // never auto-retry; use --idempotency-key for safe POST retries.
+            if (isIdempotentRead &&
+                status !== undefined &&
+                (status === 502 || status === 503 || status === 504) &&
+                config &&
+                max5xxRetries > 0) {
+                const attempt = config.__retryCount ?? 0;
+                if (attempt < max5xxRetries) {
+                    config.__retryCount = attempt + 1;
+                    const delay = nextRetryDelayMs(attempt, backoff, error.response?.headers?.['retry-after']);
+                    if (verbose) {
+                        process.stderr.write(chalk.grey(`[verbose] ${status} received — retry ${attempt + 1}/${max5xxRetries} in ${delay}ms\n`));
+                    }
+                    return sleep(delay).then(() => client.request(config));
+                }
+            }
             // Record exhausted/non-retryable HTTP responses too — they count
             // against the daily quota.
             if (quotaEnabled && error.response && config) {

package/dist/commands/batch.js

@@ -137,7 +137,7 @@ Safety:
   hitting the API.
 
 Examples:
-  $ switchbot devices batch turnOff --filter 'type~=Light,family=家里'
+  $ switchbot devices batch turnOff --filter 'type~=Light,family=home'
   $ switchbot devices batch turnOn --ids ID1,ID2,ID3
   $ switchbot devices list --format=id --filter 'type=Bot' | switchbot devices batch toggle -
   $ switchbot devices batch unlock --filter 'type=Smart Lock' --yes

package/dist/commands/capabilities.js

@@ -1,4 +1,5 @@
 import { getEffectiveCatalog } from '../devices/catalog.js';
+import { loadCache } from '../devices/cache.js';
 import { printJson } from '../utils/output.js';
 import { enumArg, stringArg } from '../utils/arg-parsers.js';
 const AGENT_GUIDE = {
@@ -149,6 +150,7 @@ export function registerCapabilitiesCommand(program) {
         .description('Print a machine-readable manifest of CLI capabilities (for agent bootstrap)')
         .option('--minimal', 'Omit per-subcommand flag details to reduce output size (alias of --compact)')
         .option('--compact', 'Emit a compact summary: identity + leaf command list with safety metadata only')
+        .option('--used', 'Restrict the catalog summary to device types present in the local cache. Mirrors `schema export --used`.')
         .option('--surface <s>', 'Restrict surfaces block to one of: cli, mcp, plan, mqtt, all (default: all)', enumArg('--surface', SURFACES))
         .option('--project <csv>', 'Project top-level fields (e.g. --project identity,commands,agentGuide)', stringArg('--project'))
         .action((opts) => {
@@ -238,6 +240,11 @@ export function registerCapabilitiesCommand(program) {
             identity: IDENTITY,
             surfaces: filteredSurfaces,
             commands: compact ? leaves : fullCommands,
+            // Flat command → meta map keyed by full command path. Published in
+            // addition to the tree (where every leaf `subcommands[*]` already
+            // carries the same fields via spread) so agents can do O(1) lookup
+            // without walking the tree.
+            commandMeta: COMMAND_META,
             ...(globalFlags ? { globalFlags } : {}),
             catalog: {
                 typeCount: catalog.length,
@@ -248,6 +255,30 @@ export function registerCapabilitiesCommand(program) {
         };
         if (!compact)
             payload.generatedAt = new Date().toISOString();
+        if (opts.used) {
+            const cache = loadCache();
+            if (!cache || Object.keys(cache.devices).length === 0) {
+                // No cache → return the payload unchanged but add a `usedFilter` note
+                // so agents know the filter was requested but noop'd.
+                payload.usedFilter = { applied: false, reason: 'no local cache — run `switchbot devices list` first' };
+            }
+            else {
+                const seen = new Set();
+                for (const id of Object.keys(cache.devices)) {
+                    const t = cache.devices[id].type;
+                    if (t)
+                        seen.add(t);
+                }
+                const filteredCatalog = catalog.filter((e) => seen.has(e.type) || (e.aliases ?? []).some((a) => seen.has(a)));
+                payload.catalog = {
+                    typeCount: filteredCatalog.length,
+                    roles: [...new Set(filteredCatalog.map((e) => e.role ?? 'other'))].sort(),
+                    destructiveCommandCount: filteredCatalog.reduce((n, e) => n + e.commands.filter((c) => c.destructive).length, 0),
+                    readOnlyTypeCount: filteredCatalog.filter((e) => e.readOnly).length,
+                };
+                payload.usedFilter = { applied: true, typesInCache: [...seen].sort() };
+            }
+        }
         const projected = opts.project
             ? projectObject(payload, opts.project.split(',').map((s) => s.trim()).filter(Boolean))
             : payload;

package/dist/commands/catalog.js

@@ -23,14 +23,18 @@ Overlay rules (applied in order):
 
 Subcommands:
   path        Print the overlay file path and whether it exists
-  show        Show the effective catalog (or one entry)
+  show        Show the effective catalog (or one entry).  Alias: list
+  list        Alias of show (matches the muscle-memory spelling)
+  search      Fuzzy search types/aliases/roles/commands for a keyword
   diff        Show what the overlay changes vs the built-in catalog
   refresh     Re-read the overlay file (clears in-process cache)
 
 Examples:
   $ switchbot catalog path
+  $ switchbot catalog list
   $ switchbot catalog show
   $ switchbot catalog show "Smart Lock"
+  $ switchbot catalog search Hub
   $ switchbot catalog show --source built-in
   $ switchbot catalog diff
   $ switchbot catalog refresh
@@ -66,7 +70,8 @@ Examples:
     });
     catalog
         .command('show')
-        .description("Show the effective catalog (or one entry). Defaults to 'effective' source.")
+        .alias('list')
+        .description("Show the effective catalog (or one entry). Alias: 'list'. Defaults to 'effective' source.")
         .argument('[type...]', 'Optional device type/alias (case-insensitive, partial match)')
         .option('--source <source>', 'Which catalog to show: built-in | overlay | effective (default)', enumArg('--source', SOURCES), 'effective')
         .action((typeParts, options) => {
@@ -139,6 +144,59 @@ Examples:
             handleError(error);
         }
     });
+    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')
+        .action((keyword) => {
+        try {
+            const q = keyword.toLowerCase();
+            const entries = getEffectiveCatalog();
+            const hits = entries.filter((e) => {
+                if (e.type.toLowerCase().includes(q))
+                    return true;
+                if ((e.role ?? '').toLowerCase().includes(q))
+                    return true;
+                if ((e.aliases ?? []).some((a) => a.toLowerCase().includes(q)))
+                    return true;
+                if (e.commands.some((c) => c.command.toLowerCase().includes(q)))
+                    return true;
+                return false;
+            });
+            if (isJsonMode()) {
+                printJson({ query: keyword, matches: hits });
+                return;
+            }
+            if (hits.length === 0) {
+                console.log(`No catalog entries match "${keyword}".`);
+                return;
+            }
+            const fmt = resolveFormat();
+            const headers = ['type', 'category', 'role', 'matched'];
+            const rows = hits.map((e) => {
+                const matched = [];
+                if (e.type.toLowerCase().includes(q))
+                    matched.push('type');
+                if ((e.aliases ?? []).some((a) => a.toLowerCase().includes(q)))
+                    matched.push('alias');
+                if ((e.role ?? '').toLowerCase().includes(q))
+                    matched.push('role');
+                const cmdMatches = e.commands
+                    .filter((c) => c.command.toLowerCase().includes(q))
+                    .map((c) => c.command);
+                if (cmdMatches.length > 0)
+                    matched.push(`commands[${cmdMatches.join(',')}]`);
+                return [e.type, e.category, e.role ?? '—', matched.join(', ') || '—'];
+            });
+            renderRows(headers, rows, fmt, resolveFields());
+            if (fmt === 'table') {
+                console.log(`\n${hits.length} match${hits.length === 1 ? '' : 'es'} for "${keyword}"`);
+            }
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
     catalog
         .command('diff')
         .description('Show what the overlay replaces, adds, or removes vs the built-in catalog')

package/dist/commands/devices.js

@@ -1,11 +1,12 @@
 import { enumArg, stringArg } from '../utils/arg-parsers.js';
-import { printTable, printKeyValue, printJson, isJsonMode, handleError, UsageError, emitJsonError } from '../utils/output.js';
+import { printTable, printKeyValue, printJson, isJsonMode, handleError, UsageError, StructuredUsageError, emitJsonError } from '../utils/output.js';
 import { resolveFormat, resolveFields, renderRows } from '../utils/format.js';
 import { findCatalogEntry, getEffectiveCatalog } from '../devices/catalog.js';
-import { getCachedDevice } from '../devices/cache.js';
+import { getCachedDevice, loadCache } from '../devices/cache.js';
 import { loadDeviceMeta } from '../devices/device-meta.js';
 import { resolveDeviceId, ALL_STRATEGIES } from '../utils/name-resolver.js';
 import { fetchDeviceList, fetchDeviceStatus, executeCommand, describeDevice, validateCommand, isDestructiveCommand, getDestructiveReason, buildHubLocationMap, DeviceNotFoundError, } from '../lib/devices.js';
+import { parseFilterExpr, matchClause, FilterSyntaxError } from '../utils/filter.js';
 import { validateParameter } from '../devices/param-validator.js';
 import { registerBatchCommand } from './batch.js';
 import { registerWatchCommand } from './watch.js';
@@ -69,7 +70,7 @@ Examples:
   $ switchbot devices list
   $ switchbot devices list --wide
   $ switchbot devices list --format tsv --fields deviceId,deviceName,type,category
-  $ switchbot devices list --json | jq '.deviceList[] | select(.familyName == "家里")'
+  $ switchbot devices list --json | jq '.deviceList[] | select(.familyName == "home")'
   $ switchbot devices list --json | jq '[.deviceList[], .infraredRemoteList[]] | group_by(.familyName)'
   $ switchbot devices list --filter type="Air Conditioner"
   $ switchbot devices list --filter category=ir
@@ -79,7 +80,7 @@ Examples:
 `)
         .option('--wide', 'Show all columns (controlType, family, roomID, room, hub, cloud)')
         .option('--show-hidden', 'Include devices hidden via "devices meta set --hide"')
-        .option('--filter <expr>', 'Filter devices: comma-separated clauses. Each clause is "key=value" (substring; exact for category), "key~value" (explicit substring), or "key=/regex/" (case-insensitive regex). Supported keys: type, name, category, room.', stringArg('--filter'))
+        .option('--filter <expr>', 'Filter devices: comma-separated clauses. Each clause is "key=value" (substring; exact for category), "key!=value" (negated substring), "key~value" (explicit substring), or "key=/regex/" (case-insensitive regex). Supported keys: type, name, category, room.', stringArg('--filter'))
         .action(async (options) => {
         try {
             const body = await fetchDeviceList();
@@ -87,49 +88,18 @@ Examples:
             const fmt = resolveFormat();
             const deviceMeta = loadDeviceMeta();
             const hubLocation = buildHubLocationMap(deviceList);
-            const SUPPORTED_KEYS = ['type', 'name', 'category', 'room'];
+            // Parse --filter into a list of clauses. Shared grammar across
+            // `devices list`, `devices batch`, and `events tail` / `mqtt-tail`.
+            const LIST_KEYS = ['type', 'name', 'category', 'room'];
             let listClauses = null;
             if (options.filter) {
-                listClauses = [];
-                for (const pair of options.filter.split(',')) {
-                    const trimmed = pair.trim();
-                    if (!trimmed)
-                        continue;
-                    const regexMatch = /^([^=~]+)=\/(.*)\/$/.exec(trimmed);
-                    const tildeIdx = trimmed.indexOf('~');
-                    const eqIdx = trimmed.indexOf('=');
-                    let key;
-                    let op;
-                    let raw;
-                    let regex;
-                    if (regexMatch) {
-                        key = regexMatch[1].trim();
-                        op = 'regex';
-                        raw = regexMatch[2];
-                        try {
-                            regex = new RegExp(raw, 'i');
-                        }
-                        catch (err) {
-                            throw new UsageError(`Invalid regex in --filter "${trimmed}": ${err.message}`);
-                        }
-                    }
-                    else if (tildeIdx !== -1 && (eqIdx === -1 || tildeIdx < eqIdx)) {
-                        key = trimmed.slice(0, tildeIdx).trim();
-                        op = 'sub';
-                        raw = trimmed.slice(tildeIdx + 1).trim().toLowerCase();
-                    }
-                    else if (eqIdx !== -1) {
-                        key = trimmed.slice(0, eqIdx).trim();
-                        op = 'eq';
-                        raw = trimmed.slice(eqIdx + 1).trim().toLowerCase();
-                    }
-                    else {
-                        throw new UsageError(`Invalid --filter pair "${trimmed}". Expected key=value, key~value, or key=/regex/.`);
-                    }
-                    if (!SUPPORTED_KEYS.includes(key)) {
-                        throw new UsageError(`Unknown --filter key "${key}". Supported: ${SUPPORTED_KEYS.join(', ')}.`);
-                    }
-                    listClauses.push({ key: key, op, raw, regex });
+                try {
+                    listClauses = parseFilterExpr(options.filter, LIST_KEYS);
+                }
+                catch (err) {
+                    if (err instanceof FilterSyntaxError)
+                        throw new UsageError(err.message);
+                    throw err;
                 }
             }
             const matchesFilter = (entry) => {
@@ -137,21 +107,7 @@ Examples:
                     return true;
                 for (const c of listClauses) {
                     const fieldVal = entry[c.key] ?? '';
-                    const lower = fieldVal.toLowerCase();
-                    let ok;
-                    if (c.op === 'regex') {
-                        ok = c.regex.test(fieldVal);
-                    }
-                    else if (c.op === 'sub') {
-                        ok = lower.includes(c.raw);
-                    }
-                    else if (c.key === 'category') {
-                        ok = lower === c.raw;
-                    }
-                    else {
-                        ok = lower.includes(c.raw);
-                    }
-                    if (!ok)
+                    if (!matchClause(fieldVal, c))
                         return false;
                 }
                 return true;
@@ -259,7 +215,7 @@ all field names returned by your specific device, then narrow with --fields.
 
 Examples:
   $ switchbot devices status ABC123DEF456
-  $ switchbot devices status --name "客厅空调"
+  $ switchbot devices status --name "Living Room AC"
   $ switchbot devices status ABC123DEF456 --json
   $ switchbot devices status ABC123DEF456 --format yaml
   $ switchbot devices status ABC123DEF456 --format tsv --fields power,battery
@@ -352,6 +308,8 @@ Examples:
         .option('--name-room <room>', 'Narrow --name by room name (substring match)', stringArg('--name-room'))
         .option('--type <commandType>', 'Command type: "command" for built-in commands (default), "customize" for user-defined IR buttons', enumArg('--type', COMMAND_TYPES), 'command')
         .option('--yes', 'Confirm a destructive command (Smart Lock unlock, Garage open, …). --dry-run is always allowed without --yes.')
+        .option('--allow-unknown-device', 'Allow targeting a deviceId that is not in the local cache. By default unknown IDs exit 2 so --dry-run is a reliable pre-flight gate; use this flag for scripted pass-through.')
+        .option('--skip-param-validation', 'Skip client-side parameter validation (escape hatch — prefer fixing the argument over using this).')
         .option('--idempotency-key <key>', 'Client-supplied key to dedupe retries. process-local 60s window; cache is per Node process (MCP session, batch run, plan run). Independent CLI invocations do not share cache.', stringArg('--idempotency-key'))
         .addHelpText('after', `
 ────────────────────────────────────────────────────────────────────────
@@ -438,7 +396,26 @@ Examples:
             });
             _deviceId = deviceId;
             if (!getCachedDevice(deviceId)) {
-                console.error(`Note: device ${deviceId} is not in the local cache — run 'switchbot devices list' first to enable command validation.`);
+                if (options.allowUnknownDevice) {
+                    console.error(`Note: device ${deviceId} is not in the local cache — run 'switchbot devices list' first to enable command validation. (--allow-unknown-device is set, continuing.)`);
+                }
+                else {
+                    const cache = loadCache();
+                    const allIds = cache ? Object.keys(cache.devices) : [];
+                    const candidates = allIds
+                        .filter((id) => id.toLowerCase().includes(deviceId.toLowerCase()) || id.startsWith(deviceId.slice(0, 4)))
+                        .slice(0, 5)
+                        .map((id) => {
+                        const dev = cache.devices[id];
+                        return { deviceId: id, name: dev.name, type: dev.type };
+                    });
+                    throw new StructuredUsageError(`Unknown deviceId "${deviceId}" — not in local cache. Run 'switchbot devices list' first, or pass --allow-unknown-device to bypass this check.`, {
+                        error: 'unknown_device_id',
+                        deviceId,
+                        candidates,
+                        hint: `Pass --allow-unknown-device to skip this check (and rely on the API for validation).`,
+                    });
+                }
             }
             const validation = validateCommand(deviceId, cmd, parameter, options.type);
             if (!validation.ok) {
@@ -474,7 +451,7 @@ Examples:
             }
             // Raw-parameter validation (runs for known (deviceType, command) pairs only).
             const cachedForParam = getCachedDevice(deviceId);
-            if (cachedForParam && options.type === 'command') {
+            if (cachedForParam && options.type === 'command' && !options.skipParamValidation) {
                 const paramCheck = validateParameter(cachedForParam.type, cmd, parameter);
                 if (!paramCheck.ok) {
                     if (isJsonMode()) {
@@ -482,7 +459,7 @@ Examples:
                             code: 2,
                             kind: 'usage',
                             message: paramCheck.error,
-                            context: { command: cmd, deviceType: cachedForParam.type, deviceId },
+                            context: { command: cmd, deviceType: cachedForParam.type, deviceId, humanHint: paramCheck.error },
                         });
                     }
                     else {
@@ -644,21 +621,52 @@ Examples:
   $ switchbot devices commands Robot --json
 `)
         .action((typeParts) => {
-        const type = typeParts.join(' ');
         try {
-            const match = findCatalogEntry(type);
-            if (!match) {
-                throw new UsageError(`No device type matches "${type}". Try 'switchbot devices types' to see the full list.`);
+            // First try the joined form so legacy multi-word unquoted input still
+            // works (`devices commands Air Conditioner` → "Air Conditioner"). If
+            // that doesn't match and every individual token resolves on its own,
+            // treat it as variadic and emit a section per type.
+            const joined = typeParts.join(' ');
+            const joinedMatch = findCatalogEntry(joined);
+            if (joinedMatch && !Array.isArray(joinedMatch)) {
+                if (isJsonMode()) {
+                    printJson(joinedMatch);
+                }
+                else {
+                    renderCatalogEntry(joinedMatch);
+                }
+                return;
             }
-            if (Array.isArray(match)) {
-                const types = match.map((m) => m.type).join(', ');
-                throw new UsageError(`"${type}" matches multiple types: ${types}. Be more specific.`);
+            if (typeParts.length > 1) {
+                const individualMatches = [];
+                for (const t of typeParts) {
+                    const m = findCatalogEntry(t);
+                    if (!m || Array.isArray(m)) {
+                        individualMatches.length = 0;
+                        break;
+                    }
+                    individualMatches.push(m);
+                }
+                if (individualMatches.length === typeParts.length) {
+                    if (isJsonMode()) {
+                        printJson(individualMatches);
+                    }
+                    else {
+                        individualMatches.forEach((entry, i) => {
+                            if (i > 0)
+                                console.log('');
+                            renderCatalogEntry(entry);
+                        });
+                    }
+                    return;
+                }
             }
-            if (isJsonMode()) {
-                printJson(match);
-                return;
+            if (!joinedMatch) {
+                throw new UsageError(`No device type matches "${joined}". Try 'switchbot devices types' to see the full list.`);
             }
-            renderCatalogEntry(match);
+            // joinedMatch is an ambiguous-match array here
+            const types = joinedMatch.map((m) => m.type).join(', ');
+            throw new UsageError(`"${joined}" matches multiple types: ${types}. Be more specific.`);
         }
         catch (error) {
             handleError(error);

package/dist/commands/expand.js

@@ -50,7 +50,7 @@ Examples:
   $ 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 --name "客厅空调" setAll --temp 26 --mode cool --fan low --power on
+  $ switchbot devices expand --name "Living Room AC" setAll --temp 26 --mode cool --fan low --power on
 `)
         .action(async (deviceIdArg, commandArg, options) => {
         let deviceId = '';

package/dist/commands/mcp.js

@@ -9,6 +9,7 @@ import { fetchDeviceList, fetchDeviceStatus, executeCommand, describeDevice, val
 import { fetchScenes, executeScene } from '../lib/scenes.js';
 import { findCatalogEntry } from '../devices/catalog.js';
 import { getCachedDevice } from '../devices/cache.js';
+import { validateParameter } from '../devices/param-validator.js';
 import { EventSubscriptionManager } from '../mcp/events-subscription.js';
 import { deviceHistoryStore } from '../mcp/device-history.js';
 import { queryDeviceHistory } from '../devices/history-query.js';
@@ -273,6 +274,10 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`,
         },
     }, async ({ deviceId, command, parameter, commandType, confirm, idempotencyKey, dryRun }) => {
         const effectiveType = commandType ?? 'command';
+        let effectiveParameter = parameter;
+        // stringifiedParam mirrors the CLI form that validateCommand /
+        // validateParameter expect — B-1 runs on the string representation.
+        const stringifiedParam = parameter === undefined ? undefined : typeof parameter === 'string' ? parameter : JSON.stringify(parameter);
         // dryRun early-return — no API call. We still preflight the deviceId
         // against the local cache so fabricated IDs don't silently pass
         // validation (bug #SYS-3). Dry-run is meant to catch bad inputs; a
@@ -286,10 +291,24 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`,
                     context: { deviceId },
                 });
             }
+            // R-2: run B-1 param validation in dry-run too, so dry-run doesn't
+            // falsely accept inputs the live API would reject.
+            if (effectiveType !== 'customize') {
+                const pv = validateParameter(cached.type, command, stringifiedParam);
+                if (!pv.ok) {
+                    return mcpError('usage', 2, pv.error, {
+                        hint: 'Dry-run rejected the parameter client-side; the API would reject it too.',
+                        context: { deviceType: cached.type, command, parameter: stringifiedParam },
+                    });
+                }
+                if (pv.normalized !== undefined) {
+                    effectiveParameter = pv.normalized;
+                }
+            }
             const wouldSend = {
                 deviceId,
                 command,
-                parameter: parameter ?? 'default',
+                parameter: effectiveParameter ?? 'default',
                 commandType: effectiveType,
             };
             const structured = { ok: true, dryRun: true, wouldSend };
@@ -332,16 +351,30 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`,
                 },
             });
         }
-        // stringifiedParam is what validateCommand expects to decide
-        // "no-parameter" conflicts — mirror the CLI behavior.
-        const stringifiedParam = parameter === undefined ? undefined : typeof parameter === 'string' ? parameter : JSON.stringify(parameter);
+        // validateCommand covers command existence + required/unexpected-parameter.
+        // stringifiedParam was computed once at the top of the handler so dry-run
+        // and live paths share the same shape.
         const validation = validateCommand(deviceId, command, stringifiedParam, effectiveType);
         if (!validation.ok) {
             return mcpError('usage', 2, validation.error.message, { hint: validation.error.hint, context: { validationKind: validation.error.kind } });
         }
+        // R-2: run B-1 client-side parameter validator (range/format checks).
+        // Customize commands (user-defined IR buttons) opt out — the catalog
+        // cannot know their expected shape.
+        if (effectiveType !== 'customize') {
+            const pv = validateParameter(typeName, command, stringifiedParam);
+            if (!pv.ok) {
+                return mcpError('usage', 2, pv.error, {
+                    context: { deviceType: typeName, command, parameter: stringifiedParam, validationKind: 'param-out-of-range' },
+                });
+            }
+            if (pv.normalized !== undefined) {
+                effectiveParameter = pv.normalized;
+            }
+        }
         let result;
         try {
-            result = await executeCommand(deviceId, command, parameter, effectiveType, undefined, {
+            result = await executeCommand(deviceId, command, effectiveParameter, effectiveType, undefined, {
                 idempotencyKey,
             });
         }

package/dist/commands/watch.js

@@ -75,7 +75,7 @@ Examples:
   $ switchbot devices watch ABC123 --fields battery,power --interval 1m
   $ switchbot devices watch ABC123 DEF456 --interval 30s --max 10
   $ switchbot devices watch ABC123 --json | jq 'select(.changed.power)'
-  $ switchbot devices watch --name "客厅空调" --interval 10s
+  $ switchbot devices watch --name "Living Room AC" --interval 10s
 `)
         .action(async (deviceIds, options) => {
         try {

package/dist/devices/param-validator.js

@@ -100,8 +100,178 @@ export function validateParameter(deviceType, command, raw) {
     if (deviceType.startsWith('Relay Switch') && command === 'setMode') {
         return validateRelaySetMode(raw);
     }
+    if (command === 'setBrightness' && isBrightnessDevice(deviceType)) {
+        return validateSetBrightness(raw);
+    }
+    if (command === 'setColor' && isColorDevice(deviceType)) {
+        return validateSetColor(raw);
+    }
+    if (command === 'setColorTemperature' && isColorDevice(deviceType)) {
+        return validateSetColorTemperature(raw);
+    }
     return { ok: true };
 }
+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');
+}
+function validateSetBrightness(raw) {
+    if (raw === undefined || raw === '' || raw === 'default') {
+        return {
+            ok: false,
+            error: `setBrightness requires an integer 1-100 (percent). Example: "50".`,
+        };
+    }
+    const trimmed = raw.trim();
+    if (!/^-?\d+$/.test(trimmed)) {
+        return {
+            ok: false,
+            error: `setBrightness must be an integer 1-100, got ${JSON.stringify(raw)}. ${hintBrightnessRetry()}`,
+        };
+    }
+    const n = Number(trimmed);
+    if (!Number.isInteger(n) || n < 1 || n > 100) {
+        return {
+            ok: false,
+            error: `setBrightness must be an integer 1-100, got "${raw}". ${hintBrightnessRetry()}`,
+        };
+    }
+    return { ok: true, normalized: String(n) };
+}
+function hintBrightnessRetry() {
+    return `Ask the user whether they meant a percentage (1-100). Example: "50".`;
+}
+// B-12: setColor accepts R:G:B, R,G,B, #RRGGBB, #RGB, or a small CSS named color
+// palette. All forms are normalized to `R:G:B` (the only wire shape SwitchBot
+// accepts) so the caller can POST the result unchanged.
+const NAMED_COLORS = {
+    red: [255, 0, 0],
+    green: [0, 128, 0],
+    lime: [0, 255, 0],
+    blue: [0, 0, 255],
+    yellow: [255, 255, 0],
+    cyan: [0, 255, 255],
+    magenta: [255, 0, 255],
+    white: [255, 255, 255],
+    black: [0, 0, 0],
+    orange: [255, 165, 0],
+    purple: [128, 0, 128],
+    pink: [255, 192, 203],
+    brown: [165, 42, 42],
+    grey: [128, 128, 128],
+    gray: [128, 128, 128],
+    warm: [255, 180, 100],
+};
+function validateSetColor(raw) {
+    if (raw === undefined || raw === '' || raw === 'default') {
+        return {
+            ok: false,
+            error: `setColor requires a color. Expected one of: "R:G:B" (e.g. "255:0:0"), "#RRGGBB" (e.g. "#FF0000"), "#RGB", "R,G,B", or a named color (${Object.keys(NAMED_COLORS).slice(0, 8).join(', ')}, ...).`,
+        };
+    }
+    const trimmed = raw.trim();
+    // Named color.
+    const named = NAMED_COLORS[trimmed.toLowerCase()];
+    if (named) {
+        return { ok: true, normalized: `${named[0]}:${named[1]}:${named[2]}` };
+    }
+    // Hex #RRGGBB or #RGB.
+    if (trimmed.startsWith('#')) {
+        const hex = trimmed.slice(1);
+        if (/^[0-9a-fA-F]{6}$/.test(hex)) {
+            const r = parseInt(hex.slice(0, 2), 16);
+            const g = parseInt(hex.slice(2, 4), 16);
+            const b = parseInt(hex.slice(4, 6), 16);
+            return { ok: true, normalized: `${r}:${g}:${b}` };
+        }
+        if (/^[0-9a-fA-F]{3}$/.test(hex)) {
+            const r = parseInt(hex[0] + hex[0], 16);
+            const g = parseInt(hex[1] + hex[1], 16);
+            const b = parseInt(hex[2] + hex[2], 16);
+            return { ok: true, normalized: `${r}:${g}:${b}` };
+        }
+        return {
+            ok: false,
+            error: `setColor "${raw}" is not valid hex. ${hintColorRetry()}`,
+        };
+    }
+    // R:G:B or R,G,B — pick whichever separator appears.
+    const sep = trimmed.includes(':') ? ':' : trimmed.includes(',') ? ',' : null;
+    if (!sep) {
+        return {
+            ok: false,
+            error: `setColor "${raw}" is not a recognized format. ${hintColorRetry()}`,
+        };
+    }
+    const parts = trimmed.split(sep).map((s) => s.trim());
+    if (parts.length !== 3) {
+        return {
+            ok: false,
+            error: `setColor expects 3 components (R${sep}G${sep}B), got ${parts.length} (${JSON.stringify(raw)}). ${hintColorRetry()}`,
+        };
+    }
+    const nums = [];
+    for (const p of parts) {
+        if (!/^-?\d+$/.test(p)) {
+            return {
+                ok: false,
+                error: `setColor component "${p}" is not an integer. ${hintColorRetry()}`,
+            };
+        }
+        const n = Number(p);
+        if (!Number.isInteger(n) || n < 0 || n > 255) {
+            return {
+                ok: false,
+                error: `setColor components must be integers 0-255, got "${p}". ${hintColorRetry()}`,
+            };
+        }
+        nums.push(n);
+    }
+    return { ok: true, normalized: `${nums[0]}:${nums[1]}:${nums[2]}` };
+}
+function hintColorRetry() {
+    return `Expected "R:G:B" (e.g. "255:0:0"), "#RRGGBB", "#RGB", "R,G,B", or a named color.`;
+}
+function validateSetColorTemperature(raw) {
+    if (raw === undefined || raw === '' || raw === 'default') {
+        return {
+            ok: false,
+            error: `setColorTemperature requires an integer Kelvin value 2700-6500. Example: "4000".`,
+        };
+    }
+    const trimmed = raw.trim();
+    if (!/^-?\d+$/.test(trimmed)) {
+        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) {
+        return {
+            ok: false,
+            error: `setColorTemperature must be an integer 2700-6500, got "${raw}".`,
+        };
+    }
+    return { ok: true, normalized: String(n) };
+}
 function validateAcSetAll(raw) {
     if (raw === undefined || raw === '' || raw === 'default') {
         return {

package/dist/utils/filter.js

@@ -9,8 +9,10 @@ export class FilterSyntaxError extends Error {
  *
  * Grammar (per clause, recognition order):
  *   1. key=/pattern/   → regex (case-insensitive); invalid regex throws.
- *   2. key~value       → substring (case-insensitive).
- *   3. key=value       → 'eq' op (substring; caller decides whether to treat
+ *   2. key!=value      → 'neq' op (negated substring; exact-negated for keys
+ *                        listed in matchClause's `exactKeys` option).
+ *   3. key~value       → substring (case-insensitive).
+ *   4. key=value       → 'eq' op (substring; caller decides whether to treat
  *                        as exact for specific keys via matchClause's
  *                        `exactKeys` option).
  *
@@ -24,7 +26,8 @@ export function parseFilterExpr(expr, allowedKeys) {
     const parts = expr.split(',').map((p) => p.trim()).filter((p) => p.length > 0);
     const clauses = [];
     for (const part of parts) {
-        const regexMatch = /^([^=~]+)=\/(.*)\/$/.exec(part);
+        const regexMatch = /^([^=~!]+)=\/(.*)\/$/.exec(part);
+        const neqIdx = part.indexOf('!=');
         const tildeIdx = part.indexOf('~');
         const eqIdx = part.indexOf('=');
         let key;
@@ -42,6 +45,11 @@ export function parseFilterExpr(expr, allowedKeys) {
                 throw new FilterSyntaxError(`Invalid regex in --filter "${part}": ${err.message}`);
             }
         }
+        else if (neqIdx !== -1 && (tildeIdx === -1 || neqIdx < tildeIdx)) {
+            key = part.slice(0, neqIdx).trim();
+            op = 'neq';
+            raw = part.slice(neqIdx + 2).trim();
+        }
         else if (tildeIdx !== -1 && (eqIdx === -1 || tildeIdx < eqIdx)) {
             key = part.slice(0, tildeIdx).trim();
             op = 'sub';
@@ -56,7 +64,7 @@ export function parseFilterExpr(expr, allowedKeys) {
             raw = part.slice(eqIdx + 1).trim();
         }
         else {
-            throw new FilterSyntaxError(`Invalid filter clause "${part}" — expected "<key>=<value>", "<key>~<value>", or "<key>=/<regex>/"`);
+            throw new FilterSyntaxError(`Invalid filter clause "${part}" — expected "<key>=<value>", "<key>!=<value>", "<key>~<value>", or "<key>=/<regex>/"`);
         }
         if (!key) {
             throw new FilterSyntaxError(`Empty key in filter clause "${part}"`);
@@ -80,10 +88,16 @@ export function parseFilterExpr(expr, allowedKeys) {
  *             `exactKeys`, which get case-insensitive exact comparison.
  *             Default `exactKeys` is `['category']` to preserve the existing
  *             list/batch behavior for that key.
+ * - `neq`   → logical inverse of `eq` (negated substring; exact-negated for
+ *             `exactKeys`). `undefined` candidates remain non-matching so a
+ *             `neq` clause does NOT accidentally match missing data.
  */
 export function matchClause(candidate, clause, options) {
-    if (candidate === undefined)
-        return false;
+    if (candidate === undefined) {
+        // Missing field: `neq` treats absence as "definitely not X"; everything
+        // else treats it as "no evidence — don't match".
+        return clause.op === 'neq';
+    }
     if (clause.op === 'regex') {
         return clause.regex.test(candidate);
     }
@@ -93,7 +107,11 @@ export function matchClause(candidate, clause, options) {
         return cLower.includes(vLower);
     }
     const exactKeys = options?.exactKeys ?? ['category'];
-    if (exactKeys.includes(clause.key)) {
+    const exact = exactKeys.includes(clause.key);
+    if (clause.op === 'neq') {
+        return exact ? cLower !== vLower : !cLower.includes(vLower);
+    }
+    if (exact) {
         return cLower === vLower;
     }
     return cLower.includes(vLower);

package/dist/utils/flags.js

@@ -8,6 +8,14 @@ function getFlagValue(...flagNames) {
         if (idx !== -1 && idx + 1 < process.argv.length) {
             return process.argv[idx + 1];
         }
+        // Also accept the `--flag=value` token form. Commander.js recognizes it at
+        // the option layer but global-flag scans like this one used to miss it,
+        // so `--format=json` silently fell back to the default (table).
+        const prefix = `${flag}=`;
+        const combined = process.argv.find((arg) => arg.startsWith(prefix));
+        if (combined !== undefined) {
+            return combined.slice(prefix.length);
+        }
     }
     return undefined;
 }
@@ -82,6 +90,22 @@ export function getBackoffStrategy() {
         return 'linear';
     return 'exponential';
 }
+/**
+ * Max retries on 5xx / gateway-timeout responses for idempotent (GET) reads.
+ * Default 2. `--no-retry` disables retries entirely. POSTs are not retried
+ * automatically — use --idempotency-key and let the server dedupe.
+ */
+export function getRetryOn5xx() {
+    if (process.argv.includes('--no-retry'))
+        return 0;
+    const v = getFlagValue('--retry-on-5xx');
+    if (v === undefined)
+        return 2;
+    const n = Number(v);
+    if (!Number.isFinite(n) || n < 0)
+        return 2;
+    return Math.floor(n);
+}
 /**
  * Whether local quota counting is disabled. Quota counting is best-effort
  * (see src/utils/quota.ts) — this lets scripts opt out entirely when even

package/dist/utils/name-resolver.js

@@ -117,9 +117,12 @@ export function resolveDeviceId(deviceId, nameQuery, opts = {}) {
             narrow.push('--category');
         if (!opts.room)
             narrow.push('--room');
+        const strategyHint = opts.strategy === 'fuzzy'
+            ? `pass --name-strategy=first to pick the best match`
+            : `pass --name-strategy=fuzzy or --name-strategy=first to pick the best match`;
         const hint = narrow.length > 0
-            ? `Narrow with ${narrow.join(' / ')} or use the deviceId directly, or pass --name-strategy first to pick the best match.`
-            : `Use the deviceId directly, or pass --name-strategy first to pick the best match.`;
+            ? `Narrow with ${narrow.join(' / ')}, refine the name, use the deviceId directly, or ${strategyHint}.`
+            : `Refine the name, use the deviceId directly, or ${strategyHint}.`;
         throw new StructuredUsageError(`"${nameQuery}" is ambiguous — ${candidates.length} devices match.`, {
             error: 'ambiguous_name_match',
             query: nameQuery,

package/dist/utils/output.js

@@ -44,6 +44,9 @@ function formatCell(cell, style) {
     return String(cell);
 }
 function renderMarkdownTable(headers, rows) {
+    if (rows.length === 0) {
+        return '_(empty)_';
+    }
     const head = `| ${headers.map(escapeMarkdownCell).join(' | ')} |`;
     const sep = `| ${headers.map(() => '---').join(' | ')} |`;
     const body = rows.map((r) => `| ${r
@@ -246,6 +249,32 @@ export function handleError(error) {
     }
     if (payload.kind === 'usage') {
         console.error(payload.message);
+        const ctx = payload.context;
+        if (ctx && Array.isArray(ctx.candidates) && ctx.candidates.length > 0) {
+            const names = ctx.candidates
+                .map((c) => {
+                if (typeof c === 'string')
+                    return c;
+                if (c && typeof c === 'object') {
+                    const o = c;
+                    const name = typeof o.name === 'string'
+                        ? o.name
+                        : typeof o.sceneName === 'string' ? o.sceneName : undefined;
+                    const id = typeof o.deviceId === 'string'
+                        ? o.deviceId
+                        : typeof o.sceneId === 'string' ? o.sceneId : typeof o.id === 'string' ? o.id : undefined;
+                    if (name && id)
+                        return `${name} (${id})`;
+                    return name ?? id ?? JSON.stringify(c);
+                }
+                return String(c);
+            })
+                .slice(0, 6);
+            console.error(`Did you mean: ${names.join(', ')}?`);
+        }
+        if (ctx && typeof ctx.hint === 'string') {
+            console.error(ctx.hint);
+        }
         process.exit(2);
     }
     if (payload.kind === 'guard') {

package/package.json

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