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)
• RGB / RGBW / CCT / dimmable light control (shelly light, Gen2/Gen3)
• Multi-channel device support, per-plug control via --id (e.g., Shelly 2.5 dual relays, PowerStrip)
• 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
• Config backup and restore with network-safe defaults
• Schedule and webhook inspection (Gen2/Gen3)
• Device renaming and configuration from the CLI
• Structured JSON output for scripting and AI agent integration
• Shell completions with dynamic device name suggestions (bash, zsh, fish)
• Fuzzy device name matching with "did you mean?" suggestions
• Color output with automatic detection

Install

uv (recommended)

uv tool install shelly-cli

# Or run without installing
uvx shelly-cli --help

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

For multi-channel devices (dual relays, power strips), select a specific plug/channel with --id (defaults to 0). The available switch IDs are listed by shelly info.

shelly info -n "Office Strip"           # Lists Switch 0, Switch 1, ...
shelly on  -n "Office Strip" --id 1     # Turn on plug 1
shelly off -n "Office Strip" --id 3     # Turn off plug 3
shelly switch status -n "Office Strip" --id 2   # Status of plug 2

Light control (Gen2/Gen3 RGB / RGBW / CCT / dimmable)

shelly light on  -n "Desk Lamp" --color '#00ff88'        # RGB color (hex)
shelly light on  -n "Desk Lamp" --color warm             # named color
shelly light on  -n "Desk Lamp" --rgb 0,255,136 --brightness 80
shelly light set -n "Desk Lamp" --brightness 40          # change brightness, keep power state
shelly light on  -n "Strip" --rgb 255,0,0 --white 0      # RGBW: color + white channel
shelly light on  -n "Bulb" --temp 3000 --brightness 60   # CCT: color temperature (Kelvin)
shelly light off -n "Desk Lamp"
shelly light toggle -n "Desk Lamp"
shelly light status -n "Desk Lamp"

--id selects the component on multi-light devices (default 0). Brightness is 1-100 for RGB/RGBW and 0-100 for CCT/dimmable. --color accepts hex (#rrggbb) or a name (red, green, blue, white, warm, cyan, magenta, yellow, orange, purple, pink, off); --rgb takes r,g,b each 0-255.

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

Configuration

shelly config get -n "Kitchen"                  # Get device config (JSON)
shelly config get -a                            # Get config for all devices
shelly config set -n "Kitchen" eco_mode true    # Set a config value
shelly config set -n "Kitchen" name "New Name"  # Rename via config

Supported config keys: name, eco_mode, led_status_disable.

Backup and restore

shelly backup -n "Kitchen"         # Backup single device
shelly backup -a                   # Backup all devices to shelly-backups/
shelly backup -a -o ~/backups      # Custom output directory

shelly restore -n "Kitchen" shelly-backups/kitchen-2025-01-15.json

Restore skips network/WiFi/MQTT/cloud settings to avoid bricking devices.

Schedules and webhooks

shelly schedule list -n "Kitchen"  # View device schedules (Gen2/Gen3)
shelly schedule list -a            # View all device schedules

shelly webhook list -n "Kitchen"   # View device webhooks
shelly webhook list -a             # View all device webhooks

Groups

shelly group add lights "Kitchen" "Living Room" "Bedroom"
shelly group list
shelly group show lights
shelly -g lights off               # Turn off all lights
shelly -g lights status            # Status of all lights
shelly -g gen3 firmware check      # Check firmware for Gen3 devices

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"

shelly watch distinguishes rejected credentials from devices that are truly offline. When a device shows AUTH, press p to enter a replacement password with hidden input. The dashboard restores the normal terminal for the prompt, saves the credential in an owner-only config file, and resumes automatically.

Shell completions

# Generate completions (includes dynamic device name suggestions)
shelly completions zsh > ~/.zfunc/_shelly    # zsh
shelly completions bash > /etc/bash_completion.d/shelly  # bash
shelly completions fish > ~/.config/fish/completions/shelly.fish  # fish

# After installing, tab-complete device names:
# shelly -n <TAB>  →  "Kitchen Light"  "Living Room"  "Bedroom Fan"
# shelly -g <TAB>  →  "lights"  "gen1"  "gen3"

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 with types, targeting docs, and error codes
shelly schema

Error codes: DEVICE_NOT_FOUND, DEVICE_UNREACHABLE, AUTH_REQUIRED, NETWORK_ERROR, INVALID_INPUT, GROUP_NOT_FOUND, NO_CACHED_DEVICES, PARTIAL_FAILURE.

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.

Releasing

Vership owns versioning, changelog generation, release commits, and tags. See the release runbook for the verified workflow and recovery policy.