@switchbot/openapi-cli 2.3.0 → 2.5.0

package/dist/commands/capabilities.js

@@ -1,5 +1,67 @@
 import { getEffectiveCatalog } from '../devices/catalog.js';
 import { printJson } from '../utils/output.js';
+import { enumArg, stringArg } from '../utils/arg-parsers.js';
+const AGENT_GUIDE = {
+    safetyTiers: {
+        read: 'No state mutation; safe to call freely — does not consume quota unless noted.',
+        action: 'Mutates device or cloud state but is reversible and routine (turnOn, setColor).',
+        destructive: 'Hard to reverse / physical-world side effects (unlock, garage open, delete key). Requires explicit user confirmation.',
+    },
+    verifiability: {
+        local: 'Result is fully verifiable from the CLI return value itself.',
+        deviceConfirmed: 'Device returns an ack with an observable state field.',
+        deviceDependent: 'Verifiability depends on the specific device (IR is never verifiable).',
+        none: 'No feedback — e.g. IR transmission. Pair with an external sensor to confirm.',
+    },
+};
+const COMMAND_META = {
+    // devices: reads
+    'devices list': { mutating: false, consumesQuota: true, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 600 },
+    'devices status': { mutating: false, consumesQuota: true, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 500 },
+    'devices describe': { mutating: false, consumesQuota: true, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 600 },
+    '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: 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 },
+    // scenes
+    'scenes list': { mutating: false, consumesQuota: true, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 500 },
+    'scenes execute': { mutating: true, consumesQuota: true, idempotencySupported: false, agentSafetyTier: 'action', verifiability: 'deviceDependent', typicalLatencyMs: 1500 },
+    'scenes describe': { mutating: false, consumesQuota: true, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 500 },
+    // webhook
+    'webhook setup': { mutating: true, consumesQuota: true, idempotencySupported: false, agentSafetyTier: 'action', verifiability: 'local', typicalLatencyMs: 500 },
+    'webhook query': { mutating: false, consumesQuota: true, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 500 },
+    'webhook delete': { mutating: true, consumesQuota: true, idempotencySupported: false, agentSafetyTier: 'destructive', verifiability: 'local', typicalLatencyMs: 500 },
+    // quota
+    'quota status': { mutating: false, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 10 },
+    'quota show': { mutating: false, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 10 },
+    'quota reset': { mutating: true, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'action', verifiability: 'local', typicalLatencyMs: 10 },
+    // doctor / schema / capabilities / catalog / config / cache / events / history / plan
+    'doctor': { mutating: false, consumesQuota: true, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 900 },
+    'schema export': { mutating: false, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 20 },
+    'capabilities': { mutating: false, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 15 },
+    'catalog': { mutating: false, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 15 },
+    'config set-token': { mutating: true, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'destructive', verifiability: 'local', typicalLatencyMs: 5 },
+    'config show': { mutating: false, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 5 },
+    'config list-profiles': { mutating: false, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 5 },
+    'cache status': { mutating: false, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 5 },
+    'cache clear': { mutating: true, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'action', verifiability: 'local', typicalLatencyMs: 5 },
+    'events mqtt-tail': { mutating: false, consumesQuota: true, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 500 },
+    'history show': { mutating: false, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 20 },
+    'history replay': { mutating: true, consumesQuota: true, idempotencySupported: true, agentSafetyTier: 'action', verifiability: 'deviceDependent', typicalLatencyMs: 1000 },
+    'history range': { mutating: false, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 50 },
+    'history stats': { mutating: false, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 20 },
+    'history aggregate': { mutating: false, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 80 },
+    'plan run': { mutating: true, consumesQuota: true, idempotencySupported: true, agentSafetyTier: 'action', verifiability: 'deviceDependent', typicalLatencyMs: 2000 },
+    'plan validate': { mutating: false, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 10 },
+    'plan schema': { mutating: false, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 10 },
+    'completion': { mutating: false, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 5 },
+    'mcp serve': { mutating: false, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 10 },
+};
+function metaFor(command) {
+    return COMMAND_META[command] ?? null;
+}
 const IDENTITY = {
     product: 'SwitchBot',
     domain: 'IoT smart home device control',
@@ -27,84 +89,163 @@ const MCP_TOOLS = [
     'search_catalog',
     'account_overview',
     'get_device_history',
+    'query_device_history',
+    'aggregate_device_history',
 ];
+const IDEMPOTENCY_CONTRACT = {
+    flag: '--idempotency-key <key>',
+    windowSeconds: 60,
+    replayBehavior: 'Same (command, parameter, deviceId) within window → returns cached result with replayed:true.',
+    conflictBehavior: 'Same key + different (command, parameter) within window → exit 2, error:"idempotency_conflict".',
+    keyStorage: 'In-memory SHA-256 fingerprint; raw key never stored, no disk persistence.',
+    scope: 'Process-local. Replay + conflict apply within a single long-lived process (MCP session, devices batch, plan run, history replay). Independent CLI invocations do NOT share cache — each fresh `node` process starts empty.',
+    mcp: 'MCP send_command accepts the same idempotencyKey field with identical semantics.',
+};
+function enumerateLeaves(program, prefix = '') {
+    const out = [];
+    for (const cmd of program.commands) {
+        const full = prefix ? `${prefix} ${cmd.name()}` : cmd.name();
+        if (cmd.commands.length === 0) {
+            const meta = metaFor(full);
+            if (meta) {
+                out.push({ name: full, ...meta });
+            }
+            else {
+                // Unknown leaf → default to read-safe with a warning flag so agents notice.
+                out.push({
+                    name: full,
+                    mutating: false,
+                    consumesQuota: false,
+                    idempotencySupported: false,
+                    agentSafetyTier: 'read',
+                    verifiability: 'local',
+                    typicalLatencyMs: 50,
+                });
+            }
+        }
+        else {
+            out.push(...enumerateLeaves(cmd, full));
+        }
+    }
+    return out;
+}
+function projectObject(obj, fields) {
+    const out = {};
+    for (const f of fields) {
+        if (f in obj)
+            out[f] = obj[f];
+    }
+    return out;
+}
 export function registerCapabilitiesCommand(program) {
+    const SURFACES = ['cli', 'mcp', 'plan', 'mqtt', 'all'];
     program
         .command('capabilities')
         .description('Print a machine-readable manifest of CLI capabilities (for agent bootstrap)')
-        .option('--minimal', 'Omit per-subcommand flag details to reduce output size')
+        .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('--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) => {
+        const compact = Boolean(opts.minimal || opts.compact);
         const catalog = getEffectiveCatalog();
-        const allCommands = [
-            ...program.commands,
-            // Commander adds 'help' implicitly; include it explicitly so it appears in the manifest
-            { name: () => 'help', description: () => 'Display help for a command', commands: [], options: [], registeredArguments: [] },
-        ];
-        const commands = allCommands.map((c) => {
-            const entry = {
-                name: c.name(),
-                description: c.description(),
-            };
-            if (!opts.minimal) {
-                entry.subcommands = c.commands.map((s) => ({
-                    name: s.name(),
-                    description: s.description(),
-                    args: s.registeredArguments.map((a) => ({
-                        name: a.name(),
-                        required: a.required,
-                        variadic: a.variadic,
-                    })),
-                    flags: s.options.map((o) => ({
-                        flags: o.flags,
-                        description: o.description,
-                    })),
-                }));
+        const leaves = enumerateLeaves(program);
+        const fullCommands = compact
+            ? undefined
+            : [
+                ...program.commands,
+                { name: () => 'help', description: () => 'Display help for a command', commands: [], options: [], registeredArguments: [] },
+            ].map((c) => {
+                const full = c.name();
+                const entry = {
+                    name: full,
+                    description: c.description(),
+                };
+                entry.subcommands = c.commands.map((s) => {
+                    const leafName = `${full} ${s.name()}`;
+                    const meta = metaFor(leafName);
+                    return {
+                        name: s.name(),
+                        description: s.description(),
+                        args: s.registeredArguments.map((a) => ({
+                            name: a.name(),
+                            required: a.required,
+                            variadic: a.variadic,
+                        })),
+                        flags: s.options.map((o) => ({
+                            flags: o.flags,
+                            description: o.description,
+                        })),
+                        ...(meta ?? {}),
+                    };
+                });
+                const selfMeta = metaFor(full);
+                if (selfMeta)
+                    Object.assign(entry, selfMeta);
+                return entry;
+            });
+        const globalFlags = compact
+            ? undefined
+            : program.options.map((opt) => ({ flags: opt.flags, description: opt.description }));
+        const surfaces = {
+            mcp: {
+                entry: 'mcp serve',
+                protocol: 'stdio (default) or --port <n> for HTTP',
+                tools: MCP_TOOLS,
+                resources: ['switchbot://events'],
+                toolMeta: 'Each MCP tool mirrors the CLI leaf command metadata (mutating, consumesQuota, agentSafetyTier, idempotencySupported).',
+            },
+            mqtt: {
+                mode: 'consumer',
+                authSource: 'SWITCHBOT_TOKEN + SWITCHBOT_SECRET (auto-provisioned via POST /v1.1/iot/credential)',
+                cliCmd: 'events mqtt-tail',
+                mcpResource: 'switchbot://events',
+                protocol: 'MQTTS with TLS client certificates (AWS IoT)',
+            },
+            plan: {
+                schemaCmd: 'plan schema',
+                validateCmd: 'plan validate -',
+                runCmd: 'plan run -',
+            },
+            cli: {
+                catalogCmd: 'schema export',
+                discoveryCmd: 'capabilities',
+                healthCmd: 'doctor --json',
+                healthCmdSchemaVersion: 1,
+                helpFlag: '--help',
+                idempotencyContract: IDEMPOTENCY_CONTRACT,
+            },
+        };
+        const filteredSurfaces = (() => {
+            if (!opts.surface || opts.surface === 'all')
+                return surfaces;
+            const picked = {};
+            if (opts.surface in surfaces) {
+                picked[opts.surface] = surfaces[opts.surface];
             }
-            return entry;
-        });
-        const globalFlags = program.options.map((opt) => ({
-            flags: opt.flags,
-            description: opt.description,
-        }));
+            return picked;
+        })();
         const roles = [...new Set(catalog.map((e) => e.role ?? 'other'))].sort();
-        printJson({
+        const payload = {
             version: program.version(),
-            generatedAt: new Date().toISOString(),
+            schemaVersion: '2',
+            agentGuide: AGENT_GUIDE,
             identity: IDENTITY,
-            surfaces: {
-                mcp: {
-                    entry: 'mcp serve',
-                    protocol: 'stdio (default) or --port <n> for HTTP',
-                    tools: MCP_TOOLS,
-                    resources: ['switchbot://events'],
-                },
-                mqtt: {
-                    mode: 'consumer',
-                    authSource: 'SWITCHBOT_TOKEN + SWITCHBOT_SECRET (auto-provisioned via POST /v1.1/iot/credential)',
-                    cliCmd: 'events mqtt-tail',
-                    mcpResource: 'switchbot://events',
-                    protocol: 'MQTTS with TLS client certificates (AWS IoT)',
-                },
-                plan: {
-                    schemaCmd: 'plan schema',
-                    validateCmd: 'plan validate -',
-                    runCmd: 'plan run -',
-                },
-                cli: {
-                    catalogCmd: 'schema export',
-                    discoveryCmd: 'capabilities',
-                    healthCmd: 'doctor --json',
-                    helpFlag: '--help',
-                },
-            },
-            commands,
-            globalFlags,
+            surfaces: filteredSurfaces,
+            commands: compact ? leaves : fullCommands,
+            ...(globalFlags ? { globalFlags } : {}),
             catalog: {
                 typeCount: catalog.length,
                 roles,
                 destructiveCommandCount: catalog.reduce((n, e) => n + e.commands.filter((c) => c.destructive).length, 0),
                 readOnlyTypeCount: catalog.filter((e) => e.readOnly).length,
             },
-        });
+        };
+        if (!compact)
+            payload.generatedAt = new Date().toISOString();
+        const projected = opts.project
+            ? projectObject(payload, opts.project.split(',').map((s) => s.trim()).filter(Boolean))
+            : payload;
+        printJson(projected);
     });
 }

package/dist/commands/config.js

@@ -1,7 +1,9 @@
 import fs from 'node:fs';
+import readline from 'node:readline';
 import { execFileSync } from 'node:child_process';
 import { stringArg } from '../utils/arg-parsers.js';
-import { saveConfig, showConfig, listProfiles } from '../config.js';
+import { intArg } from '../utils/arg-parsers.js';
+import { saveConfig, showConfig, listProfiles, readProfileMeta } from '../config.js';
 import { isJsonMode, printJson } from '../utils/output.js';
 import chalk from 'chalk';
 function parseEnvFile(file) {
@@ -31,6 +33,62 @@ function readFromOp(ref) {
     const stdout = execFileSync('op', ['read', ref], { encoding: 'utf-8' });
     return stdout.trim();
 }
+// Replace raw token/secret positional slots in process.argv with "***" so
+// neither verbose traces nor crash dumps nor any later inspector observe them.
+function scrubArgvCredentials() {
+    const argv = process.argv;
+    for (let i = 2; i < argv.length - 2; i++) {
+        if (argv[i] === 'config' && argv[i + 1] === 'set-token') {
+            // Slots i+2 and i+3 (if not option flags) are token/secret.
+            for (const off of [2, 3]) {
+                const slot = i + off;
+                if (slot < argv.length && !argv[slot].startsWith('-')) {
+                    argv[slot] = '***';
+                }
+            }
+            return;
+        }
+    }
+}
+async function promptSecret(question) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stderr, terminal: true });
+    const stdoutAny = process.stdout;
+    const mutableStdout = process.stderr;
+    return new Promise((resolve) => {
+        process.stderr.write(question);
+        const stdin = process.stdin;
+        let answer = '';
+        const onData = (chunk) => {
+            const s = chunk.toString('utf-8');
+            for (const ch of s) {
+                if (ch === '\r' || ch === '\n') {
+                    stdin.removeListener('data', onData);
+                    if (stdin.setRawMode)
+                        stdin.setRawMode(false);
+                    stdin.pause();
+                    process.stderr.write('\n');
+                    rl.close();
+                    resolve(answer);
+                    return;
+                }
+                if (ch === '\u0003') {
+                    process.exit(130);
+                }
+                if (ch === '\u007f' || ch === '\b') {
+                    answer = answer.slice(0, -1);
+                    continue;
+                }
+                answer += ch;
+            }
+        };
+        if (stdin.setRawMode)
+            stdin.setRawMode(true);
+        stdin.resume();
+        stdin.on('data', onData);
+        void stdoutAny;
+        void mutableStdout;
+    });
+}
 export function registerConfigCommand(program) {
     const config = program
         .command('config')
@@ -53,18 +111,38 @@ Obtain your token/secret from the SwitchBot mobile app:
         .option('--from-env-file <path>', 'Read SWITCHBOT_TOKEN and SWITCHBOT_SECRET from a dotenv file', stringArg('--from-env-file'))
         .option('--from-op <tokenRef>', 'Read token via 1Password CLI (op read). Pair with --op-secret <ref>', stringArg('--from-op'))
         .option('--op-secret <secretRef>', '1Password reference for the secret, used with --from-op', stringArg('--op-secret'))
+        .option('--label <text>', 'Human-friendly label for this profile (shown in config show / list-profiles)', stringArg('--label'))
+        .option('--description <text>', 'Longer description, e.g. "home account" or "work devices"', stringArg('--description'))
+        .option('--daily-cap <n>', 'Local cap on SwitchBot API calls per UTC day for this profile', intArg('--daily-cap', { min: 1 }))
+        .option('--default-flags <csv>', 'Comma-separated flags auto-applied for this profile (e.g. "--audit-log")', stringArg('--default-flags'))
         .addHelpText('after', `
 Examples:
-  $ switchbot config set-token <token> <secret>
-  $ switchbot --profile work config set-token <token> <secret>
+  # Interactive (recommended) — credentials never touch shell history / ps listing
+  $ switchbot config set-token
+  Token: ****
+  Secret: ****
+
+  # Import from dotenv / 1Password (non-interactive, still safe)
   $ switchbot config set-token --from-env-file ./.env
   $ switchbot config set-token --from-op op://vault/switchbot/token --op-secret op://vault/switchbot/secret
 
+  # Advanced / non-interactive (DISCOURAGED — leaks to shell history)
+  $ switchbot config set-token <token> <secret>
+  $ switchbot --profile work config set-token <token> <secret>
+
 Files are written with mode 0600. Profiles live under ~/.switchbot/profiles/<name>.json.
 `)
         .action(async (tokenArg, secretArg, options) => {
         let token = tokenArg;
         let secret = secretArg;
+        const hadPositional = tokenArg !== undefined && secretArg !== undefined;
+        // Scrub early: commander has already parsed the values, so we can safely
+        // rewrite argv before anything else (verbose trace, crash dumps, …) sees it.
+        if (hadPositional) {
+            scrubArgvCredentials();
+            console.error('⚠ Passing token/secret as positional arguments is discouraged — they may be persisted in shell history, process listings, and agent logs.');
+            console.error('  Prefer: switchbot config set-token (interactive), --from-env-file, or --from-op.');
+        }
         if (options.fromEnvFile) {
             if (!fs.existsSync(options.fromEnvFile)) {
                 const msg = `--from-env-file: file not found: ${options.fromEnvFile}`;
@@ -107,8 +185,26 @@ Files are written with mode 0600. Profiles live under ~/.switchbot/profiles/<nam
                 process.exit(1);
             }
         }
+        // No credentials yet and stdin is a TTY → interactive prompt (safest path).
+        if ((!token || !secret) && !options.fromEnvFile && !options.fromOp && process.stdin.isTTY) {
+            if (isJsonMode()) {
+                const msg = 'Interactive mode cannot run under --json. Provide token/secret via --from-env-file, --from-op, or positional args.';
+                console.error(JSON.stringify({ error: { code: 2, kind: 'usage', message: msg } }));
+                process.exit(2);
+            }
+            try {
+                if (!token)
+                    token = (await promptSecret('Token: ')).trim();
+                if (!secret)
+                    secret = (await promptSecret('Secret: ')).trim();
+            }
+            catch {
+                console.error('Interactive prompt failed.');
+                process.exit(1);
+            }
+        }
         if (!token || !secret) {
-            const msg = 'Missing token/secret. Provide positional arguments or use --from-env-file / --from-op.';
+            const msg = 'Missing token/secret. Run interactively, or use --from-env-file / --from-op, or pass positional arguments (discouraged).';
             if (isJsonMode()) {
                 console.error(JSON.stringify({ error: { code: 2, kind: 'usage', message: msg } }));
             }
@@ -117,7 +213,19 @@ Files are written with mode 0600. Profiles live under ~/.switchbot/profiles/<nam
             }
             process.exit(2);
         }
-        saveConfig(token, secret);
+        saveConfig(token, secret, {
+            label: options.label,
+            description: options.description,
+            limits: options.dailyCap ? { dailyCap: Number.parseInt(options.dailyCap, 10) } : undefined,
+            defaults: options.defaultFlags
+                ? {
+                    flags: options.defaultFlags
+                        .split(',')
+                        .map((s) => s.trim())
+                        .filter(Boolean),
+                }
+                : undefined,
+        });
         if (isJsonMode()) {
             printJson({ ok: true, message: 'credentials saved' });
         }
@@ -133,18 +241,33 @@ Files are written with mode 0600. Profiles live under ~/.switchbot/profiles/<nam
     });
     config
         .command('list-profiles')
