@switchbot/openapi-cli 2.5.0 → 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)
 
@@ -221,6 +222,12 @@ switchbot devices list --filter category=physical
 switchbot devices list --filter type=Bot
 switchbot devices list --filter name=living,category=physical
 
+# Filter operators: = (substring; exact for `category`), ~ (substring),
+# =/regex/ (case-insensitive regex). Clauses are AND-ed.
+switchbot devices list --filter 'name~living'
+switchbot devices list --filter 'type=/Hub.*/'
+switchbot devices list --filter 'name~office,type=/Bulb|Strip/'
+
 # Filter by family / room (family & room info requires the 'src: OpenClaw'
 # header, which this CLI sends on every request)
 switchbot devices list --json | jq '.deviceList[] | select(.familyName == "Home")'
@@ -255,6 +262,21 @@ switchbot devices commands "Smart Lock"
 switchbot devices commands curtain      # Case-insensitive, substring match
 ```
 
+#### Filter expressions — per-command reference
+
+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`), `!=` (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.
+
 #### Parameter formats
 
 `parameter` is optional — omit it for commands like `turnOn`/`turnOff` (auto-defaults to `"default"`).
@@ -278,7 +300,11 @@ 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.
 
 For the complete per-device command reference, see the [SwitchBot API docs](https://github.com/OpenWonderLabs/SwitchBotAPI#send-device-control-commands).
 
@@ -302,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
 
@@ -333,7 +359,7 @@ Stores local annotations (alias, hidden flag, notes) in `~/.switchbot/device-met
 ```bash
 # Send the same command to every device matching a filter
 switchbot devices batch turnOff --filter 'type=Bot'
-switchbot devices batch setBrightness 50 --filter 'type~=Light,family=Living'
+switchbot devices batch setBrightness 50 --filter 'type~Light,family=Living'
 
 # Explicit device IDs (comma-separated)
 switchbot devices batch turnOn --ids ID1,ID2,ID3
@@ -343,9 +369,18 @@ switchbot devices list --format=id --filter 'type=Bot' | switchbot devices batch
 
 # Destructive commands require --yes
 switchbot devices batch unlock --filter 'type=Smart Lock' --yes
+
+# Skip devices whose cached status is offline (default: off)
+switchbot devices batch turnOn --ids ID1,ID2 --skip-offline
+
+# --idempotency-key is an alias for --idempotency-key-prefix; both append -<deviceId>
+switchbot devices batch turnOn --ids ID1,ID2 --idempotency-key morning-lights
 ```
 
-Sends the same command to many devices in one run. Uses the same `--filter` expressions as `devices list`. Destructive commands (Smart Lock unlock, Garage Door Opener, etc.) require `--yes` to prevent accidents.
+Sends the same command to many devices in one run. Filter grammar matches `devices list` (`=` substring, `~` substring, `=/regex/` regex — clauses AND-ed); supported keys here are `type`, `family`, `room`, `category`. Destructive commands (Smart Lock unlock, Garage Door Opener, etc.) require `--yes` to prevent accidents.
+
+`--skip-offline` reads from the local status cache only (no new API calls);
+skipped devices appear under `summary.skipped` with `skippedReason:'offline'`.
 
 ### `scenes` — run manual scenes
 
@@ -390,6 +425,9 @@ switchbot events tail --filter deviceId=ABC123
 # Stop after 5 matching events
 switchbot events tail --filter 'type=WoMeter' --max 5
 
+# Stop after 10 minutes regardless of event count
+switchbot events tail --for 10m
+
 # Custom port / path
 switchbot events tail --port 8080 --path /hook --json
 ```
@@ -401,7 +439,7 @@ Output (one JSON line per matched event):
 { "t": "2024-01-01T12:00:00.000Z", "remote": "1.2.3.4:54321", "path": "/", "body": {...}, "matched": true }
 ```
 
-Filter keys: `deviceId=<id>`, `type=<deviceType>` (comma-separated for AND logic).
+Filter keys: `deviceId`, `type`. Operators: `=` (substring), `~` (substring), `=/regex/` (case-insensitive regex). Clauses comma-separated and AND-ed.
 
 #### `events mqtt-tail` — real-time MQTT stream
 
@@ -414,6 +452,9 @@ switchbot events mqtt-tail --topic 'switchbot/#'
 
 # Stop after 10 events
 switchbot events mqtt-tail --max 10 --json
+
+# Stop after a fixed duration (emits __session_start under --json before connect)
+switchbot events mqtt-tail --for 30s --json
 ```
 
 Connects to the SwitchBot MQTT service automatically using the same credentials configured for the REST API (`SWITCHBOT_TOKEN` + `SWITCHBOT_SECRET`). No additional MQTT configuration is required — the client certificates are provisioned on first use.
@@ -514,9 +555,12 @@ switchbot devices watch <deviceId>
 
 # Custom interval; emit every tick even when nothing changed
 switchbot devices watch <deviceId> --interval 10s --include-unchanged --json
+
+# Time-bounded: stop after 5 minutes instead of a fixed tick count
+switchbot devices watch <deviceId> --for 5m
 ```
 
-Output is a JSONL stream of status-change events (with `--json`) or a refreshed table. Use `--max <n>` to stop after N ticks.
+Output is a JSONL stream of status-change events (with `--json`) or a refreshed table. Use `--max <n>` to stop after N ticks, or `--for <duration>` to stop after an elapsed wall-clock window (e.g. `30s`, `1h`, `2d`). When both are set, whichever limit trips first wins.
 
 ### `mcp` — Model Context Protocol server
 
@@ -561,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)
@@ -583,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
 
@@ -781,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/agent-bootstrap.js

@@ -3,6 +3,7 @@ import { loadCache } from '../devices/cache.js';
 import { getEffectiveCatalog } from '../devices/catalog.js';
 import { readProfileMeta } from '../config.js';
 import { todayUsage, DAILY_QUOTA } from '../utils/quota.js';
+import { ALL_STRATEGIES } from '../utils/name-resolver.js';
 import { createRequire } from 'node:module';
 const require = createRequire(import.meta.url);
 const { version: pkgVersion } = require('../../package.json');
@@ -24,6 +25,7 @@ const QUICK_REFERENCE = {
     safety: ['--dry-run', '--idempotency-key <k>', '--audit-log', '--no-quota'],
     observability: ['doctor --json', 'quota status', 'cache status', 'events mqtt-tail'],
     history: ['history range <id> --since 7d', 'history stats <id>'],
+    meta: ['devices meta set <id> --alias <name>', 'devices meta list', 'devices meta get <id>'],
 };
 export function registerAgentBootstrapCommand(program) {
     program
@@ -97,6 +99,7 @@ Examples:
             identity: IDENTITY,
             quickReference: QUICK_REFERENCE,
             safetyTiers: SAFETY_TIERS,
+            nameStrategies: [...ALL_STRATEGIES],
             profile: meta
                 ? {
                     label: meta.label ?? null,

package/dist/commands/batch.js

@@ -1,11 +1,11 @@
 import { intArg, enumArg, stringArg } from '../utils/arg-parsers.js';
-import { printJson, isJsonMode, handleError, buildErrorPayload } from '../utils/output.js';
+import { printJson, isJsonMode, handleError, buildErrorPayload, UsageError, emitJsonError } from '../utils/output.js';
 import { fetchDeviceList, executeCommand, isDestructiveCommand, buildHubLocationMap, } from '../lib/devices.js';
 import { createClient } from '../api/client.js';
 import { parseFilter, applyFilter, FilterSyntaxError } from '../utils/filter.js';
 import { isDryRun } from '../utils/flags.js';
 import { DryRunSignal } from '../api/client.js';
-import { getCachedTypeMap } from '../devices/cache.js';
+import { getCachedTypeMap, getCachedDevice, loadStatusCache } from '../devices/cache.js';
 const DEFAULT_CONCURRENCY = 5;
 const COMMAND_TYPES = ['command', 'customize'];
 /**
@@ -101,6 +101,8 @@ export function registerBatchCommand(devices) {
         .option('--type <commandType>', '"command" (default) or "customize" for user-defined IR buttons', enumArg('--type', COMMAND_TYPES), 'command')
         .option('--stdin', 'Read deviceIds from stdin, one per line (same as trailing "-")')
         .option('--idempotency-key-prefix <prefix>', 'Client-supplied prefix for idempotency keys (key per device: <prefix>-<deviceId>). 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-prefix'))
+        .option('--idempotency-key <prefix>', 'Alias for --idempotency-key-prefix.', stringArg('--idempotency-key'))
+        .option('--skip-offline', 'Skip devices whose cached status is offline (no API call; cache miss → send as usual).')
         .addHelpText('after', `
 Targets are resolved in this priority order:
   1. --ids when present       (explicit deviceIds)
@@ -144,6 +146,14 @@ Examples:
         // Trailing "-" sentinel selects stdin mode.
         const extra = commandObj.args ?? [];
         const readStdin = Boolean(options.stdin) || extra.includes('-');
+        // Accept --idempotency-key as alias; reject when both forms are supplied.
+        if (options.idempotencyKey !== undefined && options.idempotencyKeyPrefix !== undefined) {
+            handleError(new UsageError('Use either --idempotency-key or --idempotency-key-prefix, not both.'));
+            return;
+        }
+        if (options.idempotencyKey !== undefined && options.idempotencyKeyPrefix === undefined) {
+            options.idempotencyKeyPrefix = options.idempotencyKey;
+        }
         let client;
         const getClient = () => (client ??= createClient());
         let resolved;
@@ -157,7 +167,7 @@ Examples:
         catch (error) {
             if (error instanceof FilterSyntaxError) {
                 if (isJsonMode()) {
-                    console.error(JSON.stringify({ error: { code: 2, kind: 'usage', message: error.message } }));
+                    emitJsonError({ code: 2, kind: 'usage', message: error.message });
                 }
                 else {
                     console.error(`Error: ${error.message}`);
@@ -166,7 +176,7 @@ Examples:
             }
             if (error instanceof Error && error.message.startsWith('No target devices')) {
                 if (isJsonMode()) {
-                    console.error(JSON.stringify({ error: { code: 2, kind: 'usage', message: error.message } }));
+                    emitJsonError({ code: 2, kind: 'usage', message: error.message });
                 }
                 else {
                     console.error(`Error: ${error.message}`);
@@ -179,7 +189,7 @@ Examples:
             const out = {
                 succeeded: [],
                 failed: [],
-                summary: { total: 0, ok: 0, failed: 0, skipped: 0, durationMs: 0 },
+                summary: { total: 0, ok: 0, failed: 0, skipped: 0, durationMs: 0, unverifiableCount: 0 },
             };
             if (isJsonMode())
                 printJson(out);
@@ -188,6 +198,24 @@ Examples:
             return;
         }
         const effectiveType = (options.type === 'customize' ? 'customize' : 'command');
+        // --skip-offline: preflight using the status cache (no network). Cache
+        // miss = send as usual; only definite "offline" cached entries skip.
+        const preSkipped = [];
+        if (options.skipOffline && resolved.ids.length > 0) {
+            const statusCache = loadStatusCache();
+            const kept = [];
+            for (const id of resolved.ids) {
+                const entry = statusCache.entries[id];
+                const online = entry?.body?.onlineStatus;
+                if (online === 'offline') {
+                    preSkipped.push({ deviceId: id, reason: 'offline' });
+                }
+                else {
+                    kept.push(id);
+                }
+            }
+            resolved = { ...resolved, ids: kept };
+        }
         // Pre-flight: identify destructive targets before spending API calls.
         const blockedForDestructive = [];
         for (const id of resolved.ids) {
@@ -202,15 +230,13 @@ Examples:
         if (blockedForDestructive.length > 0 && !options.yes) {
             if (isJsonMode()) {
                 const deviceIds = blockedForDestructive.map((b) => b.deviceId);
-                console.error(JSON.stringify({
-                    error: {
-                        code: 2,
-                        kind: 'guard',
-                        message: `Destructive command "${cmd}" requires --yes to run on ${blockedForDestructive.length} device(s).`,
-                        hint: 'Re-issue the call with --yes to proceed.',
-                        context: { command: cmd, deviceIds },
-                    },
-                }));
+                emitJsonError({
+                    code: 2,
+                    kind: 'guard',
+                    message: `Destructive command "${cmd}" requires --yes to run on ${blockedForDestructive.length} device(s).`,
+                    hint: 'Re-issue the call with --yes to proceed.',
+                    context: { command: cmd, deviceIds },
+                });
             }
             else {
                 console.error(`Refusing to run destructive command "${cmd}" on ${blockedForDestructive.length} device(s) without --yes:`);
@@ -324,14 +350,26 @@ Examples:
         const failed = outcomes.filter((o) => o.ok === false);
         const dryRunned = outcomes.filter((o) => o.ok === 'dry-run');
         const result = {
-            succeeded: succeeded.map((s) => ({
-                deviceId: s.deviceId,
-                result: s.result,
-                startedAt: s.startedAt,
-                finishedAt: s.finishedAt,
-                durationMs: s.durationMs,
-                replayed: s.replayed,
-            })),
+            succeeded: succeeded.map((s) => {
+                const isIr = getCachedDevice(s.deviceId)?.category === 'ir';
+                const entry = {
+                    deviceId: s.deviceId,
+                    result: s.result,
+                    startedAt: s.startedAt,
+                    finishedAt: s.finishedAt,
+                    durationMs: s.durationMs,
+                    replayed: s.replayed,
+                };
+                if (isIr) {
+                    entry.subKind = 'ir-no-feedback';
+                    entry.verification = {
+                        verifiable: false,
+                        reason: 'IR transmission is unidirectional; no receipt acknowledgment is possible.',
+                        suggestedFollowup: 'Confirm visible change manually or via a paired state sensor.',
+                    };
+                }
+                return entry;
+            }),
             failed: failed.map((f) => ({
                 deviceId: f.deviceId,
                 error: f.error,
@@ -339,12 +377,14 @@ Examples:
                 finishedAt: f.finishedAt,
                 durationMs: f.durationMs,
             })),
+            ...(preSkipped.length > 0 ? { skipped: preSkipped } : {}),
             summary: {
-                total: resolved.ids.length,
+                total: resolved.ids.length + preSkipped.length,
                 ok: succeeded.length,
                 failed: failed.length,
-                skipped: dryRunned.length,
+                skipped: dryRunned.length + preSkipped.length,
                 durationMs: Date.now() - startedAt,
+                unverifiableCount: succeeded.filter((s) => getCachedDevice(s.deviceId)?.category === 'ir').length,
                 schemaVersion: '1.1',
                 maxConcurrent: concurrency,
                 staggerMs,

package/dist/commands/cache.js

@@ -48,6 +48,10 @@ Examples:
         .command('show')
         .alias('status')
         .description('Summarize the cache files (paths, ages, entry counts)')
+        .addHelpText('after', `
+Cache TTL is computed from the 'lastUpdated' field inside the JSON, not the file mtime.
+touch does not invalidate; use 'cache clear' to force a refresh.
+`)
         .action(() => {
         const summary = describeCache();
         if (isJsonMode()) {
@@ -82,9 +86,21 @@ Examples:
         .command('clear')
         .description('Delete cache files')
         .option('--key <which>', 'Which cache to clear: "list" | "status" | "all" (default)', enumArg('--key', CACHE_KEYS), 'all')
+        .option('--status', 'Shorthand for --key status')
+        .option('--list', 'Shorthand for --key list')
         .action((options) => {
         try {
-            const key = options.key;
+            if (options.status && options.list) {
+                throw new UsageError('--status and --list are mutually exclusive.');
+            }
+            if ((options.status || options.list) && options.key !== 'all') {
+                throw new UsageError('--status / --list cannot be combined with --key.');
+            }
+            let key = options.key;
+            if (options.status)
+                key = 'status';
+            if (options.list)
+                key = 'list';
             if (!['list', 'status', 'all'].includes(key)) {
                 throw new UsageError(`Unknown --key "${key}". Expected: list, status, all.`);
             }

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 = {
@@ -22,6 +23,11 @@ const COMMAND_META = {
     'devices types': { mutating: false, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 20 },
     'devices commands': { mutating: false, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 20 },
     'devices watch': { mutating: false, consumesQuota: true, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 500 },
+    // devices meta (local metadata — no quota, no API call)
+    'devices meta set': { mutating: true, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'action', verifiability: 'local', typicalLatencyMs: 5 },
+    'devices meta get': { mutating: false, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 5 },
+    'devices meta list': { mutating: false, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 5 },
+    'devices meta clear': { mutating: true, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'action', verifiability: 'local', typicalLatencyMs: 5 },
     // devices: actions
     'devices command': { mutating: true, consumesQuota: true, idempotencySupported: true, agentSafetyTier: 'action', verifiability: 'deviceDependent', typicalLatencyMs: 800 },
     'devices batch': { mutating: true, consumesQuota: true, idempotencySupported: true, agentSafetyTier: 'action', verifiability: 'deviceDependent', typicalLatencyMs: 1200 },
@@ -144,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) => {
@@ -233,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,
@@ -243,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')