Home Assistant

Home Assistant CLI

Control Home Assistant via hass-cli.

Install

# 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):

export HASS_SERVER="http://homeassistant.local:8123"
export HASS_TOKEN="your-token-here"

Or for Clawdbot, store credentials in TOOLS.md:

## Home Assistant
- **URL:** `http://homeassistant.local:8123`
- **Token:** `eyJ...your-token...`

Then reference TOOLS.md before making calls.

Quick Reference

# 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

# 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:

  curl -s -H "Authorization: Bearer $HASS_TOKEN" "$HASS_SERVER/api/states" | jq