homekit

HomeKit Control

Golden Rule: Device Map First

Before your first HomeKit action in a session, read memory/homekit-device-map.json.

This compact device map has every device as a flat list with display_name, id (UUID), room, type (semantic category), controls (writable characteristics), and state. It's optimized for fast LLM scanning and disambiguation.

Refresh the cache periodically or when devices may have changed:

homeclaw-cli device-map --format agent -o memory/homekit-device-map.json

Resolving What the User Means

1. Match user's words against display_name and room from the cached map
2. Use type to disambiguate — lighting devices support brightness; power devices are on/off only. A "Closet Light" with type: power cannot dim.
3. If ambiguous, prefer the device in the most likely room (main living areas > bedrooms > outdoor)
4. If still ambiguous, ask
5. Always use UUIDs for write operations — many devices share names (9 "Overhead" lights, multiple "Blinds"). Use display_name for reading, id (UUID) for set, import-scene, and automations create commands
6. Check controls before sending a command — if brightness isn't in controls, don't try to set it
7. If no match found, refresh the cache first — devices may have been added/renamed:

   homeclaw-cli device-map --format agent -o memory/homekit-device-map.json
   

   Then retry the match. Only tell the user "device not found" if it's still missing after refresh.

Commands

# Discovery
homeclaw-cli device-map --format agent   # LLM-optimized flat list (default cache format)
homeclaw-cli device-map --format json      # Full detail with aliases, manufacturer
homeclaw-cli device-map --format md        # Markdown tables by room
homeclaw-cli search "<query>" --json       # Search by name/room/category
homeclaw-cli get "<name-or-uuid>" --json   # Full detail on one device
homeclaw-cli list --room "Kitchen" --json  # All devices in a room

# Control — always use UUID for reliability
homeclaw-cli set "<uuid>" power true                   # On/off
homeclaw-cli set "<uuid>" brightness 50                # Lights (0-100)
homeclaw-cli set "<uuid>" target_temperature 72        # Thermostat
homeclaw-cli set "<uuid>" target_heating_cooling auto  # HVAC: off/heat/cool/auto
homeclaw-cli set "<uuid>" lock_target_state locked     # Locks: locked/unlocked
homeclaw-cli set "<uuid>" target_position 100          # Blinds (0=closed, 100=open)

# Multi-gang switches — one accessory, several channels sharing a service type
homeclaw-cli set "<uuid>" power true --service-name "Pendentes"  # By service name
homeclaw-cli set "<uuid>" power true --service-id "<service-uuid>"  # By service UUID (names can repeat)
homeclaw-cli set "<uuid>" power true --service-index 2           # By channel number (ServiceLabelIndex)

# Scenes
homeclaw-cli scenes --json              # List all scenes
homeclaw-cli get-scene "<name>" --json  # Full detail: all actions (accessory, room, characteristic, value)
homeclaw-cli trigger "<scene-name>"     # Run a scene
homeclaw-cli import-scene scene.json --dry-run   # Preview scene import
homeclaw-cli import-scene scene.json              # Create scene from JSON
echo '{"name": "...", "actions": [...]}' | homeclaw-cli import-scene -   # Read JSON from stdin (works from any directory, sandbox-safe)
homeclaw-cli delete-scene "<name-or-uuid>" --dry-run   # Preview deletion
homeclaw-cli delete-scene "<name-or-uuid>"             # Delete a scene

# Room assignment — supports UUID for duplicate names
homeclaw-cli assign-rooms rooms.json --dry-run    # Preview room assignments
homeclaw-cli assign-rooms rooms.json              # Assign accessories to rooms
echo '[{"accessory": "...", "room": "..."}]' | homeclaw-cli assign-rooms -   # stdin also works here
# JSON format: bare array [{"uuid": "...", "room": "..."} or {"accessory": "...", "room": "..."}]
#              (or the same array wrapped as {"assignments": [...]})
# Use "uuid" when multiple accessories share the same name (e.g., ceiling fan + light)

# Management — rename, rooms, zones
homeclaw-cli rename "<name-or-uuid>" "<new-name>"           # Rename accessory
homeclaw-cli rename "<name-or-uuid>" "<new-name>" --dry-run # Preview rename
homeclaw-cli rename-room "<name-or-uuid>" "<new-name>"      # Rename room
homeclaw-cli create-room "<name>"                            # Create room
homeclaw-cli remove-room "<name-or-uuid>"                    # Remove room
homeclaw-cli remove-accessory "<name-or-uuid>"               # Remove accessory
homeclaw-cli create-zone "<name>"                            # Create zone
homeclaw-cli remove-zone "<name-or-uuid>"                    # Remove zone
homeclaw-cli add-room-to-zone "<room>" "<zone>"              # Add room to zone
homeclaw-cli remove-room-from-zone "<room>" "<zone>"         # Remove room from zone

# Automations (button programming)
homeclaw-cli automations list --json                          # List all automations
homeclaw-cli automations get "<name-or-uuid>" --json          # Detail view
homeclaw-cli automations delete "<name-or-uuid>" [--dry-run]
homeclaw-cli automations enable "<name-or-uuid>"
homeclaw-cli automations disable "<name-or-uuid>"

# Create with inline actions (creates a scene named after the automation)
# ALWAYS use UUIDs for target accessories to avoid name collisions
homeclaw-cli automations create --name "Sarah's Room Open" \
  --accessory "Office Button" \
  --action "BE21C139-413A-50F9-B97F-B9BDA06302A8:power:true" \
  --action "52195C6F-6FAA-5E52-AA56-840A6605EEAA:target_position:100" \
  --press single --service-index 1

# Create with a named scene
homeclaw-cli automations create --name "Movie Mode" \
  --accessory "Remote Button" \
  --scene "Movie Time" \
  --press single

# Press types: single (0), double (1), long (2)
# --action format: "UUID:property:value" (repeatable, UUID strongly preferred over names)
# --scene and --action are mutually exclusive
# Use --service-index for multi-button accessories (e.g., Aqara in fast mode)
# Note: inline actions create a visible scene (Apple uses a private API for hidden ones)

# Export to file (any format)
homeclaw-cli device-map --format agent -o memory/homekit-device-map.json
homeclaw-cli device-map --format md -o device-map.md