Home Assistant CLI

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.

Security Scan

The skill mostly matches its stated purpose (wrapping the official hass-cli), but the package metadata omits the obvious secret/environment requirement (HASS_TOKEN/HASS_SERVER) and the runtime instructions contain actions that can leak or weaken credentials, so the requests and documentation are not fully consistent or proportionate.

Purpose & Capability

The skill's name, description, and commands align with a Home Assistant CLI wrapper and legitimately need the hass-cli binary and access to a Home Assistant server. The install options (pip/homebrew) are appropriate for a Python CLI tool.

Instruction Scope

SKILL.md instructs the agent/user to set HASS_SERVER and HASS_TOKEN, test connections, and even echo $HASS_TOKEN in troubleshooting — but the skill metadata did not declare any required environment variables. The instructions otherwise stay within Home Assistant control scope and do not ask to read system files outside of typical shell configs.

Install Mechanism

Install spec uses pip and Homebrew formulas for homeassistant-cli, which is expected for this upstream project and is a low-to-moderate risk install path. No download-from-URL or arbitrary extraction is used.

Credentials

Runtime usage clearly requires a long-lived Home Assistant token (HASS_TOKEN) and server URL (HASS_SERVER). Those sensitive environment variables are not listed in requires.env or primary credential fields in the metadata — an omission that reduces transparency and could cause unintentional credential exposure. The troubleshooting guidance suggests echoing the token and using --insecure for certs, both of which can weaken secrecy or security if followed without caution.

Persistence & Privilege

The skill does not request permanent/always-on inclusion (always:false), does not modify other skills, and does not claim access to unrelated config paths or credentials. Autonomy is enabled by default (disable-model-invocation:false) which is standard and not by itself a red flag.

What to consider before installing

This skill appears to be a straightforward wrapper around the official hass-cli tool, but the metadata is missing the fact that you must provide HASS_SERVER and a long-lived HASS_TOKEN. Before installing: (1) verify the pip/homebrew package comes from the official project (check maintainers and repo), (2) be prepared to supply a Home Assistant long-lived access token — treat it like a password and avoid echoing it into terminals or logs, (3) avoid using --insecure in production (it disables SSL verification), (4) prefer storing the token in a secure secret store instead of exporting it in a shared shell config, and (5) consider whether you want an agent with autonomous invocation to run hass-cli commands against your home network. The metadata omission lowers transparency; ask the publisher to add required env vars (HASS_SERVER, HASS_TOKEN) to the skill manifest before trusting it.

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.