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