---
name: home-assistant-control
description: Control and inspect Home Assistant via REST API for entities, states, services, scenes, scripts, and automations. Use when the user asks to turn devices on/off, set values like brightness or temperature, trigger scenes/scripts/automations, or check current home/sensor status.
homepage: https://github.com/Hogar23/home-assistant-control
metadata:
  {
    "openclaw": {
      "emoji": "🏠",
      "requires": {
        "bins": ["bash", "curl", "jq"],
        "env": ["HA_TOKEN", "HA_URL_PUBLIC"]
      }
    }
  }
---

# Home Assistant Control

Use Home Assistant REST API with a long-lived access token.

## Requirements

### For skill users (runtime)

- `bash`
- `curl`
- `jq`
- Home Assistant long-lived token (`HA_TOKEN`)
- Home Assistant public base URL (`HA_URL_PUBLIC`)

### For skill maintainers (packaging/validation)

- `python3`
- `pyyaml` (required by `skill-creator` validator/packager scripts)

## Required environment variables

- `HA_TOKEN` (required)
- `HA_URL_PUBLIC` (required; canonical target and fallback)
- Optional URL behavior:
  - if `HA_URL_LOCAL` is set (and no `HA_URL` override), local is tried first, then fallback to `HA_URL_PUBLIC`
  - `HA_URL` is an explicit override (if set, used directly)

## Secrets handling (publish-safe)

- Keep keys/URLs in an external file, not in the skill folder.
- Set `HA_ENV_FILE=/absolute/path/to/file.env` when you want file-based secret loading.
- If `HA_ENV_FILE` is not set, scripts only use environment variables already present in the shell.
- `scripts/ha_call.sh` and `scripts/self_check.sh` load env file only when `HA_ENV_FILE` is provided.

## Core workflow

1. Parse the user request into target entity/service + desired action.
2. Check `references/naming-context.md` for manual alias mappings first.
3. Verify entity exists before changing state.
4. Execute service call.
5. Re-check state and report outcome clearly.

## Useful endpoints

- List states: `GET /api/states`
- Single state: `GET /api/states/{entity_id}`
- Call service: `POST /api/services/{domain}/{service}`

Headers:

- `Authorization: Bearer $HA_TOKEN`
- `Content-Type: application/json`

## Scripts

- `scripts/ha_env.sh` — loads env file only when `HA_ENV_FILE` is explicitly set, using safe KEY=VALUE parsing (no `source`/`eval`).
- `scripts/ha_call.sh` — generic API caller for Home Assistant.
- `scripts/fill_entities_md.sh` — generate `references/entities.md` from `GET /api/states`.
  - Full map: `./scripts/fill_entities_md.sh`
  - Filter domains: `./scripts/fill_entities_md.sh --domains light,switch,climate,sensor`
- `scripts/save_naming_context.sh` — refresh `references/naming-context.md` for user-specific naming.
  - `./scripts/save_naming_context.sh`
- `scripts/ha_entity_find.sh` — search entities by partial entity id or friendly name.
  - `./scripts/ha_entity_find.sh kitchen`
  - `./scripts/ha_entity_find.sh temp --domains sensor,climate --limit 30`
- `scripts/ha_safe_action.sh` — execute service actions with safety checks and risk confirmation.
  - `./scripts/ha_safe_action.sh light turn_on light.kitchen '{"brightness_pct":60}'`
  - `./scripts/ha_safe_action.sh lock unlock lock.front_door --dry-run`
  - Add `--yes` to bypass interactive confirmation for risky domains.
- `scripts/self_check.sh` — verify prerequisites and API connectivity/auth before running actions.
  - `./scripts/self_check.sh`

## Safety

- Confirm before high-impact actions (locks, alarms, garage/doors, heating shutdown).
- Do not print raw token values.
- If target entity is ambiguous, ask a follow-up question.
- Keep API paths scoped to Home Assistant endpoints only (`/api/...`).
- Use only HTTP(S) Home Assistant base URLs (`HA_URL*`), prefer HTTPS for public access.
- Avoid code execution when loading env files: parse key/value pairs, do not use `source` on untrusted paths.

## Reference files

- `references/entities.md` — entity inventory
- `references/naming-context.md` — user alias memory for natural names (e.g. "living room light")

## Publishing notes

- Keep examples generic (`example_*` IDs), no personal hostnames/tokens.
- Do not commit `.env` or any private env file with real tokens.
- Keep the skill focused: API workflow + reusable scripts + entity reference.