Home Assistant

Control Home Assistant smart home devices, run automations, and receive webhook events. Use when controlling lights, switches, climate, scenes, scripts, or any HA entity. Supports bidirectional communication via REST API (outbound) and webhooks (inbound triggers from HA automations).

Security Scan

The skill's behavior mostly matches a Home Assistant CLI, but its declared metadata omits required binaries and environment usage and it recommends storing long‑lived tokens and receiving inbound webhooks without clear guidance — these mismatches and webhook implications merit caution.

Purpose & Capability

The name/description and provided scripts (scripts/ha.sh) align with a Home Assistant controller: it uses HA_URL and HA_TOKEN to call HA REST endpoints, control entities, and trigger automations. However, registry metadata claims no required binaries or env vars while SKILL.md and the script clearly require curl and jq and expect either a config file (~/.config/home-assistant/config.json) or HA_URL/HA_TOKEN environment variables.

Instruction Scope

SKILL.md stays within the stated purpose (calling HA REST API and describing webhook usage). It directs creating a plaintext config file in the user's home or setting HA_URL/HA_TOKEN env vars and documents inbound webhook configuration from HA. It does not instruct the agent to read unrelated system files. Caveat: it presumes the platform will accept inbound webhooks at a public URL ("your-clawdbot-url"), but the skill does not provide safe guidance for exposing an agent or how webhook authentication/verification should be handled.

Install Mechanism

No install spec is present; this is instruction-only with a small included bash script. There is no external download/extract step. Risk from installation mechanics is low.

Credentials

The skill requires a long‑lived Home Assistant token (HA_TOKEN) and HA_URL for operation and depends on jq and curl, but the registry metadata lists no required env vars or binaries. That mismatch is suspicious because sensitive credentials are needed but were not declared as required in the registry metadata. Also the SKILL.md recommends storing a long‑lived access token in a plaintext file in the user home, which is a reasonable but sensitive practice that users should be aware of.

Persistence & Privilege

always: false and model invocation is allowed (normal). The skill does not request system-wide configuration changes or attempt to modify other skills. It reads/writes only its own config path (~/.config/home-assistant/config.json).

What to consider before installing

This skill appears to be a straightforward Home Assistant CLI, but there are some mismatches you should consider before installing: (1) The skill uses curl and jq and requires HA_URL and HA_TOKEN, yet the registry metadata doesn't declare those requirements — treat that as a red flag and confirm you understand what secrets the skill needs. (2) It recommends storing a long‑lived access token in ~/.config/home-assistant/config.json (plaintext in your home directory) — ensure the file permissions are locked (e.g., 600) and you are comfortable storing such a token there. (3) The SKILL.md explains receiving inbound webhooks to a "clawdbot" URL; if you plan to enable that, verify how the agent runtime exposes webhook endpoints, ensure the webhook URL is not publicly exposing sensitive controls, and require authentication/verification on inbound requests. (4) Because the skill's source/homepage is unknown, prefer installing only if you can audit the included script (scripts/ha.sh) yourself or if you trust the publisher. If you want to proceed, verify jq and curl are installed, create the config file with restrictive permissions, and consider using a short‑lived or limited token if possible. If you need higher assurance, ask the publisher for authoritative source and a homepage or inspect the script line‑by‑line (it is small and readable).

Control your smart home via Home Assistant's REST API and webhooks.

Setup

Option 1: Config File (Recommended)

Create ~/.config/home-assistant/config.json:

{
  "url": "https://your-ha-instance.duckdns.org",
  "token": "your-long-lived-access-token"
}

Option 2: Environment Variables

export HA_URL="http://homeassistant.local:8123"
export HA_TOKEN="your-long-lived-access-token"

Getting a Long-Lived Access Token

1. Open Home Assistant → Profile (bottom left)
2. Scroll to "Long-Lived Access Tokens"
3. Click "Create Token", name it (e.g., "Clawdbot")
4. Copy the token immediately (shown only once)

Quick Reference

List Entities

