/shelly

name: shelly
description: "Read and control Shelly smart relays, plugs, lights, covers, shutters, shades, sensors, and energy devices through local Gen1/Gen2 HTTP APIs, Shelly Gen2 RPC methods such as Cover.GetConfig and Cover.GetStatus, or the Shelly Cloud Control API with guarded output changes."
user-invocable: true
requires:
  bins:
    - node
credentials:
  - id: shelly-cloud-auth-key
    kind: api_key
    required: false
    secret_ref:
      source: store
      id: SHELLY_CLOUD_AUTH_KEY
    scope: "Shelly Cloud Control API tenant host auth_key query parameter"
    how_to_obtain: "Generate an Authorization cloud key in Shelly Smart Control user settings. Set `SHELLY_CLOUD_AUTH_KEY` through browser admin at the active `/admin/secrets` route; if browser admin is unavailable, use `/secret set SHELLY_CLOUD_AUTH_KEY \"<key>\"` in browser `/chat` or TUI; local console fallback: `hybridclaw secret set SHELLY_CLOUD_AUTH_KEY \"<key>\"`."
  - id: shelly-cloud-access-token
    kind: bearer
    required: false
    secret_ref:
      source: store
      id: SHELLY_CLOUD_ACCESS_TOKEN
    scope: "Shelly Cloud Real Time Events HTTP API Authorization bearer"
    how_to_obtain: "Use Shelly's documented OAuth flow for the Real Time Events API. Set `SHELLY_CLOUD_ACCESS_TOKEN` through browser admin at the active `/admin/secrets` route; if browser admin is unavailable, use `/secret set SHELLY_CLOUD_ACCESS_TOKEN \"<access-token>\"` in browser `/chat` or TUI; local console fallback: `hybridclaw secret set SHELLY_CLOUD_ACCESS_TOKEN \"<access-token>\"`."
metadata:
  hybridclaw:
    category: home-automation
    short_description: "Shelly local and cloud device reads plus guarded output control."
    tags:
      - shelly
      - smart-home
      - iot
      - energy
      - relay
    stakes_tiers:
      green:
        - device.info
        - device.status
        - device.config
        - device.methods
        - device.components
        - gen1.get
        - rpc.get
        - cover.config
        - cover.status
        - switch.status
        - relay.status
        - cloud.state
        - cloud.oauth-token
        - cloud.all-status
        - cloud.websocket-url
      amber:
        - gen1.set
        - rpc.call
        - cloud.websocket-command
        - cover.open
        - cover.close
        - cover.stop
        - cover.goto
        - switch.set
        - switch.toggle
        - relay.set
        - light.set
      red:
        - factory-reset
        - reboot
        - firmware-update
    escalation:
      writes: confirm-each
      route: f14
    cost_measurement:
      system: UsageTotals
      sub_limit_key: shelly

Shelly

Use this skill for Shelly device inspection and guarded control through the bundled helper. Keep the markdown instructions generic; API-specific request construction belongs in `shelly.cjs`.

Core Contract

• Run Shelly HTTP operations through `skills/shelly/shelly.cjs`. Do not

handcraft Shelly URLs or JSON bodies when the helper supports the operation.

• The helper executes HTTP operations through the HybridClaw gateway, so normal

Shelly reads and writes should be a single helper command. Use `--request` only when an explicit request specification is needed for debugging or code review. For WebSocket planning outputs, use the emitted `webSocket` object as the complete connection or message specification.

• Read state before any relay, switch, light, or cover control operation.
• Treat control operations as amber. Before asking for approval, build an

`approval-plan` for the selected operation and include its `approvedHelperCommandText` in the approval request. Stop after presenting the plan. Only after the operator confirms in a later message, run that helper command exactly and use its emitted request specification unchanged.

• Do not perform factory reset, reboot, firmware update, Wi-Fi reset, auth

changes, or certificate upload through this skill.

Helper Operations

Use this command surface directly; do not rediscover flags by trial and error. Run `node skills/shelly/shelly.cjs --help` only when the surface below appears stale. The helper owns the Shelly API method, path, body selection, gateway dispatch, secret injection, and response wrapping. Normal HTTP commands execute the request and return `command: "live"`, the operation, a redacted request summary, and the gateway result. `--request` emits a request wrapper containing `command`, `operation`, `stakesTier`, and `httpRequest` without executing it. WebSocket helpers emit `webSocket` instead of `httpRequest`. `approval-plan` emits no `httpRequest`; it validates an amber command and returns the exact approved helper command to run after confirmation.

Command surface:

node skills/shelly/shelly.cjs [--format json|pretty] [--request] <resource> <action> [flags]
node skills/shelly/shelly.cjs [--format json|pretty] approval-plan <resource> <action> [flags]

device info --device-url http://192.0.2.10 [--ident]
device status --device-url http://192.0.2.10
device config --device-url http://192.0.2.10
device methods --device-url http://192.0.2.10
device components --device-url http://192.0.2.10 [--include status] [--include config] [--key switch:0]
cover config --device-url http://192.0.2.10 --id 0
cover status --device-url http://192.0.2.10 --id 0
cover open --device-url http://192.0.2.10 --id 0 --operator-grant
cover close --device-url http://192.0.2.10 --id 0 --operator-grant
cover stop --device-url http://192.0.2.10 --id 0 --operator-grant
cover goto --device-url http://192.0.2.10 --id 0 --position 50 --operator-grant
cover status --cloud-host https://<HOST> --device-id abc123
cover goto --cloud-host https://<HOST> --device-id abc123 --position 50 --operator-grant
switch status --device-url http://192.0.2.10 --id 0
switch set --device-url http://192.0.2.10 --id 0 --on true --operator-grant
switch toggle --device-url http://192.0.2.10 --id 0 --operator-grant
switch set --cloud-host htt