@switchbot/openapi-cli 2.1.0 → 2.2.1

package/dist/index.js

@@ -1,6 +1,8 @@
 #!/usr/bin/env node
-import { Command, CommanderError } from 'commander';
+import { Command, CommanderError, InvalidArgumentError } from 'commander';
 import { createRequire } from 'node:module';
+import { intArg, stringArg, enumArg } from './utils/arg-parsers.js';
+import { parseDurationToMs } from './utils/flags.js';
 import { registerConfigCommand } from './commands/config.js';
 import { registerDevicesCommand } from './commands/devices.js';
 import { registerScenesCommand } from './commands/scenes.js';
@@ -19,25 +21,44 @@ import { registerCapabilitiesCommand } from './commands/capabilities.js';
 const require = createRequire(import.meta.url);
 const { version: pkgVersion } = require('../package.json');
 const program = new Command();
+// Top-level subcommand names. Used by stringArg to produce clearer errors when
+// a value is omitted and the next argv token turns out to be a subcommand name.
+const TOP_LEVEL_COMMANDS = [
+    'config', 'devices', 'scenes', 'webhook', 'completion', 'mcp',
+    'quota', 'catalog', 'cache', 'events', 'doctor', 'schema',
+    'history', 'plan', 'capabilities',
+];
+const cacheModeArg = (value) => {
+    if (value.startsWith('-')) {
+        throw new InvalidArgumentError(`--cache requires a mode value, got "${value}". ` +
+            `Valid: "off", "auto", or a duration like "5m", "1h". Use --cache=<mode> if needed.`);
+    }
+    if (value === 'off' || value === 'auto')
+        return value;
+    if (parseDurationToMs(value) !== null)
+        return value;
+    throw new InvalidArgumentError(`--cache must be "off", "auto", or a duration like "30s"/"5m"/"1h" (got "${value}")`);
+};
 program
     .name('switchbot')
     .description('Command-line tool for SwitchBot API v1.1')
     .version(pkgVersion)
     .option('--json', 'Output raw JSON response (disables tables; useful for pipes/scripts)')
-    .option('--format <type>', 'Output format: table (default), json, jsonl, tsv, yaml, id')
-    .option('--fields <csv>', 'Comma-separated list of columns to include (e.g. --fields=id,name,type)')
+    .option('--format <type>', 'Output format: table (default), json, jsonl, tsv, yaml, id', enumArg('--format', ['table', 'json', 'jsonl', 'tsv', 'yaml', 'id']))
+    .option('--fields <csv>', 'Comma-separated list of columns to include (e.g. --fields=id,name,type)', stringArg('--fields', { disallow: TOP_LEVEL_COMMANDS }))
     .option('-v, --verbose', 'Log HTTP request/response details to stderr')
     .option('--dry-run', 'Print mutating requests without sending them (GETs still execute)')
-    .option('--timeout <ms>', 'HTTP request timeout in milliseconds (default: 30000)')
-    .option('--retry-on-429 <n>', 'Max 429 retries before surfacing the error (default: 3)')
-    .option('--backoff <strategy>', 'Backoff strategy for retries: "linear" or "exponential" (default)')
+    .option('--timeout <ms>', 'HTTP request timeout in milliseconds (default: 30000)', intArg('--timeout', { min: 1 }))
+    .option('--retry-on-429 <n>', 'Max 429 retries before surfacing the error (default: 3)', intArg('--retry-on-429', { min: 0 }))
+    .option('--backoff <strategy>', 'Backoff strategy for retries: "linear" or "exponential" (default)', enumArg('--backoff', ['linear', 'exponential']))
     .option('--no-retry', 'Disable 429 retries entirely (equivalent to --retry-on-429 0)')
     .option('--no-quota', 'Disable the local ~/.switchbot/quota.json counter for this run')
-    .option('--cache <mode>', 'Cache mode: "off" | "auto" (default: list 1h, status off) | duration like 5m, 1h, 30s (enables both stores)')
+    .option('--cache <mode>', 'Cache mode: "off" | "auto" (default: list 1h, status off) | duration like 5m, 1h, 30s (enables both stores)', cacheModeArg)
     .option('--no-cache', 'Disable cache reads (equivalent to --cache off)')
