@switchbot/openapi-cli 2.4.0 → 2.5.1

package/README.md

@@ -221,6 +221,12 @@ switchbot devices list --filter category=physical
 switchbot devices list --filter type=Bot
 switchbot devices list --filter name=living,category=physical
 
+# Filter operators: = (substring; exact for `category`), ~ (substring),
+# =/regex/ (case-insensitive regex). Clauses are AND-ed.
+switchbot devices list --filter 'name~living'
+switchbot devices list --filter 'type=/Hub.*/'
+switchbot devices list --filter 'name~office,type=/Bulb|Strip/'
+
 # Filter by family / room (family & room info requires the 'src: OpenClaw'
 # header, which this CLI sends on every request)
 switchbot devices list --json | jq '.deviceList[] | select(.familyName == "Home")'
@@ -255,6 +261,21 @@ switchbot devices commands "Smart Lock"
 switchbot devices commands curtain      # Case-insensitive, substring match
 ```
 
+#### Filter expressions — per-command reference
+
+Three commands accept `--filter`. They share one three-operator grammar,
+but each exposes its own key set:
+
+| Command                             | Operators                                                                                     | Supported keys                        |
+|-------------------------------------|-----------------------------------------------------------------------------------------------|---------------------------------------|
+| `devices list`                      | `=` (substring; **exact** for `category`), `~` (substring), `=/regex/` (case-insensitive regex) | `type`, `name`, `category`, `room`    |
+| `devices batch`                     | same                                                                                          | `type`, `family`, `room`, `category`  |
+| `events tail` / `events mqtt-tail`  | same (tail only; mqtt-tail uses `--topic` instead)                                            | `deviceId`, `type`                    |
+
+Clauses are comma-separated and AND-ed. No OR across clauses — use regex
+alternation (`=/A|B/`) for that. `category` is the one key that stays exact
+under `=` to preserve `category=physical` / `category=ir` semantics.
+
 #### Parameter formats
 
 `parameter` is optional — omit it for commands like `turnOn`/`turnOff` (auto-defaults to `"default"`).
@@ -280,6 +301,8 @@ Generic parameter shapes (which one applies is decided by the device — see the
 
 Parameters for `setAll` (Air Conditioner), `setPosition` (Curtain / Blind Tilt), and `setMode` (Relay Switch) are validated client-side before the request — malformed shapes, out-of-range values, and JSON for CSV fields all fail fast with exit 2. Command names are also case-normalized against the catalog (e.g. `turnon` is auto-corrected to `turnOn` with a stderr warning); unknown names still exit 2 with the supported-commands list.
 
+Negative numeric parameters (e.g. `setBrightness -1` for a probe) are passed through to the command validator instead of being swallowed by the flag parser as an unknown option.
+
 For the complete per-device command reference, see the [SwitchBot API docs](https://github.com/OpenWonderLabs/SwitchBotAPI#send-device-control-commands).
 
 #### `devices expand` — named flags for packed parameters
@@ -333,7 +356,7 @@ Stores local annotations (alias, hidden flag, notes) in `~/.switchbot/device-met
 ```bash
 # Send the same command to every device matching a filter
 switchbot devices batch turnOff --filter 'type=Bot'
-switchbot devices batch setBrightness 50 --filter 'type~=Light,family=Living'
+switchbot devices batch setBrightness 50 --filter 'type~Light,family=Living'
 
 # Explicit device IDs (comma-separated)
 switchbot devices batch turnOn --ids ID1,ID2,ID3
@@ -343,9 +366,18 @@ switchbot devices list --format=id --filter 'type=Bot' | switchbot devices batch
 
 # Destructive commands require --yes
 switchbot devices batch unlock --filter 'type=Smart Lock' --yes
+
+# Skip devices whose cached status is offline (default: off)
+switchbot devices batch turnOn --ids ID1,ID2 --skip-offline
+
+# --idempotency-key is an alias for --idempotency-key-prefix; both append -<deviceId>
+switchbot devices batch turnOn --ids ID1,ID2 --idempotency-key morning-lights
 ```
 
