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

Domain	Services
light	turn_on, turn_off, toggle
switch	turn_on, turn_off, toggle
climate	set_temperature, set_hvac_mode
cover	open_cover, close_cover, stop_cover
media_player	play_media, pause, volume_set
script	turn_on (runs script)
scene	turn_on (activates scene)
automation	trigger, turn_on, turn_off

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'