This script allows you to rename entities in your Home Assistant setup using the command line interface.

• Installation
• Usage
• Custom Format Variables
• Examples
• License

To use this script, you need to have Home Assistant CLI installed (and configured!)

# pipx
pipx install homeassistant-cli

# regular pip
pip install --user homeassistant-cli

Then, download the hass-rename-entites.sh script and make it executable:

chmod +x hass-rename-entites.sh

You can use the script with various options:

./hass-rename-entites.sh [options]

Options:

• -h, --help: Display this help message
• -D, --debug: Enable debug mode
• -k, --dry-run, --dryrun: Enable dry run mode
• -n, --no-restart: Do not restart Home Assistant after renaming the entities
• --watchman: Generate a new watchman report after renaming the entities"
• -P, --patch-config-files: Patch config files after renaming the entities (sed and replace on all files in ${HASS_CONFIG_DIR:-/config})
• -i, --integration <integration>: Filter by integration
• -m, --manufacturer <manufacturer>: Filter by manufacturer
• --only-named, --named-only: Only consider named devices
• --device-filter, --df, -f <filter>: Filter devices by a custom string
• --entity-filter, --ef, -e <filter>: Filter entities by a custom string
• -F, --format <format>: Specify a custom name format
• --strip-purpose, --sp <string>: Strip a custom string from the entity's purpose
• -p, --prefix <prefix>: Specify a custom prefix

hass-cli -o yaml device list

When specifying a custom format using the -F or --format flag, you can use several variables that will be replaced by their respective values. Here is a list of these variables:

• ${ENTITY_TYPE}: The type of the entity (e.g., light, switch, sensor, etc.).
• ${INTEGRATION}: The integration to which the entity belongs (e.g., hue, homekit, etc.).
• ${DEVICE_AREA_ID}: Area ID of the device.
• ${AREA_ID}: Area ID of the entity (defaults to DEVICE_AREA_ID if not set).
• ${SLUG_DEVICE_NAME}: The "slugified" version of the device name. This is a URL-friendly version of the name where spaces are replaced with underscores and special characters are removed.
• ${SLUG_OG_NAME_PURPOSE}: The "slugified" version of the original name of the entity, with the device name removed. This typically leaves the purpose or role of the entity (e.g., temperature, motion, etc.).
• ${SLUG_ENTITY_FRIENDLY_NAME}: The "slugified" version of the entity's friendly name. This is the name that you see in the Home Assistant UI.
• ${SLUG_OG_DEVICE_NAME}: The "slugified" version of the original device name.
• ${SLUG_OG_NAME}: The "slugified" version of the original name of the entity.
• ${SLUG_OG_NAME_LAST_WORD}: The "slugified" version of the last word in the original name.
• ${SLUG_PREFIX}: The "slugified" version of the prefix provided using the -p or --prefix flag.
• ${SLUG_PLATFORM}: The "slugified" version of the platform to which the entity belongs.

The default format is the following:

${ENTITY_TYPE,,}.${SLUG_PREFIX}${SLUG_PLATFORM}_${SLUG_DEVICE_NAME}_${SLUG_OG_NAME_PURPOSE}

Here are some examples showing how to use the script:

To only rename devices that have a name:

./hass-rename-entites.sh --dry-run --named-only

To only rename entities from a specific integration and specify a custom format:

./hass-rename-entites.sh --dry-run \
  --named-only \
  -i bluetooth \
  --format '${ENTITY_TYPE}.ble_${SLUG_DEVICE_NAME}_${SLUG_OG_NAME_PURPOSE}' \
  --strip-purpose ble

To only rename entities from a specific manufacturer:

./hass-rename-entites.sh --dry-run -m switchbot

To only rename entities from a specific integration and device:

./hass-rename-entites.sh --dry-run \
  -i hue \
  --device-filter 'motion' \
  --format '${ENTITY_TYPE}.${INTEGRATION}_${SLUG_DEVICE_NAME}_${SLUG_OG_NAME_PURPOSE}'

To only rename entities from a specific integration and entity type:

./hass-rename-entites.sh --dry-run \
  -i hue \
  --device-filter 'light' \
  --entity-filter "^light." \
  --format '${ENTITY_TYPE}.${INTEGRATION}_${SLUG_DEVICE_NAME}'

To only rename entities from a specific integration and entity type (not starting with "light."):

./hass-rename-entites.sh --dry-run \
  -i hue \
  --device-filter 'light' \
  --entity-filter '^(?!light\.)' \
  --format '${ENTITY_TYPE}.${INTEGRATION}_${SLUG_DEVICE_NAME}_${SLUG_OG_NAME_PURPOSE}'

To only rename entities from a specific integration and entity type (excluding "light."):

./hass-rename-entites.sh --dry-run \
  -i hue \
  --entity-filter '^(?!light\.)' \
  --format '${ENTITY_TYPE}.${INTEGRATION}_${SLUG_DEVICE_NAME}_${SLUG_OG_NAME_PURPOSE}'

To rename HomeKit devices (excluding presence sensors):

./hass-rename-entites.sh --dry-run \
  -i homekit \
  --device-filter '^(?!.+ presence sensor)' \
  --format '${ENTITY_TYPE}.${INTEGRATION}_${SLUG_DEVICE_NAME}_${SLUG_OG_NAME_PURPOSE}'

To rename HomeKit presence sensors:

./hass-rename-entites.sh --dry-run \
  -i homekit \
  --device-filter '.+ presence sensor' \
  --entity-filter "^binary_sensor\..+" \
  --format '${ENTITY_TYPE}.${INTEGRATION}_${SLUG_DEVICE_NAME}_${SLUG_ENTITY_FRIENDLY_NAME//presence_/}'

To rename Shelly devices:

./hass-rename-entites.sh --dry-run \
  -m Shelly \
  --format '${ENTITY_TYPE}.shelly_${SLUG_DEVICE_NAME}$(sed -r "s/^(.+)/_\1/" <<< "${SLUG_OG_NAME_PURPOSE}")'

To rename Yeelight devices:

hass-rename-entites.sh --dry-run \
  -i yeelight \
  --format '${ENTITY_TYPE}.${INTEGRATION}_${SLUG_DEVICE_NAME}'

To rename ZHA devices:

hass-rename-entites.sh --dry-run \
  --named-only \
  -i zha \
  --format '${ENTITY_TYPE}.${INTEGRATION}_${SLUG_DEVICE_NAME}_${SLUG_OG_NAME_PURPOSE}'

This project is licensed under the GPL-3.0 License.