mirror of
https://github.com/hanzoskill/homey.git
synced 2026-10-30 21:10:06 +00:00
7.3 KiB
7.3 KiB
Homey CLI Examples
Real-world usage examples for homeycli.
Setup
Pick local (LAN/VPN) or cloud (remote/headless).
# Local mode (LAN/VPN)
homeycli auth discover-local --json
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 mode (remote/headless)
echo "CLOUD_TOKEN" | homeycli auth set-token --stdin
# or interactive (hidden input): homeycli auth set-token --prompt
# Check what will be used
homeycli auth status
# Test connection
homeycli status
Basic Commands
Check Status
homeycli status
Output:
🏠 Homey Status:
Name: Home
Connection: local (http://192.168.1.50)
Platform: local 2
Hostname: homey-abc123
Homey ID: 5f9a1234567890abcdef
Status: ✓ Connected
List All Devices
homeycli devices
List Devices (JSON)
homeycli devices --json | jq '.[] | select(.class == "light")'
Controlling Lights
Basic On/Off
# Turn on
homeycli device "Living Room Light" on
# Turn off
homeycli device "Bedroom Lamp" off
Dimming
# 50% brightness
homeycli device "Kitchen Light" set dim 0.5
# 100% brightness
homeycli device "Kitchen Light" set dim 1.0
# 10% brightness (night mode)
homeycli device "Bedroom Light" set dim 0.1
Color Control
# Set hue (0-1 scale)
homeycli device "RGB Strip" set light_hue 0.0 # Red
homeycli device "RGB Strip" set light_hue 0.33 # Green
homeycli device "RGB Strip" set light_hue 0.66 # Blue
# Set saturation
homeycli device "RGB Strip" set light_saturation 1.0 # Full color
homeycli device "RGB Strip" set light_saturation 0.5 # Pastel
# Set temperature (warm to cool)
homeycli device "White Light" set light_temperature 0.0 # Warm
homeycli device "White Light" set light_temperature 1.0 # Cool
Climate Control
Thermostat
# Set target temperature (Celsius)
homeycli device "Living Room Thermostat" set target_temperature 21
# Get current temperature
homeycli device "Living Room Thermostat" get measure_temperature
# Check heating status
homeycli device "Living Room Thermostat" get thermostat_state
Media Control
Volume
# Set volume (0-1 scale)
homeycli device "Sonos Living Room" set volume_set 0.5
# Mute
homeycli device "Sonos Living Room" set volume_mute true
# Unmute
homeycli device "Sonos Living Room" set volume_mute false
Security
Locks
# Lock
homeycli device "Front Door" set locked true
# Unlock
homeycli device "Front Door" set locked false
# Check status
homeycli device "Front Door" get locked
Sensors
# Check motion
homeycli device "Hallway Motion" get alarm_motion
# Check door/window contact
homeycli device "Front Door Sensor" get alarm_contact
# Check battery level
homeycli device "Motion Sensor" get measure_battery
Flows (Automations)
List Flows
homeycli flows
Trigger Flows
# By name
homeycli flow trigger "Good Morning"
homeycli flow trigger "Good Night"
homeycli flow trigger "Movie Time"
# By ID (if you know it)
homeycli flow trigger "5f9a1234567890abcdef"
Zones
List All Zones
homeycli zones
Complex Workflows
Morning Routine
#!/bin/bash
# Turn on bedroom light at low brightness
homeycli device "Bedroom Light" on
homeycli device "Bedroom Light" set dim 0.2
# Set comfortable temperature
homeycli device "Bedroom Thermostat" set target_temperature 20
# Trigger morning flow
homeycli flow trigger "Good Morning"
Movie Mode
#!/bin/bash
# Dim living room lights
homeycli device "Living Room Main" set dim 0.1
homeycli device "TV Backlight" on
homeycli device "TV Backlight" set dim 0.3
# Or just trigger a flow
homeycli flow trigger "Movie Time"
Night Routine
#!/bin/bash
# Turn off all main lights
homeycli device "Living Room" off
homeycli device "Kitchen" off
homeycli device "Hallway" off
# Night light in bedroom
homeycli device "Bedroom Light" on
homeycli device "Bedroom Light" set dim 0.05
# Lock doors
homeycli device "Front Door" set locked true
# Trigger night flow
homeycli flow trigger "Good Night"
Check All Sensors
#!/bin/bash
# Get all sensor readings as JSON
homeycli devices --json | jq '.[] | select(.class == "sensor") | {
name: .name,
temperature: .capabilitiesObj.measure_temperature.value,
humidity: .capabilitiesObj.measure_humidity.value,
battery: .capabilitiesObj.measure_battery.value
}'
Integration with AI (Bot)
When using with Bot, the AI can:
# Natural language → command translation
User: "Turn on the living room lights"
Clawd: homeycli device "Living Room" on
User: "Set bedroom temperature to 21"
Clawd: homeycli device "Bedroom Thermostat" set target_temperature 21
User: "Dim the kitchen lights to 50%"
Clawd: homeycli device "Kitchen" set dim 0.5
User: "What's the temperature in the living room?"
Clawd: homeycli device "Living Room Sensor" get measure_temperature
Fuzzy Matching Examples
The CLI is forgiving with device names:
# All of these work for "Living Room - Main Light":
homeycli device "Living Room - Main Light" on # Exact match
homeycli device "Living Room Main Light" on # Close match
homeycli device "living room light" on # Case insensitive
homeycli device "living light" on # Substring match
homeycli device "livng light" on # Typo tolerance
JSON Processing
Extract Specific Info
# All lights that are on
homeycli devices --json | jq '.[] | select(.class == "light" and .capabilitiesObj.onoff.value == true)'
# All devices in "Living Room" zone
homeycli devices --json | jq '.[] | select(.zone == "Living Room")'
# All sensors with low battery
homeycli devices --json | jq '.[] | select(.capabilitiesObj.measure_battery.value < 20)'
# Temperature readings
homeycli devices --json | jq '.[] | select(.capabilitiesObj.measure_temperature) | {name, temp: .capabilitiesObj.measure_temperature.value}'
Error Handling
Device Not Found
# If device doesn't exist, you'll see suggestions
homeycli device "Living Ight" on
# Error: Device not found: Living Ight
# Did you mean: Living Room - Main Light?
Invalid Capability
homeycli device "Motion Sensor" set onoff true
# Error: Device "Motion Sensor" does not support capability: onoff
# Available: alarm_motion, measure_battery, measure_temperature
Tips
- Use
--jsonfor scripting - Parse output withjq,grep, etc. - Fuzzy matching - Don't worry about exact device names
- Check capabilities first - Use
homeycli devicesto see what each device supports - Group commands in flows - Complex automations are easier as Homey flows
Getting Help
homeycli --help # General help
homeycli device --help # Device command help
homeycli flow --help # Flow command help
Troubleshooting
No auth configured:
# Shows mode + whether local/cloud credentials are present (never prints full tokens)
homeycli auth status
Connection timeout:
# Check Homey is online
homeycli status
homeycli status
API rate limits:
- Cloud mode may be rate-limited by Athom/Homey
- If you hit limits, wait a minute and retry
- Batch operations when possible