@switchbot/openapi-cli 2.1.0 → 2.2.1

package/README.md

@@ -165,7 +165,8 @@ switchbot config show
 | `--no-retry`                | Disable automatic 429 retries                                            |
 | `--backoff <strategy>`      | Retry backoff: `exponential` (default) or `linear`                      |
 | `--no-quota`                | Disable local request-quota tracking                                     |
-| `--audit-log [path]`        | Append mutating commands to a JSONL audit log (default path: `~/.switchbot/audit.log`) |
+| `--audit-log`               | Append mutating commands to a JSONL audit log (default path: `~/.switchbot/audit.log`) |
+| `--audit-log-path <path>`   | Custom audit log path; use together with `--audit-log`                   |
 | `-V`, `--version`           | Print the CLI version                                                    |
 | `-h`, `--help`              | Show help for any command or subcommand                                  |
 
@@ -176,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
@@ -205,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'
 
@@ -212,6 +216,11 @@ switchbot devices list --json | jq '.deviceList[].deviceId'
 # Physical: category = "physical"
 switchbot devices list --format=tsv --fields=deviceId,type,category
 
+# Filter devices by type / name / category / room (server-side filter keys)
+switchbot devices list --filter category=physical
+switchbot devices list --filter type=Bot
+switchbot devices list --filter name=living,category=physical
+
 # Filter by family / room (family & room info requires the 'src: OpenClaw'
 # header, which this CLI sends on every request)
 switchbot devices list --json | jq '.deviceList[] | select(.familyName == "Home")'
@@ -221,6 +230,16 @@ switchbot devices list --json | jq '[.deviceList[], .infraredRemoteList[]] | gro
 switchbot devices status <deviceId>
 switchbot devices status <deviceId> --json
 
+# Resolve device by fuzzy name instead of ID (status, command, describe, expand, watch)
+switchbot devices status --name "客厅空调"
+switchbot devices command --name "Office Light" turnOn
+switchbot devices describe --name "Kitchen Bot"
+
+# Batch status across multiple devices
+switchbot devices status --ids ABC,DEF,GHI
+switchbot devices status --ids ABC,DEF --fields power,battery  # only show specific fields
+switchbot devices status --ids ABC,DEF --format jsonl           # one JSON line per device
+
 # Send a control command
 switchbot devices command <deviceId> <cmd> [parameter] [--type command|customize]
 
@@ -229,7 +248,7 @@ switchbot devices describe <deviceId>
 switchbot devices describe <deviceId> --json
 
 # Discover what's supported (offline reference, no API call)
-switchbot devices types                 # List all device types + IR remote types
+switchbot devices types                 # List all device types + IR remote types (incl. role column)
 switchbot devices commands <type>       # Show commands, parameter formats, and status fields
 switchbot devices commands Bot
 switchbot devices commands "Smart Lock"