-    .option('--config <path>', 'Override credential file location (default: ~/.switchbot/config.json)')
-    .option('--profile <name>', 'Use a named profile: ~/.switchbot/profiles/<name>.json')
-    .option('--audit-log [path]', 'Append every mutating command to JSONL audit log (default ~/.switchbot/audit.log)')
+    .option('--config <path>', 'Override credential file location (default: ~/.switchbot/config.json)', stringArg('--config', { disallow: TOP_LEVEL_COMMANDS }))
+    .option('--profile <name>', 'Use a named profile: ~/.switchbot/profiles/<name>.json', stringArg('--profile', { disallow: TOP_LEVEL_COMMANDS }))
+    .option('--audit-log', 'Append every mutating command to JSONL audit log (default path: ~/.switchbot/audit.log)')
+    .option('--audit-log-path <path>', 'Custom audit log file path; use together with --audit-log', stringArg('--audit-log-path', { disallow: TOP_LEVEL_COMMANDS }))
     .showHelpAfterError('(run with --help to see usage)')
     .showSuggestionAfterError();
 registerConfigCommand(program);
@@ -94,24 +115,33 @@ Discovery:
 
 Docs: https://github.com/OpenWonderLabs/SwitchBotAPI
 `);
-// Map commander usage errors (unknown option, missing argument, etc.) to exit code 2.
-program.exitOverride((err) => {
-    // --help and --version print to stdout and exit 0
+// Map commander usage errors (unknown option, missing argument, argParser
+// InvalidArgumentError, etc.) to exit code 2. Commander's exitOverride is
+// per-command: subcommand errors won't bubble to the root override, so walk
+// every registered command and apply the same handler.
+const usageExitHandler = (err) => {
     if (err.code === 'commander.helpDisplayed' || err.code === 'commander.version') {
         process.exit(0);
     }
-    // Everything else from commander (unknown option, missing argument,
-    // invalid choice, conflicting options, unknown command) is a usage error.
     process.exit(2);
-});
+};
+function applyExitOverride(cmd) {
+    cmd.exitOverride(usageExitHandler);
+    cmd.commands.forEach(applyExitOverride);
+}
+applyExitOverride(program);
 try {
     await program.parseAsync();
 }
 catch (err) {
-    // exitOverride already handled CommanderErrors; anything that escapes is a
-    // runtime error (should be rare since actions use handleError).
+    // Subcommand-level CommanderErrors (e.g. InvalidArgumentError from an
+    // argParser on a subcommand option) don't always hit the root exitOverride.
+    // Mirror the root mapping so all usage errors surface as exit 2.
     if (err instanceof CommanderError) {
-        process.exit(err.exitCode ?? 2);
+        if (err.code === 'commander.helpDisplayed' || err.code === 'commander.version') {
+            process.exit(0);
+        }
+        process.exit(2);
     }
     throw err;
 }

package/dist/lib/devices.js

@@ -147,9 +147,13 @@ export function validateCommand(deviceId, cmd, parameter, commandType) {
     const spec = builtinCommands.find((c) => c.command === cmd);
     if (!spec) {
         const unique = [...new Set(builtinCommands.map((c) => c.command))];
+        const caseMatch = unique.find((c) => c.toLowerCase() === cmd.toLowerCase());
+        const hint = caseMatch
+            ? `Did you mean "${caseMatch}"? Supported commands: ${unique.join(', ')}`
+            : `Supported commands: ${unique.join(', ')}`;
         return {
             ok: false,
-            error: new CommandValidationError(`"${cmd}" is not a supported command for ${cached.name} (${cached.type}).`, 'unknown-command', `Supported commands: ${unique.join(', ')}`),
+            error: new CommandValidationError(`"${cmd}" is not a supported command for ${cached.name} (${cached.type}).`, 'unknown-command', hint),
         };
     }
     const noParamExpected = spec.parameter === '—';
@@ -160,6 +164,17 @@ export function validateCommand(deviceId, cmd, parameter, commandType) {
             error: new CommandValidationError(`"${cmd}" takes no parameter, but one was provided: "${parameter}".`, 'unexpected-parameter', `Try: switchbot devices command ${deviceId} ${cmd}`),
         };
     }
+    // Warn when a parameter is required but the user omitted it
+    const paramRequired = !noParamExpected && spec.parameter !== 'default';
+    if (paramRequired && !userProvidedParam) {
+        const example = spec.exampleParams?.[0];
+        return {
+            ok: false,
+            error: new CommandValidationError(`"${cmd}" requires a parameter (${spec.parameter}).`, 'missing-parameter', example
+                ? `Example: switchbot devices command <deviceId> ${cmd} "${example}"`
+                : `See: switchbot devices commands ${cached.type}`),
+        };
+    }
     return { ok: true };
 }
 /**

package/dist/mcp/device-history.js

@@ -0,0 +1,66 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+const MAX_HISTORY = 100;
+function historyDir() {
+    return path.join(os.homedir(), '.switchbot', 'device-history');
+}
+export class DeviceHistoryStore {
+    dir;
+    constructor() {
+        this.dir = historyDir();
+    }
+    record(deviceId, topic, deviceType, payload, t) {
+        try {
+            if (!fs.existsSync(this.dir))
+                fs.mkdirSync(this.dir, { recursive: true });
+            const file = path.join(this.dir, `${deviceId}.json`);
+            const existing = fs.existsSync(file)
+                ? JSON.parse(fs.readFileSync(file, 'utf-8'))
+                : { latest: null, history: [] };
+            const entry = { t: t ?? new Date().toISOString(), topic, deviceType, payload };
+            existing.latest = entry;
+            existing.history = [entry, ...existing.history].slice(0, MAX_HISTORY);
+            fs.writeFileSync(file, JSON.stringify(existing, null, 2), { mode: 0o600 });
+        }
+        catch {
+            // best-effort — history loss is non-fatal
+        }
+    }
+    getLatest(deviceId) {
+        try {
+            const file = path.join(this.dir, `${deviceId}.json`);
+            if (!fs.existsSync(file))
+                return null;
+            return JSON.parse(fs.readFileSync(file, 'utf-8')).latest;
+        }
+        catch {
+            return null;
+        }
+    }
+    getHistory(deviceId, limit = 20) {
+        try {
+            const file = path.join(this.dir, `${deviceId}.json`);
+            if (!fs.existsSync(file))
+                return [];
+            const data = JSON.parse(fs.readFileSync(file, 'utf-8'));
+            return data.history.slice(0, Math.min(limit, MAX_HISTORY));
+        }
+        catch {
+            return [];
+        }
+    }
+    listDevices() {
+        try {
+            if (!fs.existsSync(this.dir))
+                return [];
+            return fs.readdirSync(this.dir)
+                .filter((f) => f.endsWith('.json'))
+                .map((f) => f.slice(0, -5));
+        }
+        catch {
+            return [];
+        }
+    }
+}
+export const deviceHistoryStore = new DeviceHistoryStore();

package/dist/mcp/events-subscription.js

@@ -5,6 +5,7 @@ import { fetchDeviceList } from '../lib/devices.js';
 import { getCachedDevice } from '../devices/cache.js';
 import { createClient } from '../api/client.js';
 import { log } from '../logger.js';
+import { deviceHistoryStore } from './device-history.js';
 export class EventSubscriptionManager {
     mqttClient = null;
     subscribers = new Map();
@@ -35,12 +36,18 @@ export class EventSubscriptionManager {
             client.onMessage((topic, payload) => {
                 try {
                     const data = JSON.parse(payload.toString());
-                    const deviceId = this.extractDeviceId(topic);
-                    if (deviceId && data.state) {
+                    // Support SwitchBot direct format: { eventType, context: { deviceMac, deviceType, ... } }
+                    // and AWS IoT shadow format: $aws/things/<id>/shadow/... with data.state
+                    const context = data.context;
+                    const deviceId = context?.deviceMac ?? this.extractDeviceId(topic);
+                    const payloadData = context ?? data.state;
+                    const deviceType = String(context?.deviceType ?? 'Unknown');
+                    if (deviceId && payloadData) {
+                        deviceHistoryStore.record(deviceId, topic, deviceType, payloadData);
                         this.addEvent({
                             kind: 'shadow.updated',
                             deviceId,
-                            payload: data.state,
+                            payload: payloadData,
                             timestamp: Date.now(),
                         });
                     }

package/dist/mqtt/client.js

@@ -17,6 +17,14 @@ export class SwitchBotMqttClient {
     async connect() {
         if (this.client && this.state === 'connected')
             return;
+        // Remove stale listeners before replacing the client instance, otherwise
+        // the old client's close event fires after the new connection is established
+        // (AWS IoT drops the old session), triggering a spurious reconnect loop.
+        if (this.client) {
+            this.client.removeAllListeners();
+            this.client.end(true);
+            this.client = null;
+        }
         this.setState('connecting');
         this.credentialExpired = false;
         this.reconnectAttempts = 0;

package/dist/mqtt/credential.js

@@ -2,8 +2,9 @@ import crypto from 'node:crypto';
 import { buildAuthHeaders } from '../auth.js';
 const CREDENTIAL_ENDPOINT = 'https://api.switchbot.net/v1.1/iot/credential';
 export async function fetchMqttCredential(token, secret) {
-    // Derive a stable instance ID per token so the server can track this client.
-    const instanceId = crypto.createHash('sha256').update(token).digest('hex').slice(0, 16);
+    // Use a random instanceId so each CLI session gets its own clientId, avoiding
+    // conflicts with the SwitchBot cloud service that shares the same account credentials.
+    const instanceId = crypto.randomUUID().replace(/-/g, '').slice(0, 16);
     const headers = buildAuthHeaders(token, secret);
     const res = await fetch(CREDENTIAL_ENDPOINT, {
         method: 'POST',

package/dist/sinks/dispatcher.js

@@ -0,0 +1,12 @@
+export class SinkDispatcher {
+    sinks;
+    constructor(sinks) {
+        this.sinks = sinks;
+    }
+    async dispatch(event) {
+        await Promise.allSettled(this.sinks.map((s) => s.write(event)));
+    }
+    async close() {
+        await Promise.allSettled(this.sinks.map((s) => s.close?.()));
+    }
+}

package/dist/sinks/file.js

@@ -0,0 +1,19 @@
+import fs from 'node:fs';
+import path from 'node:path';
+export class FileSink {
+    filePath;
+    constructor(filePath) {
+        this.filePath = path.resolve(filePath);
+        const dir = path.dirname(this.filePath);
+        if (!fs.existsSync(dir))
+            fs.mkdirSync(dir, { recursive: true });
+    }
+    async write(event) {
+        try {
+            fs.appendFileSync(this.filePath, JSON.stringify(event) + '\n', { encoding: 'utf-8' });
+        }
+        catch {
+            // best-effort
+        }
+    }
+}

package/dist/sinks/format.js

@@ -0,0 +1,56 @@
+const ICONS = {
+    'Bot': '🤖',
+    'Curtain': '🪟',
+    'Hub': '📡',
+    'Hub 2': '📡',
+    'Hub 3': '📡',
+    'Hub Mini': '📡',
+    'Smart Lock': '🔒',
+    'Smart Lock Pro': '🔒',
+    'Plug': '🔌',
+    'Plug Mini (US)': '🔌',
+    'Plug Mini (JP)': '🔌',
+    'Color Bulb': '💡',
+    'Strip Light': '💡',
+    'Contact Sensor': '🚪',
+    'Motion Sensor': '👁',
+    'Meter': '🌡',
+    'MeterPro': '🌡',
+    'Climate Panel': '🌡',
+    'WoMeter': '🌡',
+    'WoIOSensor': '🌡',
+};
+function icon(deviceType) {
+    return ICONS[deviceType] ?? '📱';
+}
+export function formatEventText(context) {
+    const type = context.deviceType ?? 'Unknown';
+    const pfx = `${icon(type)} ${type}`;
+    const parts = [];
+    if (context.temperature !== undefined)
+        parts.push(`${context.temperature}°C`);
+    if (context.humidity !== undefined)
+        parts.push(`${context.humidity}%`);
+    if (parts.length)
+        return `${pfx}: ${parts.join(' / ')}`;
+    if (context.power !== undefined)
+        return `${pfx}: ${context.power}`;
+    if (context.lockState !== undefined)
+        return `${pfx}: ${context.lockState}`;
+    if (context.openState !== undefined)
+        return `${pfx}: ${context.openState}`;
+    if (context.detectionState !== undefined)
+        return `${pfx}: ${context.detectionState}`;
+    if (context.brightness !== undefined)
+        return `${pfx}: ${context.brightness}`;
+    return `${pfx}: state change`;
+}
+export function parseSinkEvent(payload) {
+    const p = payload;
+    const context = (p?.context ?? {});
+    return {
+        deviceId: String(context.deviceMac ?? 'unknown'),
+        deviceType: String(context.deviceType ?? 'Unknown'),
+        text: formatEventText(context),
+    };
+}

package/dist/sinks/homeassistant.js

@@ -0,0 +1,44 @@
+export class HomeAssistantSink {
+    url;
+    token;
+    webhookId;
+    eventType;
+    constructor(opts) {
+        this.url = opts.url.replace(/\/$/, '');
+        this.token = opts.token;
+        this.webhookId = opts.webhookId;
+        this.eventType = opts.eventType ?? 'switchbot_event';
+    }
+    async write(event) {
+        try {
+            let endpoint;
+            const headers = { 'content-type': 'application/json' };
+            if (this.webhookId) {
+                // Webhook mode: no auth needed, HA triggers automations directly
+                endpoint = `${this.url}/api/webhook/${this.webhookId}`;
+            }
+            else if (this.token) {
+                // REST event API: fires a custom event on the HA event bus
+                endpoint = `${this.url}/api/events/${this.eventType}`;
+                headers['authorization'] = `Bearer ${this.token}`;
+            }
+            else {
+                console.error('[homeassistant] requires --ha-webhook-id or --ha-token');
+                return;
+            }
+            const res = await fetch(endpoint, {
+                method: 'POST',
+                headers,
+                body: JSON.stringify(event),
+                signal: AbortSignal.timeout(10000),
+            });
+            if (!res.ok) {
+                const body = await res.text().catch(() => '');
+                console.error(`[homeassistant] POST failed: HTTP ${res.status} ${body.slice(0, 200)}`);
+            }
+        }
+        catch (err) {
+            console.error(`[homeassistant] error: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+}

