Skip to main content

ha-link

A small CLI tool for managing Home Assistant custom integration development against a single HA core clone.

Instead of maintaining one HA core clone per integration, ha-link symlinks your selected integrations into the core's custom_components/ directory so you can switch between them with an interactive picker.

Edits to your integration source are reflected immediately in the running HA instance — no copying needed.

Requirements

Install

pip install ha-link
# or
uv tool install ha-link

First run

Run ha-link with no arguments. If no config is found, a short wizard guides you through setting the core path and registering your first integration repo:

No HA core path configured yet.
? Path to your HA core repo: ~/Developer/homeassistant/core
Core set to: /home/you/Developer/homeassistant/core

No integrations registered yet.
? Add your first integration repo now? Yes
? Path to the integration repo: ~/Developer/my-integration
? Alias for this integration: my-integration
Registered 'my-integration' (my_integration)

Usage

ha-link                      # interactive picker → sync symlinks
ha-link list                 # show all registered repos and their link status
ha-link add <path>           # register a new integration repo
ha-link remove <alias>       # unregister a repo (existing symlink not removed)
ha-link set-core <path>      # change the HA core path

Picker

Running ha-link with no arguments opens an interactive checkbox. Use arrow keys and space to toggle, enter to confirm. Already-linked integrations are pre-checked.

? Select integrations to activate:
 ❯ ◉ my-integration    (my_integration)
   ◯ another-one       (another_integration)

Adding a new integration

Point ha-link add at the repo root. It auto-detects the integration domain from custom_components/<domain>/manifest.json and prompts for an alias.

ha-link add ~/Developer/my-new-integration
# ? Alias for this integration: [my-new-integration] my-new-integration
# Registered 'my-new-integration' (my_new_integration)

If ha-link list finds symlinks in custom_components/ that aren't registered, it marks them with [?] and offers to adopt them:

  [✓] my-integration       my_integration    ~/Developer/my-integration
  [?] (unregistered)       old_integration   ~/Developer/old-integration

Config

Config lives at ~/.config/ha-link/config.toml. You can edit it directly.

[core]
path = "/home/you/Developer/homeassistant/core"

[[repos]]
alias = "my-integration"
path = "/home/you/Developer/my-integration"

[[repos]]
alias = "another-one"
path = "/home/you/Developer/another-integration"

Each repo must contain a custom_components/<domain>/manifest.json. Symlinks are created at {core}/config/custom_components/<domain> if that directory exists (HA's built-in dev config), otherwise at {core}/custom_components/<domain>.

Metadata

Release files for ha-link 0.1.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ha-link 0.1.2
File Size Uploaded Provenance Actions
ha_link-0.1.2.tar.gz 7.4 kB With provenance Details for ha_link-0.1.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ha-link 0.1.2
File Interpreter ABI Platform Actions
ha_link-0.1.2-py3-none-any.whl Python 3 none any Details for ha_link-0.1.2-py3-none-any.whl

Total release size: 13.9 kB

Security for ha-link 0.1.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.2 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page