homebridge-cli

homebridge-cli is a command-line and MCP interface for the Homebridge UI API. It gives humans and agents a typed command surface for Homebridge status, configuration, plugins, accessories, users, backups, and raw API calls.

The CLI stores profiles in ~/.homebridge/credentials.json, sends Homebridge bearer tokens only to the configured UI host, and keeps plugin update progress on Homebridge UI's Socket.IO update channel.

Quick Start

Install the package:

npm install -g homebridge-cli

Log in to your Homebridge UI:

homebridge auth login \
  --url http://pi.lan:8581 \
  --username admin \
  --password 'your-password'

To avoid putting the password in shell history, read it from stdin instead:

printf '%s' "$HOMEBRIDGE_PASSWORD" | homebridge auth login \
  --url http://pi.lan:8581 \
  --username admin \
  --password-stdin

Run a few common checks:

homebridge auth check
homebridge status homebridge
homebridge server pairing
homebridge plugins outdated

Start the MCP server for agent/tooling integrations:

homebridge --mcp

Functionality

Commands are grouped around Homebridge UI API areas:

• auth - login, no-auth token exchange, saved-token setup, token checks, and profile inspection.
• server - bridge restart, child bridge control, pairing data, ports, network interfaces, mDNS, cache, and wallpaper commands.
• config - config editor operations, plugin config blocks, UI config properties, and config backups.
• plugins - installed plugin state, npm search/lookup, versions, schemas, changelogs, releases, aliases, custom UI assets, and plugin updates.
• accessories - accessory listing, layout, refresh, and characteristic updates.
• users - user CRUD, password changes, and 2FA setup, activation, and deactivation.
• status - CPU, RAM, network, uptime, Homebridge status, child bridges, versions, and server information.
• platform - Linux host controls, Docker startup/container tools, and hb-service settings/logs.
• backup - backup creation/download, scheduled backup management, restore upload, and restore trigger commands.
• setup - setup wizard first-user and token commands.
• api - raw GET, POST, PUT, PATCH, and DELETE commands plus Swagger coverage verification.

Use built-in discovery when you need exact options:

homebridge --help
homebridge plugins --help
homebridge --llms

Plugin Updates

Homebridge UI exposes plugin metadata over REST, but plugin install and update jobs run through its /plugins Socket.IO namespace so server progress can stream back to the client.

homebridge plugins outdated
homebridge plugins update homebridge-unifi-access --version latest
homebridge plugins update-all

plugins outdated reads /api/plugins. plugins update and plugins update-all connect to the Homebridge plugin socket with the saved bearer token, stream stdout and stderr, and finish when Homebridge acknowledges the job.

Raw API Calls

Use api commands for endpoints that do not need a dedicated ergonomic wrapper:

homebridge api get /api/status/homebridge
homebridge api put /api/server/name --body '{"name":"Homebridge"}'

Authentication And Credentials

Credentials are stored at ~/.homebridge/credentials.json with 0700 directory permissions and 0600 file permissions.

If Homebridge UI auth is disabled, request the no-auth token:

homebridge auth noauth --url http://pi.lan:8581

If you already have a bearer token, save it directly:

homebridge auth save-token --url http://pi.lan:8581 --token "$HOMEBRIDGE_TOKEN"

Developer

Install dependencies:

bun install

Run the local quality gates:

bun run build
bun run test
bun run lint
bun run format

Verify local Swagger coverage against a Homebridge UI server:

bun run coverage:live

Check the package before publishing:

bun audit
npm pack --dry-run
npm publish --dry-run --access public

The package ships bin/homebridge.js, compiled files from dist/src, type declarations, docs, changelog, and license. prepack runs bun run build so published artifacts are regenerated before packing.

Release Workflow

Releases are automated from main.

Before merging to main:

• Bump version in package.json.
• Add a matching ## x.y.z section in CHANGELOG.md.
• Open a pull request targeting main; the Release Check workflow validates the version, changelog, tests, lint, format, audit, and package dry-run.

When the release commit lands on main, the Release workflow:

1. Validates that package.json has a semver version.
2. Requires a matching changelog section.
3. Fails if that package version is already published on npm.
4. Installs a current npm CLI for Trusted Publisher support.
5. Runs build, tests, lint, format, audit, and npm pack --dry-run.
6. Creates the vX.Y.Z Git tag and GitHub release using the changelog notes.
7. Publishes the package to npm with provenance through npm Trusted Publisher OIDC.

Repository setup required once: configure npm Trusted Publisher for l3wi/homebridge-cli with workflow filename release.yml and the npm publish permission.

package.json must keep repository.url aligned with https://github.com/l3wi/homebridge-cli; npm provenance verification rejects publishes when repository metadata does not match the Trusted Publisher source.