home-assistant

Credential Check

Before using this skill, verify credentials are configured:

source .env && echo "HA URL: $HA_URL" && echo "Token: ${HA_TOKEN:0:10}..."

If this shows nothing or errors, guide the user through First-Time Setup below.

Environment Setup

Credentials are stored in .env (gitignored):

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

Quick Usage

Check API is running

source .env && curl -s -H "Authorization: Bearer $HA_TOKEN" "$HA_URL/api/"
# Should return: {"message": "API running."}

Get all entity states

source .env && curl -s -H "Authorization: Bearer $HA_TOKEN" "$HA_URL/api/states" | head -100

Get specific entity

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

Turn on a light

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

Turn off a light

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

Toggle a light

source .env && curl -s -X POST -H "Authorization: Bearer $HA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"entity_id": "light.living_room"}' \
  "$HA_URL/api/services/light/toggle"

Common Services

Lights

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

Switches

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

Climate

curl -s -X POST -H "Authorization: Bearer $HA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"entity_id": "climate.thermostat", "temperature": 72}' \
  "$HA_URL/api/services/climate/set_temperature"

Vacuum

curl -s -X POST -H "Authorization: Bearer $HA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"entity_id": "vacuum.roborock"}' \
  "$HA_URL/api/services/vacuum/start"

Scenes

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

Entity ID Patterns

First-Time Setup (If Credentials Missing)

What you need from the user

1. Home Assistant URL - e.g., http://homeassistant.local:8123
2. Long-lived access token

Step 1: Get the access token

Tell the user:

1. Open Home Assistant web UI
2. Click your profile (bottom left corner)
3. Go to Security tab
4. Scroll to Long-Lived Access Tokens
5. Click Create Token, name it (e.g., "OpenCode")
6. Copy the token immediately (it won't be shown again!)

Step 2: Add credentials to .env

cat >> .env << 'EOF'
# Home Assistant
HA_URL=http://homeassistant.local:8123
HA_TOKEN=your-long-lived-token-here
EOF

Step 3: Test it works

source .env && curl -s -H "Authorization: Bearer $HA_TOKEN" "$HA_URL/api/"
# Should return: {"message": "API running."}

API Reference

Response Codes