@switchbot/openapi-cli 2.0.1 → 2.2.0

package/dist/commands/devices.js

@@ -66,20 +66,62 @@ Examples:
   $ switchbot devices list --format tsv --fields deviceId,deviceName,type,category
   $ switchbot devices list --json | jq '.deviceList[] | select(.familyName == "家里")'
   $ switchbot devices list --json | jq '[.deviceList[], .infraredRemoteList[]] | group_by(.familyName)'
+  $ switchbot devices list --filter type="Air Conditioner"
+  $ switchbot devices list --filter category=ir
+  $ switchbot devices list --filter name=living,category=physical
 `)
         .option('--wide', 'Show all columns (controlType, family, roomID, room, hub, cloud)')
         .option('--show-hidden', 'Include devices hidden via "devices meta set --hide"')
+        .option('--filter <expr>', 'Filter devices: "type=X", "name=X", "category=physical|ir", "room=X" (comma-separated key=value pairs)')
         .action(async (options) => {
         try {
             const body = await fetchDeviceList();
             const { deviceList, infraredRemoteList } = body;
             const fmt = resolveFormat();
             const deviceMeta = loadDeviceMeta();
+            const hubLocation = buildHubLocationMap(deviceList);
+            let listFilter = null;
+            if (options.filter) {
+                listFilter = {};
+                for (const pair of options.filter.split(',')) {
+                    const eq = pair.indexOf('=');
+                    if (eq === -1)
+                        throw new UsageError(`Invalid --filter pair "${pair.trim()}". Expected key=value.`);
+                    const k = pair.slice(0, eq).trim();
+                    const v = pair.slice(eq + 1).trim();
+                    if (!['type', 'name', 'category', 'room'].includes(k)) {
+                        throw new UsageError(`Unknown --filter key "${k}". Supported: type, name, category, room.`);
+                    }
+                    listFilter[k] = v.toLowerCase();
+                }
+            }
+            const matchesFilter = (entry) => {
+                if (!listFilter)
+                    return true;
+                if (listFilter.type && !entry.type.toLowerCase().includes(listFilter.type))
+                    return false;
+                if (listFilter.name && !entry.name.toLowerCase().includes(listFilter.name))
+                    return false;
+                if (listFilter.category && entry.category !== listFilter.category)
+                    return false;
+                if (listFilter.room && !entry.room.toLowerCase().includes(listFilter.room))
+                    return false;
+                return true;
+            };
             if (fmt === 'json' && process.argv.includes('--json')) {
-                printJson(body);
+                if (listFilter) {
+                    const filteredDeviceList = deviceList.filter((d) => matchesFilter({ type: d.deviceType || '', name: d.deviceName, category: 'physical', room: d.roomName || '' }));
+                    const filteredIrList = infraredRemoteList.filter((d) => {
+                        const inherited = hubLocation.get(d.hubDeviceId);
+                        return matchesFilter({ type: d.remoteType, name: d.deviceName, category: 'ir', room: inherited?.room || '' });
+                    });
+                    printJson({ ok: true, deviceList: filteredDeviceList, infraredRemoteList: filteredIrList });
+                }
+                else {
+                    printJson({ ok: true, ...body });
+                }
                 return;
             }
-            const hubLocation = buildHubLocationMap(deviceList);
             const narrowHeaders = ['deviceId', 'deviceName', 'type', 'category'];
             const wideHeaders = ['deviceId', 'deviceName', 'type', 'category', 'controlType', 'family', 'roomID', 'room', 'hub', 'cloud', 'alias'];
             const userFields = resolveFields();
@@ -88,6 +130,8 @@ Examples:
             for (const d of deviceList) {
                 if (!options.showHidden && deviceMeta.devices[d.deviceId]?.hidden)
                     continue;
+                if (!matchesFilter({ type: d.deviceType || '', name: d.deviceName, category: 'physical', room: d.roomName || '' }))
+                    continue;
                 rows.push([
                     d.deviceId,
                     d.deviceName,
@@ -106,6 +150,8 @@ Examples:
                 if (!options.showHidden && deviceMeta.devices[d.deviceId]?.hidden)
                     continue;
                 const inherited = hubLocation.get(d.hubDeviceId);
+                if (!matchesFilter({ type: d.remoteType, name: d.deviceName, category: 'ir', room: inherited?.room || '' }))
+                    continue;
                 rows.push([
                     d.deviceId,
                     d.deviceName,
@@ -121,13 +167,22 @@ Examples:
                 ]);
             }
             if (rows.length === 0 && fmt === 'table') {
-                console.log('No devices found');
+                console.log(listFilter ? 'No devices matched the filter.' : 'No devices found');
                 return;
             }
             const defaultFields = options.wide ? undefined : narrowHeaders;
-            renderRows(wideHeaders, rows, fmt, userFields ?? defaultFields);
+            // Accept API field names and short aliases alongside canonical column names
+            const DEVICE_LIST_ALIASES = {
+                name: 'deviceName', deviceType: 'type', type: 'type',
+                roomName: 'room', familyName: 'family',
+                hubDeviceId: 'hub', enableCloudService: 'cloud',
+            };
+            renderRows(wideHeaders, rows, fmt, userFields ?? defaultFields, DEVICE_LIST_ALIASES);
             if (fmt === 'table') {
-                console.log(`\nTotal: ${deviceList.length} physical device(s), ${infraredRemoteList.length} IR remote device(s)`);
+                const totalLabel = listFilter
+                    ? `${rows.length} match(es) (${deviceList.length} physical + ${infraredRemoteList.length} IR before filter)`
+                    : `${deviceList.length} physical device(s), ${infraredRemoteList.length} IR remote device(s)`;
+                console.log(`\nTotal: ${totalLabel}`);
                 console.log(`Tip: 'switchbot devices describe <deviceId>' shows a device's supported commands.`);
             }
         }
