homey

# 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

2. **Configure**

   **Local (recommended when the agent runs on your home network):**

   ```bash
   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):**

   ```bash
   echo "<CLOUD_TOKEN>" | homeycli auth set-token --stdin
   # or interactive (hidden input): homeycli auth set-token --prompt
   ```

   Check status:

   ```bash
   homeycli auth status
   ```

3. **Test connection**

   ```bash
   homeycli status
   ```

## Commands

### Snapshot (recommended for agents)
```bash
homeycli snapshot --json
homeycli snapshot --json --include-flows
```

### List Devices
```bash
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)
```bash
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)
```bash
homeycli zones           # List all zones/rooms
homeycli zones --json    # JSON output
```

### Status
```bash
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:
```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.