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 npx homekit-cli or the global homekit binary.

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.

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 globally:

npx -y homekit-cli bridge setup --format json
npx -y 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

| Area | Commands | Write gate | | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------- | | Status | status | read-only | | Homes | homes list | read-only | | Rooms | rooms list, rooms create, rooms rename, rooms remove, rooms assign | --allow-mutation | | Accessories | accessories list, accessories get, accessories search, accessories control, accessories remove | --allow-actuation / --allow-mutation | | Scenes | scenes list, scenes get, scenes trigger, scenes import, scenes update, scenes delete | --allow-actuation / --allow-mutation | | Automations | automations list, automations get, automations create, automations create-time, automations delete, automations enable, automations disable, automations rewire, automations add-condition | --allow-mutation | | Zones | zones list, zones create, zones remove, zones add-room, zones remove-room | --allow-mutation | | Rename | rename | --allow-mutation | | Events | events list | read-only | | Device map | device-map | read-only | | Webhooks | webhooks status, webhooks setup, webhooks test, webhooks reset, webhooks log, webhooks log-stats, webhooks purge-log | setup/reset/purge require mutation | | Triggers | triggers list, triggers add, triggers update, triggers remove | mutations require --allow-mutation | | Provider | bridge setup, bridge status, bridge launch, bridge stop, bridge logs | provider-specific |

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

Configuration

| Variable | Purpose | | --------------------------------- | --------------------------------------------------------------------- | | HOMEKIT_SOCKET_PATH | Optional HomeClaw socket override. | | HOMEKIT_USE_LEGACY_TMP_SOCKET=1 | Use /tmp/homeclaw.sock instead of the App Group socket. | | HOMEKIT_MCP_PROFILE | Operator label for read/write MCP profiles. Safety gates still apply. |

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