@@ -139,8 +194,9 @@ Examples:
     devices
         .command('status')
         .description('Query the real-time status of a specific device')
-        .argument('[deviceId]', 'Device ID from "devices list" (or use --name)')
+        .argument('[deviceId]', 'Device ID from "devices list" (or use --name or --ids)')
         .option('--name <query>', 'Resolve device by fuzzy name instead of deviceId')
+        .option('--ids <list>', 'Comma-separated device IDs for batch status (incompatible with --name)')
         .addHelpText('after', `
 Status fields vary by device type. To discover them without a live call:
 
@@ -155,25 +211,70 @@ Examples:
   $ switchbot devices status ABC123DEF456 --json
   $ switchbot devices status ABC123DEF456 --format yaml
   $ switchbot devices status ABC123DEF456 --format tsv --fields power,battery
-  $ switchbot devices status ABC123DEF456 --json | jq '.battery'
+  $ switchbot devices status ABC123DEF456 --json | jq '.data.battery'
+  $ switchbot devices status --ids ABC123,DEF456,GHI789
+  $ switchbot devices status --ids ABC123,DEF456 --fields power,battery
 `)
         .action(async (deviceIdArg, options) => {
         try {
+            // Batch mode: --ids id1,id2,id3
+            if (options.ids) {
+                if (options.name)
+                    throw new UsageError('--ids and --name cannot be used together.');
+                const ids = options.ids.split(',').map((s) => s.trim()).filter(Boolean);
+                if (ids.length === 0)
+                    throw new UsageError('--ids requires at least one device ID.');
+                const results = await Promise.allSettled(ids.map((id) => fetchDeviceStatus(id)));
+                const fetchedAt = new Date().toISOString();
+                const batch = results.map((r, i) => r.status === 'fulfilled'
+                    ? { deviceId: ids[i], ok: true, _fetchedAt: fetchedAt, ...r.value }
+                    : { deviceId: ids[i], ok: false, error: r.reason?.message ?? String(r.reason) });
+                const batchFmt = resolveFormat();
+                if (isJsonMode() || batchFmt === 'json') {
+                    printJson(batch);
+                }
+                else if (batchFmt === 'jsonl') {
+                    for (const entry of batch) {
+                        console.log(JSON.stringify(entry));
+                    }
+                }
+                else {
+                    const fields = resolveFields();
+                    for (const entry of batch) {
+                        const { deviceId, ok, error, _fetchedAt: ts, ...status } = entry;
+                        console.log(`\n─── ${String(deviceId)} ───`);
+                        if (!ok) {
+                            console.error(`  error: ${String(error)}`);
+                        }
+                        else {
+                            const displayStatus = fields
+                                ? Object.fromEntries(fields.map((f) => [f, status[f] ?? null]))
+                                : status;
+                            printKeyValue(displayStatus);
+                            console.error(`  fetched at ${String(ts)}`);
+                        }
+                    }
+                }
+                return;
+            }
             const deviceId = resolveDeviceId(deviceIdArg, options.name);
             const body = await fetchDeviceStatus(deviceId);
+            const fetchedAt = new Date().toISOString();
             const fmt = resolveFormat();
             if (fmt === 'json' && process.argv.includes('--json')) {
-                printJson(body);
+                printJson({ ...body, _fetchedAt: fetchedAt });
                 return;
             }
             if (fmt !== 'table') {
-                const allHeaders = Object.keys(body);
-                const allRows = [Object.values(body)];
+                const statusWithTs = { ...body, _fetchedAt: fetchedAt };
+                const allHeaders = Object.keys(statusWithTs);
+                const allRows = [Object.values(statusWithTs)];
                 const fields = resolveFields();
                 renderRows(allHeaders, allRows, fmt, fields);
                 return;
             }
             printKeyValue(body);
+            console.error(`\nfetched at ${fetchedAt}`);
         }
         catch (error) {
             handleError(error);
@@ -184,7 +285,7 @@ Examples:
         .command('command')
         .description('Send a control command to a device')
         .argument('[deviceId]', 'Target device ID (or use --name)')
-        .argument('<cmd>', 'Command name, e.g. turnOn, turnOff, setColor, setBrightness, setAll, startClean')
+        .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')
         .option('--type <commandType>', 'Command type: "command" for built-in commands (default), "customize" for user-defined IR buttons', 'command')
@@ -235,60 +336,86 @@ Examples:
   $ switchbot devices command ABC123 "MyButton" --type customize
   $ switchbot devices command <lockId> unlock --yes
 `)
-        .action(async (deviceIdArg, cmd, parameter, options) => {
-        const deviceId = resolveDeviceId(deviceIdArg, options.name);
-        const validation = validateCommand(deviceId, cmd, parameter, options.type);
-        if (!validation.ok) {
-            const err = validation.error;
-            if (isJsonMode()) {
-                const obj = { code: 2, kind: 'usage', message: err.message };
-                if (err.hint)
-                    obj.hint = err.hint;
-                obj.context = { validationKind: err.kind };
-                console.error(JSON.stringify({ error: obj }));
+        .action(async (deviceIdArg, cmdArg, parameter, options) => {
+        try {
+            // BUG-FIX: When --name is provided, Commander misassigns the first positional
+            // to [deviceId] instead of [cmd]. Detect and shift positionals accordingly.
+            let cmd;
+            let effectiveDeviceIdArg;
+            if (options.name) {
+                if (deviceIdArg && cmdArg) {
+                    throw new UsageError('Provide either a deviceId argument or --name, not both.');
+                }
+                if (!deviceIdArg && !cmdArg) {
+                    throw new UsageError('Command name is required (e.g. turnOn, turnOff, setAll).');
+                }
+                // --name "x" turnOn  →  deviceIdArg="turnOn", cmdArg=undefined → shift
+                cmd = (deviceIdArg ?? cmdArg);
+                effectiveDeviceIdArg = undefined;
             }
             else {
-                console.error(`Error: ${err.message}`);
-                if (err.hint)
-                    console.error(err.hint);
-                if (err.kind === 'unknown-command') {
-                    const cached = getCachedDevice(deviceId);
-                    if (cached) {
-                        console.error(`Run 'switchbot devices commands ${JSON.stringify(cached.type)}' for parameter formats and descriptions.`);
-                        console.error(`(If the catalog is out of date, run 'switchbot devices list' to refresh the local cache, or pass --type customize for custom IR buttons.)`);
+                if (!cmdArg) {
+                    throw new UsageError('Command name is required (e.g. turnOn, turnOff, setAll).');
+                }
+                cmd = cmdArg;
+                effectiveDeviceIdArg = deviceIdArg;
+            }
+            const deviceId = resolveDeviceId(effectiveDeviceIdArg, options.name);
+            const validation = validateCommand(deviceId, cmd, parameter, options.type);
+            if (!validation.ok) {
+                const err = validation.error;
+                if (isJsonMode()) {
+                    const obj = { code: 2, kind: 'usage', message: err.message };
+                    if (err.hint)
+                        obj.hint = err.hint;
+                    obj.context = { validationKind: err.kind };
+                    console.error(JSON.stringify({ error: obj }));
+                }
+                else {
+                    console.error(`Error: ${err.message}`);
+                    if (err.hint)
+                        console.error(err.hint);
+                    if (err.kind === 'unknown-command') {
+                        const cached = getCachedDevice(deviceId);
+                        if (cached) {
+                            console.error(`Run 'switchbot devices commands ${JSON.stringify(cached.type)}' for parameter formats and descriptions.`);
+                            console.error(`(If the catalog is out of date, run 'switchbot devices list' to refresh the local cache, or pass --type customize for custom IR buttons.)`);
+                        }
                     }
                 }
+                process.exit(2);
             }
-            process.exit(2);
-        }
-        const cachedForGuard = getCachedDevice(deviceId);
-        if (!options.yes &&
-            !isDryRun() &&
-            isDestructiveCommand(cachedForGuard?.type, cmd, options.type)) {
-            const typeLabel = cachedForGuard?.type ?? 'unknown';
-            const reason = getDestructiveReason(cachedForGuard?.type, cmd, options.type);
-            if (isJsonMode()) {
-                console.error(JSON.stringify({
-                    error: {
-                        code: 2,
-                        kind: 'guard',
-                        message: `"${cmd}" on ${typeLabel} is destructive and requires --yes.`,
-                        hint: reason
-                            ? `Re-run with --yes to confirm. Reason: ${reason}`
-                            : 'Re-run with --yes to confirm, or --dry-run to preview without sending.',
-                        context: { command: cmd, deviceType: typeLabel, deviceId, ...(reason ? { destructiveReason: reason } : {}) },
-                    },
-                }));
+            const cachedForGuard = getCachedDevice(deviceId);
+            if (!options.yes &&
+                !isDryRun() &&
+                isDestructiveCommand(cachedForGuard?.type, cmd, options.type)) {
+                const typeLabel = cachedForGuard?.type ?? 'unknown';
+                const reason = getDestructiveReason(cachedForGuard?.type, cmd, options.type);
+                if (isJsonMode()) {
+                    console.error(JSON.stringify({
+                        error: {
+                            code: 2,
+                            kind: 'guard',
+                            message: `"${cmd}" on ${typeLabel} is destructive and requires --yes.`,
+                            hint: reason
+                                ? `Re-run with --yes to confirm. Reason: ${reason}`
+                                : 'Re-run with --yes to confirm, or --dry-run to preview without sending.',
+                            context: { command: cmd, deviceType: typeLabel, deviceId, ...(reason ? { destructiveReason: reason } : {}) },
+                        },
+                    }));
+                }
+                else {
+                    console.error(`Refusing to run destructive command "${cmd}" on ${typeLabel} without --yes.`);
+                    if (reason)
+                        console.error(`Reason: ${reason}`);
+                    console.error(`Re-run with --yes to confirm, or --dry-run to preview without sending.`);
+                }
+                process.exit(2);
             }
-            else {
-                console.error(`Refusing to run destructive command "${cmd}" on ${typeLabel} without --yes.`);
-                if (reason)
-                    console.error(`Reason: ${reason}`);
-                console.error(`Re-run with --yes to confirm, or --dry-run to preview without sending.`);
+            // Warn when --yes is given but the command is not destructive (no-op flag)
+            if (options.yes && !isDestructiveCommand(cachedForGuard?.type, cmd, options.type) && !isDryRun()) {
+                console.error(`Note: --yes has no effect; "${cmd}" is not a destructive command.`);
             }
-            process.exit(2);
-        }
-        try {
             // parameter may be a JSON object string (e.g. S10 startClean) or a plain string
             let parsedParam = parameter ?? 'default';
             if (parameter) {
@@ -311,14 +438,21 @@ Examples:
                 printJson(result);
                 return;
             }
-            console.log(`✓ Command sent: ${cmd}`);
-            if (isIr)
-                console.log('  Note: IR command sent — no device confirmation (fire-and-forget).');
-            if (body && typeof body === 'object' && Object.keys(body).length > 0) {
-                printKeyValue(body);
+            if (isIr) {
+                console.log(`→ IR signal sent: ${cmd} (no feedback — fire-and-forget)`);
+            }
+            else {
+                console.log(`✓ Command sent: ${cmd}`);
+                if (body && typeof body === 'object' && Object.keys(body).length > 0) {
+                    printKeyValue(body);
+                }
             }
         }
         catch (error) {
+            // Re-throw mock process.exit signals (Vitest intercepts process.exit as thrown
+            // Error('__exit__')) so they aren't double-handled and the exit code is preserved.
+            if (error instanceof Error && error.message === '__exit__')
+                throw error;
             handleError(error);
         }
     });
@@ -342,9 +476,10 @@ Examples:
                 printJson(catalog);
                 return;
             }
-            const headers = ['type', 'category', 'commands', 'aliases'];
+            const headers = ['type', 'role', 'category', 'commands', 'aliases'];
             const rows = catalog.map((e) => [
                 e.type,
+                e.role ?? '—',
                 e.category,
                 String(e.commands.length),
                 (e.aliases ?? []).join(', ') || '—',
@@ -535,6 +670,7 @@ function renderCatalogEntry(entry) {
     }
     else {
         console.log('\nCommands:');
+        const hasExamples = entry.commands.some((c) => c.exampleParams && c.exampleParams.length > 0);
         const rows = entry.commands.map((c) => {
             const flags = [];
             if (c.commandType === 'customize')
@@ -542,9 +678,13 @@ function renderCatalogEntry(entry) {
             if (c.destructive)
                 flags.push('!destructive');
             const label = flags.length > 0 ? `${c.command}  [${flags.join(', ')}]` : c.command;
-            return [label, c.parameter, c.description];
+            const base = [label, c.parameter, c.description];
+            return hasExamples ? [...base, (c.exampleParams ?? []).join(' | ') || ''] : base;
         });
-        printTable(['command', 'parameter', 'description'], rows);
+        const tableHeaders = hasExamples
+            ? ['command', 'parameter', 'description', 'example']
+            : ['command', 'parameter', 'description'];
+        printTable(tableHeaders, rows);
         const hasDestructive = entry.commands.some((c) => c.destructive);
         if (hasDestructive) {
             console.log('\n[!destructive] commands have hard-to-reverse real-world effects — confirm before issuing.');

package/dist/commands/doctor.js

@@ -101,6 +101,38 @@ function checkNodeVersion() {
     }
     return { name: 'node', status: 'ok', detail: `Node ${process.versions.node}` };
 }
+function checkMqtt() {
+    // MQTT credentials are auto-provisioned from the SwitchBot API using the
+    // account's token+secret — no extra env vars needed. Report availability
+    // based on whether REST credentials are configured (no network call).
+    const hasEnvCreds = Boolean(process.env.SWITCHBOT_TOKEN && process.env.SWITCHBOT_SECRET);
+    if (hasEnvCreds) {
+        return {
+            name: 'mqtt',
+            status: 'ok',
+            detail: "auto-provisioned from credentials — run 'switchbot events mqtt-tail' to test live connectivity",
+        };
+    }
+    const file = configFilePath();
+    if (fs.existsSync(file)) {
+        try {
+            const cfg = JSON.parse(fs.readFileSync(file, 'utf-8'));
+            if (cfg.token && cfg.secret) {
+                return {
+                    name: 'mqtt',
+                    status: 'ok',
+                    detail: "auto-provisioned from credentials — run 'switchbot events mqtt-tail' to test live connectivity",
+                };
+            }
+        }
+        catch { /* fall through */ }
+    }
+    return {
+        name: 'mqtt',
+        status: 'warn',
+        detail: "unavailable — configure credentials first (see credentials check above)",
+    };
+}
 export function registerDoctorCommand(program) {
     program
         .command('doctor')
@@ -122,6 +154,7 @@ Examples:
             checkCache(),
             checkQuotaFile(),
             checkClockSkew(),
+            checkMqtt(),
         ];
         const summary = {
             ok: checks.filter((c) => c.status === 'ok').length,

package/dist/commands/events.js

@@ -1,5 +1,17 @@
 import http from 'node:http';
 import { printJson, isJsonMode, handleError, UsageError } from '../utils/output.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;
@@ -102,7 +114,7 @@ export function startReceiver(port, pathMatch, filter, onEvent) {
 export function registerEventsCommand(program) {
     const events = program
         .command('events')
-        .description('Subscribe to local webhook events forwarded by SwitchBot');
+        .description('Receive SwitchBot device events — webhook receiver (tail) or MQTT stream (mqtt-tail)');
     events
         .command('tail')
         .description('Run a local HTTP receiver and print incoming webhook events as JSONL')
@@ -184,4 +196,179 @@ Examples:
             handleError(error);
         }
     });
+    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('--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')
+        .option('--webhook-url <url>', 'Webhook URL for webhook sink')
+        .option('--openclaw-url <url>', 'OpenClaw gateway URL (default: http://localhost:18789)')
+        .option('--openclaw-token <token>', 'Bearer token for OpenClaw (or env OPENCLAW_TOKEN)')
+        .option('--openclaw-model <id>', 'OpenClaw agent model ID to route events to')
+        .option('--telegram-token <token>', 'Telegram bot token (or env TELEGRAM_TOKEN)')
+        .option('--telegram-chat <id>', 'Telegram chat/channel ID to send messages to')
+        .option('--ha-url <url>', 'Home Assistant base URL (e.g. http://homeassistant.local:8123)')
+        .option('--ha-token <token>', 'HA long-lived access token (for REST event API)')
+        .option('--ha-webhook-id <id>', 'HA webhook ID (no auth; takes priority over --ha-token)')
+        .option('--ha-event-type <type>', 'HA event type for REST API (default: switchbot_event)')
+        .addHelpText('after', `
+Connects to the SwitchBot MQTT service using your existing credentials
+(SWITCHBOT_TOKEN + SWITCHBOT_SECRET or ~/.switchbot/config.json).
+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 --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 {
+            const maxEvents = options.max !== undefined ? Number(options.max) : null;
+            if (maxEvents !== null && (!Number.isInteger(maxEvents) || maxEvents < 1)) {
+                throw new UsageError(`Invalid --max "${options.max}". Must be a positive integer.`);
+            }
+            const loaded = tryLoadConfig();
+            if (!loaded) {
+                throw new UsageError('No credentials found. Run \'switchbot config set-token\' or set SWITCHBOT_TOKEN and SWITCHBOT_SECRET.');
+            }
+            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(loaded.token, loaded.secret);
+            const topic = options.topic ?? credential.topics.status;
+            let eventCount = 0;
+            const ac = new AbortController();
+            const client = new SwitchBotMqttClient(credential, () => fetchMqttCredential(loaded.token, loaded.secret));
+            const unsub = client.onMessage((msgTopic, payload) => {
+                let parsed;
+                try {
+                    parsed = JSON.parse(payload.toString('utf-8'));
+                }
+                catch {
+                    parsed = payload.toString('utf-8');
+                }
+                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 {
+                    // 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();
+                }
+            });
+            const unsubState = client.onStateChange((state) => {
+                if (!isJsonMode()) {
+                    console.error(`[${new Date().toLocaleTimeString()}] MQTT state: ${state}`);
+                }
+            });
+            await client.connect();
+            client.subscribe(topic);
+            if (!isJsonMode()) {
+                console.error(`Connected to ${credential.brokerUrl} (Ctrl-C to stop)`);
+            }
+            await new Promise((resolve) => {
+                const cleanup = () => {
+                    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 });
+            });
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
 }