---

name: home-assistant-manager description: Expert-level Home Assistant configuration management with efficient deployment workflows (git and rapid scp iteration), remote CLI access via SSH and hass-cli, automation verification protocols, log analysis, reload vs restart optimization, and comprehensive Lovelace dashboard management for tablet-optimized UIs. Includes template patterns, card types, debugging strategies, and real-world examples.

Home Assistant Manager

Expert-level Home Assistant configuration management with efficient workflows, remote CLI access, and verification protocols.

Core Capabilities

• Remote Home Assistant instance management via SSH and hass-cli
• Smart deployment workflows (git-based and rapid iteration)
• Configuration validation and safety checks
• Automation testing and verification
• Log analysis and error detection
• Reload vs restart optimization
• Lovelace dashboard development and optimization
• Template syntax patterns and debugging
• Tablet-optimized UI design

Prerequisites

Before starting, verify the environment has:

1. SSH access to Home Assistant instance (root@homeassistant.local)
2. hass-cli installed locally
3. Environment variables loaded (HASS_SERVER, HASS_TOKEN)
4. Git repository connected to HA /config directory
5. Context7 MCP server with Home Assistant docs (recommended)

Remote Access Patterns

Using hass-cli (Local, via REST API)

All hass-cli commands use environment variables automatically:

# List entities
hass-cli state list

# Get specific state
hass-cli state get sensor.entity_name

# Call services
hass-cli service call automation.reload
hass-cli service call automation.trigger --arguments entity_id=automation.name

Using SSH for HA CLI

# Check configuration validity
ssh root@homeassistant.local "ha core check"

# Restart Home Assistant
ssh root@homeassistant.local "ha core restart"

# View logs
ssh root@homeassistant.local "ha core logs"

# Tail logs with grep
ssh root@homeassistant.local "ha core logs | grep -i error | tail -20"

Deployment Workflows

Standard Git Workflow (Final Changes)

Use for changes you want in version control:

# 1. Make changes locally
# 2. Check validity
ssh root@homeassistant.local "ha core check"

# 3. Commit and push
git add file.yaml
git commit -m "Description"
git push

# 4. CRITICAL: Pull to HA instance
ssh root@homeassistant.local "cd /config && git pull"

# 5. Reload or restart
hass-cli service call automation.reload  # if reload sufficient
# OR
ssh root@homeassistant.local "ha core restart"  # if restart needed

# 6. Verify
hass-cli state get sensor.new_entity
ssh root@homeassistant.local "ha core logs | grep -i error | tail -20"

Rapid Development Workflow (Testing/Iteration)

Use scp for quick testing before committing:

# 1. Make changes locally
# 2. Quick deploy
scp automations.yaml root@homeassistant.local:/config/

# 3. Reload/restart
hass-cli service call automation.reload

# 4. Test and iterate (repeat 1-3 as needed)

# 5. Once finalized, commit to git
git add automations.yaml
git commit -m "Final tested changes"
git push

When to use scp:

• 🚀 Rapid iteration and testing
• 🔄 Frequent small adjustments
• 🧪 Experimental changes
• 🎨 UI/Dashboard work

When to use git:

• ✅ Final tested changes
• 📦 Version control tracking
• 🔒 Important configs
• 👥 Changes to document

Reload vs Restart Decision Making

ALWAYS assess if reload is sufficient before requiring a full restart.

Can be reloaded (fast, preferred):

• ✅ Automations: hass-cli service call automation.reload
• ✅ Scripts: hass-cli service call script.reload
• ✅ Scenes: hass-cli service call scene.reload
• ✅ Template entities: hass-cli service call template.reload
• ✅ Groups: hass-cli service call group.reload
• ✅ Themes: hass-cli service call frontend.reload_themes

Require full restart:

• ❌ Min/Max sensors and platform-based sensors
• ❌ New integrations in configuration.yaml
• ❌ Core configuration changes
• ❌ MQTT sensor/binary_sensor platforms

Automation Verification Workflow

ALWAYS verify automations after deployment:

Step 1: Deploy

git add automations.yaml && git commit -m "..." && git push
ssh root@homeassistant.local "cd /config && git pull"

Step 2: Check Configuration

ssh root@homeassistant.local "ha core check"

Step 3: Reload

hass-cli service call automation.reload

Step 4: Manually Trigger

hass-cli service call automation.trigger --arguments entity_id=automation.name

Why trigger manually?

