Ha Integrations

ha-integrations

Config entries are the runtime instances of integrations. Prerequisite: ../ha-shared/SKILL.md.

List/get/update/enable/disable go over WebSocket; reload and delete are REST-only config endpoints. The CLI routes both for you.

List & inspect

hass-cli integration list                       # all config entries
hass-cli integration list --domain hue          # only one integration's entries
hass-cli integration get <entry_id>

Key fields per entry: entry_id, domain, title, state (loaded/setup_retry/setup_error/not_loaded/...), disabled_by, reason (why it failed), source (how it was set up).

Find broken integrations:

hass-cli integration list -o json | rg -B2 -A2 '"state": "setup_(error|retry)"'

Lifecycle

hass-cli integration reload  <entry_id>         # re-run setup (no restart)
hass-cli integration disable <entry_id>         # stop loading it
hass-cli integration enable  <entry_id>
hass-cli integration delete  <entry_id>         # remove the entry entirely

reload/disable/delete return {"require_restart": ...}; if true, the change needs a Home Assistant restart to fully apply.

Update entry preferences

hass-cli integration update <entry_id> --data '{"title":"Living Room Hue","pref_disable_polling":true}'

Updatable fields: title, pref_disable_new_entities, pref_disable_polling. Per-integration options (the options flow) are interactive multi-step and are not exposed as a single command; drive them with raw ws against config_entries/options/flow if needed.

Add an integration (config flow)

Adding an integration is a schema-driven, multi-step flow. Drive it with integration flow:

hass-cli integration flow handlers --type helper    # what can be set up
hass-cli integration flow start <domain>            # begin; returns the first step
hass-cli integration flow get <flow_id>             # re-read a flow's current step
hass-cli integration flow step <flow_id> --data '{...}'   # submit each step's input
hass-cli integration flow abort <flow_id>           # cancel

Each step response has a type:

• form — fill data_schema fields, submit with step. last_step hints it's the final one. errors is populated on validation failure (re-submit).
• menu — submit {"next_step_id":"<one of menu_options>"}.
• create_entry — done; result.entry_id is the new config entry.
• abort — flow ended early; reason says why.
• external_step — needs a browser (e.g. OAuth); not CLI-friendly.

Worked example (the random helper integration):

ID=$(hass-cli integration flow start random -o json | jq -r .flow_id)
hass-cli integration flow step $ID --data '{"next_step_id":"sensor"}'   # menu -> form
hass-cli integration flow step $ID --data '{"name":"My Random"}'         # -> create_entry

OAuth / hub integrations that need a browser redirect (external_step) can't be completed from the CLI. Helper and local integrations work fully.

Discovery & in-progress flows

Discovered devices (bluetooth/zeroconf/dhcp/ssdp/usb/...) surface as in-progress config flows:

hass-cli integration flow progress      # discovered + awaiting-input flows
hass-cli integration flow ignore <flow_id>   # stop suggesting a discovery
hass-cli raw ws usb/scan                 # trigger a USB rescan

To set up a discovered device, take its flow_id from flow progress and drive it with integration flow step (it already has a started flow).

For radio gateways (ZHA / Z-Wave JS / Matter / Thread), this skill covers the integration's lifecycle. Protocol-layer operations — pairing a Zigbee device, joining a Z-Wave node, network backups, Matter commissioning, Thread datasets — are in ../ha-gateway/SKILL.md.