zigporter 0.6.0

CLI toolkit for Zigbee device management in Home Assistant: migrate from ZHA to Zigbee2MQTT, rename entities, and fix stale registry entries

zigporter

Home Assistant device management from the command line — migrate from ZHA to Zigbee2MQTT,
rename entities and devices with full cascade across automations, scripts, and dashboards.

Features

Interactive Demo → — see every command in action before installing.

Command	Description
migrate	Interactive wizard: remove from ZHA → factory reset → pair with Z2M → restore names, areas, and entity IDs
rename‑entity	Rename a HA entity ID and cascade the change across automations, scripts, scenes, and all Lovelace dashboards
rename‑device	Rename any HA device by name and cascade the change to all its entities and references
check	Verify HA and Z2M connectivity before making changes
inspect	Show a device's current state across ZHA, Z2M, and the HA registry
export	Snapshot your ZHA device inventory to JSON
list‑z2m	List all devices currently paired with Zigbee2MQTT
fix‑device	Post-migration cleanup: remove stale ZHA device entries, delete their entities, and rename any _2/_3 suffixed Z2M entities back to their original IDs
stale	Scan all integrations for offline devices and interactively remove, annotate, or ignore them

---

[!NOTE] Early Development — Tested with HA OS 2026.2.3 · Supervisor 2026.02.2 · Z2M 2.8.0-1. Open an issue if you run a different configuration.

---

Installation

uv tool install zigporter

Or with pip:

pip install zigporter

Configuration

Run the setup wizard to get started:

zigporter setup

This prompts for HA credentials (required) and Zigbee2MQTT settings (optional — only needed for migrate and list-z2m).

You can also set environment variables directly or create the file manually:

Variable	Required	Description
HA_URL	Yes	Home Assistant base URL
HA_TOKEN	Yes	Long-Lived Access Token
HA_VERIFY_SSL	No	true (default) or false for self-signed certificates
Z2M_URL	Only for migrate and list-z2m	Zigbee2MQTT ingress URL
Z2M_MQTT_TOPIC	Only for migrate and list-z2m	Z2M base MQTT topic (default: zigbee2mqtt)

See Configuration for full details.

Migrate ZHA → Zigbee2MQTT

---

[!WARNING] Back up first — The migration wizard removes devices from ZHA and makes changes to entity IDs, automations, and dashboards that are difficult to reverse. Before running, back up your Home Assistant configuration. This tool is provided as-is with no warranty. Use at your own risk.

---

# Verify connectivity first
zigporter check

# Run the migration wizard
zigporter migrate

The wizard guides you through each device one at a time:

1. Remove from ZHA — polls the HA registry until the device is gone
2. Factory reset — prompts to clear the old pairing on the physical device
3. Pair with Z2M — opens a 300 s permit-join window and polls by IEEE address
4. Rename — restores the original ZHA name and area in Z2M and HA
5. Restore entity IDs — renames IEEE-hex entity IDs back to friendly names; detects _2/_3 suffix conflicts caused by stale ZHA entries and offers to delete them and rename the Z2M entities back to their original IDs
6. Review — shows all Lovelace cards referencing the device
7. Validate — polls HA entity states until all entities come online; offers a "Reload Z2M integration" option to force-refresh sensor state without leaving the CLI

Progress is saved after every step. Press Ctrl-C to pause; rerun to resume.

# Check progress without entering the wizard
zigporter migrate --status

Fix a Previously Migrated Device

If you migrated a device before the suffix-conflict fix was added, or if stale ZHA entries were left behind, use fix-device to clean them up:

zigporter fix-device

The command scans HA for devices that have both a stale ZHA entry and an active Z2M entry, lets you pick one, deletes the stale ZHA entities, removes the ZHA device from the registry, and renames any _2/_3 suffixed Z2M entities back to their original IDs so dashboard cards work again.

Find and Clean Up Offline Devices

Scan HA for devices whose entities are all unavailable or unknown:

zigporter stale

The command lists every offline device grouped as New / Stale / Ignored. For each device you can:

• Remove — delete the entry from the HA registry
• Mark as stale — add a note and come back later
• Ignore — suppress devices you know are intentionally offline

Decisions persist across runs. Hub and gateway devices with active children (e.g. a Plejd GWY-01 whose lights are responsive) are automatically excluded to avoid false positives.

Rename an Entity

Rename a Home Assistant entity ID and automatically update every reference — automations, scripts, scenes, and Lovelace dashboards.

Both arguments are optional. Run with no arguments for a guided wizard:

# Interactive wizard — pick entity from a list, edit the new ID in-place
zigporter rename-entity

# Provide the old ID only — prompts for the new ID (pre-filled for editing)
zigporter rename-entity sensor.old_device_energy

# Preview changes (dry run)
zigporter rename-entity light.living_room_1 light.living_room_ceiling

# Apply the rename
zigporter rename-entity light.living_room_1 light.living_room_ceiling --apply

Without --apply the command shows a full diff and prompts for confirmation before writing. New entity IDs are validated against the domain.entity_name format before any changes are made.

Note: Jinja2 template expressions ({{ states('old.id') }}) are not patched automatically — review them after renaming.

Rename a Device

Rename any Home Assistant device by name and cascade the change to all its entities and references in HA. Supports partial name matching.

Both arguments are optional. Run with no arguments for a guided wizard:

# Interactive wizard — pick device from an area-grouped list, type the new name
zigporter rename-device

# Restrict the picker to Zigbee devices only (ZHA + Zigbee2MQTT)
zigporter rename-device --filter=zigbee

# Provide the old name only — prompts for the new name
zigporter rename-device "Living Room 1"

# Preview changes (dry run)
zigporter rename-device "Living Room 1" "Living Room Ceiling"

# Apply the rename
zigporter rename-device "Living Room 1" "Living Room Ceiling" --apply

If Z2M_URL is configured and the device is managed by Zigbee2MQTT, the command also offers to rename the Z2M friendly name in a separate prompt — so you stay in control of whether HA and Z2M names are kept in sync.

Development

uv sync --dev
uv run pytest
uv run ruff check .
uv run ruff format .

See Development for architecture details and contribution guidelines.

License

MIT — see LICENSE.