home-assistant

# Home Assistant CLI Control Home Assistant via `hass-cli`. ## Install ```bash # macOS (Homebrew) brew install homeassistant-cli # pip (any platform) pip install homeassistant-cli # Verify hass-cli --version ``` ## Setup ### 1. Find Your Home Assistant URL Common URLs (try in order): - `http://homeassistant.local:8123` — Default mDNS hostname - `http://homeassistant:8123` — If using Docker/hostname - `http://<IP-ADDRESS>:8123` — Direct IP (e.g., `http://192.168.1.100:8123`) - `https://your-instance.ui.nabu.casa` — If using Nabu Casa cloud Test it: open the URL in a browser — you should see the HA login page. ### 2. Create a Long-Lived Access Token 1. Open Home Assistant in your browser 2. Click your **profile** (bottom-left of the sidebar, your name/icon) 3. Scroll down to **Long-Lived Access Tokens** 4. Click **Create Token** 5. Give it a name (e.g., "Clawdbot" or "CLI") 6. **Copy the token immediately** — you won't see it again! The token looks like: `eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3...` ### 3. Configure Environment Variables Add to your shell profile (`~/.zshrc` or `~/.bashrc`): ```bash export HASS_SERVER="http://homeassistant.local:8123" export HASS_TOKEN="your-token-here" ``` Or for Clawdbot, store credentials in TOOLS.md: ```markdown ## Home Assistant - **URL:** `http://homeassistant.local:8123` - **Token:** `eyJ...your-token...` ``` Then reference TOOLS.md before making calls. ## Quick Reference ```bash # List all entities hass-cli state list # Filter entities (pipe to grep) hass-cli state list | grep -i kitchen # Get specific entity state hass-cli state get light.kitchen # Turn on/off hass-cli service call switch.turn_on --arguments entity_id=switch.fireplace hass-cli service call switch.turn_off --arguments entity_id=switch.fireplace hass-cli service call light.turn_on --arguments entity_id=light.kitchen hass-cli service call light.turn_off --arguments entity_id=light.kitchen # Light brightness (0-255) hass-cli service call light.turn_on --arguments entity_id=light.kitchen,brightness=128 # Toggle hass-cli service call switch.toggle --arguments entity_id=switch.fireplace # Climate hass-cli service call climate.set_temperature --arguments entity_id=climate.thermostat,temperature=72 # Run automation/script hass-cli service call automation.trigger --arguments entity_id=automation.evening_lights hass-cli service call script.turn_on --arguments entity_id=script.movie_mode ``` ## Entity Naming Patterns - `light.*` — Lights - `switch.*` — Switches, plugs, relays - `sensor.*` — Temperature, humidity, power, etc. - `binary_sensor.*` — Motion, door/window, presence - `climate.*` — Thermostats, HVAC - `cover.*` — Blinds, garage doors - `media_player.*` — TVs, speakers - `automation.*` — Automations - `script.*` — Scripts - `scene.*` — Scenes ## Discovery Tips ```bash # Find all lights hass-cli state list | grep "^light\." # Find devices by room name hass-cli state list | grep -i bedroom # Find all "on" devices hass-cli state list | grep -E "\s+on\s+" # Get entity attributes (JSON) hass-cli --format json state get light.kitchen ``` ## Notes - Empty `[]` response from service calls = success - Use exact entity_id from `state list` - Multiple arguments: comma-separated (no spaces) - If hass-cli unavailable, use REST API as fallback: ```bash curl -s -H "Authorization: Bearer $HASS_TOKEN" "$HASS_SERVER/api/states" | jq ```