homekit-cli

homekit-cli is a TypeScript CLI and MCP server for inspecting and operating Apple HomeKit through the installed HomeClaw app.

HomeClaw owns Apple’s HomeKit entitlement, HomeKit permission prompt, and native HMHomeManager access. This package owns the agent-facing surface: Incur command groups, schemas, MCP tools, safety gates, docs, and npx skills workflow guidance.

Why the CLI?

Apple HomeKit access is entitlement-gated. A normal Node process cannot directly use HMHomeManager, prompt for HomeKit permission, or read the Home database. homekit-cli keeps Node on the agent/tooling side and talks to HomeClaw over its local Unix socket.

That means a signed App Store or TestFlight app is a hard prerequisite. Install HomeClaw from the Mac App Store, launch it once, and approve HomeKit access before running homekit-cli.

HomeClaw also bundles its own CLI and MCP server. Skip setup for those bundled surfaces; this repo provides the documented homekit CLI, MCP server, schemas, and external npx skills workflow.

Related MCP server: hass-mcp

Architecture

flowchart LR
  User["User or agent"] --> CLI["homekit CLI"]
  CLI --> Commands["Incur command tree"]
  Commands --> Socket["HomeClaw Unix socket"]
  Socket --> HomeClaw["HomeClaw.app"]
  HomeClaw --> HomeKit["Apple HomeKit"]
  Commands --> MCP["MCP server"]

Quick Start

Install and launch HomeClaw first, then approve HomeKit permission in HomeClaw. Do not configure HomeClaw's bundled CLI or MCP server.

Run without installing:

npx homekit-cli bridge setup --format json
npx homekit-cli status --format json

Or install globally:

npm i -g homekit-cli
homekit bridge setup --format json
homekit status --format json

Run as MCP without a global install:

npx -y homekit-cli --mcp

Install the published workflow skill:

npx skills add l3wi/homekit-cli --skill homekit

Development

Run from a local checkout:

bun install
bun run build
node dist/bin.js bridge setup --format json
node dist/bin.js status --format json

Run locally:

bun run dev -- --help

Run as MCP:

node dist/bin.js --mcp

Install the repo-local skill during development:

npx skills add ./skills --skill homekit --copy -y

CLI/MCP Surface

control/set style operations remain intentionally explicit. No wildcard writes are supported.

Configuration

Default socket path:

~/Library/Group Containers/group.com.shahine.homeclaw/homeclaw.sock

Signing, notarization, provisioning profiles, app groups, and native release scripts do not live on main.

If HomeClaw is not installed or not running, the CLI exits with install guidance, the expected socket path, and the App Store link.

Project Structure

Project structure:

src/                  CLI, command groups, HomeClaw socket client helpers
test/                 Vitest tests
docs/                 architecture, command, MCP, safety, and runbook docs
examples/             MCP/config examples
skills/homekit/       external npx-skills package

Useful commands:

bun install
bun run typecheck
bun run test
bun run lint
bun run build

License

MIT