zigporter 0.3.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.

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.

Try it

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

Features

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

Requirements

• Python 3.12+
• uv
• Home Assistant with the Zigbee2MQTT add-on

Installation

uv tool install zigporter

Or with pip:

pip install zigporter

Configuration

Run the setup wizard to get started:

zigporter setup

This prompts for all required values and saves them to ~/.config/zigporter/.env.

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	For migrate / list-z2m / rename-device	Zigbee2MQTT ingress URL
Z2M_MQTT_TOPIC	No	Z2M base MQTT topic (default: zigbee2mqtt)

See Configuration for full details.

Migrate ZHA → Zigbee2MQTT

# Verify connectivity first
zigporter check

# Run the migration wizard
zigporter migrate

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.

On the first non-status run, zigporter requires a one-time backup confirmation and stores that acknowledgement in ~/.config/zigporter/.backup-confirmed.

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.

Rename an Entity

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

# 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.

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:

# 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.