-Sends the same command to many devices in one run. Uses the same `--filter` expressions as `devices list`. Destructive commands (Smart Lock unlock, Garage Door Opener, etc.) require `--yes` to prevent accidents.
+Sends the same command to many devices in one run. Filter grammar matches `devices list` (`=` substring, `~` substring, `=/regex/` regex — clauses AND-ed); supported keys here are `type`, `family`, `room`, `category`. Destructive commands (Smart Lock unlock, Garage Door Opener, etc.) require `--yes` to prevent accidents.
+
+`--skip-offline` reads from the local status cache only (no new API calls);
+skipped devices appear under `summary.skipped` with `skippedReason:'offline'`.
 
 ### `scenes` — run manual scenes
 
@@ -390,6 +422,9 @@ switchbot events tail --filter deviceId=ABC123
 # Stop after 5 matching events
 switchbot events tail --filter 'type=WoMeter' --max 5
 
+# Stop after 10 minutes regardless of event count
+switchbot events tail --for 10m
+
 # Custom port / path
 switchbot events tail --port 8080 --path /hook --json
 ```
@@ -401,7 +436,7 @@ Output (one JSON line per matched event):
 { "t": "2024-01-01T12:00:00.000Z", "remote": "1.2.3.4:54321", "path": "/", "body": {...}, "matched": true }
 ```
 
-Filter keys: `deviceId=<id>`, `type=<deviceType>` (comma-separated for AND logic).
+Filter keys: `deviceId`, `type`. Operators: `=` (substring), `~` (substring), `=/regex/` (case-insensitive regex). Clauses comma-separated and AND-ed.
 
 #### `events mqtt-tail` — real-time MQTT stream
 
@@ -414,6 +449,9 @@ switchbot events mqtt-tail --topic 'switchbot/#'
 
 # Stop after 10 events
 switchbot events mqtt-tail --max 10 --json
+
+# Stop after a fixed duration (emits __session_start under --json before connect)
+switchbot events mqtt-tail --for 30s --json
 ```
 
 Connects to the SwitchBot MQTT service automatically using the same credentials configured for the REST API (`SWITCHBOT_TOKEN` + `SWITCHBOT_SECRET`). No additional MQTT configuration is required — the client certificates are provisioned on first use.
@@ -514,9 +552,12 @@ switchbot devices watch <deviceId>
 
 # Custom interval; emit every tick even when nothing changed
 switchbot devices watch <deviceId> --interval 10s --include-unchanged --json
+
+# Time-bounded: stop after 5 minutes instead of a fixed tick count
+switchbot devices watch <deviceId> --for 5m
 ```
 
-Output is a JSONL stream of status-change events (with `--json`) or a refreshed table. Use `--max <n>` to stop after N ticks.
+Output is a JSONL stream of status-change events (with `--json`) or a refreshed table. Use `--max <n>` to stop after N ticks, or `--for <duration>` to stop after an elapsed wall-clock window (e.g. `30s`, `1h`, `2d`). When both are set, whichever limit trips first wins.
 
 ### `mcp` — Model Context Protocol server
 

package/dist/commands/agent-bootstrap.js

@@ -3,6 +3,7 @@ import { loadCache } from '../devices/cache.js';
 import { getEffectiveCatalog } from '../devices/catalog.js';
 import { readProfileMeta } from '../config.js';
 import { todayUsage, DAILY_QUOTA } from '../utils/quota.js';
+import { ALL_STRATEGIES } from '../utils/name-resolver.js';
 import { createRequire } from 'node:module';
 const require = createRequire(import.meta.url);
 const { version: pkgVersion } = require('../../package.json');
