{"id":45887063,"url":"https://github.com/nordstad/zigporter","last_synced_at":"2026-03-04T21:00:45.839Z","repository":{"id":340871283,"uuid":"1167049347","full_name":"nordstad/zigporter","owner":"nordstad","description":"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.","archived":false,"fork":false,"pushed_at":"2026-03-03T21:35:40.000Z","size":1739,"stargazers_count":0,"open_issues_count":1,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-03T21:43:45.934Z","etag":null,"topics":["home-assistant","zha","zigbee2mqtt"],"latest_commit_sha":null,"homepage":"https://nordstad.github.io/zigporter/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nordstad.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-25T22:21:08.000Z","updated_at":"2026-03-03T21:35:44.000Z","dependencies_parsed_at":"2026-03-03T20:00:48.200Z","dependency_job_id":null,"html_url":"https://github.com/nordstad/zigporter","commit_stats":null,"previous_names":["nordstad/zigporter"],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/nordstad/zigporter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nordstad%2Fzigporter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nordstad%2Fzigporter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nordstad%2Fzigporter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nordstad%2Fzigporter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nordstad","download_url":"https://codeload.github.com/nordstad/zigporter/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nordstad%2Fzigporter/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30092854,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-04T20:42:30.420Z","status":"ssl_error","status_checked_at":"2026-03-04T20:42:30.057Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["home-assistant","zha","zigbee2mqtt"],"created_at":"2026-02-27T16:17:12.597Z","updated_at":"2026-03-04T21:00:45.806Z","avatar_url":"https://github.com/nordstad.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# zigporter\n\n[![CI](https://github.com/nordstad/zigporter/actions/workflows/ci.yml/badge.svg)](https://github.com/nordstad/zigporter/actions/workflows/ci.yml)\n[![codecov](https://codecov.io/gh/nordstad/zigporter/branch/main/graph/badge.svg)](https://codecov.io/gh/nordstad/zigporter)\n[![Documentation](https://img.shields.io/badge/docs-zensical-blue)](https://nordstad.github.io/zigporter)\n[![PyPI - Version](https://img.shields.io/pypi/v/zigporter?label=PyPI)](https://pypi.org/project/zigporter/)\n[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![PyPI Downloads](https://static.pepy.tech/personalized-badge/zigporter?period=total\u0026units=INTERNATIONAL_SYSTEM\u0026left_color=BLACK\u0026right_color=GREEN\u0026left_text=downloads)](https://pepy.tech/projects/zigporter)\n\nHome Assistant device management from the command line — migrate from ZHA to Zigbee2MQTT,\nrename entities and devices with full cascade across automations, scripts, and dashboards.\n\n\u003e **Early Development** — Tested with HA OS 2026.2.3 · Supervisor 2026.02.2 · Z2M 2.8.0-1.\n\u003e Open an [issue](https://github.com/nordstad/zigporter/issues) if you run a different configuration.\n\n## Try it\n\n**[Interactive Demo →](https://nordstad.github.io/zigporter/interactive-demo/)** — see every command in action before installing.\n\n## Features\n\n\u003ctable\u003e\n  \u003cthead\u003e\n    \u003ctr\u003e\u003cth\u003eCommand\u003c/th\u003e\u003cth\u003eDescription\u003c/th\u003e\u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n    \u003ctr\u003e\u003ctd nowrap\u003e\u003ccode\u003emigrate\u003c/code\u003e\u003c/td\u003e\u003ctd\u003eInteractive wizard: remove from ZHA → factory reset → pair with Z2M → restore names, areas, and entity IDs\u003c/td\u003e\u003c/tr\u003e\n    \u003ctr\u003e\u003ctd nowrap\u003e\u003ccode\u003erename\u0026#x2011;entity\u003c/code\u003e\u003c/td\u003e\u003ctd\u003eRename a HA entity ID and cascade the change across automations, scripts, scenes, and all Lovelace dashboards\u003c/td\u003e\u003c/tr\u003e\n    \u003ctr\u003e\u003ctd nowrap\u003e\u003ccode\u003erename\u0026#x2011;device\u003c/code\u003e\u003c/td\u003e\u003ctd\u003eRename any HA device by name and cascade the change to all its entities and references\u003c/td\u003e\u003c/tr\u003e\n    \u003ctr\u003e\u003ctd nowrap\u003e\u003ccode\u003echeck\u003c/code\u003e\u003c/td\u003e\u003ctd\u003eVerify HA and Z2M connectivity before making changes\u003c/td\u003e\u003c/tr\u003e\n    \u003ctr\u003e\u003ctd nowrap\u003e\u003ccode\u003einspect\u003c/code\u003e\u003c/td\u003e\u003ctd\u003eShow a device's current state across ZHA, Z2M, and the HA registry\u003c/td\u003e\u003c/tr\u003e\n    \u003ctr\u003e\u003ctd nowrap\u003e\u003ccode\u003eexport\u003c/code\u003e\u003c/td\u003e\u003ctd\u003eSnapshot your ZHA device inventory to JSON\u003c/td\u003e\u003c/tr\u003e\n    \u003ctr\u003e\u003ctd nowrap\u003e\u003ccode\u003elist\u0026#x2011;z2m\u003c/code\u003e\u003c/td\u003e\u003ctd\u003eList all devices currently paired with Zigbee2MQTT\u003c/td\u003e\u003c/tr\u003e\n    \u003ctr\u003e\u003ctd nowrap\u003e\u003ccode\u003efix\u0026#x2011;device\u003c/code\u003e\u003c/td\u003e\u003ctd\u003ePost-migration cleanup: remove stale ZHA device entries, delete their entities, and rename any \u003ccode\u003e_2\u003c/code\u003e/\u003ccode\u003e_3\u003c/code\u003e suffixed Z2M entities back to their original IDs\u003c/td\u003e\u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\n## Requirements\n\n- Python 3.12+\n- [uv](https://docs.astral.sh/uv/)\n- Home Assistant with the Zigbee2MQTT add-on\n\n## Installation\n\n```bash\nuv tool install zigporter\n```\n\nOr with pip:\n\n```bash\npip install zigporter\n```\n\n## Configuration\n\nRun the setup wizard to get started:\n\n```bash\nzigporter setup\n```\n\nThis prompts for all required values and saves them to `~/.config/zigporter/.env`.\n\nYou can also set environment variables directly or create the file manually:\n\n| Variable | Required | Description |\n|---|---|---|\n| `HA_URL` | Yes | Home Assistant base URL |\n| `HA_TOKEN` | Yes | [Long-Lived Access Token](https://www.home-assistant.io/docs/authentication/#your-account-profile) |\n| `HA_VERIFY_SSL` | No | `true` (default) or `false` for self-signed certificates |\n| `Z2M_URL` | For `migrate` / `list-z2m` / `rename-device` | Zigbee2MQTT ingress URL |\n| `Z2M_MQTT_TOPIC` | No | Z2M base MQTT topic (default: `zigbee2mqtt`) |\n\nSee [Configuration](https://nordstad.github.io/zigporter/getting-started/configuration/) for full details.\n\n## Migrate ZHA → Zigbee2MQTT\n\n```bash\n# Verify connectivity first\nzigporter check\n\n# Run the migration wizard\nzigporter migrate\n```\n\n\u003e **Back up first** — The migration wizard removes devices from ZHA and makes changes to\n\u003e entity IDs, automations, and dashboards that are difficult to reverse. Before running,\n\u003e [back up your Home Assistant configuration](https://www.home-assistant.io/common-tasks/os/#backups).\n\u003e This tool is provided **as-is** with no warranty. Use at your own risk.\n\nOn the first non-status run, `zigporter` requires a one-time backup confirmation and stores\nthat acknowledgement in `~/.config/zigporter/.backup-confirmed`.\n\nThe wizard guides you through each device one at a time:\n\n1. Remove from ZHA — polls the HA registry until the device is gone\n2. Factory reset — prompts to clear the old pairing on the physical device\n3. Pair with Z2M — opens a 300 s permit-join window and polls by IEEE address\n4. Rename — restores the original ZHA name and area in Z2M and HA\n5. 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\n6. Review — shows all Lovelace cards referencing the device\n7. 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\n\nProgress is saved after every step. Press `Ctrl-C` to pause; rerun to resume.\n\n```bash\n# Check progress without entering the wizard\nzigporter migrate --status\n```\n\n## Fix a Previously Migrated Device\n\nIf you migrated a device before the suffix-conflict fix was added, or if stale ZHA entries\nwere left behind, use `fix-device` to clean them up:\n\n```bash\nzigporter fix-device\n```\n\nThe command scans HA for devices that have both a stale ZHA entry and an active Z2M entry,\nlets you pick one, deletes the stale ZHA entities, removes the ZHA device from the registry,\nand renames any `_2`/`_3` suffixed Z2M entities back to their original IDs so dashboard\ncards work again.\n\n## Rename an Entity\n\nRename a Home Assistant entity ID and automatically update every reference — automations,\nscripts, scenes, and Lovelace dashboards:\n\n```bash\n# Preview changes (dry run)\nzigporter rename-entity light.living_room_1 light.living_room_ceiling\n\n# Apply the rename\nzigporter rename-entity light.living_room_1 light.living_room_ceiling --apply\n```\n\nWithout `--apply` the command shows a full diff and prompts for confirmation before writing.\n\n\u003e **Note:** Jinja2 template expressions (`{{ states('old.id') }}`) are not patched automatically — review them after renaming.\n\n## Rename a Device\n\nRename any Home Assistant device by name and cascade the change to all its entities and\nreferences in HA. Supports partial name matching:\n\n```bash\n# Preview changes (dry run)\nzigporter rename-device \"Living Room 1\" \"Living Room Ceiling\"\n\n# Apply the rename\nzigporter rename-device \"Living Room 1\" \"Living Room Ceiling\" --apply\n```\n\nIf `Z2M_URL` is configured and the device is managed by Zigbee2MQTT, the command also\noffers to rename the Z2M friendly name in a separate prompt — so you stay in control of\nwhether HA and Z2M names are kept in sync.\n\n## Development\n\n```bash\nuv sync --dev\nuv run pytest\nuv run ruff check .\nuv run ruff format .\n```\n\nSee [Development](https://nordstad.github.io/zigporter/development/) for architecture details and contribution guidelines.\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnordstad%2Fzigporter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnordstad%2Fzigporter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnordstad%2Fzigporter/lists"}