homeassistant-cli – OpenClaw Skill

---

name: homeassistant-cli description: Advanced Home Assistant control using the official hass-cli tool. Features auto-completion, event monitoring, history queries, and rich output formatting. Alternative to the curl-based homeassistant skill - choose this if you want a more interactive CLI experience with better discovery and formatting. homepage: https://github.com/home-assistant-ecosystem/home-assistant-cli metadata: { "openclaw": { "emoji": "🏡", "requires": { "bins": ["hass-cli"] }, "install": [ { "id": "pip", "kind": "pip", "package": "homeassistant-cli", "bins": ["hass-cli"], "label": "Install Home Assistant CLI (pip)", }, { "id": "brew", "kind": "brew", "formula": "homeassistant-cli", "bins": ["hass-cli"], "label": "Install Home Assistant CLI (brew)", }, ], }, }

Home Assistant CLI

Control your Home Assistant smart home devices using the official hass-cli tool — a feature-rich command-line interface with auto-completion, event monitoring, and flexible output formatting.

Why This Skill vs. homeassistant (curl-based)?

Choose homeassistant-cli if you want:

• ✅ Auto-completion for entity IDs and services (bash/zsh/fish)
• ✅ Event monitoring in real-time (hass-cli event watch)
• ✅ History queries (hass-cli state history)
• ✅ Better output formatting (table/YAML/JSON with one flag)
• ✅ Interactive exploration (easier to discover entities and services)
• ✅ Comprehensive documentation with examples and troubleshooting

Choose homeassistant (curl) if you want:

• ✅ Zero dependencies (curl + jq are pre-installed)
• ✅ Lightweight and fast
• ✅ Better for scripting and automation
• ✅ No Python requirements

Both work great — this skill is for users who interact frequently with Home Assistant and want a richer CLI experience.

Setup

Before using hass-cli, configure authentication:

1. Generate a long-lived access token in Home Assistant:

   • Navigate to your profile: https://your-homeassistant:8123/profile
   • Scroll to "Long-Lived Access Tokens"
   • Create a new token

2. Set environment variables (add to shell config for persistence):

   export HASS_SERVER=https://homeassistant.local:8123
   export HASS_TOKEN=<your-token>
   

3. Test connection:

   hass-cli info
   

Common Commands

List Entities

# List all entities
hass-cli state list

# Filter by domain
hass-cli state list light
hass-cli state list switch
hass-cli state list sensor

# Get specific entity state
hass-cli state get light.living_room

Control Devices

# Turn on/off lights
hass-cli service call light.turn_on --arguments entity_id=light.living_room
hass-cli service call light.turn_off --arguments entity_id=light.living_room

# Set brightness (0-255)
hass-cli service call light.turn_on --arguments entity_id=light.bedroom,brightness=128

# Turn on/off switches
hass-cli service call switch.turn_on --arguments entity_id=switch.fan
hass-cli service call switch.turn_off --arguments entity_id=switch.fan

# Toggle any device
hass-cli service call homeassistant.toggle --arguments entity_id=light.kitchen

List and Call Services

# List all services
hass-cli service list

# Filter services
hass-cli service list light
hass-cli service list 'home.*toggle'

# Get service details (YAML output)
hass-cli -o yaml service list homeassistant.toggle

Work with Scenes

# List scenes
hass-cli state list scene

# Activate a scene
hass-cli service call scene.turn_on --arguments entity_id=scene.movie_time

Monitor Events

# Watch all events
hass-cli event watch

# Watch specific event type
hass-cli event watch state_changed
hass-cli event watch automation_triggered

History

# Get state history (last 50 minutes)
hass-cli state history --since 50m light.living_room

# Multiple entities
hass-cli state history --since 1h light.living_room switch.fan

Output Formats

Control output with -o or --output:

# Table (default)
hass-cli state list

# YAML
hass-cli -o yaml state get light.living_room

# JSON
hass-cli -o json state list light

# No headers (for scripting)
hass-cli --no-headers state list

Tips

• Entity discovery: Use hass-cli state list to find entity IDs
• Service discovery: Use hass-cli service list to find available services
• Auto-completion: See references/autocomplete.md for shell setup
• Troubleshooting: See references/troubleshooting.md

Examples

See references/examples.md for common automation patterns and use cases.

Home Assistant CLI Skill for OpenClaw

Advanced Home Assistant control using the official hass-cli tool.

🌟 Features

• Auto-completion for entity IDs and services (bash/zsh/fish)
• Event monitoring in real-time
• History queries for state changes
• Rich output formatting (table/YAML/JSON)
• Interactive exploration of entities and services
• Comprehensive documentation with examples and troubleshooting

🆚 Comparison with homeassistant (curl-based)

Feature	homeassistant-cli (this)	homeassistant (curl)
Dependencies	hass-cli (Python)	curl + jq (built-in)
Auto-completion	✅ Yes	❌ No
Event monitoring	✅ Yes	❌ No
History queries	✅ Yes	❌ No
Output formats	Table/YAML/JSON	JSON only
Setup complexity	Medium	Simple
Best for	Interactive use	Scripting/automation

Both are great! Choose based on your workflow:

• Interactive control → homeassistant-cli
• Lightweight scripting → homeassistant (curl)

📦 Installation

1. Install hass-cli

Via pip:

pip install homeassistant-cli

Via Homebrew:

brew install homeassistant-cli

2. Configure Connection

Set environment variables in your shell config (~/.zshrc or ~/.bashrc):

export HASS_SERVER=http://your-homeassistant:8123
export HASS_TOKEN=<your-long-lived-token>

Get your token:

1. Open Home Assistant web interface
2. Click your profile (bottom left)
3. Scroll to "Long-Lived Access Tokens"
4. Click "CREATE TOKEN"
5. Copy the token (only shown once!)

3. Test Connection

hass-cli state list

🚀 Quick Start

List Devices

# All entities
hass-cli state list

# Only lights
hass-cli state list light

# Only switches
hass-cli state list switch

Control Devices

# Turn on light
hass-cli service call light.turn_on --arguments entity_id=light.living_room

# Turn off light
hass-cli service call light.turn_off --arguments entity_id=light.living_room

# Set brightness
hass-cli service call light.turn_on --arguments entity_id=light.bedroom,brightness=128

Monitor Events

# Watch all events
hass-cli event watch

# Watch state changes only
hass-cli event watch state_changed

Query History

# Last hour
hass-cli state history --since 1h light.living_room

# Last 30 minutes
hass-cli state history --since 30m switch.fan

📚 Documentation

Inside the skill package:

• SKILL.md — Main guide with common commands
• references/examples.md — Automation patterns and use cases
• references/autocomplete.md — Shell auto-completion setup
• references/troubleshooting.md — Common issues and solutions

🛠️ Requirements

• Home Assistant (any version with REST API)
• Python 3.8+
• Long-lived access token

📄 License

MIT

🙏 Credits

• Built on home-assistant-cli
• Created for the OpenClaw agent framework