@@ -24,6 +25,7 @@ const QUICK_REFERENCE = {
     safety: ['--dry-run', '--idempotency-key <k>', '--audit-log', '--no-quota'],
     observability: ['doctor --json', 'quota status', 'cache status', 'events mqtt-tail'],
     history: ['history range <id> --since 7d', 'history stats <id>'],
+    meta: ['devices meta set <id> --alias <name>', 'devices meta list', 'devices meta get <id>'],
 };
 export function registerAgentBootstrapCommand(program) {
     program
@@ -97,6 +99,7 @@ Examples:
             identity: IDENTITY,
             quickReference: QUICK_REFERENCE,
             safetyTiers: SAFETY_TIERS,
+            nameStrategies: [...ALL_STRATEGIES],
             profile: meta
                 ? {
                     label: meta.label ?? null,
@@ -116,6 +119,9 @@ Examples:
                 scope: cachedDevices.length > 0 ? 'used' : 'all',
                 types: catalogTypes,
             },
+            // hints: empty array means no hints to report; always emitted, never null.
+            // An empty array signals "nothing to act on" — agents should not treat
+            // it as a disabled or missing field.
             hints: cachedDevices.length === 0
                 ? ['Run `switchbot devices list` once to populate the device cache for richer bootstrap output.']
                 : [],

package/dist/commands/batch.js

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

package/dist/commands/cache.js

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

package/dist/commands/capabilities.js

@@ -22,12 +22,18 @@ const COMMAND_META = {
     'devices types': { mutating: false, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 20 },
     'devices commands': { mutating: false, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 20 },
     'devices watch': { mutating: false, consumesQuota: true, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 500 },
+    // devices meta (local metadata — no quota, no API call)
+    'devices meta set': { mutating: true, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'action', verifiability: 'local', typicalLatencyMs: 5 },
+    'devices meta get': { mutating: false, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 5 },
+    'devices meta list': { mutating: false, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 5 },
+    'devices meta clear': { mutating: true, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'action', verifiability: 'local', typicalLatencyMs: 5 },
     // devices: actions
     'devices command': { mutating: true, consumesQuota: true, idempotencySupported: true, agentSafetyTier: 'action', verifiability: 'deviceDependent', typicalLatencyMs: 800 },
     'devices batch': { mutating: true, consumesQuota: true, idempotencySupported: true, agentSafetyTier: 'action', verifiability: 'deviceDependent', typicalLatencyMs: 1200 },
     // scenes
     'scenes list': { mutating: false, consumesQuota: true, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 500 },
     'scenes execute': { mutating: true, consumesQuota: true, idempotencySupported: false, agentSafetyTier: 'action', verifiability: 'deviceDependent', typicalLatencyMs: 1500 },
+    'scenes describe': { mutating: false, consumesQuota: true, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 500 },
     // webhook
     'webhook setup': { mutating: true, consumesQuota: true, idempotencySupported: false, agentSafetyTier: 'action', verifiability: 'local', typicalLatencyMs: 500 },
     'webhook query': { mutating: false, consumesQuota: true, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 500 },
@@ -51,6 +57,7 @@ const COMMAND_META = {
     'history replay': { mutating: true, consumesQuota: true, idempotencySupported: true, agentSafetyTier: 'action', verifiability: 'deviceDependent', typicalLatencyMs: 1000 },
     'history range': { mutating: false, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 50 },
     'history stats': { mutating: false, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 20 },
+    'history aggregate': { mutating: false, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 80 },
     'plan run': { mutating: true, consumesQuota: true, idempotencySupported: true, agentSafetyTier: 'action', verifiability: 'deviceDependent', typicalLatencyMs: 2000 },
     'plan validate': { mutating: false, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 10 },
     'plan schema': { mutating: false, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 10 },
@@ -88,6 +95,7 @@ const MCP_TOOLS = [
     'account_overview',
     'get_device_history',
     'query_device_history',
+    'aggregate_device_history',
 ];
 const IDEMPOTENCY_CONTRACT = {
     flag: '--idempotency-key <key>',

package/dist/commands/config.js

@@ -4,7 +4,7 @@ import { execFileSync } from 'node:child_process';
 import { stringArg } from '../utils/arg-parsers.js';
 import { intArg } from '../utils/arg-parsers.js';
 import { saveConfig, showConfig, listProfiles, readProfileMeta } from '../config.js';
-import { isJsonMode, printJson } from '../utils/output.js';
+import { isJsonMode, printJson, emitJsonError } from '../utils/output.js';
 import chalk from 'chalk';
 function parseEnvFile(file) {
     const out = {};
@@ -147,7 +147,7 @@ Files are written with mode 0600. Profiles live under ~/.switchbot/profiles/<nam
             if (!fs.existsSync(options.fromEnvFile)) {
                 const msg = `--from-env-file: file not found: ${options.fromEnvFile}`;
                 if (isJsonMode()) {
-                    console.error(JSON.stringify({ error: { code: 2, kind: 'usage', message: msg } }));
+                    emitJsonError({ code: 2, kind: 'usage', message: msg });
                 }
                 else {
                     console.error(msg);
@@ -162,7 +162,7 @@ Files are written with mode 0600. Profiles live under ~/.switchbot/profiles/<nam
             if (!options.opSecret) {
                 const msg = '--from-op requires --op-secret <ref> for the secret reference.';
                 if (isJsonMode()) {
-                    console.error(JSON.stringify({ error: { code: 2, kind: 'usage', message: msg } }));
+                    emitJsonError({ code: 2, kind: 'usage', message: msg });
                 }
                 else {
                     console.error(msg);
@@ -176,7 +176,7 @@ Files are written with mode 0600. Profiles live under ~/.switchbot/profiles/<nam
             catch (err) {
                 const msg = `1Password CLI read failed: ${err instanceof Error ? err.message : String(err)}`;
                 if (isJsonMode()) {
-                    console.error(JSON.stringify({ error: { code: 1, kind: 'runtime', message: msg, hint: 'Ensure the "op" CLI is installed and authenticated (op signin).' } }));
+                    emitJsonError({ code: 1, kind: 'runtime', message: msg, hint: 'Ensure the "op" CLI is installed and authenticated (op signin).' });
                 }
                 else {
                     console.error(msg);
@@ -189,7 +189,7 @@ Files are written with mode 0600. Profiles live under ~/.switchbot/profiles/<nam
         if ((!token || !secret) && !options.fromEnvFile && !options.fromOp && process.stdin.isTTY) {
             if (isJsonMode()) {
                 const msg = 'Interactive mode cannot run under --json. Provide token/secret via --from-env-file, --from-op, or positional args.';
-                console.error(JSON.stringify({ error: { code: 2, kind: 'usage', message: msg } }));
+                emitJsonError({ code: 2, kind: 'usage', message: msg });
                 process.exit(2);
             }
             try {
@@ -206,7 +206,7 @@ Files are written with mode 0600. Profiles live under ~/.switchbot/profiles/<nam
         if (!token || !secret) {
             const msg = 'Missing token/secret. Run interactively, or use --from-env-file / --from-op, or pass positional arguments (discouraged).';
             if (isJsonMode()) {
-                console.error(JSON.stringify({ error: { code: 2, kind: 'usage', message: msg } }));
+                emitJsonError({ code: 2, kind: 'usage', message: msg });
             }
             else {
                 console.error(msg);

package/dist/commands/device-meta.js

@@ -1,6 +1,6 @@
 import { stringArg } from '../utils/arg-parsers.js';
 import { handleError, isJsonMode, printJson, printTable, UsageError } from '../utils/output.js';
-import { loadDeviceMeta, setDeviceMeta, clearDeviceMeta, getDeviceMeta, getMetaFilePath, } from '../devices/device-meta.js';
+import { loadDeviceMeta, saveDeviceMeta, setDeviceMeta, clearDeviceMeta, getDeviceMeta, getMetaFilePath, } from '../devices/device-meta.js';
 export function registerDevicesMetaCommand(devices) {
     const meta = devices
         .command('meta')
@@ -14,6 +14,7 @@ export function registerDevicesMetaCommand(devices) {
         .option('--hide', 'Hide this device from "devices list"')
         .option('--show', 'Un-hide this device')
         .option('--notes <text>', 'Freeform notes shown in "devices describe"', stringArg('--notes'))
+        .option('--force', 'Reassign alias even if it already belongs to another device')
         .action((deviceId, options) => {
         try {
             if (options.hide && options.show) {
@@ -22,6 +23,22 @@ export function registerDevicesMetaCommand(devices) {
             if (!options.alias && !options.hide && !options.show && !options.notes) {
                 throw new UsageError('Specify at least one of: --alias, --hide, --show, --notes');
             }
+            // Enforce alias uniqueness across devices
+            if (options.alias !== undefined) {
+                const meta = loadDeviceMeta();
+                const holder = Object.entries(meta.devices).find(([id, m]) => m.alias === options.alias && id !== deviceId);
+                if (holder) {
+                    if (!options.force) {
+                        throw new UsageError(`Alias "${options.alias}" is already assigned to device ${holder[0]}. Use --force to reassign.`);
+                    }
+                    // --force: clear the alias from the previous holder
+                    meta.devices[holder[0]] = { ...meta.devices[holder[0]], alias: undefined };
+                    saveDeviceMeta(meta);
+                    if (!isJsonMode()) {
+                        console.log(`(reassigned alias from ${holder[0]})`);
+                    }
+                }
+            }
             const patch = {};
             if (options.alias !== undefined)
                 patch.alias = options.alias;