A powerful, intuitive command-line interface for managing Shelly smart home devices.
Installation • Quick Start • Highlights • Documentation • Contributing
- 🎯 Full Shelly API Coverage - Control all Gen1, Gen2, Gen3, and Gen4 devices
- 📊 TUI Dashboard - Interactive terminal dashboard inspired by k9s and gh-dash
- 🔍 Device Discovery - Automatic discovery via mDNS, BLE, and CoIoT
- ⚡ Batch Operations - Control multiple devices simultaneously
- 🎬 Scene Management - Create and activate scenes across devices
- 🔧 Firmware Management - Check, update, and manage firmware versions
- 📜 Script Management - Upload, edit, and manage device scripts (Gen2+)
- ⏰ Schedule Management - Create and manage on-device schedules
- 💾 Backup & Restore - Full device configuration backup and restore
- 🔌 Plugin System - Extend functionality with custom plugins (gh-style)
- 🏷️ Alias System - Create shortcuts for common commands
- 🎨 Theme Support - 280+ built-in themes via bubbletint
- 🐚 Shell Completions - Bash, Zsh, Fish, and PowerShell
- 📤 Multiple Output Formats - JSON, YAML, table, and CSV output
- ⚡ Energy Monitoring - Track power consumption and energy usage
- 🏠 Smart Home Protocols - BTHome, Zigbee, Matter, and LoRa support
Built different: gh-style architecture with factory pattern DI, 280+ themes, extensible plugin system, and comprehensive device coverage across all Shelly generations.
brew install tj-smith47/tap/shelly-cligo install github.com/tj-smith47/shelly-cli/cmd/shelly@latest# Pull the image
docker pull ghcr.io/tj-smith47/shelly-cli:latest
# Run a command
docker run --rm ghcr.io/tj-smith47/shelly-cli:latest device list
# With config mount
docker run --rm -v ~/.config/shelly:/home/shelly/.config/shelly ghcr.io/tj-smith47/shelly-cli:latest status kitchenDownload the latest release from the releases page.
Available for:
- Linux (amd64, arm64)
- macOS (amd64, arm64)
- Windows (amd64)
# Initialize the CLI (first-time setup)
shelly init
# Discover devices on your network
shelly discover
# Add a device to your registry
shelly device add living-room 192.168.1.100
# Control devices with quick commands
shelly on living-room
shelly off living-room
shelly toggle living-room
# Get device status
shelly status living-room
# Launch the TUI dashboard
shelly dash
# Update firmware
shelly firmware update living-roomLaunch an interactive terminal dashboard with real-time device status, quick control, and power monitoring graphs:
shelly dashKeyboard-driven navigation with customizable keybindings and 280+ color themes. Press ? in the dashboard for help.
Print ASCII wiring diagrams for any Shelly device model directly in your terminal:
shelly diagram -m plus-2pm
shelly diagram -m pro-4pm -s detailed
shelly diagram -m dimmer-2 -g 1 -s compactSupports schematic, compact, and detailed styles across all device topologies and generations.
Control your Shelly devices through AI assistants via the Model Context Protocol:
# One-command setup for popular AI tools
shelly mcp claude enable
shelly mcp vscode enable
shelly mcp cursor enable
shelly mcp configure --geminiSee the MCP documentation for manual configuration and available tools.
Extend functionality with gh-style plugins:
shelly plugin install gh:user/shelly-notify
shelly plugin create myext --lang goSee docs/plugins.md for the development guide.
280+ built-in color themes:
shelly theme set dracula
shelly theme preview nordSee docs/themes.md for customization and custom theme creation.
📖 Full Documentation Site - Browse the complete documentation online.
- Configuration Reference - Complete configuration options and environment variables
- Plugin Development - Create custom plugins
- Theme Customization - Theme system details
- Command Reference - Auto-generated documentation for all commands
- Man Pages - Unix manual pages
- Architecture - Directory structure and placement guide
- Development Guide - Development patterns and standards
- Dependencies - Library dependencies
- Testing Strategy - Test coverage approach
- Example Configurations - Ready-to-use config files
- Example Aliases - Pre-built command shortcuts
- Example Scripts - Automation shell scripts
- Example Plugins - Plugin implementation examples
- Deployment Examples - Docker, Kubernetes, Prometheus
Shelly CLI includes opt-in anonymous usage telemetry to help improve the CLI. This is disabled by default and must be explicitly enabled.
What we collect (when enabled):
- Command name (e.g., "device list", "switch on")
- Whether the command succeeded or failed
- CLI version, OS, and architecture
- Command execution duration
See the full payload definition: internal/telemetry/telemetry.go#Event
What we DO NOT collect:
- Device information (names, addresses, configurations)
- IP addresses or network information
- Personal data of any kind
- Authentication credentials
- Command arguments or parameters
How to enable/disable:
# Enable during setup wizard
shelly init
# Enable via config command
shelly config set telemetry=true
# Disable
shelly config set telemetry=falseThe telemetry data is sent to a self-hosted endpoint and is used solely for understanding which commands are most useful and identifying issues.
Contributions are welcome! Please read our Contributing Guidelines before submitting a PR.
# Clone repository
git clone https://github.com/tj-smith47/shelly-cli.git
cd shelly-cli
# Install dependencies
go mod download
# Build
go build -o shelly ./cmd/shelly
# Run tests
go test ./...
# Lint
golangci-lint run ./...We welcome script / manifest contributions! If you've written useful automation scripts or integrations, please submit a PR to add them to the examples directory.
Found a bug? Have a feature request? Use the built-in feedback command:
# Submit feedback (opens GitHub issue form)
shelly feedback
# Run diagnostics for bug reports
shelly doctorYou can also open an issue directly on GitHub.
Apache License 2.0 - see LICENSE for details.
- Built on shelly-go library
- TUI powered by Bubble Tea
- Themes by bubbletint
- Inspired by gh CLI and k9s
Generated entirely by Claude Opus 4.5 over many iterations 🤖