-        .description('List named profiles under ~/.switchbot/profiles/')
+        .description('List named profiles under ~/.switchbot/profiles/ (with labels and daily caps)')
         .action(() => {
         const profiles = listProfiles();
+        const enriched = profiles.map((p) => {
+            const meta = readProfileMeta(p);
+            return {
+                name: p,
+                label: meta?.label,
+                description: meta?.description,
+                dailyCap: meta?.limits?.dailyCap,
+            };
+        });
         if (isJsonMode()) {
-            printJson({ profiles });
+            printJson({ profiles: enriched });
             return;
         }
         if (profiles.length === 0) {
             console.log('No profiles. Create one with: switchbot --profile <name> config set-token ...');
             return;
         }
-        for (const p of profiles)
-            console.log(p);
+        for (const p of enriched) {
+            const bits = [p.name];
+            if (p.label)
+                bits.push(`— ${p.label}`);
+            if (p.dailyCap)
+                bits.push(`[dailyCap=${p.dailyCap}]`);
+            console.log(bits.join(' '));
+        }
     });
 }

package/dist/commands/devices.js

@@ -200,6 +200,10 @@ Examples:
         .description('Query the real-time status of a specific device')
         .argument('[deviceId]', 'Device ID from "devices list" (or use --name or --ids)')
         .option('--name <query>', 'Resolve device by fuzzy name instead of deviceId', stringArg('--name'))
