https://github.com/pschmitt/hass-rename-entities
Home Assistant CLI script to rename entities in bulk
https://github.com/pschmitt/hass-rename-entities
hass home-assistant renamer
Last synced: 2 months ago
JSON representation
Home Assistant CLI script to rename entities in bulk
- Host: GitHub
- URL: https://github.com/pschmitt/hass-rename-entities
- Owner: pschmitt
- License: gpl-3.0
- Created: 2023-07-28T21:05:51.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-01-12T08:25:21.000Z (over 1 year ago)
- Last Synced: 2024-05-17T00:11:11.498Z (11 months ago)
- Topics: hass, home-assistant, renamer
- Language: Shell
- Homepage:
- Size: 73.2 KB
- Stars: 11
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 🚀 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](#-installation)
- [Usage](#-usage)
- [Custom Format Variables](#-custom-format-variables)
- [Examples](#-examples)
- [License](#-license)
## 🎉 Installation
To use this script, you need to have [Home Assistant CLI](https://github.com/home-assistant-ecosystem/home-assistant-cli)
installed (and configured!)
```bash
# pipx
pipx install homeassistant-cli
# regular pip
pip install --user homeassistant-cli
```
Then, download the `hass-rename-entites.sh` script and make it executable:
```bash
chmod +x hass-rename-entites.sh
```
## 💡 Usage
You can use the script with various options:
```bash
./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](https://github.com/dummylabs/thewatchman) 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 `: Filter by integration
- `-m, --manufacturer `: Filter by manufacturer
- `--only-named, --named-only`: Only consider named devices
- `--device-filter, --df, -f `: Filter devices by a custom string
- `--entity-filter, --ef, -e `: Filter entities by a custom string
- `-F, --format `: Specify a custom name format
- `--strip-purpose, --sp `: Strip a custom string from the entity's purpose
- `-p, --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:
>
> ```shell
> 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:
```bash
${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](#rename-shelly-devices)).
## 🎈 Examples
Here are some examples showing how to use the script:
### Only Rename Named Devices
To only rename devices that have a name:
```bash
./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:
```bash
./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:
```bash
./hass-rename-entites.sh --dry-run -m switchbot
```
### Filter by Integration and Device
To only rename entities from a specific integration and device:
```bash
./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:
```bash
./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."):
```bash
./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."):
```bash
./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):
```bash
./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:
```bash
./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:
```bash
./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:
```bash
hass-rename-entites.sh --dry-run \
-i yeelight \
--format '${ENTITY_TYPE}.${INTEGRATION}_${SLUG_DEVICE_NAME}'
```
### Rename ZHA Devices
To rename ZHA devices:
```bash
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](./LICENSE).