package/dist/sinks/openclaw.js

@@ -0,0 +1,33 @@
+export class OpenClawSink {
+    url;
+    token;
+    model;
+    constructor(opts) {
+        this.url = (opts.url ?? 'http://localhost:18789').replace(/\/$/, '');
+        this.token = opts.token;
+        this.model = opts.model;
+    }
+    async write(event) {
+        try {
+            const res = await fetch(`${this.url}/v1/chat/completions`, {
+                method: 'POST',
+                headers: {
+                    'content-type': 'application/json',
+                    'authorization': `Bearer ${this.token}`,
+                },
+                body: JSON.stringify({
+                    model: this.model,
+                    messages: [{ role: 'user', content: event.text }],
+                }),
+                signal: AbortSignal.timeout(10000),
+            });
+            if (!res.ok) {
+                const body = await res.text().catch(() => '');
+                console.error(`[openclaw] POST failed: HTTP ${res.status} ${body.slice(0, 200)}`);
+            }
+        }
+        catch (err) {
+            console.error(`[openclaw] error: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+}

package/dist/sinks/stdout.js

@@ -0,0 +1,5 @@
+export class StdoutSink {
+    async write(event) {
+        console.log(JSON.stringify(event));
+    }
+}

package/dist/sinks/telegram.js

@@ -0,0 +1,28 @@
+export class TelegramSink {
+    token;
+    chatId;
+    constructor(opts) {
+        this.token = opts.token;
+        this.chatId = opts.chatId;
+    }
+    async write(event) {
+        try {
+            const res = await fetch(`https://api.telegram.org/bot${this.token}/sendMessage`, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify({
+                    chat_id: this.chatId,
+                    text: event.text,
+                }),
+                signal: AbortSignal.timeout(10000),
+            });
+            if (!res.ok) {
+                const body = await res.text().catch(() => '');
+                console.error(`[telegram] POST failed: HTTP ${res.status} ${body.slice(0, 200)}`);
+            }
+        }
+        catch (err) {
+            console.error(`[telegram] error: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+}

package/dist/sinks/types.js

@@ -0,0 +1 @@
+export {};

package/dist/sinks/webhook.js

@@ -0,0 +1,22 @@
+export class WebhookSink {
+    url;
+    constructor(url) {
+        this.url = url;
+    }
+    async write(event) {
+        try {
+            const res = await fetch(this.url, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify(event),
+                signal: AbortSignal.timeout(10000),
+            });
+            if (!res.ok) {
+                console.error(`[webhook] POST failed: HTTP ${res.status}`);
+            }
+        }
+        catch (err) {
+            console.error(`[webhook] error: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+}

package/dist/utils/arg-parsers.js

@@ -0,0 +1,62 @@
+import { InvalidArgumentError } from 'commander';
+import { parseDurationToMs } from './flags.js';
+/**
+ * Commander argParser callbacks that fail fast when a required-value flag
+ * swallows the next token (another flag, a subcommand name, etc.) — the
+ * default Commander behavior is to take the next argv token verbatim.
+ *
+ * Use `--flag=<val>` form to pass values that legitimately start with `--`.
+ */
+export function intArg(flagName, opts) {
+    return (value) => {
+        if (value.startsWith('-')) {
+            throw new InvalidArgumentError(`${flagName} requires a numeric value, got "${value}". ` +
+                `Did you forget a value? Use ${flagName}=<n> if the value really starts with "-".`);
+        }
+        const n = Number(value);
+        if (!Number.isInteger(n)) {
+            throw new InvalidArgumentError(`${flagName} must be an integer (got "${value}")`);
+        }
+        if (opts?.min !== undefined && n < opts.min) {
+            throw new InvalidArgumentError(`${flagName} must be >= ${opts.min} (got "${value}")`);
+        }
+        if (opts?.max !== undefined && n > opts.max) {
+            throw new InvalidArgumentError(`${flagName} must be <= ${opts.max} (got "${value}")`);
+        }
+        return String(n);
+    };
+}
+export function durationArg(flagName) {
+    return (value) => {
+        if (value.startsWith('-')) {
+            throw new InvalidArgumentError(`${flagName} requires a duration value, got "${value}". ` +
+                `Use ${flagName}=<dur> if the value really starts with "-".`);
+        }
+        const ms = parseDurationToMs(value);
+        if (ms === null) {
+            throw new InvalidArgumentError(`${flagName} must look like "30s", "1m", "500ms", "1h" (got "${value}")`);
+        }
+        return value;
+    };
+}
+export function stringArg(flagName, opts) {
+    return (value) => {
+        if (value.startsWith('--')) {
+            throw new InvalidArgumentError(`${flagName} requires a value. "${value}" looks like another option — ` +
+                `did you forget the value? Use ${flagName}=<val> if your value really starts with "--".`);
+        }
+        if (opts?.disallow?.includes(value)) {
+            throw new InvalidArgumentError(`${flagName} requires a value but got "${value}", which is a subcommand name. ` +
+                `Did you forget the value? Use ${flagName}=<val> or put ${flagName} after the subcommand.`);
+        }
+        return value;
+    };
+}
+export function enumArg(flagName, allowed) {
+    return (value) => {
+        if (!allowed.includes(value)) {
+            throw new InvalidArgumentError(`${flagName} must be one of: ${allowed.join(', ')} (got "${value}")`);
+        }
+        return value;
+    };
+}

package/dist/utils/flags.js

@@ -17,7 +17,7 @@ export function isVerbose() {
 export function isDryRun() {
     return process.argv.includes('--dry-run');
 }
-/** HTTP request timeout in milliseconds. Default 30s. */
+/** HTTP request timeout in milliseconds. Default 30s. Minimum 100ms (values below 100ms are ignored). */
 export function getTimeout() {
     const v = getFlagValue('--timeout');
     if (!v)
@@ -25,6 +25,10 @@ export function getTimeout() {
     const n = Number(v);
     if (!Number.isFinite(n) || n <= 0)
         return 30_000;
+    if (n < 100) {
+        process.stderr.write(`Warning: --timeout ${n}ms is too low to complete any request; using 100ms minimum.\n`);
+        return 100;
+    }
     return n;
 }
 /** Override for the credentials file path. */
@@ -36,20 +40,17 @@ export function getProfile() {
     return getFlagValue('--profile');
 }
 /**
- * Audit log path. `--audit-log <path>` enables JSONL append on every mutating
- * command; default path is ~/.switchbot/audit.log when `--audit-log` is given
- * without a value. Returns null when the flag is absent.
+ * Audit log path. `--audit-log` enables JSONL append on every mutating command.
+ * Use `--audit-log-path <path>` to specify a custom file; otherwise defaults to
+ * ~/.switchbot/audit.log. Returns null when --audit-log is absent.
  */
 export function getAuditLog() {
-    const idx = process.argv.indexOf('--audit-log');
-    if (idx === -1)
+    if (!process.argv.includes('--audit-log'))
         return null;
-    const next = process.argv[idx + 1];
-    if (!next || next.startsWith('-')) {
-        // bare --audit-log → default location
-        return `${process.env.HOME ?? process.env.USERPROFILE ?? '.'}/.switchbot/audit.log`;
-    }
-    return next;
+    const customPath = getFlagValue('--audit-log-path');
+    if (customPath)
+        return customPath;
+    return `${process.env.HOME ?? process.env.USERPROFILE ?? '.'}/.switchbot/audit.log`;
 }
 /**
  * Max 429 retries before surfacing the error. Default 3. `--no-retry`

package/dist/utils/format.js

@@ -32,15 +32,16 @@ export function resolveFormat() {
 export function resolveFields() {
     return getFields();
 }
-export function filterFields(headers, rows, fields) {
+export function filterFields(headers, rows, fields, aliases) {
     if (!fields || fields.length === 0)
         return { headers, rows };
-    const unknown = fields.filter((f) => !headers.includes(f));
+    const resolved = aliases ? fields.map((f) => aliases[f] ?? f) : fields;
+    const unknown = fields.filter((_, i) => !headers.includes(resolved[i]));
     if (unknown.length > 0) {
         throw new UsageError(`Unknown field(s): ${unknown.map((f) => `"${f}"`).join(', ')}. ` +
             `Allowed: ${headers.map((f) => `"${f}"`).join(', ')}.`);
     }
-    const indices = fields.map((f) => headers.indexOf(f));
+    const indices = resolved.map((f) => headers.indexOf(f));
     return {
         headers: indices.map((i) => headers[i]),
         rows: rows.map((row) => indices.map((i) => row[i])),
@@ -62,8 +63,8 @@ function rowToObject(headers, row) {
     }
     return obj;
 }
-export function renderRows(headers, rows, format, fields) {
-    const filtered = filterFields(headers, rows, fields);
+export function renderRows(headers, rows, format, fields, aliases) {
+    const filtered = filterFields(headers, rows, fields, aliases);
     const h = filtered.headers;
     const r = filtered.rows;
     switch (format) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@switchbot/openapi-cli",
-  "version": "2.1.0",
+  "version": "2.2.1",
   "description": "SwitchBot smart home CLI — control devices, run scenes, stream real-time events, and integrate AI agents via MCP. Full API v1.1 coverage.",
   "keywords": [
     "switchbot",