@switchbot/openapi-cli 2.5.1 → 2.6.0

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)
 
@@ -263,18 +264,18 @@ 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.
 
 #### Parameter formats
 
@@ -299,7 +300,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.
 
@@ -325,7 +328,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 +605,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 +629,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 +828,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/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';
@@ -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;
@@ -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/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.0",
   "description": "SwitchBot smart home CLI — control devices, run scenes, stream real-time events, and integrate AI agents via MCP. Full API v1.1 coverage.",
   "keywords": [
     "switchbot",