Skill: hogar23/home-assistant-control (version 1.0.3)

--- 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.

path: references/entities.md
content: # Home Assistant Entity Map

Fill this with your real entities to avoid guesswork.

## Lights

- light.example_living_room

## Switches

- switch.example_boiler

## Climate

- climate.example_downstairs

## Sensors

- sensor.example_outdoor_temperature

## Scenes

- scene.example_evening

## Scripts

- script.example_good_night

## Automations

- automation.example_morning_routine


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)