shelly

A fast CLI for discovering, monitoring, and controlling Shelly smart home devices.

Features

• Auto-discovery of Shelly devices on the local network (with subnet auto-detection)
• Unified Gen1 + Gen2/Gen3 support (transparent protocol handling)
• Multi-switch device support (e.g., Shelly 2.5 with dual relays)
• Interactive watch dashboard with live power, temperature, WiFi monitoring -- and switch control
• Energy consumption tracking (total kWh per device)
• Detailed device info view (model, firmware, uptime, WiFi, temperature)
• Device health checks (temperature, WiFi signal, firmware, uptime)
• Device authentication (--password flag or config file)
• Device groups with filter-based and name-based definitions
• Firmware check and update across all devices
• Device renaming from the CLI
• Structured JSON output for scripting and AI agent integration
• Shell completions (bash, zsh, fish, powershell)
• Fuzzy device name matching with "did you mean?" suggestions
• Color output with automatic detection

Install

uv (recommended)

uv tool install shelly-cli

Homebrew (macOS/Linux)

brew install rvben/tap/shelly-cli

pip

pip install shelly-cli

Cargo

cargo install shelly-cli

Pre-built binaries

Download from GitHub Releases.

Quick Start

# 1. Discover devices (auto-detects your subnet)
shelly discover

# 2. See what you found
shelly devices

# 3. Check device health
shelly health

Usage

Device control

shelly on "Kitchen Light"          # Turn on
shelly off "Kitchen Light"         # Turn off
shelly toggle -n "Living Room"     # Toggle
shelly status -n "Kitchen Light"   # Get status

Monitoring

shelly watch                       # Interactive dashboard
shelly health                      # Health check all devices
shelly power -a                    # Power usage for all devices
shelly energy -a                   # Total energy (kWh) per device
shelly info -n "Kitchen Light"     # Detailed device info

Device management

shelly rename -n "old-name" "New Name"    # Rename device
shelly firmware check -a                   # Check for updates
shelly firmware update -a                  # Update all firmware
shelly reboot -n "Kitchen Light"          # Reboot device

Groups

shelly group add lights "Kitchen" "Living Room" "Bedroom"
shelly group list
shelly -g lights off               # Turn off all lights
shelly -g lights status            # Status of all lights

Authentication

For devices with authentication enabled:

# Per-command
shelly --password "secret" status -a

# Or set in config file (~/.config/shelly-cli/config.toml)
# [auth]
# password = "secret"

Configuration

shelly config get -n "Kitchen"     # Get device config
shelly completions zsh             # Generate shell completions

Agent Integration

Designed for scripting and AI agent use with structured, machine-readable output.

# Structured JSON output (auto-enabled when piped)
shelly status -a | jq '.data'

# Consistent envelope: {"ok": true, "data": ...} or {"ok": false, "error": {...}}
shelly -n "nonexistent" status
# {"ok": false, "error": {"code": "DEVICE_NOT_FOUND", "message": "..."}}

# Machine-readable schema
shelly schema

Groups Configuration

Groups are defined in a TOML file:

# ~/.config/shelly-cli/groups.toml (Linux)
# ~/Library/Application Support/shelly-cli/groups.toml (macOS)

[groups]
lights = ["Kitchen Light", "Living Room Light", "Bedroom Light"]
gen1 = { filter = "gen1" }
gen3 = { filter = "gen3" }
all = { filter = "all" }

Or manage via CLI: shelly group add, shelly group remove, shelly group show.

Supported Devices

License

MIT License -- see LICENSE file.