Homey Smart Home Control
Control Athom Homey devices via local (LAN/VPN) or cloud APIs using token authentication.
Setup
Requires Node.js >= 18.
-
Decide local vs cloud
- Local (LAN/VPN): use a local API key from the Homey Web App + Homey IP address
- Cloud (remote/headless): use a cloud token from Developer Tools
-
Configure
Local (recommended when the agent runs on your home network):
homeycli auth discover-local --save --pick 1
echo "<LOCAL_API_KEY>" | homeycli auth set-local --stdin
# or interactive (hidden input): homeycli auth set-local --prompt
Cloud (recommended for VPS/headless hosting):
echo "<CLOUD_TOKEN>" | homeycli auth set-token --stdin
# or interactive (hidden input): homeycli auth set-token --prompt
Check status:
homeycli auth status
-
Test connection
homeycli status
Commands
Snapshot (recommended for agents)
homeycli snapshot --json
homeycli snapshot --json --include-flows
List Devices
homeycli devices # Pretty table output
homeycli devices --json # JSON output for AI parsing (includes latest values)
Filter by name (returns multiple matches)
homeycli devices --match "kitchen" --json
Control Devices
Turn devices on/off:
homeycli device "Living Room Light" on
homeycli device "Bedroom Lamp" off
Set specific capabilities:
homeycli device "Dimmer" set dim 0.5 # 50% brightness
homeycli device "Thermostat" set target_temperature 21 # Set temperature
homeycli device "RGB Light" set light_hue 0.5 # Hue (0-1)
homeycli device "Lock" set locked true # Lock device
Get capability values:
homeycli device "Thermostat" get measure_temperature
homeycli device "Motion Sensor" get alarm_motion
Get all values for a device (multi-sensors)
homeycli device "Living Room Air" values
homeycli device "Living Room Air" get
Flows (Automations)
homeycli flows # List all flows
homeycli flows --json # JSON output
homeycli flows --match "good" --json # Filter flows by name
homeycli flow trigger "Good Night" # Trigger by name
homeycli flow trigger <flow-id> # Trigger by ID
Zones (Rooms)
homeycli zones # List all zones/rooms
homeycli zones --json # JSON output
Status
homeycli status # Show Homey connection info
Common Capabilities
| Capability | Type | Description | Example |
|---|
onoff
| boolean | Power on/off | true
, false
|
dim
| number | Brightness (0-1) | 0.5
(50%) |
light_hue
| number | Color hue (0-1) | 0.33
(green) |
light_saturation
| number | Color saturation (0-1) | 1.0
(full) |
light_temperature
| number | Color temp (0-1) | 0.5
(neutral) |
target_temperature
| number | Thermostat target (°C) | 21
|
measure_temperature
| number | Current temp (read-only) | - |
locked
| boolean | Lock state | true
, false
|
alarm_motion
| boolean | Motion detected (read-only) | - |
alarm_contact
| boolean | Contact sensor (read-only) | - |
volume_set
| number | Volume (0-1) | 0.5
|
Use
homeycli devices
to see what capabilities each device supports.
Fuzzy Matching
Device and flow names support fuzzy matching:
- Exact match: "Living Room Light" → finds "Living Room Light"
- Substring: "living light" → finds "Living Room Light"
- Levenshtein distance: "livng light" → finds "Living Room Light" (typo-tolerant)
JSON Mode
Add
--json
to any command for machine-readable output:
homeycli devices --json | jq '.[] | select(.class == "light")'
homeycli status --json
Examples
Morning routine:
homeycli device "Bedroom Light" on
homeycli device "Bedroom Light" set dim 0.3
homeycli device "Thermostat" set target_temperature 20
Check temperature:
homeycli device "Living Room" get measure_temperature
Trigger scene:
homeycli flow trigger "Movie Time"
List all lights:
homeycli devices --json | jq '.[] | select(.class == "light") | .name'
Troubleshooting
"No auth configured"
Local (LAN/VPN):
- Save local config:
echo "<LOCAL_API_KEY>" | homeycli auth set-local --address http://<homey-ip> --stdin
Cloud (remote/headless):
- Save cloud token:
echo "<CLOUD_TOKEN>" | homeycli auth set-token --stdin
- Cloud tokens can be created in Homey Developer Tools: https://tools.developer.homey.app/api/clients
"Device not found" / ambiguous match
- List devices with
homeycli devices --json
(or homeycli devices --match <query> --json
) to find the right id
- If a query matches more than one device, the CLI returns candidate IDs and asks you to specify the device by ID
"Capability not supported"
- Check available capabilities:
homeycli devices
shows what each device supports
- Common issue: trying to turn on a sensor (use
get
instead of set
)
API Reference
The CLI uses the official
homey-api
npm package (v3.15.0).
Auth/connection modes:
- Local mode:
HomeyAPI.createLocalAPI({ address, token })
using the Homey Web App local API key.
- Cloud mode:
AthomCloudAPI
using a cloud bearer token (PAT) to create a session and access devices/flows/zones.