curl -s -H "Authorization: Bearer $HA_TOKEN" "$HA_URL/api/states" | jq '.[].entity_id'

Get Entity State

curl -s -H "Authorization: Bearer $HA_TOKEN" "$HA_URL/api/states/light.living_room"

Control Devices

# Turn on
curl -X POST -H "Authorization: Bearer $HA_TOKEN" -H "Content-Type: application/json" \
  "$HA_URL/api/services/light/turn_on" -d '{"entity_id": "light.living_room"}'

# Turn off
curl -X POST -H "Authorization: Bearer $HA_TOKEN" -H "Content-Type: application/json" \
  "$HA_URL/api/services/light/turn_off" -d '{"entity_id": "light.living_room"}'

# Set brightness (0-255)
curl -X POST -H "Authorization: Bearer $HA_TOKEN" -H "Content-Type: application/json" \
  "$HA_URL/api/services/light/turn_on" -d '{"entity_id": "light.living_room", "brightness": 128}'

Run Scripts & Automations

# Trigger script
curl -X POST -H "Authorization: Bearer $HA_TOKEN" "$HA_URL/api/services/script/turn_on" \
  -H "Content-Type: application/json" -d '{"entity_id": "script.goodnight"}'

# Trigger automation
curl -X POST -H "Authorization: Bearer $HA_TOKEN" "$HA_URL/api/services/automation/trigger" \
  -H "Content-Type: application/json" -d '{"entity_id": "automation.motion_lights"}'

Activate Scenes

curl -X POST -H "Authorization: Bearer $HA_TOKEN" "$HA_URL/api/services/scene/turn_on" \
  -H "Content-Type: application/json" -d '{"entity_id": "scene.movie_night"}'

Common Services

Domain	Service	Example entity_id
light	turn_on, turn_off, toggle	light.kitchen
switch	turn_on, turn_off, toggle	switch.fan
climate	set_temperature, set_hvac_mode	climate.thermostat
cover	open_cover, close_cover, stop_cover	cover.garage
media_player	play_media, media_pause, volume_set	media_player.tv
scene	turn_on	scene.relax
script	turn_on	script.welcome_home
automation	trigger, turn_on, turn_off	automation.sunrise

Inbound Webhooks (HA → Clawdbot)

To receive events from Home Assistant automations:

1. Create HA Automation with Webhook Action

# In HA automation
action:
  - service: rest_command.notify_clawdbot
    data:
      event: motion_detected
      area: living_room

2. Define REST Command in HA

# configuration.yaml
rest_command:
  notify_clawdbot:
    url: "https://your-clawdbot-url/webhook/home-assistant"
    method: POST
    headers:
      Authorization: "Bearer {{ webhook_secret }}"
      Content-Type: "application/json"
    payload: '{"event": "{{ event }}", "area": "{{ area }}"}'

3. Handle in Clawdbot

Clawdbot receives the webhook and can notify you or take action based on the event.

CLI Wrapper

The scripts/ha.sh CLI provides easy access to all HA functions:

# Test connection
ha.sh info

# List entities
ha.sh list all          # all entities
ha.sh list lights       # just lights
ha.sh list switch       # just switches

# Search entities
ha.sh search kitchen    # find entities by name

# Get/set state
ha.sh state light.living_room
ha.sh states light.living_room   # full details with attributes
ha.sh on light.living_room
ha.sh on light.living_room 200   # with brightness (0-255)
ha.sh off light.living_room
ha.sh toggle switch.fan

# Scenes & scripts
ha.sh scene movie_night
ha.sh script goodnight

# Climate
ha.sh climate climate.thermostat 22

# Call any service
ha.sh call light turn_on '{"entity_id":"light.room","brightness":200}'

Troubleshooting

• 401 Unauthorized: Token expired or invalid. Generate a new one.
• Connection refused: Check HA_URL, ensure HA is running and accessible.
• Entity not found: List entities to find the correct entity_id.

API Reference

For advanced usage, see references/api.md.