+        .option('--name-strategy <s>', 'Name match strategy: exact|prefix|substring|fuzzy|first|require-unique (default: fuzzy)', stringArg('--name-strategy'))
+        .option('--name-type <type>', 'Narrow --name by device type (e.g. "Bot", "Color Bulb")', stringArg('--name-type'))
+        .option('--name-category <cat>', 'Narrow --name by category: physical|ir', enumArg('--name-category', ['physical', 'ir']))
+        .option('--name-room <room>', 'Narrow --name by room name (substring match)', stringArg('--name-room'))
         .option('--ids <list>', 'Comma-separated device IDs for batch status (incompatible with --name)', stringArg('--ids'))
         .addHelpText('after', `
 Status fields vary by device type. To discover them without a live call:
@@ -261,7 +265,12 @@ Examples:
                 }
                 return;
             }
-            const deviceId = resolveDeviceId(deviceIdArg, options.name);
+            const deviceId = resolveDeviceId(deviceIdArg, options.name, {
+                strategy: options.nameStrategy ?? 'fuzzy',
+                type: options.nameType,
+                category: options.nameCategory,
+                room: options.nameRoom,
+            });
             const body = await fetchDeviceStatus(deviceId);
             const fetchedAt = new Date().toISOString();
             const fmt = resolveFormat();
@@ -292,9 +301,13 @@ Examples:
         .argument('[cmd]', 'Command name, e.g. turnOn, turnOff, setColor, setBrightness, setAll, startClean')
         .argument('[parameter]', 'Command parameter. Omit for commands like turnOn/turnOff (defaults to "default"). Format depends on the command (see below).')
         .option('--name <query>', 'Resolve device by fuzzy name instead of deviceId', stringArg('--name'))
+        .option('--name-strategy <s>', 'Name match strategy: exact|prefix|substring|fuzzy|first|require-unique (default for command: require-unique)', stringArg('--name-strategy'))
+        .option('--name-type <type>', 'Narrow --name by device type (e.g. "Bot", "Color Bulb")', stringArg('--name-type'))
+        .option('--name-category <cat>', 'Narrow --name by category: physical|ir', enumArg('--name-category', ['physical', 'ir']))
+        .option('--name-room <room>', 'Narrow --name by room name (substring match)', stringArg('--name-room'))
         .option('--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('--idempotency-key <key>', 'Idempotency key for deduplication (60s window; same key replays cached result)', stringArg('--idempotency-key'))
+        .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', `
 ────────────────────────────────────────────────────────────────────────
 For the full list of commands a specific device supports — and their
@@ -367,7 +380,13 @@ Examples:
                 cmd = cmdArg;
                 effectiveDeviceIdArg = deviceIdArg;
             }
