py-homeassistant-cli
by @xwings
Tiny and short Python CLI tool to control Home Assistant devices and automations via the REST API. No external dependencies — uses only Python 3.6+ standard...
clawhub install py-homeassistant-cli📖 About This Skill
name: py-homeassistant-cli description: > Tiny and short Python CLI tool to control Home Assistant devices and automations via the REST API. No external dependencies — uses only Python 3.6+ standard library. license: MIT homepage: https://github.com/xwings/py-homeassistant-cli compatibility: Requires Python 3.6+. Network access to Home Assistant instance. metadata: {"author": "xwings", "openclaw": { env: ["HA_URL", "HA_TOKEN"],"bins": ["python3 {baseDir}/scripts/homeassistant-cli.py"]}}
Home Assistant Skill
Control smart home devices via the Home Assistant REST API using the Python CLI tool at {baseDir}/scripts/homeassistant-cli.py. No external dependencies — uses only Python standard library.
Setup
Configure via environment variables or command-line arguments (args take priority):
# Optional: Environment variables
export HA_URL="http://10.0.0.10:8123"
export HA_TOKEN="your_long_lived_access_token"pass via args (overrides env vars)
python3 {baseDir}/scripts/homeassistant-cli.py --server http://10.0.0.10:8123 --token YOUR_TOKEN check
Use --help on any command for details: python3 {baseDir}/scripts/homeassistant-cli.py light --help
Safety Rules
Always confirm with the user before: locking/unlocking locks, arming/disarming alarm panels, opening/closing garage doors or gates, disabling security automations.
Command Reference
All commands follow: python3 {baseDir}/scripts/homeassistant-cli.py [--server URL] [--token TOKEN]
Discovery & Status
check # Check API connectivity
entities # List all entities
entities --domain light # List entities by domain (light, switch, sensor, etc.)
state # Get full entity state JSON
areas # List all areas
area-entities [--domain light] # Entities in an area, optionally filtered
area-of # Find which area an entity belongs to
floors # List all floors and their areas
services [--domain light] # List available services
dashboard # Quick overview: lights on, doors, temps, locks, presence
presence [--trackers] # Who is home (--trackers for device trackers)
weather [--forecast daily|hourly] [-e entity] # Current weather or forecast
Device Control
switch
light [--brightness 80] [--rgb 255,150,50] [--color-temp 300]
fan [--percentage 50]
cover [--position 50]
lock
media [--level 0.5]
vacuum
climate [--temperature 72] [--mode auto]
alarm [--code 1234]
scene
Automations & Scripts
automation [entity_id]
script [entity_id] [--variables '{"key": "value"}']
Notifications
notify list # List notification targets
notify send "message" [--title "title"] # Send notification
Input Helpers
input boolean # Toggle
input number # Set number
input select "option" # Set selection
input text "value" # Set text
input datetime "07:30:00" # Set time
Calendar & TTS
calendar list # List calendars
calendar events [--days 14] # Upcoming events
tts "message" # Text-to-speech
Templates, History & Logbook
template '{{ states.light | list | count }} lights' # Evaluate Jinja2
history [--start ISO8601] [--end ISO8601] # State history
logbook [--entity entity_id] [--limit 20] # Logbook entries
Template functions: states(), is_state(), state_attr(), areas(), area_entities(), area_name(), floors(), floor_areas(), labels(), label_entities(), devices(), device_entities(), now(), relative_time().
Generic Service Call
service --data '{"entity_id": "light.living_room"}'Batch: pass array of entity_ids
service light turn_off --data '{"entity_id": ["light.room1", "light.room2"]}'
Tesla
Entities: sensor.mao_dou_battery, device_tracker.mao_dou_location_tracker, device_tracker.mao_dou_destination_location_tracker, automation.tesla_battery_below_20
tesla battery # Battery level
tesla location # GPS coordinates, heading, speed
tesla destination # Destination location
tesla automations # List Tesla-related entities
Entity Domains
| Domain | Examples | Domain | Examples |
|--------|----------|--------|----------|
| switch.* | Smart plugs | light.* | Lights (Hue, LIFX) |
| climate.* | Thermostats, AC | cover.* | Blinds, garage doors |
| lock.* | Smart locks | fan.* | Fans, ventilation |
| media_player.* | TVs, speakers | vacuum.* | Robot vacuums |
| alarm_control_panel.* | Security systems | scene.* | Pre-configured scenes |
| script.* | Action sequences | automation.* | Automations |
| sensor.* | Temp, humidity, power | binary_sensor.* | Motion, door/window |
| person.* | Presence tracking | device_tracker.* | Device locations |
| weather.* | Weather/forecasts | calendar.* | Calendar events |
| notify.* | Notification targets | tts.* | Text-to-speech |
| input_boolean.* | Virtual toggles | input_number.* | Numeric sliders |
| input_select.* | Dropdown selectors | input_text.* | Text inputs |
| input_datetime.* | Date/time inputs | | |
HTTP Status Codes
| Code | Meaning | |------|---------| | 200 | Success | | 400 | Bad request (malformed JSON) | | 401 | Unauthorized (bad/missing token) | | 404 | Entity or endpoint not found | | 503 | HA starting up or unavailable |
Notes
entities --domain firstservice command for any operation not covered by dedicated commands⚙️ Configuration
Configure via environment variables or command-line arguments (args take priority):
# Optional: Environment variables
export HA_URL="http://10.0.0.10:8123"
export HA_TOKEN="your_long_lived_access_token"pass via args (overrides env vars)
python3 {baseDir}/scripts/homeassistant-cli.py --server http://10.0.0.10:8123 --token YOUR_TOKEN check
Use --help on any command for details: python3 {baseDir}/scripts/homeassistant-cli.py light --help
📋 Tips & Best Practices
entities --domain firstservice command for any operation not covered by dedicated commands