openwonderlabs/switchbot-openapi-cli/switchbot

SwitchBot skill

Drive the user's SwitchBot smart home through the switchbot CLI. Always query the CLI for ground truth — never guess commands, deviceIds, or parameter values.

Authority chain

Network requirements

switchbot codex setup requires outbound internet (npm registry + GitHub). If it fails with a network error, read references/codex-network.md for the ~/.codex/config.toml fix.

Required bootstrap

Before any action, run:

switchbot agent-bootstrap --compact

The response contains: cliVersion, safetyTiers, nameStrategies, profile, quota, devices[] (cached, with deviceId/type/name/category/roomName), catalog, and hints[].

If devices look stale (user just added one), refresh with switchbot devices list --json.

Then read the user's policy:

cat ~/.config/openclaw/switchbot/policy.yaml 2>/dev/null

If the file doesn't exist, proceed with default safety tiers and tell the user once they can create one with switchbot policy new.

Resolving a name to a device

When the user says "bedroom light", resolve in this order:

1. alias — policy.yaml alias map → <deviceId>. Most reliable.
2. exact — device name == "bedroom light" (case-insensitive).
3. prefix — name starts with the phrase.
4. substring — name contains the phrase.
5. fuzzy — Levenshtein distance ≤ 2.
6. require-unique — multiple matches at same tier → stop and ask. Never pick silently.

Safety gates

Policy overrides: confirmations.always_confirm forces confirmation; confirmations.never_confirm pre-approves (never add destructive actions). quiet_hours requires confirmation even for mutation.

Policy compliance

1. Run switchbot policy validate --live --json through the CLI once per device-control session. Use policy_validate(live=true) only when a separately configured MCP server exposes it; the default profile does not.
2. Honour quiet_hours, always_confirm, and never_confirm from the validated policy.
3. No policy file → proceed with default tiers.

Never write to policy.yaml without showing a diff and getting explicit approval.

Audit logging

The default MCP profile does not expose audit administration. Review past activity with switchbot history show --json through the CLI, or use audit_query / audit_stats only when a separately configured server exposes those tools. Enable CLI mutation logging explicitly with switchbot --audit-log devices command <id> <cmd>.

Output modes

Always use --json when parsing output. Use --format=markdown for user-facing summaries. Never parse markdown or human tables programmatically — re-run with --json.

Credentials

First-time login: switchbot auth login (opens browser). Headless: add --no-open. Inspect the active keychain backend: switchbot auth keychain describe --json. Reset cache without touching credentials: switchbot reset [--all]. Never run auth login or auth keychain set on the user's behalf.

Declarative automations (CLI ≥ 3.9.0)

When the user wants "when X, do Y", author a rule in policy.yaml instead of a shell loop. Validate the policy through switchbot policy validate --json; CLI 3.9.0 requires "0.2". A legacy "0.1" file must be migrated with CLI ≤2.15 before returning to this CLI.

Start with dry_run: true:

automation:
  enabled: true
  rules:
    - name: "hallway motion at night"
      when: { source: mqtt, event: motion.detected, device: "hallway sensor" }
      conditions:
        - time_between: ["22:00", "07:00"]
      then:
        - { command: "devices command <id> turnOn", device: "hallway lamp" }
      throttle: { max_per: "10m" }
      dry_run: true

Trigger kinds: source: mqtt (shadow events), source: cron (schedule + optional days:), source: webhook (bearer-token HTTP). Conditions: time_between, {device, field, op, value}, all:, any:, not:.

The validator rejects any rule with a destructive action in then[]. Always start dry, confirm firings via switchbot rules tail --follow, then remove dry_run.

switchbot policy validate
switchbot rules lint && switchbot rules reload

Semi-autonomous workflow — plan suggest + --require-approval

switchbot plan suggest --intent "turn off all lights" --device <id1> --device <id2>
# Review/edit the generated JSON
switchbot plan run plan.json --require-approval

Non-destructive steps run automatically; destructive steps prompt once. Via MCP: call plan_suggest, then have the user run --require-approval in a TTY session.

Common pitfalls

1. Don't parse help text. Always --help --json.
2. Don't rely on `--name` picking one hit. Resolve the name yourself; pass deviceId directly.
3. Check `commands[]` before calling a command. switchbot devices describe <id> --json — not every device supports every command.
4. Quota counts attempts, not successes. Above 80%, slow down and batch.
5. `--json` envelope — every response is {"schemaVersion":"1.2","data":...} or {"schemaVersion":"1.2","error":{...}}. Read .data, check .error first. Parsers that read top-level fields silently get undefined.

Error handling

{ "error": { "kind": "usage|auth|quota|network|upstream|internal", "message": "...", "hint": "..." } }

• usage → you called something wrong; re-read help and retry.
• auth → run switchbot doctor --section credentials.
• quota → stop; resets at midnight UTC.
• network → retry once, then surface.
• upstream → relay verbatim.
• internal → ask user to run switchbot doctor --json and file an issue.

Never retry destructive actions automatically. For mutation retries, use a local fingerprint {deviceId, command, args, minute-bucket} as an idempotency gate.

Things to never do

• Ask the user for their SwitchBot token or secret.
• Suggest flags that bypass safety tiers (--skip-confirmation, --force) unless the user named them explicitly.
• Claim IR actions "succeeded" — IR is open-loop; say the signal was sent.
• Write to policy.yaml without showing a diff and getting explicit approval.
• Generate a rule with a destructive command in then[].
• Arm a rule (dry_run: false) on first author without the user confirming firings.
• Set automation.enabled: true without explicitly informing the user.
• Run switchbot doctor --fix --yes without the user asking.

Version

Targets @switchbot/openapi-cli ≥ 3.9.0. If switchbot --version is older: npm update -g @switchbot/openapi-cli.

<!-- MAINTENANCE: Identical copy at plugins/switchbot/skills/switchbot/SKILL.md — keep both in sync. -->