home-assistant

name: home-assistant description: Home Assistant smart home control and management. Use when the user wants to control lights, switches, sensors, climate, or other smart home devices, query entity states, create automations, manage dashboards, or work with Home Assistant configuration. Activate for phrases like "turn on the lights", "check temperature", "create automation", "HA", "home assistant", or smart home device control.

Home Assistant Control

Control and manage Home Assistant instances via REST and WebSocket APIs.

Prerequisites

Set environment variables:

• HA_URL - Home Assistant URL (e.g., http://192.168.4.2:8123)
• HA_TOKEN - Long-lived access token (Profile → Security → Long-Lived Access Tokens)

Usage

Use scripts/ha.py with uv:

uv run "${SKILL_DIR}/scripts/ha.py" <command> [options]

Commands

Query Entities

# List all entities
uv run "${SKILL_DIR}/scripts/ha.py" states

# Get specific entity
uv run "${SKILL_DIR}/scripts/ha.py" states light.living_room

# Filter by domain
uv run "${SKILL_DIR}/scripts/ha.py" states --domain light

Control Devices

# Turn on single light
uv run "${SKILL_DIR}/scripts/ha.py" call light turn_on --entity light.living_room

# Turn on with brightness
uv run "${SKILL_DIR}/scripts/ha.py" call light turn_on --entity light.living_room --data '{"brightness": 128}'

# Turn off all lights in an area (room)
uv run "${SKILL_DIR}/scripts/ha.py" call light turn_off --area arbeitszimmer

# Turn on multiple entities at once
uv run "${SKILL_DIR}/scripts/ha.py" call light turn_on --entity "light.kitchen,light.dining"

# Target by device
uv run "${SKILL_DIR}/scripts/ha.py" call switch turn_off --device my_device_id

List Areas

# List all areas (full JSON)
uv run "${SKILL_DIR}/scripts/ha.py" areas

# Compact view (id: name)
uv run "${SKILL_DIR}/scripts/ha.py" areas --compact

User Management (WebSocket)

# List users
uv run "${SKILL_DIR}/scripts/ha.py" users list

# Create user
uv run "${SKILL_DIR}/scripts/ha.py" users create "tablet" --password "secret123"

# Delete user
uv run "${SKILL_DIR}/scripts/ha.py" users delete <user_id>

Access Tokens (WebSocket)

# Create a long-lived access token (valid for 365 days by default)
uv run "${SKILL_DIR}/scripts/ha.py" token "claude-code"

# Create token with custom lifespan (e.g., 30 days)
uv run "${SKILL_DIR}/scripts/ha.py" token "my-app" --days 30

Note: To create a token, you need a valid HA_TOKEN first (bootstrap with a short-lived token or existing long-lived token from the UI).

Configuration

# Check config validity
uv run "${SKILL_DIR}/scripts/ha.py" config check

# Restart Home Assistant
uv run "${SKILL_DIR}/scripts/ha.py" restart

History & Logbook

# Get entity history (last 24 hours)
uv run "${SKILL_DIR}/scripts/ha.py" history sensor.temperature

# Get last 12 hours, show only last 10 entries
uv run "${SKILL_DIR}/scripts/ha.py" history sensor.temperature --hours 12 --last 10

# Get logbook entries
uv run "${SKILL_DIR}/scripts/ha.py" logbook --hours 24

# Get logbook for specific entity
uv run "${SKILL_DIR}/scripts/ha.py" logbook --entity light.living_room --last 20

Templates

# Render a Jinja2 template
uv run "${SKILL_DIR}/scripts/ha.py" template "{{ states('sensor.temperature') }}"

# Complex template
uv run "${SKILL_DIR}/scripts/ha.py" template "{% for light in states.light %}{{ light.entity_id }}: {{ light.state }}{% endfor %}"

Services & Events

# List all services
uv run "${SKILL_DIR}/scripts/ha.py" services

# List services for specific domain
uv run "${SKILL_DIR}/scripts/ha.py" services --domain light

# Compact service list (domain.service format)
uv run "${SKILL_DIR}/scripts/ha.py" services --compact

# Fire an event
uv run "${SKILL_DIR}/scripts/ha.py" events my_custom_event --data '{"key": "value"}'

System Info

# Get Home Assistant info (summary)
uv run "${SKILL_DIR}/scripts/ha.py" info

# Get full config JSON
uv run "${SKILL_DIR}/scripts/ha.py" info --full

Common Domains & Services

Writing Automations

Create YAML automation files:

automation:
  - alias: "Lights on at sunset"
    trigger:
      - platform: sun
        event: sunset
    condition:
      - condition: state
        entity_id: binary_sensor.someone_home
        state: "on"
    action:
      - service: light.turn_on
        target:
          entity_id: light.living_room
        data:
          brightness_pct: 80

SSH Access (Optional)

For direct config editing on Home Assistant OS:

ssh root@<ha-host> 'cat /config/configuration.yaml'
ssh root@<ha-host> 'ha core restart'