@switchbot/openapi-cli 2.2.0 → 2.3.0

package/README.md

@@ -177,6 +177,8 @@ switchbot --help
 switchbot devices command --help
 ```
 
+> **Tip — required-value flags and subcommands.** Flags like `--profile`, `--timeout`, `--max`, and `--interval` take a value. If you omit it, Commander will happily consume the next token — including a subcommand name. Since v2.2.1 the CLI rejects that eagerly (exit 2 with a clear error), but if you ever hit `unknown command 'list'` after something like `switchbot --profile list`, use the `--flag=value` form: `switchbot --profile=home devices list`.
+
 ### `--dry-run`
 
 Intercepts every non-GET request: the CLI prints the URL/body it would have
@@ -206,6 +208,7 @@ switchbot config list-profiles                 # List saved profiles
 # Default columns (4): deviceId, deviceName, type, category
 # Pass --wide for the full 10-column operator view
 switchbot devices list
+switchbot devices ls              # short alias for 'list'
 switchbot devices list --wide
 switchbot devices list --json | jq '.deviceList[].deviceId'
 
@@ -275,6 +278,8 @@ Generic parameter shapes (which one applies is decided by the device — see the
 | `<json object>`     | `'{"action":"sweep","param":{"fanLevel":2,"times":1}}'`  |
 | Custom IR button    | `devices command <id> MyButton --type customize`         |
 
+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.
+
 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

package/dist/commands/batch.js

@@ -1,3 +1,4 @@
+import { intArg, enumArg, stringArg } from '../utils/arg-parsers.js';
 import { printJson, isJsonMode, handleError, buildErrorPayload } from '../utils/output.js';
 import { fetchDeviceList, executeCommand, isDestructiveCommand, buildHubLocationMap, } from '../lib/devices.js';
 import { createClient } from '../api/client.js';
@@ -6,6 +7,7 @@ import { isDryRun } from '../utils/flags.js';
 import { DryRunSignal } from '../api/client.js';
 import { getCachedTypeMap } from '../devices/cache.js';
 const DEFAULT_CONCURRENCY = 5;
+const COMMAND_TYPES = ['command', 'customize'];
 /** Run `task(x)` for every element with at most `concurrency` running at once. */
 async function runPool(items, concurrency, task) {
     const results = new Array(items.length);
@@ -84,13 +86,13 @@ export function registerBatchCommand(devices) {
         .description('Send the same command to many devices in one run (filter- or stdin-driven)')
         .argument('<command>', 'Command name, e.g. turnOn, turnOff, setBrightness')
         .argument('[parameter]', 'Command parameter (same rules as `devices command`; omit for no-arg)')
-        .option('--filter <expr>', 'Target devices matching a filter, e.g. type=Bot,family=Home')
-        .option('--ids <csv>', 'Explicit comma-separated list of deviceIds')
-        .option('--concurrency <n>', 'Max parallel in-flight requests (default 5)', '5')
+        .option('--filter <expr>', 'Target devices matching a filter, e.g. type=Bot,family=Home', stringArg('--filter'))
+        .option('--ids <csv>', 'Explicit comma-separated list of deviceIds', stringArg('--ids'))
+        .option('--concurrency <n>', 'Max parallel in-flight requests (default 5)', intArg('--concurrency', { min: 1 }), '5')
         .option('--yes', 'Allow destructive commands (Smart Lock unlock, garage open, ...)')
-        .option('--type <commandType>', '"command" (default) or "customize" for user-defined IR buttons', 'command')
+        .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>)')
+        .option('--idempotency-key-prefix <prefix>', 'Prefix for idempotency keys (key per device: <prefix>-<deviceId>)', stringArg('--idempotency-key-prefix'))
         .addHelpText('after', `
 Targets are resolved in this priority order:
   1. --ids when present       (explicit deviceIds)

package/dist/commands/cache.js

