Skill: maxsumrall/homey (version 1.1.2)

--- name: homey description: Control Athom Homey smart home devices via local (LAN/VPN) or cloud APIs. List/control devices, trigger flows, query zones. Works with Homey Pro, Cloud, and Bridge. metadata: {"clawdbot":{"requires":{"bins":["homeycli"]},"install":[{"id":"homey-npm","kind":"node","package":".","bins":["homeycli"],"label":"Install Homey CLI"}]}} --- # 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.

path: CHANGELOG.md
content: # Changelog

## 1.1.2

- Add `homeycli` wrapper entrypoint to reduce "permission denied" issues and automatically install npm deps if missing.
- Add `homeycli device <name> capabilities` to list settable capabilities.
- Local onboarding smoothing: `auth set-local` attempts mDNS discovery if address is missing.

## 1.1.1

- Auth hardening: reject wrong token types early (local triple-part key vs cloud token) and validate token characters to avoid invalid HTTP header errors.

## 1.1.0

- Add **local + cloud** connection modes with `HOMEY_MODE=auto|local|cloud`.
- Add local onboarding:
  - `homeycli auth discover-local` (mDNS)
  - `homeycli auth discover-local --save --pick <n>` / `--homey-id <id>`
  - `homeycli auth set-local` (stores local API key)
- Improve cloud/headless setup (`auth set-token --stdin/--prompt`) and clearer `auth status` output.
- Refactor name/id resolution to be deterministic and shared across devices/flows.
- Docs: updated setup instructions + stable JSON output contract (`docs/output.md`).

## 1.0.1

- LLM-friendly output improvements: IDs always included, multi-sensor friendly `values` map.
- Added `snapshot` command (status + zones + devices; optional flows).
- Added `--match` filtering for `devices` and `flows`.
- Added `auth set-token` and `auth status` helper commands.
- Improved ambiguous name handling (returns candidates, asks for ID).


path: EXAMPLES.md
content: # Homey CLI Examples

Real-world usage examples for `homeycli`.

## Setup

Pick **local** (LAN/VPN) or **cloud** (remote/headless).

```bash
# 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
```bash
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
```bash
homeycli devices
```

### List Devices (JSON)
```bash
homeycli devices --json | jq '.[] | select(.class == "light")'
```

## Controlling Lights

### Basic On/Off
```bash
# Turn on
homeycli device "Living Room Light" on

# Turn off
homeycli device "Bedroom Lamp" off
```

### Dimming
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
homeycli flows
```

### Trigger Flows
```bash
# 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
```bash
homeycli zones
```

## Complex Workflows

### Morning Routine
```bash
#!/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
```bash
#!/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
```bash
#!/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
```bash
#!/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 (Clawdbot)

When using with Clawdbot, the AI can:

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

```bash
# 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
```bash
# 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
```bash
# 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
```bash
homeycli device "Motion Sensor" set onoff true
# Error: Device "Motion Sensor" does not support capability: onoff
# Available: alarm_motion, measure_battery, measure_temperature
```

## Tips

1. **Use `--json` for scripting** - Parse output with `jq`, `grep`, etc.
2. **Fuzzy matching** - Don't worry about exact device names
3. **Check capabilities first** - Use `homeycli devices` to see what each device supports
4. **Group commands in flows** - Complex automations are easier as Homey flows

## Getting Help

```bash
homeycli --help                  # General help
homeycli device --help           # Device command help
homeycli flow --help             # Flow command help
```

## Troubleshooting

**No auth configured:**
```bash
# Shows mode + whether local/cloud credentials are present (never prints full tokens)
homeycli auth status
```

**Connection timeout:**
```bash
# 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


path: INSTALL.sh
content: #!/bin/bash
# Quick install script for Homey CLI skill

set -e

LINK=0
for arg in "$@"; do
  case "$arg" in
    --link)
      LINK=1
      ;;
    --no-link)
      LINK=0
      ;;
  esac
done

echo "🦞 Installing Homey CLI Skill..."
echo ""

# Check if we're in the right directory
if [ ! -f "package.json" ]; then
  echo "❌ Error: package.json not found. Run this from the homey skill directory."
  exit 1
fi

# Install dependencies
echo "📦 Installing dependencies..."
npm install

# Make CLI executable (best-effort)
echo "🔧 Making CLI executable..."
chmod +x bin/homeycli.js bin/homeycli 2>/dev/null || true

# Check for auth
if [ -z "$HOMEY_TOKEN" ] && [ -z "$HOMEY_LOCAL_TOKEN" ] && [ ! -f "$HOME/.homey/config.json" ]; then
  echo ""
  echo "⚠️  No Homey auth found (env vars or ~/.homey/config.json)."
  echo ""
  echo "Local mode (LAN/VPN):"
  echo "  # discover local address (best effort via mDNS)"
  echo "  ./bin/homeycli.js auth discover-local --json"
  echo "  ./bin/homeycli.js auth discover-local --save --pick 1"
  echo "  # generate a local API key in the Homey Web App"
  echo "  ./bin/homeycli.js auth set-local --prompt"
  echo ""
  echo "Cloud mode (remote/headless):"
  echo "  # create a cloud token in Developer Tools: https://tools.developer.homey.app/api/clients"
  echo "  ./bin/homeycli.js auth set-token --prompt"
  echo ""
  echo "Env vars (optional):"
  echo "  export HOMEY_MODE=auto|local|cloud"
  echo "  export HOMEY_ADDRESS=\"http://192.168.1.50\""
  echo "  export HOMEY_LOCAL_TOKEN=\"...\""
  echo "  export HOMEY_TOKEN=\"...\""
  echo ""
else
  echo "✅ Auth appears to be configured (env var or config file present)"
fi

# Test CLI
echo ""
echo "🧪 Testing CLI..."
if ./bin/homeycli.js --help > /dev/null 2>&1; then
  echo "✅ CLI works!"
else
  echo "❌ CLI test failed"
  exit 1
fi

# Link globally (optional, non-interactive)
if [ "$LINK" -eq 1 ]; then
  echo ""
  echo "🔗 Linking globally with npm link..."
  npm link
  echo "✅ Installed globally as 'homeycli'"
else
  echo ""
  echo "Skipped global install. Use ./bin/homeycli.js to run, or pass --link."
fi

echo ""
echo "🎉 Installation complete!"
echo ""
echo "Next steps:"
echo "  1. Check config: ./bin/homeycli.js auth status"
echo "  2. Test: ./bin/homeycli.js status"
echo "  3. List devices: ./bin/homeycli.js devices --json"
echo ""


path: docs/_config.yml
content: title: homeycli
description: Homey CLI (LLM/agent-friendly)
theme: jekyll-theme-cayman


Security scan verdicts — ClawScan: clean | static analysis: suspicious | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)