Home Assistant Ops

Use this skill as the operator's playbook for making bulk, reviewable changes to a Home Assistant instance without SSHing into the host.

Requires Node.js 22+ (uses built-in fetch

• WebSocket ; no npm deps).

Default workflow (plan -> apply -> validate)

• Inventory the current state (API) and/or registries (backup).

• Propose an explicit change set (entity_ids, names, automation ids, etc).

• Apply via API with validation (small batches, dry-run first).

• Smoke-test the specific behavior (traces + event tail).

• Record a timestamped log + a rollback mapping.

• (Optional) Snapshot before/after for diff/rollback.

Setup

Set environment variables (never pass tokens on the command line):

export HA_URL="http://<home-assistant-host>:8123" export HA_TOKEN="<long-lived-access-token>"

Run scripts using node :

node scripts/ha_ops.js --help

Keep logs in a working folder (scripts write timestamped .md files by default).

First questions (to avoid rework)

• What's the HA version and deployment type (OS / Container / Core)?

• Which Zigbee stack is used (ZHA vs Zigbee2MQTT) and which devices are affected?

• Which parts are YAML-managed vs UI-managed (automations, scripts, scenes, dashboards)?

• Do we have a recent backup to inspect before making bulk changes?

• Is the goal UI clarity, automation correctness, performance/latency, or all of the above?

Core concepts (what to change where)

• Entity registry: source of truth for friendly-name overrides, entity_id renames, hidden/disabled, and some area assignment.

• Device registry: best place to assign areas for physical devices (entity area often inherits).

• Blueprint inputs: not templatable; state triggers need a static entity list at config-load time.

• HA "group helpers": great for UI/targeting/maintenance, but they don't make Zigbee unicast faster (they expand to member calls).

Scripts

All scripts read HA_URL and HA_TOKEN from environment variables.

ha_ops.js

• Single CLI with subcommands

All operations are available under a single CLI:

List commands

node scripts/ha_ops.js --help

Command help

node scripts/ha_ops.js cleanup --help

ha_ops.js cleanup

• Bulk cleanup (dry-run by default)

Dry-run all default steps (default)

node scripts/ha_ops.js cleanup

Apply specific steps

node scripts/ha_ops.js cleanup --apply
--steps rename-switch-suffix,prefix-lights-cove

Prefix custom patterns with area names

node scripts/ha_ops.js cleanup --apply
--steps prefix-generic
--pattern "Thermometer:^Thermometer"
--pattern "Blinds:^Blinds"

Output proposed changes as JSON

node scripts/ha_ops.js cleanup --json

Available steps:

• rename-switch-suffix : Rename "Lights ... Switch" to "Lights ..."

• create-groups : Create/update switch groups for sync automations

• prefix-lights-cove : Prefix Lights/Cove names with area

• prefix-generic : Prefix entities matching --pattern with area

ha_ops.js snapshot

• Capture state for diffing

Full snapshot

node scripts/ha_ops.js snapshot

Skip noisy sections

node scripts/ha_ops.js snapshot
--no-lovelace --no-scenes

Include runtime states (noisy for diffs)

node scripts/ha_ops.js snapshot --include-states

ha_ops.js rollback

• Revert registry changes from a snapshot

Preview what would be rolled back

node scripts/ha_ops.js rollback
snapshot_before.json --dry-run

Apply rollback

node scripts/ha_ops.js rollback
snapshot_before.json --yes

ha_ops.js find-references

• Find entity_id usage

Search for entity references before renaming

node scripts/ha_ops.js find-references
--needle "switch.bedroom_lights"

Search from a rename mapping file

node scripts/ha_ops.js find-references
--map-json rename_map.json --backup-root /path/to/backup

ha_ops.js tail-events

• Monitor events in real-time

Tail state changes

node scripts/ha_ops.js tail-events

Filter to specific entities

node scripts/ha_ops.js tail-events
--entity switch.bedroom_lights --entity switch.bedroom_lights_2

Include ZHA events

node scripts/ha_ops.js tail-events
--event-type state_changed --event-type zha_event

ha_ops.js name-review-from-backup

• Offline naming analysis

Analyze backup for naming candidates

node scripts/ha_ops.js name-review-from-backup
--backup-root /path/to/backup

Error recovery

If a script fails mid-way:

• Check the log file for what was applied before the failure.

• Use ha_ops.js rollback with your before-snapshot to revert registry changes.

• Fix the underlying issue (network, permissions, entity conflicts).

• Re-run the script (operations are generally idempotent).

Resources

• API reference: references/api.md

• Ops playbook: references/playbook.md

• Entity ID conventions: references/id_conventions.md

Logging convention

Prefer one markdown log per run (timestamped), listing every entity/automation changed and the before/after values.