HomeKit REST API + CLI for macOS
I built lilhomie so my AI assistant could control my house. Now you can too.
It's a macOS app that runs a local REST API for your HomeKit devices. The CLI talks to the app. No hacks, no workarounds — just Apple's native HomeKit framework exposed over HTTP.
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ lilhomie CLI │ ───► │ lilhomie.app │ ───► │ HomeKit │
│ (or any HTTP) │ │ (REST server) │ │ (Apple API) │
└─────────────────┘ └─────────────────┘ └─────────────────┘
- 🖥️ macOS app runs the server on
localhost:8420 - ⌨️ CLI sends requests to the app
- 🏠 100% Apple HomeKit — no reverse engineering, no cloud APIs
- 🔒 Local only — never touches the internet (unless you're an idiot)
- 🚀 Raycast extension — coming soon
Grab the latest release:
lil-homie-v1.0-mac.zip— macOS applilhomie-cli-v1.0.zip— CLI binary
- Unzip and drag lilhomie.app to Applications
- Launch and grant HomeKit access when prompted
- Server starts automatically on port 8420
# Download and install
curl -L https://github.com/ghostmfr/lilhomie/releases/latest/download/lilhomie-cli.zip -o lilhomie.zip
unzip lilhomie.zip
sudo mv lilhomie /usr/local/bin/Completion scripts for bash, zsh, and fish are included in the
completions/ directory of this repository. After installing the binary, set
up completions for your shell:
# Option A — copy to a fpath directory (recommended)
sudo cp completions/lilhomie.zsh /usr/local/share/zsh/site-functions/_lilhomie
# Option B — add completions dir to fpath in ~/.zshrc
mkdir -p ~/.config/lilhomie/completions
cp completions/lilhomie.zsh ~/.config/lilhomie/completions/
echo 'fpath=(~/.config/lilhomie/completions $fpath)' >> ~/.zshrc
echo 'autoload -Uz compinit && compinit' >> ~/.zshrc
# Option C — Oh-My-Zsh
cp completions/lilhomie.zsh ~/.oh-my-zsh/completions/_lilhomie# Option A — bash-completion framework
sudo cp completions/lilhomie.bash /etc/bash_completion.d/lilhomie
# Option B — source directly from ~/.bashrc
mkdir -p ~/.config/lilhomie/completions
cp completions/lilhomie.bash ~/.config/lilhomie/completions/
echo 'source ~/.config/lilhomie/completions/lilhomie.bash' >> ~/.bashrc# User completions directory (no sudo required)
cp completions/lilhomie.fish ~/.config/fish/completions/lilhomie.fish
# Or system-wide
sudo cp completions/lilhomie.fish /usr/share/fish/vendor_completions.d/lilhomie.fishThen restart your shell (or run exec $SHELL) and tab-completion for
lilhomie will be available.
The API runs on http://localhost:8420 while the app is running.
Device names: Copy the quoted HomeKit accessory name or ID from
lilhomie list. Names are case-insensitive and may be shortened to partial words (bed readmatches"Bedroom Reading Lamp"). Quote CLI names that contain spaces. In HTTP paths, use URL-encoded spaces (Desk%20Lamp) or underscores (Desk_Lamp).
# List all devices
curl localhost:8420/devices
# Get device info
curl localhost:8420/device/Desk_Lamp
# Toggle
curl -X POST localhost:8420/device/Desk_Lamp/toggle
# Explicit on/off
curl -X POST localhost:8420/device/Desk_Lamp/on
curl -X POST localhost:8420/device/Desk_Lamp/off
# Set brightness
curl -X POST localhost:8420/device/Desk_Lamp/set \
-H "Content-Type: application/json" \
-d '{"brightness": 50}'# List rooms
curl localhost:8420/rooms
# All devices in room
curl localhost:8420/room/Office
# Room on/off
curl -X POST localhost:8420/room/Office/on
curl -X POST localhost:8420/room/Office/off
# Room-scoped device on/off
curl -X POST localhost:8420/room/Office/device/Desk_Lamp/on
curl -X POST localhost:8420/room/Office/device/Desk_Lamp/off# List scenes
curl localhost:8420/scenes
# Trigger scene
curl -X POST localhost:8420/scene/Good_Night/triggerlilhomie list # List all devices
lilhomie status "Desk Lamp" # Device status
lilhomie on "Desk Lamp" # Turn on
lilhomie off "Desk Lamp" # Turn off
lilhomie toggle "Desk Lamp" # Toggle
lilhomie set "Desk Lamp" 50 # Set brightness to 50%
lilhomie scenes # List scenes
lilhomie scene "Good Night" # Trigger scene
lilhomie info # Show Homie app statusAdd --json (or -j) to any command to get raw JSON back instead of the
human-readable output. Perfect for piping into jq or any other tool.
# List all devices as JSON
lilhomie list --json
# Filter to devices that are currently on
lilhomie list --json | jq '.devices[] | select(.isOn) | .name'
# Get a single device as JSON
lilhomie status "Desk Lamp" --json
# Check scenes as JSON
lilhomie scenes -j | jq '.scenes[].name'
# Use in scripts
IS_ON=$(lilhomie status "Desk Lamp" --json | jq -r '.isOn')Human-readable lilhomie list output includes copy-paste-ready names and IDs:
Office:
🟢 "Desk Lamp" [id: A1B2-C3D4] (75%)
Use either lilhomie on "Desk Lamp" or lilhomie on A1B2-C3D4. If no device matches, the HTTP API returns a 404 with the closest known name in did_you_mean.
- Home automation scripts — bash, Python, Node.js
- Stream Deck buttons — trigger via curl
- Clawdbot — quick device control via imessage
- Webhooks — IFTTT, n8n, Home Assistant
- Cron jobs — scheduled lighting
- SSH — control home from anywhere
- macOS 13.0 (Ventura) or later
- Apple Developer account (for HomeKit entitlement)
- HomeKit-compatible devices
git clone https://github.com/ghostmfr/lilhomie.git
cd lilhomie
open Homie.xcodeproj
# Build and run in XcodeSee Issues for current bugs.
MIT — see LICENSE
Made because siri sucks at turning off my lights.
Ghost Manufacture