{"id":35500270,"url":"https://github.com/jfmlima/shelly-manager","last_synced_at":"2026-02-28T04:16:03.855Z","repository":{"id":311204557,"uuid":"1030340121","full_name":"jfmlima/shelly-manager","owner":"jfmlima","description":"Local management for Shelly IoT devices without cloud connectivity.","archived":false,"fork":false,"pushed_at":"2026-01-16T19:50:32.000Z","size":3790,"stargazers_count":93,"open_issues_count":3,"forks_count":3,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-01-17T07:25:45.676Z","etag":null,"topics":["fleet-management","local","manager","shelly","web"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jfmlima.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["jfmlima"],"buy_me_a_coffee":"jfmlima","ko_fi":"jfmlima","custom":["https://www.paypal.com/donate/?hosted_button_id=MF82L7YZHV8Y4"]}},"created_at":"2025-08-01T13:24:47.000Z","updated_at":"2026-01-16T19:48:05.000Z","dependencies_parsed_at":"2025-08-22T20:53:14.079Z","dependency_job_id":"08136dbd-b1a4-4f0b-bd32-15bd02651975","html_url":"https://github.com/jfmlima/shelly-manager","commit_stats":null,"previous_names":["jfmlima/shelly-manager"],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/jfmlima/shelly-manager","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jfmlima%2Fshelly-manager","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jfmlima%2Fshelly-manager/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jfmlima%2Fshelly-manager/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jfmlima%2Fshelly-manager/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jfmlima","download_url":"https://codeload.github.com/jfmlima/shelly-manager/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jfmlima%2Fshelly-manager/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28513948,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T13:38:16.342Z","status":"ssl_error","status_checked_at":"2026-01-17T13:37:44.060Z","response_time":85,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fleet-management","local","manager","shelly","web"],"created_at":"2026-01-03T18:20:08.122Z","updated_at":"2026-02-28T04:16:03.845Z","avatar_url":"https://github.com/jfmlima.png","language":"Python","funding_links":["https://github.com/sponsors/jfmlima","https://buymeacoffee.com/jfmlima","https://ko-fi.com/jfmlima","https://www.paypal.com/donate/?hosted_button_id=MF82L7YZHV8Y4"],"categories":[],"sub_categories":[],"readme":"# Shelly Manager\n\nLocal management for Shelly IoT devices without cloud connectivity.\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![GitHub release](https://img.shields.io/github/release/jfmlima/shelly-manager.svg)](https://github.com/jfmlima/shelly-manager/releases)\n[![API CI](https://img.shields.io/github/actions/workflow/status/jfmlima/shelly-manager/api-ci.yml?label=API)](https://github.com/jfmlima/shelly-manager/actions/workflows/api-ci.yml)\n[![CLI CI](https://img.shields.io/github/actions/workflow/status/jfmlima/shelly-manager/cli-ci.yml?label=CLI)](https://github.com/jfmlima/shelly-manager/actions/workflows/cli-ci.yml)\n[![Web CI](https://img.shields.io/github/actions/workflow/status/jfmlima/shelly-manager/web-ci.yml?label=Web)](https://github.com/jfmlima/shelly-manager/actions/workflows/web-ci.yml)\n\nManage Shelly devices on your local network without connecting them to the Shelly Cloud. Scan for devices, update firmware, manage configurations, and monitor status - all locally.\n\n## Features\n\n- Device discovery using mDNS and Network Scanning\n- Firmware update management (stable/beta channels)\n- Device configuration changes\n- Bulk operations across multiple devices\n- Status monitoring\n- Component action discovery and execution\n- Dynamic device capability detection\n- Component-specific controls (switches, covers, lights, etc.)\n\nAvailable as:\n\n- Web interface\n- Command line tool\n- REST API\n\n## Roadmap\n\n- [ ] **Ensure RED compatibility** - Ensure compliance with [EU RED requirements](https://kb.shelly.cloud/knowledge-base/kbuca-what-you-need-to-know-shelly-and-eu-red) for Shelly devices\n- [ ] **Bulk action scheduling** - Schedule bulk operations to run at specific times or intervals\n\n## Screenshots\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd width=\"50%\"\u003e\n      \u003ch3\u003eDashboard Overview\u003c/h3\u003e\n      \u003cimg src=\"docs/images/dashboard-1.png\" width=\"100%\" alt=\"Dashboard\"\u003e\n      \u003cem\u003eDevice discovery and management with real-time status monitoring\u003c/em\u003e\n    \u003c/td\u003e\n    \u003ctd width=\"50%\"\u003e\n      \u003ch3\u003eSettings \u0026 Configuration\u003c/h3\u003e\n      \u003cimg src=\"docs/images/settings-1.png\" width=\"100%\" alt=\"Settings\"\u003e\n      \u003cem\u003eAPI configuration for mobile access and application preferences\u003c/em\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd width=\"50%\"\u003e\n      \u003ch3\u003eDevice Management\u003c/h3\u003e\n      \u003cimg src=\"docs/images/device-1.png\" width=\"100%\" alt=\"Device Details\"\u003e\n      \u003cem\u003eIndividual device control with component actions and status\u003c/em\u003e\n    \u003c/td\u003e\n      \u003ctd width=\"50%\"\u003e\n      \u003ch3\u003eDevice Action\u003c/h3\u003e\n      \u003cimg src=\"docs/images/device-action-1.png\" width=\"100%\" alt=\"Device Details\"\u003e\n      \u003cem\u003eComponent actions and configurations\u003c/em\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd width=\"50%\"\u003e\n      \u003ch3\u003eBulk Operations\u003c/h3\u003e\n      \u003cimg src=\"docs/images/bulk-actions-1.png\" width=\"100%\" alt=\"Bulk Actions\"\u003e\n      \u003cem\u003ePerform operations on multiple devices simultaneously\u003c/em\u003e\n    \u003c/td\u003e\n    \u003ctd width=\"50%\"\u003e\n      \u003ch3\u003eBulk Configuration Apply\u003c/h3\u003e\n      \u003cimg src=\"docs/images/bulk-apply-1.png\" width=\"100%\" alt=\"Bulk Actions\"\u003e\n      \u003cem\u003eApply configurations in bulk to multipled evices\u003c/em\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n## Quick Start\n\n### Docker\n\n\u003e ℹ️ **mDNS Discovery in Docker**\n\u003e requires host networking so the container can listen for multicast traffic.\n\u003e Add `network_mode: \"host\"` to the API container (and run on a Linux host) if you\n\u003e want to discover via mDNS while running in Docker. Without host networking,\n\u003e only the IP range scan will work.\n\n**Web UI + API Stack**:\n\n```yaml\nservices:\n  shelly-manager-api:\n    image: ghcr.io/jfmlima/shelly-manager-api:latest\n    #network_mode: \"host\" # optional, but if you mDNS please uncomment it\n    ports:\n      - \"8000:8000\"\n    environment:\n      - HOST=0.0.0.0\n      - PORT=8000\n\n  shelly-manager-web:\n    image: ghcr.io/jfmlima/shelly-manager-web:latest\n    ports:\n      - \"8080:8080\"\n    environment:\n      - VITE_BASE_API_URL=http://localhost:8000\n    depends_on:\n      - shelly-manager-api\n```\n\n**With Traefik**:\n\n```yaml\nservices:\n  shelly-manager-api:\n    container_name: shelly-manager-api\n    image: ghcr.io/jfmlima/shelly-manager-api:latest\n    environment:\n      - HOST=0.0.0.0\n      - PORT=8000\n    labels:\n      - \"traefik.enable=true\"\n      - \"traefik.http.routers.shelly-manager-api.rule=Host(`shelly-manager-api.your.domain`)\"\n      - \"traefik.http.routers.shelly-manager-api.service=shelly-manager-api\"\n      - \"traefik.http.routers.shelly-manager-api.entrypoints=web\"\n      - \"traefik.http.services.shelly-manager-api.loadbalancer.server.port=8000\"\n\n  shelly-manager-web:\n    container_name: shelly-manager-web\n    image: ghcr.io/jfmlima/shelly-manager-web:latest\n    environment:\n      - VITE_BASE_API_URL=http://shelly-manager-api.your.domain\n    depends_on:\n      - shelly-manager-api\n    labels:\n      - \"traefik.enable=true\"\n      - \"traefik.http.routers.shelly-manager-web.rule=Host(`shelly-manager.your.domain`)\"\n      - \"traefik.http.routers.shelly-manager-web.service=shelly-manager-web\"\n      - \"traefik.http.routers.shelly-manager-web.entrypoints=web\"\n      - \"traefik.http.services.shelly-manager-web.loadbalancer.server.port=8080\"\n```\n\n**Home Assistant Add-on**\n\nYou can install Shelly Manager as a Home Assistant add-on for seamless integration with your Home Assistant instance:\n\n[![Open your Home Assistant instance and show the add add-on repository dialog with a specific repository URL pre-filled.](https://my.home-assistant.io/badges/supervisor_add_addon_repository.svg)](https://my.home-assistant.io/redirect/supervisor_add_addon_repository/?repository_url=https%3A%2F%2Fgithub.com%2Fjfmlima%2Fhome-assistant-addons)\n\nOr manually:\n\n1. **Add the repository** to your Home Assistant:\n\n   ```\n   https://github.com/jfmlima/home-assistant-addons\n   ```\n\n2. **Navigate** to Settings → Add-ons → Add-on Store in your Home Assistant\n3. **Click** the three dots menu (⋮) and select \"Repositories\"\n4. **Add** the repository URL above\n5. **Install** the Shelly Manager add-on from the available add-ons list\n\nThe add-on provides the same functionality as the Docker deployment but is fully integrated with your Home Assistant environment.\n\n**CLI Only**:\n\n```bash\n# Interactive device scanning\ndocker run --rm -it \\\n  ghcr.io/jfmlima/shelly-manager-cli:latest \\\n  scan --target 192.168.1.0/24\n\n# Check device status\ndocker run --rm -it \\\n  ghcr.io/jfmlima/shelly-manager-cli:latest \\\n  device status 192.168.1.100\n\n# Bulk firmware updates\ndocker run --rm -it \\\n  ghcr.io/jfmlima/shelly-manager-cli:latest \\\n  bulk update --target 192.168.1.0/24\n```\n\n**API Only**:\n\n```bash\ndocker run -p 8000:8000 \\\n  ghcr.io/jfmlima/shelly-manager-api:latest\n```\n\n### Configuration\n\nShelly Manager is zero-configuration by default. All scan and management parameters are provided at runtime via the Web UI, CLI flags, API parameters or ENV variables. This ensures flexibility and removes the need for managing static configuration files.\n\nFor persistent storage of discovered devices in the Web UI, the application leverages browser localStorage. For API-based integrations, the client is responsible for maintaining device lists.\n\n## Architecture\n\n```\n├── packages/\n│   ├── core/              # 🏛️ Business Logic \u0026 Domain Models\n│   ├── api/               # 🌐 HTTP REST API (Litestar)\n│   ├── cli/               # 💻 Command Line Interface (Click)\n│   └── web/               # 🖥️ Modern Web UI (React + TypeScript)\n└── docker-compose.yml     # Development environment\n```\n\n### Package Overview\n\n| Package                       | Purpose                                             | Documentation                          |\n| ----------------------------- | --------------------------------------------------- | -------------------------------------- |\n| **🏛️ [Core](packages/core/)** | Pure business logic, domain models, and use cases   | [Core README](packages/core/README.md) |\n| **🌐 [API](packages/api/)**   | HTTP REST API for web applications and integrations | [API README](packages/api/README.md)   |\n| **💻 [CLI](packages/cli/)**   | Modern command-line interface with rich output      | [CLI README](packages/cli/README.md)   |\n| **🖥️ [Web](packages/web/)**   | Responsive web UI for device management             | [Web README](packages/web/README.md)   |\n\n## API Overview\n\nThe REST API provides complete device management capabilities:\n\n```bash\n# Health and status\nGET /api/health                    # Service health check\nGET /api/devices/scan              # Discover devices on network\nGET /api/devices/{ip}/status       # Get device status\n\n# Device operations\nPOST /api/devices/{ip}/update      # Update device firmware\nPOST /api/devices/{ip}/reboot      # Reboot device\nPOST /api/devices/bulk/update      # Bulk firmware updates\n\n# Component Actions\nGET /api/devices/{ip}/components/actions           # Discover available actions\nPOST /api/devices/{ip}/components/{id}/action      # Execute component action\n```\n\n**API Documentation**: Start the API server and visit `http://localhost:8000/docs` for interactive OpenAPI documentation\n\n## CLI Overview\n\nThe CLI provides powerful automation capabilities:\n\n```bash\n# Device discovery\nshelly-manager scan --target 192.168.1.0/24\nshelly-manager scan --use-mdns\n\n# Device operations\nshelly-manager device status 192.168.1.100\nshelly-manager device reboot 192.168.1.100\nshelly-manager update check --all\n\n# Bulk operations\nshelly-manager bulk reboot --target 192.168.1.100-110\nshelly-manager bulk update --target 10.0.0.0/24\n```\n\n**CLI Documentation**: See [CLI README](packages/cli/README.md) for complete command reference.\n\n## Web UI Overview\n\nThe web interface provides an intuitive management experience:\n\n- **Device Discovery**: Network scanning with visual results\n- **Bulk Operations**: Select multiple devices for batch operations\n- **Real-time Status**: Live device status monitoring\n- **Configuration Management**: Easy device configuration editing\n- **Dark Mode**: System-aware theme switching\n\n**Web Documentation**: See [Web README](packages/web/README.md) for setup and features.\n\n## Requirements\n\n- **Docker** (recommended) or **Python 3.11+**\n- **Network access** to Shelly devices on your local network\n- **Optional**: Device credentials for authenticated devices\n\n## Security \u0026 Credentials\n\nShelly Manager supports password-protected Shelly Gen2 devices (HTTP Digest Auth). To enable this feature, you must provide an encryption key.\n\n### 1. Generate an Encryption Key\n\nThe application requires a valid Fernet key in the `SHELLY_SECRET_KEY` environment variable.\n\n```bash\n# Generate a key using Python\npython -c \"from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())\"\n```\n\n### 2. Set the Environment Variable\n\n**Linux / macOS**\n```bash\nexport SHELLY_SECRET_KEY=\"your-generated-key\"\n```\n\n**Docker**\n```bash\ndocker run -e SHELLY_SECRET_KEY=\"your-generated-key\" ...\n```\n\n**docker-compose.yml**\n```yaml\nenvironment:\n  - SHELLY_SECRET_KEY=your-generated-key\n```\n\n### 3. Manage Credentials\n\nUse the CLI to manage device credentials. Data is stored encrypted locally.\n\n```bash\n# Set credentials for a specific device\nshelly-manager credentials set AABBCCDDEEFF mypassword --username admin\n\n# Set a global fallback password (used if device-specific not found)\nshelly-manager credentials set-global myfallbackpass\n\n# List stored credentials (safe, no passwords shown)\nshelly-manager credentials list\n\n# Delete credentials\nshelly-manager credentials delete AABBCCDDEEFF\n```\n\n## Development\n\nFor local development and contributing to Shelly Manager:\n\n```bash\n# Clone and setup development environment\ngit clone https://github.com/jfmlima/shelly-manager.git\ncd shelly-manager\n\n# Start development stack\ndocker-compose up -d\n\n# Or install locally with uv\nuv sync --extra dev\n```\n\n**Development Guide**: See [DEVELOPMENT.md](DEVELOPMENT.md) for detailed setup instructions, testing, and contribution guidelines.\n\n## 🤝 Contributing\n\nWe welcome contributions! Here's how to get started:\n\n1. **Fork** the repository\n2. **Clone** your fork locally\n3. **Create** a feature branch (`git checkout -b feature/amazing-feature`)\n4. **Make** your changes following our [development guidelines](DEVELOPMENT.md)\n5. **Add** tests for new functionality\n6. **Submit** a pull request\n\n### Development Principles\n\n- **Clean Architecture**: Keep domain logic in the core package\n- **Type Safety**: Use comprehensive type hints throughout\n- **Testing**: Write tests for all new functionality\n- **Documentation**: Update relevant documentation for changes\n\n### Getting Help\n\n- 📖 **Documentation**: Check package-specific READMEs\n- 🐛 **Bug Reports**: Open an issue with reproduction steps\n- 💡 **Feature Requests**: Describe your use case in an issue\n- 💬 **Questions**: Start a discussion for general questions\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file.\n\n## Disclaimer\n\n**USE AT YOUR OWN RISK**: This software is provided \"as is\" without warranty of any kind. The developers of Shelly Manager are not responsible for any damage, malfunction, or loss of data that may occur to your Shelly devices, network infrastructure, or any other equipment as a result of using this software.\n\nUnderstand that firmware updates and device modifications carry inherent risks.\n\nBy using this software, you acknowledge that you do so at your own risk and that the developers disclaim all liability for any damages or losses that may result from its use.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjfmlima%2Fshelly-manager","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjfmlima%2Fshelly-manager","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjfmlima%2Fshelly-manager/lists"}