homeassistant-toolkit

name	homeassistant-toolkit
description	Deep integration with Home Assistant via REST API. Control devices, manage automations, query entity states, and orchestrate scenes/scripts from the command line.

Home Assistant Toolkit

Full-featured CLI for Home Assistant power users. Control your smart home without opening a browser.

Prerequisites

Requirement	Details
Home Assistant	2023.1+ with REST API enabled
Long-Lived Access Token	Generate at /profile → Long-Lived Access Tokens
Python 3.6+	Pre-installed on most systems
curl	For direct API calls (fallback)

Environment Variables

export HA_URL="http://192.168.1.100:8123"    # Your HA instance URL
export HA_TOKEN="eyJ0eXAiOiJKV..."           # Long-Lived Access Token

Quick Start

# Check connection & server info
bash scripts/ha-toolkit.sh status

# List all entities
bash scripts/ha-toolkit.sh entities

# Turn on a light
bash scripts/ha-toolkit.sh call light.turn_on light.living_room

# Get entity state
bash scripts/ha-toolkit.sh state sensor.temperature_outdoor

# Fire an automation
bash scripts/ha-toolkit.sh automation trigger automation.morning_routine

# List all scenes and activate one
bash scripts/ha-toolkit.sh scenes
bash scripts/ha-toolkit.sh scene activate scene.movie_night

Commands Reference

Device Control

Command	Description
call <service> <entity_id> [json_data]	Call any HA service with optional JSON payload
toggle <entity_id>	Toggle an entity on/off
state <entity_id>	Get full state + attributes of an entity
entities [domain]	List entities, optionally filtered by domain
history <entity_id> [hours]	Fetch state history (default: 24h)

Automation Management

Command	Description
automations	List all automations with status
automation trigger <automation_id>	Manually trigger an automation
automation enable <automation_id>	Enable a disabled automation
automation disable <automation_id>	Disable an automation

Scenes & Scripts

Command	Description
scenes	List all configured scenes
scene activate <scene_id>	Activate a scene
scripts	List all scripts
script run <script_id>	Run a script

System & Diagnostics

Command	Description
status	HA server info (version, location, timezone)
config	Show full HA configuration
logs [lines]	Fetch recent HA log entries
services [domain]	List available services
dashboard	Interactive overview of key entities

Advanced Usage

Bulk Operations

# Turn off all lights
bash scripts/ha-toolkit.sh call light.turn_off all

# Set multiple attributes
bash scripts/ha-toolkit.sh call light.turn_on light.bedroom '{"brightness": 128, "color_temp": 350}'

Monitoring Mode

# Watch an entity for changes (polls every 5 seconds)
bash scripts/ha-toolkit.sh watch sensor.power_consumption 5

Integration with Cron

# Check garage door every 30 min, notify if open
*/30 * * * * bash /path/to/ha-toolkit.sh state cover.garage_door | grep -q "open" && echo "Garage is open!" | mail -s "Alert" [e-mail]

Error Handling

The toolkit validates:

• HA_URL and HA_TOKEN are set before any API call
• HTTP response codes (401 unauthorized, 404 not found, etc.)
• JSON parsing with graceful fallback
• Network connectivity with timeout controls

Troubleshooting

"Connection refused" — Verify HA is running and the URL is correct. Check firewall rules.

"401 Unauthorized" — Your token may be expired or invalid. Generate a new one from the HA profile page.

"Entity not found" — Use entities command to list valid entity IDs. Check domain prefix (e.g., light. vs switch.).

Security Notes

• Tokens are read from environment variables only — never stored on disk by the script
• All API calls use HTTPS when your HA instance supports it
• Consider using a dedicated HA user with limited permissions for automation scripts