diff --git a/homeassistant/readme.md b/homeassistant/readme.md
new file mode 100644
index 0000000..e47ef2b
--- /dev/null
+++ b/homeassistant/readme.md
@@ -0,0 +1,67 @@
+# Home Assistant CLI Scripts
+
+A small collection of Bash scripts for controlling Home Assistant devices from the command line.
+
+The scripts use the Home Assistant REST API and expect a `.env` file containing your server URL and long-lived access token.
+
+## Light Control
+
+`light.sh` controls both dimmable lights and basic on/off lights.
+
+### Dimmable lights
+
+Set brightness from `0` to `100`:
+
+```bash
+~/sh/ha/light.sh office_fan 0
+~/sh/ha/light.sh office_fan 50
+~/sh/ha/light.sh office_fan 100
+```
+
+### Basic lights / smart outlets
+
+Turn lights on or off:
+
+```bash
+~/sh/ha/light.sh office on
+~/sh/ha/light.sh office off
+```
+
+---
+
+## Fan Control
+
+`fan.sh` controls Home Assistant fan entities.
+
+Turn the fan on or off:
+
+```bash
+~/sh/ha/fan.sh office on
+~/sh/ha/fan.sh office off
+```
+
+Set one of the six speed levels:
+
+```bash
+~/sh/ha/fan.sh office 1
+~/sh/ha/fan.sh office 2
+~/sh/ha/fan.sh office 3
+~/sh/ha/fan.sh office 4
+~/sh/ha/fan.sh office 5
+~/sh/ha/fan.sh office 6
+```
+
+---
+
+## Switch Control
+
+`switch.sh` controls basic smart switches.
+
+Examples:
+
+```bash
+~/sh/ha/switch.sh bedroomlcd off
+~/sh/ha/switch.sh officecrt on
+~/sh/ha/switch.sh officelcds on
+```
+