@switchbot/openapi-cli 2.2.0 → 2.2.1

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'
 

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';
@@ -12,6 +13,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 +40,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 +75,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 +198,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 +290,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
@@ -361,6 +364,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;
@@ -539,7 +545,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);

package/dist/commands/expand.js

@@ -1,3 +1,4 @@
+import { intArg, stringArg } from '../utils/arg-parsers.js';
 import { handleError, isJsonMode, printJson, UsageError } from '../utils/output.js';
 import { getCachedDevice } from '../devices/cache.js';
 import { executeCommand, isDestructiveCommand, getDestructiveReason } from '../lib/devices.js';
@@ -88,15 +89,15 @@ export function registerExpandCommand(devices) {
         .description('Send a command with semantic flags instead of raw positional parameters')
         .argument('[deviceId]', 'Target device ID from "devices list" (or use --name)')
         .argument('[command]', 'Command name: setAll (AC), setPosition (Curtain/Blind Tilt), setMode (Relay Switch 2)')
-        .option('--name <query>', 'Resolve device by fuzzy name instead of deviceId')
-        .option('--temp <celsius>', 'AC setAll: temperature in Celsius (16-30)')
-        .option('--mode <mode>', 'AC: auto|cool|dry|fan|heat  Curtain: default|performance|silent  Relay: toggle|edge|detached|momentary')
-        .option('--fan <speed>', 'AC setAll: fan speed auto|low|mid|high')
-        .option('--power <state>', 'AC setAll: on|off')
-        .option('--position <percent>', 'Curtain setPosition: 0-100 (0=open, 100=closed)')
-        .option('--direction <dir>', 'Blind Tilt setPosition: up|down')
-        .option('--angle <percent>', 'Blind Tilt setPosition: 0-100 (0=closed, 100=open)')
-        .option('--channel <n>', 'Relay Switch 2 setMode: channel 1 or 2')
+        .option('--name <query>', 'Resolve device by fuzzy name instead of deviceId', stringArg('--name'))
+        .option('--temp <celsius>', 'AC setAll: temperature in Celsius (16-30)', intArg('--temp', { min: 16, max: 30 }))
+        .option('--mode <mode>', 'AC: auto|cool|dry|fan|heat  Curtain: default|performance|silent  Relay: toggle|edge|detached|momentary', stringArg('--mode'))
+        .option('--fan <speed>', 'AC setAll: fan speed auto|low|mid|high', stringArg('--fan'))
+        .option('--power <state>', 'AC setAll: on|off', stringArg('--power'))
+        .option('--position <percent>', 'Curtain setPosition: 0-100 (0=open, 100=closed)', intArg('--position', { min: 0, max: 100 }))
+        .option('--direction <dir>', 'Blind Tilt setPosition: up|down', stringArg('--direction'))
+        .option('--angle <percent>', 'Blind Tilt setPosition: 0-100 (0=closed, 100=open)', intArg('--angle', { min: 0, max: 100 }))
+        .option('--channel <n>', 'Relay Switch 2 setMode: channel 1 or 2', intArg('--channel', { min: 1, max: 2 }))
         .option('--yes', 'Confirm destructive commands')
         .addHelpText('after', `
 Translates semantic flags into the wire parameter format, then sends the command.

package/dist/commands/history.js

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

package/dist/commands/mcp.js

@@ -2,6 +2,7 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { z } from 'zod';
+import { intArg, stringArg } from '../utils/arg-parsers.js';
 import { handleError, isJsonMode } from '../utils/output.js';
 import { fetchDeviceList, fetchDeviceStatus, executeCommand, describeDevice, validateCommand, isDestructiveCommand, getDestructiveReason, searchCatalog, DeviceNotFoundError, toMcpDescribeShape, toMcpDeviceListShape, toMcpIrDeviceShape, } from '../lib/devices.js';
 import { fetchScenes, executeScene } from '../lib/scenes.js';
@@ -489,11 +490,11 @@ Inspect locally:
     mcp
         .command('serve')
         .description('Start the MCP server on stdio (default) or HTTP (--port)')
-        .option('--port <n>', 'Listen on HTTP instead of stdio (Streamable HTTP transport)')
-        .option('--bind <host>', 'IP address to bind (default 127.0.0.1; use 0.0.0.0 to accept external connections)', '127.0.0.1')
-        .option('--auth-token <token>', 'Bearer token for HTTP requests (required for --bind 0.0.0.0; falls back to SWITCHBOT_MCP_TOKEN env var)')
-        .option('--cors-origin <url>', 'Allowed CORS origin(s) for HTTP (repeatable)')
-        .option('--rate-limit <n>', 'Max requests per minute per profile (default 60)', '60')
+        .option('--port <n>', 'Listen on HTTP instead of stdio (Streamable HTTP transport)', intArg('--port', { min: 1, max: 65535 }))
+        .option('--bind <host>', 'IP address to bind (default 127.0.0.1; use 0.0.0.0 to accept external connections)', stringArg('--bind'), '127.0.0.1')
+        .option('--auth-token <token>', 'Bearer token for HTTP requests (required for --bind 0.0.0.0; falls back to SWITCHBOT_MCP_TOKEN env var)', stringArg('--auth-token'))
+        .option('--cors-origin <url>', 'Allowed CORS origin(s) for HTTP (repeatable)', stringArg('--cors-origin'))
+        .option('--rate-limit <n>', 'Max requests per minute per profile (default 60)', intArg('--rate-limit', { min: 1 }), '60')
         .action(async (options) => {
         try {
             if (options.port) {

package/dist/commands/schema.js

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

package/dist/commands/watch.js

@@ -2,6 +2,7 @@ import { printJson, isJsonMode, handleError, UsageError } from '../utils/output.
 import { fetchDeviceStatus } from '../lib/devices.js';
 import { getCachedDevice } from '../devices/cache.js';
 import { parseDurationToMs, getFields } from '../utils/flags.js';
+import { intArg, durationArg, stringArg } from '../utils/arg-parsers.js';
 import { createClient } from '../api/client.js';
 import { resolveDeviceId } from '../utils/name-resolver.js';
 const DEFAULT_INTERVAL_MS = 30_000;
@@ -57,9 +58,9 @@ export function registerWatchCommand(devices) {
         .command('watch')
         .description('Poll device status on an interval and emit field-level changes (JSONL)')
         .argument('[deviceId...]', 'One or more deviceIds to watch (or use --name for one device)')
-        .option('--name <query>', 'Resolve one device by fuzzy name (combined with any positional IDs)')
-        .option('--interval <dur>', `Polling interval: "30s", "1m", "500ms", ... (default 30s, min ${MIN_INTERVAL_MS / 1000}s)`, '30s')
-        .option('--max <n>', 'Stop after N ticks (default: run until Ctrl-C)')
+        .option('--name <query>', 'Resolve one device by fuzzy name (combined with any positional IDs)', stringArg('--name'))
+        .option('--interval <dur>', `Polling interval: "30s", "1m", "500ms", ... (default 30s, min ${MIN_INTERVAL_MS / 1000}s)`, durationArg('--interval'), '30s')
+        .option('--max <n>', 'Stop after N ticks (default: run until Ctrl-C)', intArg('--max', { min: 1 }))
         .option('--include-unchanged', 'Emit a tick even when no field changed')
         .addHelpText('after', `
 Each poll emits one JSON line per deviceId with the shape:

package/dist/commands/webhook.js

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

package/dist/config.js

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

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,26 +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('--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')
+    .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);
@@ -95,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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@switchbot/openapi-cli",
-  "version": "2.2.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",