Skip to content
ghostmfrPublic

About

REST API & CLI control for HomeKit

Resources

Stars

8 stars

Watchers

0 watching

Forks

Repository files navigation

lilhomie icon

lilhomie

HomeKit REST API + CLI for macOS

Platform License Release CI


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.

How it works

┌─────────────────┐      ┌─────────────────┐      ┌─────────────────┐
│  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

Screenshots

lilhomie main view lilhomie API endpoints lilhomie settings


Installation

Download

Grab the latest release:

👉 Download lilhomie

  • lil-homie-v1.0-mac.zip — macOS app
  • lilhomie-cli-v1.0.zip — CLI binary

Setup

  1. Unzip and drag lilhomie.app to Applications
  2. Launch and grant HomeKit access when prompted
  3. Server starts automatically on port 8420

CLI Installation

# 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/

Shell Completions

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:

zsh

# 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

bash

# 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

fish

# 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.fish

Then restart your shell (or run exec $SHELL) and tab-completion for lilhomie will be available.


REST API

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 read matches "Bedroom Reading Lamp"). Quote CLI names that contain spaces. In HTTP paths, use URL-encoded spaces (Desk%20Lamp) or underscores (Desk_Lamp).

Devices

# 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}'

Rooms

# 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

Scenes

# List scenes
curl localhost:8420/scenes

# Trigger scene
curl -X POST localhost:8420/scene/Good_Night/trigger

CLI

lilhomie 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 status

JSON output flag

Add --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.


Use Cases

  • 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

Requirements

  • macOS 13.0 (Ventura) or later
  • Apple Developer account (for HomeKit entitlement)
  • HomeKit-compatible devices

Building from Source

git clone https://github.com/ghostmfr/lilhomie.git
cd lilhomie
open Homie.xcodeproj
# Build and run in Xcode

Known Issues

See Issues for current bugs.


License

MIT — see LICENSE


Made because siri sucks at turning off my lights.
Ghost Manufacture

About

REST API & CLI control for HomeKit

Resources

Stars

8 stars

Watchers

0 watching

Forks

Releases

Contributors

Languages