| name | home-assistant |
| description | Control Home Assistant smart home devices, run automations, and manage scenes. Use when controlling lights, switches, climate, scenes, scripts, or any HA entity. |
| version | 1.0.0 |
| requires | {"bins":["jq","curl"]} |
| always | false |
Home Assistant
Control your smart home via Home Assistant's REST API.
Setup
Option 1: Config File (Recommended)
Create ~/.janus/home-assistant/config.json (restrict permissions — contains secret token):
mkdir -p ~/.janus/home-assistant
cat > ~/.janus/home-assistant/config.json << 'EOF'
{
"url": "https://your-ha-instance.duckdns.org",
"token": "your-long-lived-access-token"
}
EOF
chmod 600 ~/.janus/home-assistant/config.json
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
- Open Home Assistant → Profile (bottom left)
- Scroll to "Long-Lived Access Tokens"
- Click "Create Token", name it (e.g., "Janus")
- Copy the token immediately (shown only once)
CLI Wrapper
Use scripts/ha.sh via exec for all HA operations:
ha.sh info
ha.sh list all
ha.sh list lights
ha.sh list switch
ha.sh search kitchen
ha.sh state light.living_room
ha.sh states light.living_room
ha.sh on light.living_room
ha.sh on light.living_room 200
ha.sh off light.living_room
ha.sh toggle switch.fan
ha.sh scene movie_night
ha.sh script goodnight
ha.sh climate climate.thermostat 22
ha.sh call light turn_on '{"entity_id":"light.room","brightness":200}'
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 |
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.