@switchbot/openapi-cli 2.1.0 → 2.2.1

package/dist/commands/events.js

@@ -1,8 +1,18 @@
 import http from 'node:http';
 import { printJson, isJsonMode, handleError, UsageError } from '../utils/output.js';
+import { intArg, stringArg } from '../utils/arg-parsers.js';
 import { SwitchBotMqttClient } from '../mqtt/client.js';
 import { fetchMqttCredential } from '../mqtt/credential.js';
 import { tryLoadConfig } from '../config.js';
+import { SinkDispatcher } from '../sinks/dispatcher.js';
+import { StdoutSink } from '../sinks/stdout.js';
+import { FileSink } from '../sinks/file.js';
+import { WebhookSink } from '../sinks/webhook.js';
+import { OpenClawSink } from '../sinks/openclaw.js';
+import { TelegramSink } from '../sinks/telegram.js';
+import { HomeAssistantSink } from '../sinks/homeassistant.js';
+import { parseSinkEvent } from '../sinks/format.js';
+import { deviceHistoryStore } from '../mcp/device-history.js';
 const DEFAULT_PORT = 3000;
 const DEFAULT_PATH = '/';
 const MAX_BODY_BYTES = 1_000_000;
@@ -109,10 +119,10 @@ export function registerEventsCommand(program) {
     events
         .command('tail')
         .description('Run a local HTTP receiver and print incoming webhook events as JSONL')
-        .option('--port <n>', `Local port to listen on (default ${DEFAULT_PORT})`, String(DEFAULT_PORT))
-        .option('--path <p>', `HTTP path to match (default "${DEFAULT_PATH}"; use "*" for all paths)`, DEFAULT_PATH)
-        .option('--filter <expr>', 'Filter events, e.g. "deviceId=ABC123" or "type=Bot" (comma-separated)')
-        .option('--max <n>', 'Stop after N matching events (default: run until Ctrl-C)')
+        .option('--port <n>', `Local port to listen on (default ${DEFAULT_PORT})`, intArg('--port', { min: 1, max: 65535 }), String(DEFAULT_PORT))
+        .option('--path <p>', `HTTP path to match (default "${DEFAULT_PATH}"; use "*" for all paths)`, stringArg('--path'), DEFAULT_PATH)
+        .option('--filter <expr>', 'Filter events, e.g. "deviceId=ABC123" or "type=Bot" (comma-separated)', stringArg('--filter'))
+        .option('--max <n>', 'Stop after N matching events (default: run until Ctrl-C)', intArg('--max', { min: 1 }))
         .addHelpText('after', `
 SwitchBot posts events to a single webhook URL configured via:
   $ switchbot webhook setup https://<your-public-host>/<path>
@@ -190,8 +200,20 @@ Examples:
     events
         .command('mqtt-tail')
         .description('Subscribe to SwitchBot MQTT shadow events and stream them as JSONL')
-        .option('--topic <pattern>', 'MQTT topic filter (default: SwitchBot shadow topic from credential)')
-        .option('--max <n>', 'Stop after N events (default: run until Ctrl-C)')
+        .option('--topic <pattern>', 'MQTT topic filter (default: SwitchBot shadow topic from credential)', stringArg('--topic'))
+        .option('--max <n>', 'Stop after N events (default: run until Ctrl-C)', intArg('--max', { min: 1 }))
+        .option('--sink <type>', 'Output sink: stdout (default), file, webhook, openclaw, telegram, homeassistant (repeatable)', (val, prev) => [...prev, val], [])
+        .option('--sink-file <path>', 'File path for file sink', stringArg('--sink-file'))
+        .option('--webhook-url <url>', 'Webhook URL for webhook sink', stringArg('--webhook-url'))
+        .option('--openclaw-url <url>', 'OpenClaw gateway URL (default: http://localhost:18789)', stringArg('--openclaw-url'))
+        .option('--openclaw-token <token>', 'Bearer token for OpenClaw (or env OPENCLAW_TOKEN)', stringArg('--openclaw-token'))
+        .option('--openclaw-model <id>', 'OpenClaw agent model ID to route events to', stringArg('--openclaw-model'))
+        .option('--telegram-token <token>', 'Telegram bot token (or env TELEGRAM_TOKEN)', stringArg('--telegram-token'))
+        .option('--telegram-chat <id>', 'Telegram chat/channel ID to send messages to', stringArg('--telegram-chat'))
+        .option('--ha-url <url>', 'Home Assistant base URL (e.g. http://homeassistant.local:8123)', stringArg('--ha-url'))
+        .option('--ha-token <token>', 'HA long-lived access token (for REST event API)', stringArg('--ha-token'))
+        .option('--ha-webhook-id <id>', 'HA webhook ID (no auth; takes priority over --ha-token)', stringArg('--ha-webhook-id'))
+        .option('--ha-event-type <type>', 'HA event type for REST API (default: switchbot_event)', stringArg('--ha-event-type'))
         .addHelpText('after', `
 Connects to the SwitchBot MQTT service using your existing credentials
 (SWITCHBOT_TOKEN + SWITCHBOT_SECRET or ~/.switchbot/config.json).
@@ -200,10 +222,25 @@ No additional MQTT configuration required.
 Output (JSONL, one event per line):
   { "t": "<ISO>", "topic": "<mqtt-topic>", "payload": <parsed JSON or raw string> }
 
+Sink types (--sink, repeatable):
+  stdout             Print JSONL to stdout (default when no --sink given)
+  file               Append JSONL to --sink-file <path>
+  webhook            HTTP POST to --webhook-url <url>
+  openclaw           POST to OpenClaw via --openclaw-url / --openclaw-token / --openclaw-model
+  telegram           Send to Telegram via --telegram-token / --telegram-chat
+  homeassistant      POST to HA via --ha-url + --ha-webhook-id (or --ha-token)
+
+Device state is also persisted to ~/.switchbot/device-history/<deviceId>.json
+regardless of sink configuration.
+
 Examples:
   $ switchbot events mqtt-tail
-  $ switchbot events mqtt-tail --topic 'switchbot/#'
   $ switchbot events mqtt-tail --max 10 --json
+  $ switchbot events mqtt-tail --sink file --sink-file ~/.switchbot/events.jsonl
+  $ switchbot events mqtt-tail --sink openclaw --openclaw-token abc --openclaw-model home-agent
+  $ switchbot events mqtt-tail --sink telegram --telegram-token <token> --telegram-chat <chatId>
+  $ switchbot events mqtt-tail --sink homeassistant --ha-url http://ha.local:8123 --ha-webhook-id switchbot
+  $ switchbot events mqtt-tail --sink stdout --sink openclaw --openclaw-token abc --openclaw-model home
 `)
         .action(async (options) => {
         try {
@@ -211,20 +248,70 @@ Examples:
             if (maxEvents !== null && (!Number.isInteger(maxEvents) || maxEvents < 1)) {
                 throw new UsageError(`Invalid --max "${options.max}". Must be a positive integer.`);
             }
-            let creds;
             const loaded = tryLoadConfig();
             if (!loaded) {
                 throw new UsageError('No credentials found. Run \'switchbot config set-token\' or set SWITCHBOT_TOKEN and SWITCHBOT_SECRET.');
             }
-            creds = loaded;
+            const sinkTypes = options.sink;
+            let dispatcher = null;
+            if (sinkTypes.length > 0) {
+                const sinks = sinkTypes.map((type) => {
+                    switch (type) {
+                        case 'stdout':
+                            return new StdoutSink();
+                        case 'file': {
+                            if (!options.sinkFile)
+                                throw new UsageError('--sink file requires --sink-file <path>');
+                            return new FileSink(options.sinkFile);
+                        }
+                        case 'webhook': {
+                            if (!options.webhookUrl)
+                                throw new UsageError('--sink webhook requires --webhook-url <url>');
+                            return new WebhookSink(options.webhookUrl);
+                        }
+                        case 'openclaw': {
+                            const token = options.openclawToken ?? process.env.OPENCLAW_TOKEN;
+                            if (!token)
+                                throw new UsageError('--sink openclaw requires --openclaw-token or env OPENCLAW_TOKEN');
+                            if (!options.openclawModel)
+                                throw new UsageError('--sink openclaw requires --openclaw-model <id>');
+                            return new OpenClawSink({ url: options.openclawUrl, token, model: options.openclawModel });
+                        }
+                        case 'telegram': {
+                            const token = options.telegramToken ?? process.env.TELEGRAM_TOKEN;
+                            if (!token)
+                                throw new UsageError('--sink telegram requires --telegram-token or env TELEGRAM_TOKEN');
+                            if (!options.telegramChat)
+                                throw new UsageError('--sink telegram requires --telegram-chat <id>');
+                            return new TelegramSink({ token, chatId: options.telegramChat });
+                        }
+                        case 'homeassistant': {
+                            if (!options.haUrl)
+                                throw new UsageError('--sink homeassistant requires --ha-url <url>');
+                            if (!options.haWebhookId && !options.haToken) {
+                                throw new UsageError('--sink homeassistant requires --ha-webhook-id or --ha-token');
+                            }
+                            return new HomeAssistantSink({
+                                url: options.haUrl,
+                                token: options.haToken,
+                                webhookId: options.haWebhookId,
+                                eventType: options.haEventType,
+                            });
+                        }
+                        default:
+                            throw new UsageError(`Unknown --sink type "${type}". Supported: stdout, file, webhook, openclaw, telegram, homeassistant`);
+                    }
+                });
+                dispatcher = new SinkDispatcher(sinks);
+            }
             if (!isJsonMode()) {
                 console.error('Fetching MQTT credentials from SwitchBot service…');
             }
-            const credential = await fetchMqttCredential(creds.token, creds.secret);
+            const credential = await fetchMqttCredential(loaded.token, loaded.secret);
             const topic = options.topic ?? credential.topics.status;
             let eventCount = 0;
             const ac = new AbortController();
-            const client = new SwitchBotMqttClient(credential, () => fetchMqttCredential(creds.token, creds.secret));
+            const client = new SwitchBotMqttClient(credential, () => fetchMqttCredential(loaded.token, loaded.secret));
             const unsub = client.onMessage((msgTopic, payload) => {
                 let parsed;
                 try {
@@ -233,18 +320,43 @@ Examples:
                 catch {
                     parsed = payload.toString('utf-8');
                 }
-                const record = { t: new Date().toISOString(), topic: msgTopic, payload: parsed };
-                if (isJsonMode()) {
-                    printJson(record);
+                const t = new Date().toISOString();
+                if (dispatcher) {
+                    const { deviceId, deviceType, text } = parseSinkEvent(parsed);
+                    const sinkEvent = { t, topic: msgTopic, deviceId, deviceType, payload: parsed, text };
+                    deviceHistoryStore.record(deviceId, msgTopic, deviceType, parsed, t);
+                    dispatcher.dispatch(sinkEvent).catch(() => { });
                 }
                 else {
-                    console.log(JSON.stringify(record));
+                    // Default behavior: record history + print to stdout
+                    const { deviceId, deviceType } = parseSinkEvent(parsed);
+                    deviceHistoryStore.record(deviceId, msgTopic, deviceType, parsed, t);
+                    const record = { t, topic: msgTopic, payload: parsed };
+                    if (isJsonMode()) {
+                        printJson(record);
+                    }
+                    else {
+                        console.log(JSON.stringify(record));
+                    }
                 }
                 eventCount++;
                 if (maxEvents !== null && eventCount >= maxEvents) {
                     ac.abort();
                 }
             });
+            let mqttFailed = false;
+            const unsubState = client.onStateChange((state) => {
+                if (!isJsonMode()) {
+                    console.error(`[${new Date().toLocaleTimeString()}] MQTT state: ${state}`);
+                }
+                if (state === 'failed') {
+                    mqttFailed = true;
+                    if (!isJsonMode()) {
+                        console.error('MQTT connection failed permanently (credential expired or reconnect exhausted) — exiting.');
+                    }
+                    ac.abort();
+                }
+            });
             await client.connect();
             client.subscribe(topic);
             if (!isJsonMode()) {
@@ -255,12 +367,18 @@ Examples:
                     process.removeListener('SIGINT', cleanup);
                     process.removeListener('SIGTERM', cleanup);
                     unsub();
+                    unsubState();
+                    dispatcher?.close().catch(() => { });
                     client.disconnect().then(resolve).catch(resolve);
                 };
                 process.once('SIGINT', cleanup);
                 process.once('SIGTERM', cleanup);
                 ac.signal.addEventListener('abort', cleanup, { once: true });
             });
+            if (mqttFailed) {
+                // Surface as a runtime error so supervisors (pm2, systemd) can restart.
+                process.exit(1);
+            }
         }
         catch (error) {
             handleError(error);

package/dist/commands/expand.js

@@ -1,7 +1,9 @@
+import { intArg, stringArg } from '../utils/arg-parsers.js';
 import { handleError, isJsonMode, printJson, UsageError } from '../utils/output.js';
 import { getCachedDevice } from '../devices/cache.js';
 import { executeCommand, isDestructiveCommand, getDestructiveReason } from '../lib/devices.js';
 import { isDryRun } from '../utils/flags.js';
+import { resolveDeviceId } from '../utils/name-resolver.js';
 import { DryRunSignal } from '../api/client.js';
 // ---- Mapping tables --------------------------------------------------------
 const AC_MODE_MAP = { auto: 1, cool: 2, dry: 3, fan: 4, heat: 5 };
@@ -85,16 +87,17 @@ export function registerExpandCommand(devices) {
     devices
         .command('expand')
         .description('Send a command with semantic flags instead of raw positional parameters')
-        .argument('<deviceId>', 'Target device ID from "devices list"')
-        .argument('<command>', 'Command name: setAll (AC), setPosition (Curtain/Blind Tilt), setMode (Relay Switch 2)')
-        .option('--temp <celsius>', 'AC setAll: temperature in Celsius (16-30)')
-        .option('--mode <mode>', 'AC: auto|cool|dry|fan|heat  Curtain: default|performance|silent  Relay: toggle|edge|detached|momentary')
-        .option('--fan <speed>', 'AC setAll: fan speed auto|low|mid|high')
-        .option('--power <state>', 'AC setAll: on|off')
-        .option('--position <percent>', 'Curtain setPosition: 0-100 (0=open, 100=closed)')
-        .option('--direction <dir>', 'Blind Tilt setPosition: up|down')
-        .option('--angle <percent>', 'Blind Tilt setPosition: 0-100 (0=closed, 100=open)')
-        .option('--channel <n>', 'Relay Switch 2 setMode: channel 1 or 2')
+        .argument('[deviceId]', 'Target device ID from "devices list" (or use --name)')
+        .argument('[command]', 'Command name: setAll (AC), setPosition (Curtain/Blind Tilt), setMode (Relay Switch 2)')
+        .option('--name <query>', 'Resolve device by fuzzy name instead of deviceId', stringArg('--name'))
+        .option('--temp <celsius>', 'AC setAll: temperature in Celsius (16-30)', intArg('--temp', { min: 16, max: 30 }))
+        .option('--mode <mode>', 'AC: auto|cool|dry|fan|heat  Curtain: default|performance|silent  Relay: toggle|edge|detached|momentary', stringArg('--mode'))
+        .option('--fan <speed>', 'AC setAll: fan speed auto|low|mid|high', stringArg('--fan'))
+        .option('--power <state>', 'AC setAll: on|off', stringArg('--power'))
+        .option('--position <percent>', 'Curtain setPosition: 0-100 (0=open, 100=closed)', intArg('--position', { min: 0, max: 100 }))
+        .option('--direction <dir>', 'Blind Tilt setPosition: up|down', stringArg('--direction'))
+        .option('--angle <percent>', 'Blind Tilt setPosition: 0-100 (0=closed, 100=open)', intArg('--angle', { min: 0, max: 100 }))
+        .option('--channel <n>', 'Relay Switch 2 setMode: channel 1 or 2', intArg('--channel', { min: 1, max: 2 }))
         .option('--yes', 'Confirm destructive commands')
         .addHelpText('after', `
 Translates semantic flags into the wire parameter format, then sends the command.
@@ -123,9 +126,24 @@ Examples:
   $ switchbot devices expand <blindId>   setPosition  --direction up --angle 50
   $ switchbot devices expand <relayId>   setMode      --channel 1 --mode edge
   $ switchbot devices expand <acId>      setAll       --temp 22 --mode heat --fan auto --power on --dry-run
+  $ switchbot devices expand --name "客厅空调" setAll --temp 26 --mode cool --fan low --power on
 `)
-        .action(async (deviceId, command, options) => {
+        .action(async (deviceIdArg, commandArg, options) => {
+        let deviceId = '';
+        let command = '';
         try {
+            // When --name is provided, Commander assigns the first positional to deviceIdArg
+            // and leaves commandArg undefined. Detect and shift.
+            let effectiveDeviceIdArg = deviceIdArg;
+            let effectiveCommand = commandArg;
+            if (options.name && deviceIdArg && !commandArg) {
+                effectiveCommand = deviceIdArg;
+                effectiveDeviceIdArg = undefined;
+            }
+            deviceId = resolveDeviceId(effectiveDeviceIdArg, options.name);
+            if (!effectiveCommand)
+                throw new UsageError('A command argument is required (setAll, setPosition, setMode).');
+            command = effectiveCommand;
             const cached = getCachedDevice(deviceId);
             const deviceType = cached?.type ?? '';
             let parameter;

package/dist/commands/history.js

@@ -1,5 +1,6 @@
 import path from 'node:path';
 import os from 'node:os';
+import { intArg, stringArg } from '../utils/arg-parsers.js';
 import { printJson, isJsonMode, handleError } from '../utils/output.js';
 import { readAudit } from '../utils/audit.js';
 import { executeCommand } from '../lib/devices.js';
@@ -21,8 +22,8 @@ Examples:
     history
         .command('show')
         .description('Print recent audit entries')
-        .option('--file <path>', `Path to the audit log (default ${DEFAULT_AUDIT})`)
-        .option('--limit <n>', 'Show only the last N entries')
+        .option('--file <path>', `Path to the audit log (default ${DEFAULT_AUDIT})`, stringArg('--file'))
+        .option('--limit <n>', 'Show only the last N entries', intArg('--limit', { min: 1 }))
         .action((options) => {
         const file = options.file ?? DEFAULT_AUDIT;
         const entries = readAudit(file);
@@ -52,7 +53,7 @@ Examples:
         .command('replay')
         .description('Re-run a recorded command by its 1-indexed position')
         .argument('<index>', 'Entry index (1 = oldest; as shown by "history show")')
-        .option('--file <path>', `Path to the audit log (default ${DEFAULT_AUDIT})`)
+        .option('--file <path>', `Path to the audit log (default ${DEFAULT_AUDIT})`, stringArg('--file'))
         .addHelpText('after', `
 Dry-run-honouring: pass --dry-run on the parent command to preview without
 sending the actual call. Errors from the recorded entry are NOT replayed —

package/dist/commands/mcp.js

@@ -2,12 +2,14 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { z } from 'zod';
+import { intArg, stringArg } from '../utils/arg-parsers.js';
 import { handleError, isJsonMode } from '../utils/output.js';
 import { fetchDeviceList, fetchDeviceStatus, executeCommand, describeDevice, validateCommand, isDestructiveCommand, getDestructiveReason, searchCatalog, DeviceNotFoundError, toMcpDescribeShape, toMcpDeviceListShape, toMcpIrDeviceShape, } from '../lib/devices.js';
 import { fetchScenes, executeScene } from '../lib/scenes.js';
 import { findCatalogEntry } from '../devices/catalog.js';
 import { getCachedDevice } from '../devices/cache.js';
 import { EventSubscriptionManager } from '../mcp/events-subscription.js';
+import { deviceHistoryStore } from '../mcp/device-history.js';
 import { todayUsage } from '../utils/quota.js';
 import { describeCache } from '../devices/cache.js';
 import { withRequestContext } from '../lib/request-context.js';
@@ -110,6 +112,40 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`,
             structuredContent: { status: body },
         };
     });
+    // ---- get_device_history ----------------------------------------------------
+    server.registerTool('get_device_history', {
+        title: 'Get locally-persisted device state history',
+        description: 'Return device state history recorded from MQTT events (persisted to ~/.switchbot/device-history/). ' +
+            'No API call — zero quota cost. Use when you need recent historical readings or want to avoid a live API call. ' +
+            'Omit deviceId to list all devices with stored history.',
+        inputSchema: {
+            deviceId: z.string().optional().describe('Device MAC address (deviceId). Omit to list all devices with history.'),
+            limit: z.number().int().min(1).max(100).optional().describe('Max history entries to return (default 20, max 100)'),
+        },
+        outputSchema: {
+            deviceId: z.string().optional(),
+            latest: z.unknown().optional(),
+            history: z.array(z.unknown()).optional(),
+            devices: z.array(z.object({ deviceId: z.string(), latest: z.unknown() })).optional(),
+        },
+    }, async ({ deviceId, limit }) => {
+        if (deviceId) {
+            const latest = deviceHistoryStore.getLatest(deviceId);
+            const history = deviceHistoryStore.getHistory(deviceId, limit ?? 20);
+            const result = { deviceId, latest, history };
+            return {
+                content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+                structuredContent: result,
+            };
+        }
+        const ids = deviceHistoryStore.listDevices();
+        const devices = ids.map((id) => ({ deviceId: id, latest: deviceHistoryStore.getLatest(id) }));
+        const result = { devices };
+        return {
+            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+            structuredContent: result,
+        };
+    });
     // ---- send_command ---------------------------------------------------------
     server.registerTool('send_command', {
         title: 'Send a control command to a device',
@@ -454,11 +490,11 @@ Inspect locally:
     mcp
         .command('serve')
         .description('Start the MCP server on stdio (default) or HTTP (--port)')
-        .option('--port <n>', 'Listen on HTTP instead of stdio (Streamable HTTP transport)')
-        .option('--bind <host>', 'IP address to bind (default 127.0.0.1; use 0.0.0.0 to accept external connections)', '127.0.0.1')
-        .option('--auth-token <token>', 'Bearer token for HTTP requests (required for --bind 0.0.0.0; falls back to SWITCHBOT_MCP_TOKEN env var)')
-        .option('--cors-origin <url>', 'Allowed CORS origin(s) for HTTP (repeatable)')
-        .option('--rate-limit <n>', 'Max requests per minute per profile (default 60)', '60')
+        .option('--port <n>', 'Listen on HTTP instead of stdio (Streamable HTTP transport)', intArg('--port', { min: 1, max: 65535 }))
+        .option('--bind <host>', 'IP address to bind (default 127.0.0.1; use 0.0.0.0 to accept external connections)', stringArg('--bind'), '127.0.0.1')
+        .option('--auth-token <token>', 'Bearer token for HTTP requests (required for --bind 0.0.0.0; falls back to SWITCHBOT_MCP_TOKEN env var)', stringArg('--auth-token'))
+        .option('--cors-origin <url>', 'Allowed CORS origin(s) for HTTP (repeatable)', stringArg('--cors-origin'))
+        .option('--rate-limit <n>', 'Max requests per minute per profile (default 60)', intArg('--rate-limit', { min: 1 }), '60')
         .action(async (options) => {
         try {
             if (options.port) {

package/dist/commands/plan.js

@@ -210,10 +210,18 @@ Workflow:
             process.exit(2);
         }
         if (isJsonMode()) {
-            printJson({ valid: true, steps: result.plan.steps.length });
+            const out = { valid: true, steps: result.plan.steps.length };
+            if (result.plan.steps.length === 0)
+                out.warning = 'plan has no steps — nothing will execute';
+            printJson(out);
         }
         else {
-            console.log(`✓ plan valid (${result.plan.steps.length} step${result.plan.steps.length === 1 ? '' : 's'})`);
+            if (result.plan.steps.length === 0) {
+                console.log('✓ plan valid — but 0 steps: nothing will execute');
+            }
+            else {
+                console.log(`✓ plan valid (${result.plan.steps.length} step${result.plan.steps.length === 1 ? '' : 's'})`);
+            }
         }
     });
     plan

package/dist/commands/scenes.js

@@ -27,7 +27,7 @@ Examples:
                 printJson(scenes);
                 return;
             }
-            renderRows(['sceneId', 'sceneName'], scenes.map((s) => [s.sceneId, s.sceneName]), fmt, resolveFields());
+            renderRows(['sceneId', 'sceneName'], scenes.map((s) => [s.sceneId, s.sceneName]), fmt, resolveFields(), { id: 'sceneId', name: 'sceneName' });
             if (fmt === 'table' && scenes.length === 0) {
                 console.log('No scenes found');
             }

package/dist/commands/schema.js

@@ -1,3 +1,4 @@
+import { enumArg, stringArg } from '../utils/arg-parsers.js';
 import { printJson } from '../utils/output.js';
 import { getEffectiveCatalog } from '../devices/catalog.js';
 function toSchemaEntry(e) {
@@ -24,15 +25,17 @@ function toSchemaCommand(c) {
     };
 }
 export function registerSchemaCommand(program) {
+    const ROLES = ['lighting', 'security', 'sensor', 'climate', 'media', 'cleaning', 'curtain', 'fan', 'power', 'hub', 'other'];
+    const CATEGORIES = ['physical', 'ir'];
     const schema = program
         .command('schema')
         .description('Export the device catalog as structured JSON (for agent prompts / tooling)');
     schema
         .command('export')
         .description('Print the full catalog as structured JSON (one object per type)')
-        .option('--type <type>', 'Restrict to a single device type (e.g. "Strip Light")')
-        .option('--role <role>', 'Restrict to a functional role: lighting, security, sensor, climate, media, cleaning, curtain, fan, power, hub, other')
-        .option('--category <cat>', 'Restrict to "physical" or "ir"')
+        .option('--type <type>', 'Restrict to a single device type (e.g. "Strip Light")', stringArg('--type'))
+        .option('--role <role>', 'Restrict to a functional role: lighting, security, sensor, climate, media, cleaning, curtain, fan, power, hub, other', enumArg('--role', ROLES))
+        .option('--category <cat>', 'Restrict to "physical" or "ir"', enumArg('--category', CATEGORIES))
         .addHelpText('after', `
 Output is always JSON (this command ignores --format). The output is a
 catalog export — not a formal JSON Schema standard document — suitable for

package/dist/commands/watch.js

@@ -2,7 +2,9 @@ import { printJson, isJsonMode, handleError, UsageError } from '../utils/output.
 import { fetchDeviceStatus } from '../lib/devices.js';
 import { getCachedDevice } from '../devices/cache.js';
 import { parseDurationToMs, getFields } from '../utils/flags.js';
+import { intArg, durationArg, stringArg } from '../utils/arg-parsers.js';
 import { createClient } from '../api/client.js';
+import { resolveDeviceId } from '../utils/name-resolver.js';
 const DEFAULT_INTERVAL_MS = 30_000;
 const MIN_INTERVAL_MS = 1_000;
 function diff(prev, next, fields) {
@@ -55,9 +57,10 @@ export function registerWatchCommand(devices) {
     devices
         .command('watch')
         .description('Poll device status on an interval and emit field-level changes (JSONL)')
-        .argument('<deviceId...>', 'One or more deviceIds to watch')
-        .option('--interval <dur>', `Polling interval: "30s", "1m", "500ms", ... (default 30s, min ${MIN_INTERVAL_MS / 1000}s)`, '30s')
-        .option('--max <n>', 'Stop after N ticks (default: run until Ctrl-C)')
+        .argument('[deviceId...]', 'One or more deviceIds to watch (or use --name for one device)')
+        .option('--name <query>', 'Resolve one device by fuzzy name (combined with any positional IDs)', stringArg('--name'))
+        .option('--interval <dur>', `Polling interval: "30s", "1m", "500ms", ... (default 30s, min ${MIN_INTERVAL_MS / 1000}s)`, durationArg('--interval'), '30s')
+        .option('--max <n>', 'Stop after N ticks (default: run until Ctrl-C)', intArg('--max', { min: 1 }))
         .option('--include-unchanged', 'Emit a tick even when no field changed')
         .addHelpText('after', `
 Each poll emits one JSON line per deviceId with the shape:
@@ -71,9 +74,18 @@ Examples:
   $ switchbot devices watch ABC123 --fields battery,power --interval 1m
   $ switchbot devices watch ABC123 DEF456 --interval 30s --max 10
   $ switchbot devices watch ABC123 --json | jq 'select(.changed.power)'
+  $ switchbot devices watch --name "客厅空调" --interval 10s
 `)
         .action(async (deviceIds, options) => {
         try {
+            const allIds = [...deviceIds];
+            if (options.name) {
+                const resolved = resolveDeviceId(undefined, options.name);
+                if (!allIds.includes(resolved))
+                    allIds.push(resolved);
+            }
+            if (allIds.length === 0)
+                throw new UsageError('Provide at least one deviceId argument or --name.');
             const parsed = parseDurationToMs(options.interval);
             if (parsed === null || parsed < MIN_INTERVAL_MS) {
                 throw new UsageError(`Invalid --interval "${options.interval}". Minimum is ${MIN_INTERVAL_MS / 1000}s.`);
@@ -101,7 +113,7 @@ Examples:
                     const t = new Date().toISOString();
                     // Poll all devices in parallel; one failure per device doesn't stop
                     // the others.
-                    await Promise.all(deviceIds.map(async (id) => {
+                    await Promise.all(allIds.map(async (id) => {
                         const cached = getCachedDevice(id);
                         try {
                             const body = await fetchDeviceStatus(id, client);

package/dist/commands/webhook.js

@@ -1,3 +1,4 @@
+import { stringArg } from '../utils/arg-parsers.js';
 import { createClient } from '../api/client.js';
 import { printKeyValue, printJson, isJsonMode, handleError, UsageError } from '../utils/output.js';
 import chalk from 'chalk';
@@ -54,7 +55,7 @@ Example:
     webhook
         .command('query')
         .description('Query webhook configuration')
-        .option('--details <url>', 'Query detailed configuration (enable/deviceList/timestamps) for a specific URL')
+        .option('--details <url>', 'Query detailed configuration (enable/deviceList/timestamps) for a specific URL', stringArg('--details'))
         .addHelpText('after', `
 Without --details, lists all configured webhook URLs.
 With --details, prints enable/deviceList/createTime/lastUpdateTime for the given URL.

package/dist/config.js

@@ -99,7 +99,7 @@ export function showConfig() {
     const envSecret = process.env.SWITCHBOT_SECRET;
     if (envToken && envSecret) {
         console.log('Credential source: environment variables');
-        console.log(`token : ${envToken}`);
+        console.log(`token : ${maskCredential(envToken)}`);
         console.log(`secret: ${maskSecret(envSecret)}`);
         return;
     }
@@ -112,13 +112,18 @@ export function showConfig() {
         const raw = fs.readFileSync(file, 'utf-8');
         const cfg = JSON.parse(raw);
         console.log(`Credential source: ${file}`);
-        console.log(`token : ${cfg.token}`);
+        console.log(`token : ${maskCredential(cfg.token)}`);
         console.log(`secret: ${maskSecret(cfg.secret)}`);
     }
     catch {
         console.error('Failed to read config file');
     }
 }
+function maskCredential(token) {
+    if (token.length <= 8)
+        return '*'.repeat(Math.max(4, token.length));
+    return token.slice(0, 4) + '*'.repeat(token.length - 8) + token.slice(-4);
+}
 function maskSecret(secret) {
     if (secret.length <= 4)
         return '****';