@switchbot/openapi-cli 2.0.1 → 2.2.0

package/README.md

@@ -7,7 +7,7 @@
 [![CI](https://github.com/OpenWonderLabs/switchbot-openapi-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/OpenWonderLabs/switchbot-openapi-cli/actions/workflows/ci.yml)
 
 Command-line interface for the [SwitchBot API v1.1](https://github.com/OpenWonderLabs/SwitchBotAPI).
-List devices, query live status, send control commands, run scenes, and manage webhooks — all from your terminal or shell scripts.
+List devices, query live status, send control commands, run scenes, receive real-time events, and connect AI agents via the built-in MCP server — all from your terminal or shell scripts.
 
 - **npm package:** [`@switchbot/openapi-cli`](https://www.npmjs.com/package/@switchbot/openapi-cli)
 - **Source code:** [github.com/OpenWonderLabs/switchbot-openapi-cli](https://github.com/OpenWonderLabs/switchbot-openapi-cli)
@@ -41,11 +41,19 @@ Under the hood every surface shares the same catalog, cache, and HMAC client —
 - [Commands](#commands)
   - [`config`](#config--credential-management)
   - [`devices`](#devices--list-status-control)
+  - [`devices batch`](#devices-batch--bulk-commands)
+  - [`devices watch`](#devices-watch--poll-status)
   - [`scenes`](#scenes--run-manual-scenes)
   - [`webhook`](#webhook--receive-device-events-over-http)
-  - [`batch`](#batch--run-multiple-commands)
-  - [`watch`](#watch--poll-device-status)
+  - [`events`](#events--receive-device-events)
+  - [`plan`](#plan--declarative-batch-operations)
   - [`mcp`](#mcp--model-context-protocol-server)
+  - [`doctor`](#doctor--self-check)
+  - [`quota`](#quota--api-request-counter)
+  - [`history`](#history--audit-log)
+  - [`catalog`](#catalog--device-type-catalog)
+  - [`schema`](#schema--export-catalog-as-json)
+  - [`capabilities`](#capabilities--cli-manifest)
   - [`cache`](#cache--inspect-and-clear-local-cache)
   - [`completion`](#completion--shell-tab-completion)
 - [Output modes](#output-modes)
@@ -67,7 +75,7 @@ Under the hood every surface shares the same catalog, cache, and HMAC client —
 - 🎨 **Dual output modes** — colorized tables by default; `--json` passthrough for `jq` and scripting
 - 🔐 **Secure credentials** — HMAC-SHA256 signed requests; config file written with `0600`; env-var override for CI
 - 🔍 **Dry-run mode** — preview every mutating request before it hits the API
-- 🧪 **Fully tested** — 592 Vitest tests, mocked axios, zero network in CI
+- 🧪 **Fully tested** — 692 Vitest tests, mocked axios, zero network in CI
 - ⚡ **Shell completion** — Bash / Zsh / Fish / PowerShell
 
 ## Requirements
@@ -157,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                                  |
 
@@ -187,6 +196,7 @@ switchbot devices command ABC123 turnOn --dry-run
 ```bash
 switchbot config set-token <token> <secret>   # Save to ~/.switchbot/config.json
 switchbot config show                          # Print current source + masked secret
+switchbot config list-profiles                 # List saved profiles
 ```
 
 ### `devices` — list, status, control
@@ -203,6 +213,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")'
@@ -212,6 +227,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]
 
@@ -220,7 +245,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"
@@ -259,6 +284,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
@@ -272,13 +299,48 @@ switchbot devices expand <relayId> setMode --channel 1 --mode edge
 
 Run `switchbot devices expand <id> <command> --help` to see the available flags for any device command.
 
-#### `devices explain` — plain-language command description
+#### `devices explain` — one-shot device summary
+
+```bash
+# Metadata + supported commands + live status in one call
+switchbot devices explain <deviceId>
+
+# Skip live status fetch (catalog-only output, no API call)
+switchbot devices explain <deviceId> --no-live
+```
+
+Returns a combined view: static catalog info (commands, parameters, status fields) merged with the current live status. For Hub devices, also lists connected child devices. Prefer this over separate `status` + `describe` calls.
+
+#### `devices meta` — local device metadata
+
+```bash
+switchbot devices meta set <deviceId> --alias "Office Light"
+switchbot devices meta set <deviceId> --hide          # hide from `devices list`
+switchbot devices meta get <deviceId>
+switchbot devices meta list                            # show all saved metadata
+switchbot devices meta clear <deviceId>
+```
+
+Stores local annotations (alias, hidden flag, notes) in `~/.switchbot/device-meta.json`. The alias is used as a display name; `--show-hidden` on `devices list` reveals hidden devices.
+
+#### `devices batch` — bulk commands
 
 ```bash
-switchbot devices explain <deviceId> <command>   # e.g. "explain ABC123 setAll"
+# Send the same command to every device matching a filter
+switchbot devices batch turnOff --filter 'type=Bot'
+switchbot devices batch setBrightness 50 --filter 'type~=Light,family=Living'
+
+# Explicit device IDs (comma-separated)
+switchbot devices batch turnOn --ids ID1,ID2,ID3
+
+# Pipe device IDs from `devices list`
+switchbot devices list --format=id --filter 'type=Bot' | switchbot devices batch toggle -
+
+# Destructive commands require --yes
+switchbot devices batch unlock --filter 'type=Smart Lock' --yes
 ```
 
-Returns a human-readable description of what the command does and what each parameter means.
+Sends the same command to many devices in one run. Uses the same `--filter` expressions as `devices list`. Destructive commands (Smart Lock unlock, Garage Door Opener, etc.) require `--yes` to prevent accidents.
 
 ### `scenes` — run manual scenes
 
@@ -307,6 +369,101 @@ switchbot webhook delete https://your.host/hook
 
 The CLI validates that `<url>` is an absolute `http://` or `https://` URL before calling the API. `--enable` and `--disable` are mutually exclusive.
 
+### `events` — receive device events
+
+Two subcommands cover the two ways SwitchBot can push state changes to you.
+
+#### `events tail` — local webhook receiver
+
+```bash
+# Listen on port 3000 and print every incoming webhook POST
+switchbot events tail
+
+# Filter to one device
+switchbot events tail --filter deviceId=ABC123
+
+# Stop after 5 matching events
+switchbot events tail --filter 'type=WoMeter' --max 5
+
+# Custom port / path
+switchbot events tail --port 8080 --path /hook --json
+```
+
+Run `switchbot webhook setup https://your.host/hook` first to tell SwitchBot where to send events, then expose the local port via ngrok/cloudflared and point the webhook URL at it. `events tail` only runs the local receiver — tunnelling is up to you.
+
+Output (one JSON line per matched event):
+```
+{ "t": "2024-01-01T12:00:00.000Z", "remote": "1.2.3.4:54321", "path": "/", "body": {...}, "matched": true }
+```
+
+Filter keys: `deviceId=<id>`, `type=<deviceType>` (comma-separated for AND logic).
+
+#### `events mqtt-tail` — real-time MQTT stream
+
+```bash
+# Stream all shadow-update events (runs in foreground until Ctrl-C)
+switchbot events mqtt-tail
+
+# Filter to a topic subtree
+switchbot events mqtt-tail --topic 'switchbot/#'
+
+# Stop after 10 events
+switchbot events mqtt-tail --max 10 --json
+```
+
+Connects to the SwitchBot MQTT service automatically using the same credentials configured for the REST API (`SWITCHBOT_TOKEN` + `SWITCHBOT_SECRET`). No additional MQTT configuration is required — the client certificates are provisioned on first use.
+
+Output (one JSON line per message):
+```
+{ "t": "2024-01-01T12:00:00.000Z", "topic": "switchbot/abc123/status", "payload": {...} }
+```
+
+This command runs in the foreground and streams events until you press Ctrl-C. To run it persistently in the background, use a process manager:
+
+```bash
+# pm2
+pm2 start "switchbot events mqtt-tail --json" --name switchbot-events
+
+# nohup
+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
@@ -325,28 +482,36 @@ switchbot completion powershell >> $PROFILE
 
 Supported shells: `bash`, `zsh`, `fish`, `powershell` (`pwsh` is accepted as an alias).
 
-### `batch` — run multiple commands
+### `plan` — declarative batch operations
 
 ```bash
-# Run a sequence of commands from a JSON/YAML file
-switchbot batch run commands.json
-switchbot batch run commands.yaml --dry-run
+# Print the plan JSON Schema (give to your agent framework)
+switchbot plan schema
+
+# Validate a plan file without running it
+switchbot plan validate plan.json
 
-# Validate a plan file without executing it
-switchbot batch validate commands.json
+# Preview — mutations skipped, GETs still execute
+switchbot --dry-run plan run plan.json
+
+# Run — pass --yes to allow destructive steps
+switchbot plan run plan.json --yes
+switchbot plan run plan.json --continue-on-error
 ```
 
-A batch file is a JSON array of `{ deviceId, command, parameter?, commandType? }` objects.
+A plan file is a JSON document with `version`, `description`, and a `steps` array of `command`, `scene`, or `wait` steps. Steps execute sequentially; a failed step stops the run unless `--continue-on-error` is set. See [`docs/agent-guide.md`](./docs/agent-guide.md) for the full schema and agent integration patterns.
 
-### `watch` — poll device status
+### `devices watch` — poll status
 
 ```bash
 # Poll a device's status every 30 s until Ctrl-C
-switchbot watch <deviceId>
-switchbot watch <deviceId> --interval 10s --json
+switchbot devices watch <deviceId>
+
+# Custom interval; emit every tick even when nothing changed
+switchbot devices watch <deviceId> --interval 10s --include-unchanged --json
 ```
 
-Output is a stream of JSON status objects (with `--json`) or a refreshed table.
+Output is a JSONL stream of status-change events (with `--json`) or a refreshed table. Use `--max <n>` to stop after N ticks.
 
 ### `mcp` — Model Context Protocol server
 
@@ -358,6 +523,65 @@ switchbot mcp serve
 Exposes 8 MCP tools (`list_devices`, `describe_device`, `get_device_status`, `send_command`, `list_scenes`, `run_scene`, `search_catalog`, `account_overview`) plus a `switchbot://events` resource for real-time shadow updates.
 See [`docs/agent-guide.md`](./docs/agent-guide.md) for the full tool reference and safety rules (destructive-command guard).
 
+### `doctor` — self-check
+
+```bash
+switchbot doctor
+switchbot doctor --json
+```
+
+Runs 8 local checks (Node version, credentials, profiles, catalog, cache, quota file, clock, MQTT) and exits 1 if any check fails. `warn` results exit 0. The MQTT check reports `ok` when REST credentials are configured (auto-provisioned on first use). Use this to diagnose connectivity or config issues before running automation.
+
+### `quota` — API request counter
+
+```bash
+switchbot quota status     # today's usage + last 7 days
+switchbot quota reset      # delete the counter file
+```
+
+Tracks daily API calls against the 10,000/day account limit. The counter is stored in `~/.switchbot/quota.json` and incremented on every mutating request. Pass `--no-quota` to skip tracking for a single run.
+
+### `history` — audit log
+
+```bash
+switchbot history show              # recent entries (newest first)
+switchbot history show --limit 20   # last 20 entries
+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 --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
+
+```bash
+switchbot catalog show              # all 42 built-in types
+switchbot catalog show Bot          # one type
+switchbot catalog diff              # what a local overlay changes vs built-in
+switchbot catalog path              # location of the local overlay file
+switchbot catalog refresh           # reload local overlay (clears in-process cache)
+```
+
+The built-in catalog ships with the package. Create `~/.switchbot/catalog-overlay.json` to add, extend, or override type definitions without modifying the package.
+
+### `schema` — export catalog as JSON
+
+```bash
+switchbot schema export                         # all types as structured JSON
+switchbot schema export --type 'Strip Light'    # one type
+switchbot schema export --role sensor           # filter by role
+```
+
+Exports the effective catalog in a machine-readable format. Pipe the output into an agent's system prompt or tool schema to give it a complete picture of controllable devices.
+
+### `capabilities` — CLI manifest
+
+```bash
+switchbot capabilities --json
+```
+
+Prints a versioned JSON manifest describing available surfaces (CLI, MCP, MQTT, plan runner), commands, and environment variables. Designed for agents and tooling that need to discover the CLI's capabilities programmatically.
+
 ### `cache` — inspect and clear local cache
 
 ```bash
@@ -457,11 +681,11 @@ Typical errors bubble up in the form `Error: <message>` on stderr. The SwitchBot
 
 ## Environment variables
 
-| Variable            | Description                                                        |
-| ------------------- | ------------------------------------------------------------------ |
-| `SWITCHBOT_TOKEN`   | API token — takes priority over the config file                    |
-| `SWITCHBOT_SECRET`  | API secret — takes priority over the config file                   |
-| `NO_COLOR`          | Disable ANSI colors in all output (automatically respected)        |
+| Variable                    | Description                                                        |
+| --------------------------- | ------------------------------------------------------------------ |
+| `SWITCHBOT_TOKEN`           | API token — takes priority over the config file                    |
+| `SWITCHBOT_SECRET`          | API secret — takes priority over the config file                   |
+| `NO_COLOR`                  | Disable ANSI colors in all output (automatically respected)        |
 
 ## Scripting examples
 
@@ -484,7 +708,7 @@ npm install
 
 npm run dev -- <args>       # Run from TypeScript sources via tsx
 npm run build               # Compile to dist/
-npm test                    # Run the Vitest suite (592 tests)
+npm test                    # Run the Vitest suite (692 tests)
 npm run test:watch          # Watch mode
 npm run test:coverage       # Coverage report (v8, HTML + text)
 ```
@@ -506,21 +730,23 @@ src/
 ├── commands/
 │   ├── config.ts
 │   ├── devices.ts
+│   ├── expand.ts         # `devices expand` — semantic flag builder
+│   ├── explain.ts        # `devices explain` — one-shot device summary
+│   ├── device-meta.ts    # `devices meta` — local aliases / hide flags
 │   ├── scenes.ts
 │   ├── webhook.ts
-│   ├── batch.ts          # `switchbot batch run/validate`
-│   ├── watch.ts          # `switchbot watch <deviceId>`
-│   ├── mcp.ts            # `switchbot mcp serve` (MCP stdio server)
-│   ├── cache.ts          # `switchbot cache show/clear`
-│   ├── history.ts        # `switchbot history [replay]`
-│   ├── events.ts         # `switchbot events`
-│   ├── quota.ts          # `switchbot quota`
-│   ├── explain.ts        # `switchbot explain <deviceId>`
-│   ├── plan.ts           # `switchbot plan run <file>`
-│   ├── doctor.ts         # `switchbot doctor`
-│   ├── schema.ts         # `switchbot schema export`
-│   ├── catalog.ts        # `switchbot catalog search`
-│   └── completion.ts     # `switchbot completion bash|zsh|fish|powershell`
+│   ├── watch.ts          # `devices watch <deviceId>`
+│   ├── events.ts         # `events tail` / `events mqtt-tail`
+│   ├── mcp.ts            # `mcp serve` (MCP stdio/HTTP server)
+│   ├── plan.ts           # `plan run/validate`
+│   ├── cache.ts          # `cache show/clear`
+│   ├── history.ts        # `history show/replay`
+│   ├── quota.ts          # `quota status/reset`
+│   ├── catalog.ts        # `catalog show/diff/path`
+│   ├── schema.ts         # `schema export`
+│   ├── doctor.ts         # `doctor`
+│   ├── capabilities.ts   # `capabilities`
+│   └── completion.ts     # `completion bash|zsh|fish|powershell`
 └── utils/
     ├── flags.ts          # Global flag readers (isVerbose / isDryRun / getCacheMode / …)
     ├── output.ts         # printTable / printKeyValue / printJson / handleError / buildErrorPayload

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,
@@ -68,6 +78,13 @@ export function registerCapabilitiesCommand(program) {
                     tools: MCP_TOOLS,
                     resources: ['switchbot://events'],
                 },
+                mqtt: {
+                    mode: 'consumer',
+                    authSource: 'SWITCHBOT_TOKEN + SWITCHBOT_SECRET (auto-provisioned via POST /v1.1/iot/credential)',
+                    cliCmd: 'events mqtt-tail',
+                    mcpResource: 'switchbot://events',
+                    protocol: 'MQTTS with TLS client certificates (AWS IoT)',
+                },
                 plan: {
                     schemaCmd: 'plan schema',
                     validateCmd: 'plan validate -',