evilstudio/homelab-assistant-tool

CLI Tool which can help with manage your homelab devices.

v2.1.3 2026-03-05 16:45 UTC

Requires

• php: ^8.3
• ext-ctype: *
• ext-iconv: *
• ext-json: *
• ext-mbstring: *
• ext-openssl: *
• ext-pdo: *
• ext-pdo_sqlite: *
• diegonz/php-wake-on-lan: ^2.1
• doctrine/doctrine-bundle: ^2.13
• doctrine/doctrine-migrations-bundle: ^3.4
• doctrine/orm: ^3.6
• dragonmantank/cron-expression: ^3.4
• geerlingguy/ping: ^1.2
• phpseclib/phpseclib: ^3.0
• symfony/dotenv: ^7.4
• symfony/flex: ^2
• symfony/framework-bundle: ^7.4
• symfony/monolog-bundle: ^3.10
• symfony/process: ^7.4
• symfony/runtime: ^7.4
• symfony/security-bundle: ^7.4
• symfony/twig-bundle: ^7.4
• symfony/yaml: ^7.4

Requires (Dev)

• phpunit/phpunit: ^11.0
• squizlabs/php_codesniffer: ^4.0

Conflicts

• symfony/symfony: *

MIT

• Dariusz Matoga

• tool
• helper
• assistant
• homelab

README

Introduction

Homelab Assistant Tool is an application for homelab operations and automation. It combines a CLI interface with a Web UI for managing devices, UPS units, schedules, and operational logs.

For technical details, see Tech Stack.

✨ Key Features

• 🔌 Device operations

  • Start, stop, check status, and SSH operations for managed devices (via CLI)

• 🔋 UPS-aware behavior

  • UPS monitoring support and battery-aware automation logic

• ⏰ Scheduling

  • Cron-based automation with schedule-to-device assignment

• 🧾 Action logs

  • Unified action history for CLI, CRON, and WEB operations
  • Log filtering and cleanup tools

• 🌐 Web UI

  • Management views for devices, UPS, schedules, and logs
  • Manual operational actions from the browser

• 🔐 Authentication

  • simple mode (local username/password)
  • oidc mode (OIDC provider login)

📁 Project Structure

.
├── bin/             # CLI entrypoints and helper scripts
├── config/          # Symfony and app configuration
├── docs/            # Main technical documentation
├── migrations/      # Doctrine migrations
├── public/          # Web entrypoint and built assets
├── src/             # Application source code
│   ├── Command/         # CLI commands (setup, CRUD, runtime, users)
│   ├── Contract/        # Runtime contracts and enums
│   ├── Controller/      # Web controllers
│   ├── Entity/          # Doctrine entities
│   ├── EventSubscriber/ # Request/auth/log subscribers
│   ├── Factory/         # Runtime factories/adapters
│   ├── Helper/          # Configuration and helpers
│   ├── Repository/      # Doctrine repositories
│   ├── Runtime/         # Runtime models
│   └── Service/         # Application, runtime, auth, infrastructure services
├── templates/       # Twig templates (dashboard, devices, ups, schedules, logs, auth)
├── tests/           # Unit, integration, and functional test suites
└── var/             # Runtime data, cache, logs, SQLite files

🚀 Quick Start

1. Clone and install

git clone https://github.com/evilstudio/homelab-assistant-tool.git
cd homelab-assistant-tool
composer install
cp .env.example .env

2. Update .env

Set values for your environment (application/auth settings, and OIDC values when using HAT_AUTH_MODE=oidc).

3. Configure application settings

php bin/console hat:setup:configure

4. Initialize database

php bin/console hat:setup:db --init

5. Create first user (simple auth mode)

php bin/console hat:user:create

6. Run Web UI (Docker Compose)

docker compose up -d --build

Open: http://localhost:8080

For local development with Xdebug and dedicated compose config:

docker compose -f docker-compose.dev.yml up -d --build

7. Run CLI commands

php bin/console list

💻 Commands Overview

Here is a list of commands available in HAT.

Command	Description
hat:setup:configure	Configure app technical settings.
hat:setup:db	Initialize/migrate SQLite database.
hat:setup:init	Run full setup flow.
hat:device:create/update/remove/list	Manage devices.
hat:ups:create/update/remove/list	Manage UPS entries.
hat:schedule:create/update/remove/list	Manage schedules.
hat:device:check-status	Check runtime status for a device.
hat:device:ssh	Open SSH session to a device.
hat:device:start	Start a device.
hat:device:stop	Stop a device.
hat:cron:execute	Execute scheduled tasks and maintenance.
hat:logs:list	List action logs stored in DB.
hat:logs:cleanup	Remove old/all action logs from DB.
hat:user:create	Create local user for simple auth mode.
hat:user:remove	Remove local user in simple auth mode.
hat:user:reset-password	Reset local user password (simple mode).

🧭 Notes

• Business data is stored in SQLite.
• Integration/functional tests use separate SQLite DB (var/data/hat_test.sqlite).
• Runtime settings are configured in config/parameters.yaml.
• Web logs are written to var/log/web.log.

🧪 Testing & Quality

Quick Start:

# Run all tests (Xdebug off)
bin/phpunit

# Run with coverage report
bin/phpunit-coverage

📚 Documentation:

• 📖 Test Implementation Summary - Overview and current scope
• 🚀 CI/CD Guide - GitLab pipeline setup