@@ -268,6 +287,8 @@ Some commands require a packed string like `"26,2,2,on"`. `devices expand` build
 ```bash
 # Air Conditioner — setAll
 switchbot devices expand <acId> setAll --temp 26 --mode cool --fan low --power on
+# Resolve by name
+switchbot devices expand --name "客厅空调" setAll --temp 26 --mode cool --fan low --power on
 
 # Curtain / Roller Shade — setPosition
 switchbot devices expand <curtainId> setPosition --position 50 --mode silent
@@ -412,6 +433,40 @@ nohup switchbot events mqtt-tail --json >> ~/switchbot-events.log 2>&1 &
 
 Run `switchbot doctor` to verify MQTT credentials are configured correctly before connecting.
 
+#### `mqtt-tail` sinks — route events to external services
+
+By default `mqtt-tail` prints JSONL to stdout. Use `--sink` (repeatable) to route events to one or more destinations instead:
+
+| Sink | Required flags |
+|---|---|
+| `stdout` | (default when no `--sink` given) |
+| `file` | `--sink-file <path>` — append JSONL |
+| `webhook` | `--webhook-url <url>` — HTTP POST each event |
+| `openclaw` | `--openclaw-url`, `--openclaw-token` (or `$OPENCLAW_TOKEN`), `--openclaw-model` |
+| `telegram` | `--telegram-token` (or `$TELEGRAM_TOKEN`), `--telegram-chat <chatId>` |
+| `homeassistant` | `--ha-url <url>` + `--ha-webhook-id` (no auth) or `--ha-token` (REST event API) |
+
+```bash
+# Push events to an OpenClaw agent (replaces the SwitchBot channel plugin)
+switchbot events mqtt-tail \
+  --sink openclaw \
+  --openclaw-token <token> \
+  --openclaw-model my-home-agent
+
+# Write to file + push to OpenClaw simultaneously
+switchbot events mqtt-tail \
+  --sink file --sink-file ~/.switchbot/events.jsonl \
+  --sink openclaw --openclaw-token <token> --openclaw-model home
+
+# Generic webhook (n8n, Make, etc.)
+switchbot events mqtt-tail --sink webhook --webhook-url https://n8n.local/hook/abc
+
+# Forward to Home Assistant via webhook trigger
+switchbot events mqtt-tail --sink homeassistant --ha-url http://homeassistant.local:8123 --ha-webhook-id switchbot
+```
+
+Device state is also persisted to `~/.switchbot/device-history/<deviceId>.json` (latest + 100-entry ring buffer) regardless of sink configuration. This enables the `get_device_history` MCP tool to answer state queries without an API call.
+
 ### `completion` — shell tab-completion
 
 ```bash
@@ -498,7 +553,7 @@ switchbot history replay 7          # re-run entry #7
 switchbot --json history show --limit 50 | jq '.entries[] | select(.result=="error")'
 ```
 
-Reads the JSONL audit log (`~/.switchbot/audit.log` by default; override with `--audit-log`). Each entry records the timestamp, command, device ID, result, and dry-run flag. `replay` re-runs the original command with the original arguments.
+Reads the JSONL audit log (`~/.switchbot/audit.log` by default; override with `--audit-log --audit-log-path <path>`). Each entry records the timestamp, command, device ID, result, and dry-run flag. `replay` re-runs the original command with the original arguments.
 
 ### `catalog` — device type catalog
 

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/capabilities.js

@@ -26,32 +26,42 @@ const MCP_TOOLS = [
     'run_scene',
     'search_catalog',
     'account_overview',
+    'get_device_history',
 ];
 export function registerCapabilitiesCommand(program) {
     program
         .command('capabilities')
         .description('Print a machine-readable manifest of CLI capabilities (for agent bootstrap)')
-        .action(() => {
+        .option('--minimal', 'Omit per-subcommand flag details to reduce output size')
+        .action((opts) => {
         const catalog = getEffectiveCatalog();
-        const commands = program.commands
-            .filter((c) => c.name() !== 'capabilities')
-            .map((c) => ({
-            name: c.name(),
-            description: c.description(),
-            subcommands: c.commands.map((s) => ({
-                name: s.name(),
-                description: s.description(),
-                args: s.registeredArguments.map((a) => ({
-                    name: a.name(),
-                    required: a.required,
-                    variadic: a.variadic,
-                })),
-                flags: s.options.map((o) => ({
-                    flags: o.flags,
-                    description: o.description,
-                })),
-            })),
-        }));
+        const allCommands = [
+            ...program.commands,
+            // Commander adds 'help' implicitly; include it explicitly so it appears in the manifest
+            { name: () => 'help', description: () => 'Display help for a command', commands: [], options: [], registeredArguments: [] },
+        ];
+        const commands = allCommands.map((c) => {
+            const entry = {
+                name: c.name(),
+                description: c.description(),
+            };
+            if (!opts.minimal) {
+                entry.subcommands = c.commands.map((s) => ({
+                    name: s.name(),
+                    description: s.description(),
+                    args: s.registeredArguments.map((a) => ({
+                        name: a.name(),
+                        required: a.required,
+                        variadic: a.variadic,
+                    })),
+                    flags: s.options.map((o) => ({
+                        flags: o.flags,
+                        description: o.description,
+                    })),
+                }));
+            }
+            return entry;
+        });
         const globalFlags = program.options.map((opt) => ({
             flags: opt.flags,
             description: opt.description,

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) {