Homey Smart Home Control

Control Athom Homey devices via local (LAN/VPN) or cloud APIs using token authentication.

Setup

Requires Node.js >= 18.

1. 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

1. 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

1. 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: bash homeycli device "Living Room Light" on homeycli device "Bedroom Lamp" off

Set specific capabilities: bash 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: ```bash 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

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: bash homeycli devices --json | jq '.[] | select(.class == "light")' homeycli status --json

Examples

Morning routine: bash homeycli device "Bedroom Light" on homeycli device "Bedroom Light" set dim 0.3 homeycli device "Thermostat" set target_temperature 20

Check temperature: bash homeycli device "Living Room" get measure_temperature

Trigger scene: bash homeycli flow trigger "Movie Time"

List all lights: bash 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.