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 device-map --home "<home>" --format agent  # Scope map to one home
homeclaw-cli search "<query>" --json       # Search by name/room/category
homeclaw-cli search "<query>" --home "<home>" --json
homeclaw-cli get "<name-or-uuid>" --json   # Full detail on one device
homeclaw-cli get "<name-or-uuid>" --home "<home>" --json
homeclaw-cli list --room "Kitchen" --json  # All devices in a room
homeclaw-cli list --home "<home>" --room "Kitchen" --json

# Control — always use UUID for reliability
homeclaw-cli set "<uuid>" power true                   # On/off
homeclaw-cli set "<uuid>" power true --home "<home>"   # Multi-home: pin the home
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 scenes --home "<home>" --json
homeclaw-cli get-scene "<name>" --json  # Full detail: all actions (accessory, room, characteristic, value)
homeclaw-cli trigger "<scene-name>"     # Run a scene
homeclaw-cli trigger "<scene-name>" --home "<home>"
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 "<name-or-uuid>" "<new-name>" --service-name "Switch 2"  # Rename one gang of a multi-gang accessory (also --service-index / --service-id, or pass the service UUID)
homeclaw-cli set-display-as "<name-or-uuid>" light|fan|switch|outlet|default [--service-index N]  # Home app Display As (switch/outlet services only)
homeclaw-cli groups                                           # Home app accessory groups (one tile each) and members
homeclaw-cli groups create "<group>" "<member>"... [--allow-mixed]  # Members: accessory name/UUID or service UUID; one kind unless --allow-mixed
homeclaw-cli groups add|remove "<group>" "<member>"...        # Change members
homeclaw-cli groups rename "<group>" "<new-name>"             # Rename group
homeclaw-cli groups delete "<group>"                          # Delete group (accessories untouched)
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>"

# Last run: every scene, and every entry in an automation's action_sets, carries
# last_execution_date (ISO-8601 UTC, or null). HomeKit leaves it null for most
# runs, including automations a home hub runs, so null means "none recorded",
# not "never ran". Use `events` for what actually happened.

# 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); this picks the TRIGGER button
# Note: inline actions create a visible scene (Apple uses a private API for hidden ones)

# One gang of a multi-gang accessory as an action or condition target: JSON row form
# (repeatable; keys: accessory, property|characteristic, value, room, service_name, service_id, service_index)
homeclaw-cli automations create --name "Dining Unoccupied" \
  --accessory "Dining FP2" --characteristic occupancy_detected --trigger-value false \
  --action-json '{"accessory":"<uuid>","property":"power","value":"false","service_index":1}' \
  --action-json '{"accessory":"<uuid>","property":"power","value":"false","service_index":2}' --dry-run
homeclaw-cli automations add-condition "<automation>" --accessory "<uuid>" --property power --value true --service-index 2

# Changing an existing automation: edit it in place (keeps the UUID, so button
# bindings and Siri references survive). Never delete + recreate to change it.
# Only the options passed change; preview with --dry-run and show the user first.
homeclaw-cli automations edit "<automation>" --time 06:45 --days mon,tue,wed,thu,fri --dry-run
homeclaw-cli automations edit "<automation>" --time-after sunset --time-before sunrise --duration 300
homeclaw-cli automations edit "<automation>" --condition-json '{"accessory":"<uuid>","property":"contact_state","value":"0"}'
homeclaw-cli automations edit "<automation>" --name "New name"
# --condition* replaces ALL characteristic conditions; --time-after/--time-before replace
# the whole time window; clear with --clear-conditions / --clear-time-window /
# --every-day / --clear-duration. --time replaces the trigger event(s) with a time of day.
# Timer automations from the Home app accept only --name.
# After a real run check "verified": false means the re-read differs ("mismatches").

# Replacing an accessory across automations (plan only; never writes without --apply)
homeclaw-cli automations migrate-actions --replace-accessory "<old-uuid>=<new-uuid>[,<new-uuid>]" --json
homeclaw-cli automations migrate-actions --replace-accessory "<old-uuid>=<new-uuid>" --automation "<uuid>" --json
# Each action set comes back with classification + status:
#   visible_scene + supported   -> can be written with --apply (ask the user first;
#                                  shared_with lists other automations it also changes)
#   visible_scene + blocked     -> see issues (missing, ambiguous service, conflict)
#   hidden + unsupported        -> reason hidden_action_set_requires_private_spi.
#                                  Apple only lets its own Home app edit automation-owned
#                                  action sets. Do NOT work around it (no import-scene +
#                                  rewire substitute). Render manual_steps as Home app
#                                  instructions instead, then rerun the dry run to confirm.
#   trigger_only: true          -> the old accessory is this automation's trigger;
#                                  nothing to migrate, but tell the user it will break
# Never claim a hidden set was migrated. See docs/PRIVATE_API.md for the boundary.

# 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