@@ -1,3 +1,4 @@
+import { enumArg } from '../utils/arg-parsers.js';
 import { printJson, isJsonMode, handleError, UsageError } from '../utils/output.js';
 import { clearCache, clearStatusCache, describeCache, loadStatusCache, } from '../devices/cache.js';
 function formatAge(ms) {
@@ -15,6 +16,7 @@ function formatAge(ms) {
     return `${h}h ${m % 60}m`;
 }
 export function registerCacheCommand(program) {
+    const CACHE_KEYS = ['list', 'status', 'all'];
     const cache = program
         .command('cache')
         .description('Inspect and manage the local SwitchBot CLI caches')
@@ -78,7 +80,7 @@ Examples:
     cache
         .command('clear')
         .description('Delete cache files')
-        .option('--key <which>', 'Which cache to clear: "list" | "status" | "all" (default)', 'all')
+        .option('--key <which>', 'Which cache to clear: "list" | "status" | "all" (default)', enumArg('--key', CACHE_KEYS), 'all')
         .action((options) => {
         try {
             const key = options.key;

package/dist/commands/catalog.js

@@ -1,7 +1,9 @@
+import { enumArg } from '../utils/arg-parsers.js';
 import { printTable, printJson, isJsonMode, handleError, UsageError } from '../utils/output.js';
 import { resolveFormat, resolveFields, renderRows } from '../utils/format.js';
 import { DEVICE_CATALOG, findCatalogEntry, getCatalogOverlayPath, getEffectiveCatalog, loadCatalogOverlay, resetCatalogOverlayCache, } from '../devices/catalog.js';
 export function registerCatalogCommand(program) {
+    const SOURCES = ['built-in', 'overlay', 'effective'];
     const catalog = program
         .command('catalog')
         .description('Inspect the built-in device catalog and any local overlay')
@@ -66,7 +68,7 @@ Examples:
         .command('show')
         .description("Show the effective catalog (or one entry). Defaults to 'effective' source.")
         .argument('[type...]', 'Optional device type/alias (case-insensitive, partial match)')
-        .option('--source <source>', 'Which catalog to show: built-in | overlay | effective (default)', 'effective')
+        .option('--source <source>', 'Which catalog to show: built-in | overlay | effective (default)', enumArg('--source', SOURCES), 'effective')
         .action((typeParts, options) => {
         try {
             const source = options.source;

package/dist/commands/completion.js

@@ -12,13 +12,19 @@ _switchbot_completion() {
     cword="\${COMP_CWORD}"
   }
 
-  local top_cmds="config devices scenes webhook completion help"
-  local config_sub="set-token show"
-  local devices_sub="list status command types commands"
+  local top_cmds="config devices scenes webhook completion mcp quota catalog cache events doctor schema history plan capabilities help"
+  local config_sub="set-token show list-profiles"
+  local devices_sub="list ls status command types commands describe batch watch explain expand meta"
   local scenes_sub="list execute"
   local webhook_sub="setup query update delete"
+  local events_sub="tail mqtt-tail"
+  local quota_sub="status reset"
+  local catalog_sub="path show diff refresh"
+  local cache_sub="show clear"
+  local history_sub="show replay"
+  local plan_sub="schema validate run"
   local completion_shells="bash zsh fish powershell"
-  local global_opts="--json --verbose -v --dry-run --timeout --config --help -h --version -V"
+  local global_opts="--json --format --fields --verbose -v --dry-run --timeout --retry-on-429 --backoff --no-retry --no-quota --cache --no-cache --config --profile --audit-log --audit-log-path --help -h --version -V"
 
   if [[ \${cword} -eq 1 ]]; then
     COMPREPLY=( $(compgen -W "\${top_cmds} \${global_opts}" -- "\${cur}") )
@@ -43,6 +49,36 @@ _switchbot_completion() {
         COMPREPLY=( $(compgen -W "\${scenes_sub}" -- "\${cur}") )
       fi
       ;;
+    events)
+      if [[ \${cword} -eq 2 ]]; then
+        COMPREPLY=( $(compgen -W "\${events_sub}" -- "\${cur}") )
+      fi
+      ;;
+    quota)
+      if [[ \${cword} -eq 2 ]]; then
+        COMPREPLY=( $(compgen -W "\${quota_sub}" -- "\${cur}") )
+      fi
+      ;;
+    catalog)
+      if [[ \${cword} -eq 2 ]]; then
+        COMPREPLY=( $(compgen -W "\${catalog_sub}" -- "\${cur}") )
+      fi
+      ;;
+    cache)
+      if [[ \${cword} -eq 2 ]]; then
+        COMPREPLY=( $(compgen -W "\${cache_sub}" -- "\${cur}") )
+      fi
+      ;;
+    history)
+      if [[ \${cword} -eq 2 ]]; then
+        COMPREPLY=( $(compgen -W "\${history_sub}" -- "\${cur}") )
+      fi
+      ;;
+    plan)
+      if [[ \${cword} -eq 2 ]]; then
+        COMPREPLY=( $(compgen -W "\${plan_sub}" -- "\${cur}") )
+      fi
+      ;;
     webhook)
       if [[ \${cword} -eq 2 ]]; then
         COMPREPLY=( $(compgen -W "\${webhook_sub}" -- "\${cur}") )
@@ -69,22 +105,39 @@ const ZSH_SCRIPT = `# switchbot zsh completion
 #   source <(switchbot completion zsh)
 
 _switchbot() {
-  local -a top_cmds config_sub devices_sub scenes_sub webhook_sub completion_shells
+  local -a top_cmds config_sub devices_sub scenes_sub webhook_sub events_sub quota_sub catalog_sub cache_sub history_sub plan_sub completion_shells
   top_cmds=(
     'config:Manage API credentials'
     'devices:List and control devices'
     'scenes:List and execute scenes'
     'webhook:Manage webhook configuration'
     'completion:Print a shell completion script'
+    'mcp:Run the MCP server'
+    'quota:Inspect local request quota'
+    'catalog:Inspect the built-in device catalog'
+    'cache:Inspect local caches'
+    'events:Receive webhook or MQTT events'
+    'doctor:Run self-checks'
+    'schema:Export the device catalog as JSON'
+    'history:View and replay audited commands'
+    'plan:Validate and run batch plans'
+    'capabilities:Print a machine-readable manifest'
     'help:Show help for a command'
   )
-  config_sub=('set-token:Save token + secret' 'show:Show current credential source')
+  config_sub=('set-token:Save token + secret' 'show:Show current credential source' 'list-profiles:List named credential profiles')
   devices_sub=(
     'list:List all devices'
+    'ls:Alias for list'
     'status:Query device status'
     'command:Send a control command'
     'types:List known device types (offline)'
     'commands:Show commands for a device type (offline)'
+    'describe:Show metadata + supported commands for one device'
+    'batch:Send one command to many devices'
+    'watch:Poll device status and emit changes'
+    'explain:One-shot device summary'
+    'expand:Build wire-format params from semantic flags'
+    'meta:Manage local device metadata'
   )
   scenes_sub=('list:List manual scenes' 'execute:Run a scene')
   webhook_sub=(
@@ -93,15 +146,32 @@ _switchbot() {
     'update:Enable/disable a webhook'
     'delete:Delete a webhook'
   )
+  events_sub=('tail:Run a local webhook receiver' 'mqtt-tail:Stream MQTT shadow events')
+  quota_sub=('status:Show today and recent quota usage' 'reset:Delete the local quota counter')
+  catalog_sub=('path:Show overlay path' 'show:Show built-in/overlay/effective catalog' 'diff:Show overlay changes' 'refresh:Clear overlay cache')
+  cache_sub=('show:Summarize cache files' 'clear:Delete cache files')
+  history_sub=('show:Print recent audit entries' 'replay:Re-run one audited command')
+  plan_sub=('schema:Print the plan schema' 'validate:Validate a plan file' 'run:Validate and execute a plan')
   completion_shells=('bash' 'zsh' 'fish' 'powershell')
 
   local global_opts
   global_opts=(
     '--json[Raw JSON output]'
+    '--format[Output format]:type:(table json jsonl tsv yaml id)'
+    '--fields[Comma-separated output columns]:csv:'
     '(-v --verbose)'{-v,--verbose}'[Log HTTP details to stderr]'
     '--dry-run[Print mutating requests without sending]'
     '--timeout[HTTP timeout in ms]:ms:'
+    '--retry-on-429[Max 429 retries]:n:'
+    '--backoff[Retry backoff strategy]:strategy:(linear exponential)'
+    '--no-retry[Disable 429 retries]'
+    '--no-quota[Disable the local quota counter]'
+    '--cache[Cache mode]:mode:'
+    '--no-cache[Disable cache reads]'
     '--config[Override credential file path]:path:_files'
+    '--profile[Use a named credential profile]:name:'
+    '--audit-log[Append mutating commands to ~/.switchbot/audit.log]'
+    '--audit-log-path[Custom audit log file path]:path:_files'
     '(-h --help)'{-h,--help}'[Show help]'
     '(-V --version)'{-V,--version}'[Show version]'
   )
@@ -122,6 +192,12 @@ _switchbot() {
         devices)    _describe 'devices'    devices_sub ;;
         scenes)     _describe 'scenes'     scenes_sub ;;
         webhook)    _describe 'webhook'    webhook_sub ;;
+        events)     _describe 'events'     events_sub ;;
+        quota)      _describe 'quota'      quota_sub ;;
+        catalog)    _describe 'catalog'    catalog_sub ;;
+        cache)      _describe 'cache'      cache_sub ;;
+        history)    _describe 'history'    history_sub ;;
+        plan)       _describe 'plan'       plan_sub ;;
         completion) _values 'shell' $completion_shells ;;
       esac
       ;;
@@ -143,10 +219,21 @@ complete -c switchbot -f
 
 # Global options
 complete -c switchbot -l json        -d 'Raw JSON output'
+complete -c switchbot -l format   -r -d 'Output format'
+complete -c switchbot -l fields   -r -d 'Comma-separated output columns'
 complete -c switchbot -s v -l verbose -d 'Log HTTP details to stderr'
 complete -c switchbot -l dry-run     -d 'Print mutating requests without sending'
 complete -c switchbot -l timeout  -r -d 'HTTP timeout in ms'
+complete -c switchbot -l retry-on-429 -r -d 'Max 429 retries'
+complete -c switchbot -l backoff  -r -d 'Retry backoff strategy'
+complete -c switchbot -l no-retry    -d 'Disable 429 retries'
+complete -c switchbot -l no-quota    -d 'Disable the local quota counter'
+complete -c switchbot -l cache    -r -d 'Cache mode'
+complete -c switchbot -l no-cache    -d 'Disable cache reads'
 complete -c switchbot -l config   -r -d 'Credential file path'
+complete -c switchbot -l profile  -r -d 'Named credential profile'
+complete -c switchbot -l audit-log -d 'Append mutating commands to audit log'
+complete -c switchbot -l audit-log-path -r -d 'Custom audit log file path'
 complete -c switchbot -s h -l help -d 'Show help'
 complete -c switchbot -s V -l version -d 'Show version'
 
@@ -156,13 +243,23 @@ complete -c switchbot -n '__fish_use_subcommand' -a 'devices'    -d 'List and co
 complete -c switchbot -n '__fish_use_subcommand' -a 'scenes'     -d 'List and execute scenes'
 complete -c switchbot -n '__fish_use_subcommand' -a 'webhook'    -d 'Manage webhook configuration'
 complete -c switchbot -n '__fish_use_subcommand' -a 'completion' -d 'Print a shell completion script'
+complete -c switchbot -n '__fish_use_subcommand' -a 'mcp'        -d 'Run the MCP server'
+complete -c switchbot -n '__fish_use_subcommand' -a 'quota'      -d 'Inspect local request quota'
+complete -c switchbot -n '__fish_use_subcommand' -a 'catalog'    -d 'Inspect the built-in device catalog'
+complete -c switchbot -n '__fish_use_subcommand' -a 'cache'      -d 'Inspect local caches'
+complete -c switchbot -n '__fish_use_subcommand' -a 'events'     -d 'Receive webhook or MQTT events'
+complete -c switchbot -n '__fish_use_subcommand' -a 'doctor'     -d 'Run self-checks'
+complete -c switchbot -n '__fish_use_subcommand' -a 'schema'     -d 'Export the device catalog as JSON'
+complete -c switchbot -n '__fish_use_subcommand' -a 'history'    -d 'View and replay audited commands'
+complete -c switchbot -n '__fish_use_subcommand' -a 'plan'       -d 'Validate and run batch plans'
+complete -c switchbot -n '__fish_use_subcommand' -a 'capabilities' -d 'Print a machine-readable manifest'
 complete -c switchbot -n '__fish_use_subcommand' -a 'help'       -d 'Show help'
 
 # config
-complete -c switchbot -n '__fish_seen_subcommand_from config' -a 'set-token show'
+complete -c switchbot -n '__fish_seen_subcommand_from config' -a 'set-token show list-profiles'
 
 # devices
-complete -c switchbot -n '__fish_seen_subcommand_from devices' -a 'list status command types commands'
+complete -c switchbot -n '__fish_seen_subcommand_from devices' -a 'list ls status command types commands describe batch watch explain expand meta'
 
 # scenes
 complete -c switchbot -n '__fish_seen_subcommand_from scenes' -a 'list execute'
@@ -172,6 +269,24 @@ complete -c switchbot -n '__fish_seen_subcommand_from webhook' -a 'setup query u
 complete -c switchbot -n '__fish_seen_subcommand_from webhook; and __fish_seen_subcommand_from update' -l enable  -d 'Enable the webhook'
 complete -c switchbot -n '__fish_seen_subcommand_from webhook; and __fish_seen_subcommand_from update' -l disable -d 'Disable the webhook'
 
+# events
+complete -c switchbot -n '__fish_seen_subcommand_from events' -a 'tail mqtt-tail'
+
+# quota
+complete -c switchbot -n '__fish_seen_subcommand_from quota' -a 'status reset'
+
+# catalog
+complete -c switchbot -n '__fish_seen_subcommand_from catalog' -a 'path show diff refresh'
+
+# cache
+complete -c switchbot -n '__fish_seen_subcommand_from cache' -a 'show clear'
+
+# history
+complete -c switchbot -n '__fish_seen_subcommand_from history' -a 'show replay'
+
+# plan
+complete -c switchbot -n '__fish_seen_subcommand_from plan' -a 'schema validate run'
+
 # completion
 complete -c switchbot -n '__fish_seen_subcommand_from completion' -a 'bash zsh fish powershell'
 `;
@@ -186,13 +301,19 @@ Register-ArgumentCompleter -Native -CommandName switchbot -ScriptBlock {
   $tokens = $commandAst.CommandElements | ForEach-Object { $_.ToString() }
   $count = $tokens.Count
 
-  $top = 'config','devices','scenes','webhook','completion','help'
-  $configSub = 'set-token','show'
-  $devicesSub = 'list','status','command','types','commands'
+  $top = 'config','devices','scenes','webhook','completion','mcp','quota','catalog','cache','events','doctor','schema','history','plan','capabilities','help'
+  $configSub = 'set-token','show','list-profiles'
+  $devicesSub = 'list','ls','status','command','types','commands','describe','batch','watch','explain','expand','meta'
   $scenesSub = 'list','execute'
   $webhookSub = 'setup','query','update','delete'
+  $eventsSub = 'tail','mqtt-tail'
+  $quotaSub = 'status','reset'
+  $catalogSub = 'path','show','diff','refresh'
+  $cacheSub = 'show','clear'
+  $historySub = 'show','replay'
+  $planSub = 'schema','validate','run'
   $shells = 'bash','zsh','fish','powershell'
-  $globalOpts = '--json','--verbose','-v','--dry-run','--timeout','--config','--help','-h','--version','-V'
+  $globalOpts = '--json','--format','--fields','--verbose','-v','--dry-run','--timeout','--retry-on-429','--backoff','--no-retry','--no-quota','--cache','--no-cache','--config','--profile','--audit-log','--audit-log-path','--help','-h','--version','-V'
 
   function _emit($values) {
     $values |
@@ -206,6 +327,12 @@ Register-ArgumentCompleter -Native -CommandName switchbot -ScriptBlock {
     'config'     { if ($count -eq 3) { return _emit $configSub } }
     'devices'    { if ($count -eq 3) { return _emit $devicesSub } }
     'scenes'     { if ($count -eq 3) { return _emit $scenesSub } }
+    'events'     { if ($count -eq 3) { return _emit $eventsSub } }
+    'quota'      { if ($count -eq 3) { return _emit $quotaSub } }
+    'catalog'    { if ($count -eq 3) { return _emit $catalogSub } }
+    'cache'      { if ($count -eq 3) { return _emit $cacheSub } }
+    'history'    { if ($count -eq 3) { return _emit $historySub } }
+    'plan'       { if ($count -eq 3) { return _emit $planSub } }
     'webhook'    {
       if ($count -eq 3) { return _emit $webhookSub }
       if ($tokens[2] -eq 'update') { return _emit ('--enable','--disable' + $globalOpts) }

package/dist/commands/config.js

@@ -1,5 +1,6 @@
 import fs from 'node:fs';
 import { execFileSync } from 'node:child_process';
+import { stringArg } from '../utils/arg-parsers.js';
 import { saveConfig, showConfig, listProfiles } from '../config.js';
 import { isJsonMode, printJson } from '../utils/output.js';
 import chalk from 'chalk';
@@ -49,9 +50,9 @@ Obtain your token/secret from the SwitchBot mobile app:
         .description('Save token and secret (mode 0600). Use --profile to target a named profile.')
         .argument('[token]', 'API token; omit when using --from-env-file / --from-op')
         .argument('[secret]', 'API client secret; omit when using --from-env-file / --from-op')
-        .option('--from-env-file <path>', 'Read SWITCHBOT_TOKEN and SWITCHBOT_SECRET from a dotenv file')
-        .option('--from-op <tokenRef>', 'Read token via 1Password CLI (op read). Pair with --op-secret <ref>')
-        .option('--op-secret <secretRef>', '1Password reference for the secret, used with --from-op')
+        .option('--from-env-file <path>', 'Read SWITCHBOT_TOKEN and SWITCHBOT_SECRET from a dotenv file', stringArg('--from-env-file'))
+        .option('--from-op <tokenRef>', 'Read token via 1Password CLI (op read). Pair with --op-secret <ref>', stringArg('--from-op'))
+        .option('--op-secret <secretRef>', '1Password reference for the secret, used with --from-op', stringArg('--op-secret'))
         .addHelpText('after', `
 Examples:
   $ switchbot config set-token <token> <secret>

package/dist/commands/device-meta.js

@@ -1,3 +1,4 @@
+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';
 export function registerDevicesMetaCommand(devices) {
@@ -9,10 +10,10 @@ export function registerDevicesMetaCommand(devices) {
         .command('set')
         .description('Set local metadata for a device (alias, hide/show, notes)')
         .argument('<deviceId>', 'Target device ID')
-        .option('--alias <name>', 'Local alias for the device (used with --name flag)')
+        .option('--alias <name>', 'Local alias for the device (used with --name flag)', stringArg('--alias'))
         .option('--hide', 'Hide this device from "devices list"')
         .option('--show', 'Un-hide this device')
-        .option('--notes <text>', 'Freeform notes shown in "devices describe"')
+        .option('--notes <text>', 'Freeform notes shown in "devices describe"', stringArg('--notes'))
         .action((deviceId, options) => {
         try {
             if (options.hide && options.show) {

package/dist/commands/devices.js

@@ -1,3 +1,4 @@
+import { enumArg, stringArg } from '../utils/arg-parsers.js';
 import { printTable, printKeyValue, printJson, isJsonMode, handleError, UsageError } from '../utils/output.js';
 import { resolveFormat, resolveFields, renderRows } from '../utils/format.js';
 import { findCatalogEntry, getEffectiveCatalog } from '../devices/catalog.js';
@@ -5,6 +6,7 @@ import { getCachedDevice } from '../devices/cache.js';
 import { loadDeviceMeta } from '../devices/device-meta.js';
 import { resolveDeviceId } from '../utils/name-resolver.js';
 import { fetchDeviceList, fetchDeviceStatus, executeCommand, describeDevice, validateCommand, isDestructiveCommand, getDestructiveReason, buildHubLocationMap, DeviceNotFoundError, } from '../lib/devices.js';
+import { validateParameter } from '../devices/param-validator.js';
 import { registerBatchCommand } from './batch.js';
 import { registerWatchCommand } from './watch.js';
 import { registerExplainCommand } from './explain.js';
@@ -12,6 +14,7 @@ import { registerExpandCommand } from './expand.js';
 import { registerDevicesMetaCommand } from './device-meta.js';
 import { isDryRun } from '../utils/flags.js';
 export function registerDevicesCommand(program) {
+    const COMMAND_TYPES = ['command', 'customize'];
     const devices = program
         .command('devices')
         .description('Manage and control SwitchBot devices')
@@ -38,6 +41,7 @@ Run any subcommand with --help for its own flags and examples.
     // switchbot devices list
     devices
         .command('list')
+        .alias('ls')
         .description('List all physical devices and IR remote devices on the account')
         .addHelpText('after', `
 Default columns: deviceId, deviceName, type, category
@@ -72,7 +76,7 @@ Examples:
 `)
         .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)')
+        .option('--filter <expr>', 'Filter devices: "type=X", "name=X", "category=physical|ir", "room=X" (comma-separated key=value pairs)', stringArg('--filter'))
         .action(async (options) => {
         try {
             const body = await fetchDeviceList();
@@ -195,8 +199,8 @@ Examples:
         .command('status')
         .description('Query the real-time status of a specific device')
         .argument('[deviceId]', 'Device ID from "devices list" (or use --name or --ids)')
-        .option('--name <query>', 'Resolve device by fuzzy name instead of deviceId')
-        .option('--ids <list>', 'Comma-separated device IDs for batch status (incompatible with --name)')
+        .option('--name <query>', 'Resolve device by fuzzy name instead of deviceId', stringArg('--name'))
+        .option('--ids <list>', 'Comma-separated device IDs for batch status (incompatible with --name)', stringArg('--ids'))
         .addHelpText('after', `
 Status fields vary by device type. To discover them without a live call:
 
@@ -287,10 +291,10 @@ Examples:
         .argument('[deviceId]', 'Target device ID (or use --name)')
         .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')
+        .option('--name <query>', 'Resolve device by fuzzy name instead of deviceId', stringArg('--name'))
+        .option('--type <commandType>', 'Command type: "command" for built-in commands (default), "customize" for user-defined IR buttons', enumArg('--type', COMMAND_TYPES), 'command')
         .option('--yes', 'Confirm a destructive command (Smart Lock unlock, Garage open, …). --dry-run is always allowed without --yes.')
-        .option('--idempotency-key <key>', 'Idempotency key for deduplication (60s window; same key replays cached result)')
+        .option('--idempotency-key <key>', 'Idempotency key for deduplication (60s window; same key replays cached result)', stringArg('--idempotency-key'))
         .addHelpText('after', `
 ────────────────────────────────────────────────────────────────────────
 For the full list of commands a specific device supports — and their
@@ -338,19 +342,22 @@ Examples:
 `)
         .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.
+            // BUG-FIX: When --name is provided, Commander fills positionals left-to-right
+            // starting at [deviceId]. Shift them back to their semantic slots.
             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) {
+                // `--name "x" <cmd> [parameter]` → Commander binds deviceIdArg=<cmd>, cmdArg=[parameter].
+                if (!deviceIdArg) {
                     throw new UsageError('Command name is required (e.g. turnOn, turnOff, setAll).');
                 }
-                // --name "x" turnOn  →  deviceIdArg="turnOn", cmdArg=undefined → shift
-                cmd = (deviceIdArg ?? cmdArg);
+                cmd = deviceIdArg;
+                if (cmdArg !== undefined) {
+                    if (parameter !== undefined) {
+                        throw new UsageError('Too many positional arguments after --name. Expected: --name <query> <cmd> [parameter].');
+                    }
+                    parameter = cmdArg;
+                }
                 effectiveDeviceIdArg = undefined;
             }
             else {
@@ -361,6 +368,9 @@ Examples:
                 effectiveDeviceIdArg = deviceIdArg;
             }
             const deviceId = resolveDeviceId(effectiveDeviceIdArg, options.name);
+            if (!getCachedDevice(deviceId)) {
+                console.error(`Note: device ${deviceId} is not in the local cache — run 'switchbot devices list' first to enable command validation.`);
+            }
             const validation = validateCommand(deviceId, cmd, parameter, options.type);
             if (!validation.ok) {
                 const err = validation.error;
@@ -385,6 +395,37 @@ Examples:
                 }
                 process.exit(2);
             }
+            // Case-only mismatch: emit a warning and continue with the canonical name.
+            if (validation.caseNormalizedFrom && validation.normalized) {
+                console.error(`Note: '${validation.caseNormalizedFrom}' normalized to '${validation.normalized}' (case mismatch). Use exact casing to silence this warning.`);
+                cmd = validation.normalized;
+            }
+            else if (validation.normalized) {
+                cmd = validation.normalized;
+            }
+            // Raw-parameter validation (runs for known (deviceType, command) pairs only).
+            const cachedForParam = getCachedDevice(deviceId);
+            if (cachedForParam && options.type === 'command') {
+                const paramCheck = validateParameter(cachedForParam.type, cmd, parameter);
+                if (!paramCheck.ok) {
+                    if (isJsonMode()) {
+                        console.error(JSON.stringify({
+                            error: {
+                                code: 2,
+                                kind: 'usage',
+                                message: paramCheck.error,
+                                context: { command: cmd, deviceType: cachedForParam.type, deviceId },
+                            },
+                        }));
+                    }
+                    else {
+                        console.error(`Error: ${paramCheck.error}`);
+                    }
+                    process.exit(2);
+                }
+                if (paramCheck.normalized !== undefined)
+                    parameter = paramCheck.normalized;
+            }
             const cachedForGuard = getCachedDevice(deviceId);
             if (!options.yes &&
                 !isDryRun() &&
@@ -539,7 +580,7 @@ Examples:
         .command('describe')
         .description('Describe a device by ID: metadata + supported commands + status fields (1 API call)')
         .argument('[deviceId]', 'Target device ID (or use --name)')
-        .option('--name <query>', 'Resolve device by fuzzy name instead of deviceId')
+        .option('--name <query>', 'Resolve device by fuzzy name instead of deviceId', stringArg('--name'))
         .option('--live', 'Also fetch live status values and merge them into capabilities (costs 1 extra API call)')
         .addHelpText('after', `
 Makes a GET /v1.1/devices call to look up the device's type, then prints its

package/dist/commands/events.js

@@ -1,5 +1,6 @@
 import http from 'node:http';
 import { printJson, isJsonMode, handleError, UsageError } from '../utils/output.js';
+import { intArg, stringArg } from '../utils/arg-parsers.js';
 import { SwitchBotMqttClient } from '../mqtt/client.js';
 import { fetchMqttCredential } from '../mqtt/credential.js';
 import { tryLoadConfig } from '../config.js';
@@ -118,10 +119,10 @@ export function registerEventsCommand(program) {
     events
         .command('tail')
         .description('Run a local HTTP receiver and print incoming webhook events as JSONL')
-        .option('--port <n>', `Local port to listen on (default ${DEFAULT_PORT})`, String(DEFAULT_PORT))
-        .option('--path <p>', `HTTP path to match (default "${DEFAULT_PATH}"; use "*" for all paths)`, DEFAULT_PATH)
-        .option('--filter <expr>', 'Filter events, e.g. "deviceId=ABC123" or "type=Bot" (comma-separated)')
-        .option('--max <n>', 'Stop after N matching events (default: run until Ctrl-C)')
+        .option('--port <n>', `Local port to listen on (default ${DEFAULT_PORT})`, intArg('--port', { min: 1, max: 65535 }), String(DEFAULT_PORT))
+        .option('--path <p>', `HTTP path to match (default "${DEFAULT_PATH}"; use "*" for all paths)`, stringArg('--path'), DEFAULT_PATH)
+        .option('--filter <expr>', 'Filter events, e.g. "deviceId=ABC123" or "type=Bot" (comma-separated)', stringArg('--filter'))
+        .option('--max <n>', 'Stop after N matching events (default: run until Ctrl-C)', intArg('--max', { min: 1 }))
         .addHelpText('after', `
 SwitchBot posts events to a single webhook URL configured via:
   $ switchbot webhook setup https://<your-public-host>/<path>
@@ -199,20 +200,20 @@ Examples:
     events
         .command('mqtt-tail')
         .description('Subscribe to SwitchBot MQTT shadow events and stream them as JSONL')
-        .option('--topic <pattern>', 'MQTT topic filter (default: SwitchBot shadow topic from credential)')
-        .option('--max <n>', 'Stop after N events (default: run until Ctrl-C)')
+        .option('--topic <pattern>', 'MQTT topic filter (default: SwitchBot shadow topic from credential)', stringArg('--topic'))
+        .option('--max <n>', 'Stop after N events (default: run until Ctrl-C)', intArg('--max', { min: 1 }))
         .option('--sink <type>', 'Output sink: stdout (default), file, webhook, openclaw, telegram, homeassistant (repeatable)', (val, prev) => [...prev, val], [])
-        .option('--sink-file <path>', 'File path for file sink')
-        .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)')
+        .option('--sink-file <path>', 'File path for file sink', stringArg('--sink-file'))
+        .option('--webhook-url <url>', 'Webhook URL for webhook sink', stringArg('--webhook-url'))
+        .option('--openclaw-url <url>', 'OpenClaw gateway URL (default: http://localhost:18789)', stringArg('--openclaw-url'))
+        .option('--openclaw-token <token>', 'Bearer token for OpenClaw (or env OPENCLAW_TOKEN)', stringArg('--openclaw-token'))
+        .option('--openclaw-model <id>', 'OpenClaw agent model ID to route events to', stringArg('--openclaw-model'))
+        .option('--telegram-token <token>', 'Telegram bot token (or env TELEGRAM_TOKEN)', stringArg('--telegram-token'))
+        .option('--telegram-chat <id>', 'Telegram chat/channel ID to send messages to', stringArg('--telegram-chat'))
+        .option('--ha-url <url>', 'Home Assistant base URL (e.g. http://homeassistant.local:8123)', stringArg('--ha-url'))
+        .option('--ha-token <token>', 'HA long-lived access token (for REST event API)', stringArg('--ha-token'))
+        .option('--ha-webhook-id <id>', 'HA webhook ID (no auth; takes priority over --ha-token)', stringArg('--ha-webhook-id'))
+        .option('--ha-event-type <type>', 'HA event type for REST API (default: switchbot_event)', stringArg('--ha-event-type'))
         .addHelpText('after', `
 Connects to the SwitchBot MQTT service using your existing credentials
 (SWITCHBOT_TOKEN + SWITCHBOT_SECRET or ~/.switchbot/config.json).
@@ -343,10 +344,18 @@ Examples:
                     ac.abort();
                 }
             });
+            let mqttFailed = false;
             const unsubState = client.onStateChange((state) => {
                 if (!isJsonMode()) {
                     console.error(`[${new Date().toLocaleTimeString()}] MQTT state: ${state}`);
                 }
+                if (state === 'failed') {
+                    mqttFailed = true;
+                    if (!isJsonMode()) {
+                        console.error('MQTT connection failed permanently (credential expired or reconnect exhausted) — exiting.');
+                    }
+                    ac.abort();
+                }
             });
             await client.connect();
             client.subscribe(topic);
@@ -366,6 +375,10 @@ Examples:
                 process.once('SIGTERM', cleanup);
                 ac.signal.addEventListener('abort', cleanup, { once: true });
             });
+            if (mqttFailed) {
+                // Surface as a runtime error so supervisors (pm2, systemd) can restart.
+                process.exit(1);
+            }
         }
         catch (error) {
             handleError(error);