hass-cli

Shared foundation for all hass-cli skills. Read this FIRST. Covers connecting to a Home Assistant instance (HASS_SERVER + HASS_TOKEN long-lived token), the unified REST+WebSocket transport facade, output formats (table/json/yaml/ndjson), the raw passthrough escape hatches (raw api / raw ws), and the auth-error recovery table. Use whenever the user mentions Home Assistant, hass-cli, controlling smart-home entities, calling services, automations, or any HA REST/WebSocket API task.

Manage Home Assistant radio gateways and their networks with hass-cli: Zigbee (ZHA), Z-Wave JS, Matter, and Thread/OTBR. Use to pair/remove a Zigbee device, permit join, add/exclude a Z-Wave node, read network status/topology, back up a Zigbee/Z-Wave coordinator, commission a Matter device, or inspect Thread datasets. The gateway integration's own lifecycle (add/reload/delete) lives in ha-integrations; the devices it exposes live in ha-registry.

Manage Home Assistant integrations (config entries) and device discovery with hass-cli: list integrations and their state, reload, enable/disable, delete, update entry options, and inspect discovered/in-progress config flows. Use for 'list my integrations', 'reload the X integration', 'why is this integration failing', 'disable this entry', 'what was discovered on my network' requests.

Inspect and configure Home Assistant's Energy dashboard with hass-cli: read energy preferences (grid/solar/battery/gas/water sources and devices), validate the energy config, and pull consumption statistics. Use for 'show my energy setup', 'how much solar did I produce', 'what's using the most power' questions. Energy data is WebSocket + statistics-based.

Read Home Assistant entity states and recent history with hass-cli. Use to answer 'is the light on', 'what's the temperature', 'list all sensors', 'what changed recently', or to inspect any entity's current state and attributes. Covers state list/get, table shaping (--columns/--sort-by), and history/logbook reads.

Manage Home Assistant add-ons and the Supervisor/OS layer with hass-cli. Use to list/install/uninstall/update/start/stop/restart add-ons, browse the add-on store, read add-on logs, or check Core/Supervisor/OS info. Works through Core's supervisor/api WebSocket proxy with a regular admin token (no separate supervisor token needed).

Manage Home Assistant areas, devices, entities, floors, and labels with hass-cli. Use to list/create/rename/delete areas, assign devices or entities to areas, organize with floors and labels, rename entity_ids, or audit the registry. These are WebSocket-only operations (config/*_registry/*).

Query Home Assistant's recorder long-term statistics with hass-cli: list which statistic ids exist, read their metadata (unit, source, has_sum/has_mean), and pull aggregated values (sum/mean/min/max) over a time period and bucket. Use for 'how much energy/water/gas over time', 'trend of this sensor', 'monthly totals', or as the data source for consumption/audit analyses. Distinct from instantaneous state history.

Use Home Assistant's Assist voice/conversation layer with hass-cli: send a natural-language command to the conversation agent, list conversation agents and assist pipelines, list STT/TTS engines and voices, and speak text on a media player. Use for 'tell Assist to turn off the lights', 'what voice assistants are configured', 'run a sentence through HA' requests.

Read and write Home Assistant Lovelace dashboards with hass-cli: list dashboards, create/update/delete storage-mode dashboards, get and save a dashboard's full view/card config (YAML or JSON), and manage custom JS/CSS resources. Use for 'show my dashboards', 'edit the dashboard config', 'add a card', 'create a new dashboard', 'export/import a dashboard' requests.

Inspect Home Assistant system health, repair issues, error logs, logbook, and state history with hass-cli. Use to diagnose problems, check integration health, find open repairs, read recent errors, or gather the raw native data that audits (dead entities, broken automations) are derived from. Complexity scoring/audit are NOT native HA features; compute them here from native data.

Create, list, inspect, delete, and restore Home Assistant backups with hass-cli. Use for 'make a backup', 'list my backups', 'back up before I change something', 'delete old backups', 'restore this backup' requests. Backups go to configured agents (local and/or cloud/network).

Read and control the general Home Assistant entity domains with hass-cli that don't have a dedicated skill: sensor, binary_sensor, number, select, text, button, update, weather, vacuum, alarm_control_panel, siren, camera, todo lists, and calendars. Use for 'read this sensor', 'set this number/select/text helper-style entity', 'start the vacuum', 'arm the alarm', 'what's on my to-do list', 'next calendar event' requests.

Control Home Assistant climate, HVAC, thermostats, humidifiers, and water heaters with hass-cli: set target temperature, HVAC mode (heat/cool/auto/off), fan mode, preset, humidity, and water-heater operation. Use for 'set the thermostat to 21', 'turn on the AC', 'set to eco', 'set humidity to 45%' requests. All control goes through service call.

Create and manage Home Assistant helper entities with hass-cli: input_boolean, input_button, input_number, input_select, input_text, input_datetime, counter, timer, and schedule. Use to add a toggle/number/dropdown/text helper, a counter or timer, or a weekly schedule, and to list/rename/delete them. Creating a helper is a config operation (WebSocket), distinct from operating it (service call).

Control Home Assistant lights, switches, and fans with hass-cli: turn on/off, dim, set color or color temperature, set fan speed/oscillation. Use for any 'turn on the lights', 'dim to 30%', 'make it warm white', 'set fan to medium' style request. All control goes through service call.

Control Home Assistant media players with hass-cli: play/pause/stop, next/previous track, set volume, mute, select source, and play media. Use for 'pause the TV', 'set volume to 30%', 'play music in the kitchen', 'switch input to HDMI2' requests. All control goes through service call.

Send notifications and manage persistent notifications in Home Assistant with hass-cli: push messages to phones/devices via notify services, send TTS to speakers, and create/dismiss the dashboard's persistent notifications. Use for 'notify my phone', 'announce on the kitchen speaker', 'show a dashboard alert' requests.

Control Home Assistant covers, locks, valves, garage doors, and gates with hass-cli: open/close/stop covers, set position and tilt, lock/unlock, open/close valves. Use for 'open the blinds', 'close the garage', 'set shades to 50%', 'lock the front door' requests. All control goes through service call.

Work with Home Assistant presence and organization: people, zones, device trackers, and groups with hass-cli. Use to see who is home, check a person's location/zone, list zones, set a device_tracker's location, and read group membership for presence-based automations.

Create, edit, and run Home Assistant automations, scripts, and scenes with hass-cli. Use to list/get/save/delete automations, reload them, trigger them manually, or build a new automation from triggers/conditions/actions. Config writes go through the REST config editor; reload/trigger go through services.

Call Home Assistant services to control devices and trigger actions with hass-cli. Use to turn lights on/off, set climate, open covers, play media, run any domain.service. Covers discovering services (service list/describe) and calling them (service call) with --arguments and --data, including targeting by entity/device/area.

Playbook for auditing a Home Assistant instance for tech debt with hass-cli: dead/unavailable entities, duplicate entities, broken automations referencing missing entities, and unused automations. Use when the user asks to 'clean up', 'find broken/unused automations', 'find dead entities', or 'audit my setup'. These are derived analyses (not native HA features) computed from native data.

Playbook for generating a Home Assistant automation from a natural-language request with hass-cli. Use when the user says 'create an automation that...', 'when X happens do Y', 'automate my lights', or wants a new automation/script/scene built and installed. Orchestrates: gather context -> generate config -> save -> reload -> verify.