zigporter¶

CLI toolkit for Home Assistant Zigbee — migrate ZHA → Z2M, cascade-rename entities and devices, and map your mesh.

Try it before you run it — Interactive demo → walks through a full ZHA → Z2M migration with simulated devices, right in your browser.

Network map example → — network-map generates a radial SVG diagram of your Zigbee mesh with LQI-coloured edges and per-device signal badges.

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
`stale`	Scan all integrations for offline devices and interactively remove, annotate, or ignore them
`network‑map`	Generate a radial SVG diagram of your Zigbee mesh with LQI-coloured edges, hop rings, and per-device signal badges — or print a routing tree and signal table to the terminal

Claude Code skills¶

If you open the repo in Claude Code, additional slash-command skills are available on top of the CLI:

Skill	Description
`/smart-rename`	Audit all Z2M device names against a convention, get AI-suggested corrections, and apply only the ones you approve

Installation¶

uv tool install zigporter

Quick start¶

Migrate ZHA → Zigbee2MQTT¶

zigporter setup   # configure credentials once
zigporter check   # verify connectivity
zigporter migrate # start the interactive wizard

Rename an entity¶

# Preview what would change
zigporter rename-entity light.old_name light.new_name

# Apply the rename
zigporter rename-entity light.old_name light.new_name --apply

Rename a device¶

zigporter rename-device "Old Device Name" "New Device Name" --apply

Find offline devices¶

zigporter stale

See Installation and Configuration to get set up.