🚀 Home Assistant CLI Rename Entities Script

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

📚 Table of Contents

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

🎉 Installation

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

💡 Usage

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

Note

To inspect what the exact manufacturer or integration values are for your specific devices the easiest way is to run:

hass-cli -o yaml device list

📝 Custom Format Variables

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}

Note

Remember that "slugification" is a process that transforms a string into a URL-friendly format by replacing spaces with underscores, converting all letters to lowercase, and removing special characters. It helps avoiding to attempt to set invalid entity id names.

Note

The format value gets passed through eval, so you can just provide arbitrary code (sed/awk for example - see below for an example).

🎈 Examples

Here are some examples showing how to use the script:

Only Rename Named Devices

To only rename devices that have a name:

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

Filter by Integration and Specify Custom Format

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

Filter by Manufacturer

To only rename entities from a specific manufacturer:

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

Filter by Integration and Device

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}'

Filter by Integration and Entity Type

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}'

Filter by Integration and Entity Type with Negative Lookahead

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}'

Filter by Integration and Entity Type (Excluding Light)

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}'

Rename HomeKit Devices (Except Presence Sensors)

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}'

Rename HomeKit Presence Sensors

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_/}'

Rename Shelly Devices

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}")'

Rename Yeelight Devices

To rename Yeelight devices:

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

Rename ZHA Devices

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}'

📜 License

This project is licensed under the GPL-3.0 License.