Introduction
# Home Assistant
Control your smart home via Home Assistant's REST API and webhooks.
## Setup
### Option 1: Config File (Recommended)
Create `~/.config/home-assistant/config.json`: ```json { "url": "https://your-ha-instance.duckdns.org", "token": "your-long-lived-access-token" } ```
### Option 2: Environment Variables
```bash 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
```bash curl -s -H "Authorization: Bearer $HA_TOKEN" "$HA_URL/api/states" | jq '.[].entity_id' ```
### Get Entity State
```bash curl -s -H "Authorization: Bearer $HA_TOKEN" "$HA_URL/api/states/light.living_room" ```
### Control Devices
```bash # 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
```bash # 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
```bash 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
```yaml # In HA automation action: - service: rest_command.notify_clawdbot data: event: motion_detected area: living_room ```
### 2. Define REST Command in HA
```yaml # 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:
```bash # 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](references/api.md).