zigporter 0.1.0

CLI tool to migrate Zigbee devices from ZHA to Zigbee2MQTT in Home Assistant

zigporter

Because migrating 30 Zigbee devices in Home Assistant by hand is a special kind of misery.

CLI tool that automates the ZHA → Zigbee2MQTT migration in Home Assistant — one device at a time, with checkpoints so you can stop and pick up where you left off.

Early Development Notice This tool is in early development and has only been tested with one specific setup:

• Home Assistant OS 2026.2.3
• Supervisor 2026.02.2
• Zigbee2MQTT 2.8.0-1

I have not had the possibility to test with different HA or Z2M versions and setups. Feedback is very welcome — please open an issue or submit a PR if you test with a different configuration.

Early Development Notice This tool is in early development and has only been tested with one specific setup:

• Home Assistant OS 2026.2.3
• Supervisor 2026.02.2
• Zigbee2MQTT 2.8.0-1

I have not had the possibility to test with different HA or Z2M versions and setups. Feedback is very welcome — please open an issue or submit a PR if you test with a different configuration.

Requirements

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

Installation

uv tool install zigporter

Configuration

Option 1 — Setup wizard (recommended)

zigporter setup

Prompts for all values and saves to ~/.config/zigporter/.env.

Option 2 — Manual config file

Create ~/.config/zigporter/.env (see .env.example for the template):

mkdir -p ~/.config/zigporter
cp .env.example ~/.config/zigporter/.env
# edit the file with your values

Option 3 — Environment variables

Export directly in your shell or add to ~/.zshenv / ~/.bashrc:

export HA_URL=https://your-ha-instance.local
export HA_TOKEN=your_token
export Z2M_URL=https://your-ha-instance.local/abc123_zigbee2mqtt

Variable	Required	Description
HA_URL	Yes	Home Assistant URL
HA_TOKEN	Yes	Long-Lived Access Token
HA_VERIFY_SSL	No	true / false (default: true; use false for self-signed certs)
Z2M_URL	Yes	Zigbee2MQTT ingress URL
Z2M_MQTT_TOPIC	No	Z2M base topic (default: zigbee2mqtt)

Usage

# Verify your setup before migrating (recommended first step)
zigporter check

# Run the migration wizard (runs checks automatically on first run)
zigporter migrate

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

# (Optional) manually export your ZHA device inventory
zigporter export

# (Optional) inspect what's already in Z2M
zigporter list-z2m

zigporter migrate handles everything automatically on first run:

1. Runs pre-flight checks (HA reachable, ZHA active, Z2M running)
2. Prompts you to back up Home Assistant and your ZHA network
3. Fetches a ZHA export if one is not found, or offers to refresh an existing one
4. Opens the interactive migration wizard

All files are stored in ~/.config/zigporter/ so the tool works from any directory. Use --skip-checks on subsequent runs to skip the pre-flight checks.

How it works

The wizard migrates one device at a time through five steps:

1. Remove from ZHA — confirms deletion in the HA registry
2. Reset device — prompts you to factory-reset the physical device
3. Pair with Z2M — opens a 120 s permit-join window and polls by IEEE address
4. Rename — applies the original ZHA name and area in Z2M and HA
5. Validate — polls HA entity states until all are online

State is written to zha-migration-state.json after every step. Ctrl-C marks the device FAILED — rerun to retry.

See the wiki for detailed diagrams and architecture docs.

Development

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

License

MIT — see LICENSE.