shelly-cli 0.1.2

CLI for managing and controlling Shelly devices

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

Generation	Examples	Status
Gen1	Shelly 1, 1PM, 2.5, Plug S, Dimmer	Supported (switch, power, firmware)
Gen2	Shelly Plus 1, Plus 1PM, Plus 2PM	Supported (switch, power, firmware)
Gen3	Shelly Mini 1PM G3, Plus series G3	Supported (switch, power, firmware)

License

MIT License -- see LICENSE file.