-            const deviceId = resolveDeviceId(effectiveDeviceIdArg, options.name);
+            const deviceId = resolveDeviceId(effectiveDeviceIdArg, options.name, {
+                // Mutating command → default require-unique (never silently pick between ambiguous matches).
+                strategy: options.nameStrategy ?? 'require-unique',
+                type: options.nameType,
+                category: options.nameCategory,
+                room: options.nameRoom,
+            });
             if (!getCachedDevice(deviceId)) {
                 console.error(`Note: device ${deviceId} is not in the local cache — run 'switchbot devices list' first to enable command validation.`);
             }
@@ -469,10 +488,19 @@ Examples:
             }
             const body = await executeCommand(deviceId, cmd, parsedParam, options.type, undefined, { idempotencyKey: options.idempotencyKey });
             const isIr = getCachedDevice(deviceId)?.category === 'ir';
+            const verification = isIr
+                ? {
+                    verifiable: false,
+                    reason: 'IR transmission is unidirectional; no receipt acknowledgment is possible.',
+                    suggestedFollowup: 'Confirm visible change manually or via a paired state sensor.',
+                }
+                : null;
             if (isJsonMode()) {
                 const result = { ok: true, command: cmd, deviceId };
-                if (isIr)
+                if (isIr) {
                     result.subKind = 'ir-no-feedback';
+                    result.verification = verification;
+                }
                 if (body && typeof body === 'object' && Object.keys(body).length > 0) {
                     Object.assign(result, body);
                 }
@@ -481,6 +509,7 @@ Examples:
             }
             if (isIr) {
                 console.log(`→ IR signal sent: ${cmd} (no feedback — fire-and-forget)`);
+                console.error('⚠ IR (unverifiable) — no receipt acknowledgment. Confirm state manually.');
             }
             else {
                 console.log(`✓ Command sent: ${cmd}`);
@@ -581,6 +610,10 @@ Examples:
         .description('Describe a device by ID: metadata + supported commands + status fields (1 API call)')
         .argument('[deviceId]', 'Target device ID (or use --name)')
         .option('--name <query>', 'Resolve device by fuzzy name instead of deviceId', stringArg('--name'))
+        .option('--name-strategy <s>', 'Name match strategy: exact|prefix|substring|fuzzy|first|require-unique (default: fuzzy)', stringArg('--name-strategy'))
+        .option('--name-type <type>', 'Narrow --name by device type', stringArg('--name-type'))
+        .option('--name-category <cat>', 'Narrow --name by category: physical|ir', enumArg('--name-category', ['physical', 'ir']))
+        .option('--name-room <room>', 'Narrow --name by room name (substring match)', stringArg('--name-room'))
         .option('--live', 'Also fetch live status values and merge them into capabilities (costs 1 extra API call)')
         .addHelpText('after', `
 Makes a GET /v1.1/devices call to look up the device's type, then prints its
@@ -612,7 +645,12 @@ Examples:
 `)
         .action(async (deviceIdArg, options) => {
         try {
-            const deviceId = resolveDeviceId(deviceIdArg, options.name);
+            const deviceId = resolveDeviceId(deviceIdArg, options.name, {
+                strategy: options.nameStrategy ?? 'fuzzy',
+                type: options.nameType,
+                category: options.nameCategory,
+                room: options.nameRoom,
+            });
             const result = await describeDevice(deviceId, options);
             const { device, isPhysical, typeName, controlType, catalog, capabilities, source, suggestedActions: picks } = result;
             if (isJsonMode()) {