homey-cli

# Homey CLI

Safe, agent-friendly CLI for controlling Homey home automation hubs.

## What This Skill Provides

- **Device control**: Turn devices on/off, dim lights, change colors, set temperatures
- **Device inspection**: List devices, check status, read capabilities
- **Zone management**: List zones and devices per zone
- **Flow control**: List and trigger flows
- **Inventory**: Get complete hub overview

## Setup

### 1. Install Dependencies

```bash
cd skills/homey-cli
npm install
```

### 2. Create Homey App Credentials

1. Go to https://tools.developer.homey.app/tools/app
2. Create a new app with:
   - **Callback URL**: `http://localhost:8787/callback`
   - Note your **Client ID** and **Client Secret**

### 3. Configure Environment

Create `.env` file:

```bash
export HOMEY_CLIENT_ID="your-client-id"
export HOMEY_CLIENT_SECRET="your-client-secret"
export HOMEY_REDIRECT_URL="http://localhost:8787/callback"
```

### 4. Login

```bash
bash run.sh auth login
```

Follow the OAuth flow in your browser. Tokens are stored in `~/.config/homey-cli/`.

## Usage

### List Homeys

```bash
bash run.sh homey list
```

### Select Active Homey

```bash
bash run.sh homey use <homeyId>
```

### Device Operations

```bash
# List all devices
bash run.sh devices list

# List devices as JSON
bash run.sh devices list --json

# Get specific device
bash run.sh devices get <deviceId>

# Read capability value
bash run.sh devices read <deviceId> onoff

# Control devices
bash run.sh devices on <deviceId>
bash run.sh devices off <deviceId>
bash run.sh devices dim <deviceId> 0.4
bash run.sh devices color <deviceId> #FF8800
bash run.sh devices temperature <deviceId> 21.5
```

### Flow Operations

```bash
# List flows
bash run.sh flows list

# Trigger flow
bash run.sh flows trigger <flowId>
```

### Complete Inventory

```bash
bash run.sh inventory --json
```

## Safety Model

Write operations are **capability-allowlisted** for safety:

- Default allowed: `onoff`, `dim`, `light_hue`, `light_saturation`, `light_temperature`, `target_temperature`
- Override via: `export HOMEY_CLI_ALLOWED_CAPABILITIES=onoff,dim,target_temperature`

Destructive operations (delete devices, modify flows, change app settings) are **not supported**.

## Common Queries

When users ask:
- "Turn on the kitchen lights" → List devices, find match, use `devices on <deviceId>`
- "Dim living room to 50%" → Find device, use `devices dim <deviceId> 0.5`
- "What's the temperature in the bedroom?" → Find device, use `devices read <deviceId> measure_temperature`
- "List all my lights" → Use `devices list --json` and filter by class/capabilities

## Configuration Storage

- **Tokens**: `~/.config/homey-cli/credentials.json`
- **Active Homey**: `~/.config/homey-cli/config.json`

## Troubleshooting

- **Auth errors**: Re-run `bash run.sh auth login`
- **Device not found**: Check device name/ID with `bash run.sh devices list`
- **Capability not allowed**: Add to `HOMEY_CLI_ALLOWED_CAPABILITIES` or check if it's a read-only capability