HAPCTL(8) System Manager's Manual HAPCTL(8)

hapctl — control utility for openhapd

hapctl [-c file] command

hapctl is a command-line utility for managing and querying the openhapd(8) daemon. It provides commands for configuration validation, daemon status checks, and device management.

The options are as follows:

file
Specify the configuration file. The default is /etc/openhapd.conf.

The following commands are available:

Validate the configuration file syntax. Parses openhapd.conf(5) and reports any syntax errors or invalid values. Exits with status 0 if the configuration is valid, non-zero otherwise. Also displays the number of configured devices.
Display the status of the openhapd(8) daemon and pairing information. Shows whether the daemon is running, its process ID, and the current pairing state (paired, unpaired, or unknown). For paired accessories, displays the number of paired HomeKit controllers.
List all devices configured in openhapd.conf(5). For each device, displays:
  • Device name as it appears in HomeKit
  • Device type and subtype
  • MQTT topic prefix
  • Internal device identifier
Display usage information.

/etc/openhapd.conf
Default configuration file.
/var/run/openhapd.pid
Process ID of the running daemon.
/var/db/openhapd/pairings
Pairing database used for status checks.

The hapctl utility exits 0 on success, and >0 if an error occurs. Commands exit with status 0 on success.

The check command exits with non-zero status if configuration errors are found.

The status and devices commands exit with status 0 regardless of daemon state.

Validate the configuration file:

$ hapctl check
Configuration file /etc/openhapd.conf is valid
  Configured devices: 3

Check daemon status:

$ hapctl status
openhapd is running (PID 12345)
Pairing status: paired (2 controllers)

List configured devices:

$ hapctl devices
Configured devices: 2

  Bedroom Thermostat
    Type:  tasmota/thermostat
    Topic: tasmota_AABBCC
    ID:    bedroom

  Living Room Thermostat
    Type:  tasmota/thermostat
    Topic: tasmota_DDEEFF
    ID:    living_room

Use an alternate configuration file:

$ hapctl -c /etc/openhapd.test.conf check

Configuration errors are reported to with descriptive messages.

If openhapd(8) is not running, status will report:

openhapd is not running

If the pairing database cannot be read, status will report:

Pairing status: unknown (cannot read storage)

openhapd.conf(5), openhapd(8), rc(8)

The hapctl utility first appeared with openhapd(8) in 2025.

Dick Olsson <hi@senzilla.io>

hapctl reads the pairing database directly to determine pairing status. This requires read access to /var/db/openhapd/. When run as a non-root user, pairing status may be reported as “unknown”.

December 26, 2025 OpenBSD