• Instant feedback (don't wait for scheduled triggers)
• Verify logic before production
• Catch errors immediately

Step 5: Check Logs

sleep 3
ssh root@homeassistant.local "ha core logs | grep -i 'automation_name' | tail -20"

Success indicators:

• Initialized trigger AutomationName
• Running automation actions
• Executing step ...
• No ERROR or WARNING messages

Error indicators:

• Error executing script
• Invalid data for call_service
• TypeError, Template variable warning

Step 6: Verify Outcome

For notifications:

• Ask user if they received it
• Check logs for mobile_app messages

For device control:

hass-cli state get switch.device_name

For sensors:

hass-cli state get sensor.new_sensor

Step 7: Fix and Re-test if Needed

If errors found:

1. Identify root cause from error messages
2. Fix the issue
3. Re-deploy (steps 1-2)
4. Re-verify (steps 3-6)

Dashboard Management

Dashboard Fundamentals

What are Lovelace Dashboards?

• JSON files in .storage/ directory (e.g., .storage/lovelace.control_center)
• UI configuration for Home Assistant frontend
• Optimizable for different devices (mobile, tablet, wall panels)

Critical Understanding:

• Creating dashboard file is NOT enough - must register in .storage/lovelace_dashboards
• Dashboard changes don't require HA restart (just browser refresh)
• Use panel view for full-screen content (maps, cameras)
• Use sections view for organized multi-card layouts

Dashboard Development Workflow

Rapid Iteration with scp (Recommended for dashboards):

# 1. Make changes locally
vim .storage/lovelace.control_center

# 2. Deploy immediately (no git commit yet)
scp .storage/lovelace.control_center root@homeassistant.local:/config/.storage/

# 3. Refresh browser (Ctrl+F5 or Cmd+Shift+R)
# No HA restart needed!

# 4. Iterate: Repeat 1-3 until perfect

# 5. Commit when stable
git add .storage/lovelace.control_center
git commit -m "Update dashboard layout"
git push
ssh root@homeassistant.local "cd /config && git pull"

Why scp for dashboards:

• Instant feedback (no HA restart)
• Iterate quickly on visual changes
• Commit only stable versions

Creating New Dashboard

Complete workflow:

# Step 1: Create dashboard file
cp .storage/lovelace.my_home .storage/lovelace.new_dashboard

# Step 2: Register in lovelace_dashboards
# Edit .storage/lovelace_dashboards to add:
{
  "id": "new_dashboard",
  "show_in_sidebar": true,
  "icon": "mdi:tablet-dashboard",
  "title": "New Dashboard",
  "require_admin": false,
  "mode": "storage",
  "url_path": "new-dashboard"
}

# Step 3: Deploy both files
scp .storage/lovelace.new_dashboard root@homeassistant.local:/config/.storage/
scp .storage/lovelace_dashboards root@homeassistant.local:/config/.storage/

# Step 4: Restart HA (required for registry changes)
ssh root@homeassistant.local "ha core restart"
sleep 30

# Step 5: Verify appears in sidebar

Update .gitignore to track:

# Exclude .storage/ by default
.storage/

# Include dashboard files
!.storage/lovelace.new_dashboard
!.storage/lovelace_dashboards

View Types Decision Matrix

Use Panel View when:

• Displaying full-screen map (vacuum, cameras)
• Single large card needs full width
• Want zero margins/padding
• Minimize scrolling

Use Sections View when:

• Organizing multiple cards
• Need responsive grid layout
• Building multi-section dashboards

Layout Example:

// Panel view - full width, no margins
{
  "type": "panel",
  "title": "Vacuum Map",
  "path": "map",
  "cards": [
    {
      "type": "custom:xiaomi-vacuum-map-card",
      "entity": "vacuum.dusty"
    }
  ]
}

// Sections view - organized, has ~10% margins
{
  "type": "sections",
  "title": "Home",
  "sections": [
    {
      "type": "grid",
      "cards": [...]
    }
  ]
}

Card Types Quick Reference

Mushroom Cards (Modern, Touch-Optimized):

{
  "type": "custom:mushroom-light-card",
  "entity": "light.living_room",
  "use_light_color": true,
  "show_brightness_control": true,
  "collapsible_controls": true,
  "fill_container": true
}

• Best for tablets and touch screens
• Animated, colorful icons
• Built-in slider controls

Mushroom Template Card (Dynamic Content):

{
  "type": "custom:mushroom-template-card",
  "primary": "All Doors",
  "secondary": "{% set sensors = ['binary_sensor.front_door'] %}\n{% set open = sensors | select('is_state', 'on') | list | length %}\n{{ open }} / {{ sensors | length }} open",
  "icon": "mdi:door",
  "icon_color": "{% if open > 0 %}red{% else %}green{% endif %}"
}

• Use Jinja2 templates for dynamic content
• Color-code status with icon_color
• Multi-line templates use \n in JSON

Tile Card (Built-in, Modern):

{
  "type": "tile",
  "entity": "climate.thermostat",
  "features": [
    {"type": "climate-hvac-modes", "hvac_modes": ["heat", "cool", "fan_only", "off"]},
    {"type": "target-temperature"}
  ]
}

• No custom cards required
• Built-in features for controls

Common Template Patterns

Counting Open Doors:

{% set door_sensors = [
  'binary_sensor.front_door',
  'binary_sensor.back_door'
] %}
{% set open = door_sensors | select('is_state', 'on') | list | length %}
{{ open }} /