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":"[Truncated]","amber":"[Truncated]","red":"[Truncated]"},"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 https://<HOST> --device-id abc123 --on true --operator-grant
relay status --device-url http://192.0.2.10 --id 0
relay set --device-url http://192.0.2.10 --id 0 --turn on|off|toggle --operator-grant
light set --cloud-host https://<HOST> --device-id abc123 --on true --brightness 50 --operator-grant
cloud state --cloud-host https://<HOST> --device-id abc123 --select status
cloud all-status --cloud-host https://<HOST>
cloud oauth-token --cloud-host https://<HOST>
cloud websocket-url --cloud-host https://<HOST>
cloud websocket-command --cloud-host https://<HOST> --device-id abc123 --cmd roller_to_pos --params-json '{"id":0,"pos":50}' --operator-grant
gen1 get --device-url http://192.0.2.10 --path /settings [--query key=value]
gen1 set --device-url http://192.0.2.10 --path /settings/relay/0 --query default_state=on --operator-grant
rpc get --device-url http://192.0.2.10 --method Cloud.GetStatus [--param id=0] [--params-json '{}']
rpc call --device-url http://192.0.2.10 --method Cover.Calibrate --params-json '{"id":0}' --operator-grant