# daemons [View script](../daemons) Observe your homegrown launchd daemons. A LaunchAgent or LaunchDaemon runs in the background and tells you almost nothing: `launchctl` knows whether it is loaded and what its last exit code was, but not what it actually did over time - did the trigger fire? did it do work, or no-op? has it been quietly erroring for a week? `daemons` closes that gap. Each daemon appends one-line JSON records to its own activity log (the `append` write path daemons call), and four read commands turn those logs plus live `launchctl` state into a picture you can act on: `status` (a per-daemon glance), `check` (a nonzero-on-problem health gate for your login shell or a monitor), `log` (human-readable rendering), and `query` (filter and extract the raw JSONL). Two more commands act on daemons rather than just observe them: `load` and `unload` bootstrap/bootout a daemon into launchd (and log a `load`/`unload` record so the timeline explains gaps in its fires), and `registry` reveals the registry file. ## Quick start The common flow is a quick triage: glance at all daemons, skim recent activity, then isolate anything that errored. ``` $ daemons status reconcile loaded last change @ 2026-07-16T04:30:12Z (18 change, 402 noop, 0 error) screenshot-rename loaded last error @ 2026-07-16T05:12:44Z (5 change, 88 noop, 1 error) backup NOT LOADED never fired $ daemons log --all 2026-07-16T04:30:12Z reconcile CHANGE reconciled 3 drifted keys 2026-07-16T05:00:03Z screenshot-rename NOOP no new screenshots 2026-07-16T05:12:44Z screenshot-rename ERROR sips exited 1 on Screen Shot 2026-07-16.png $ daemons query --all --event error --since 1h {"ts":"2026-07-16T05:12:44Z","daemon":"screenshot-rename","event":"error","detail":"sips exited 1 on Screen Shot 2026-07-16.png"} ``` `status`, `check`, `load`, and `unload` read a small registry you set up once (see [The registry](#the-registry) below). `append`, `log`, and `query` work straight from the log files and need no registry at all. ## Logging activity from a daemon (`append`) `append` is the write path: a daemon calls it once per run to record what happened. ```bash daemons append reconcile change "reconciled 3 drifted keys" ``` The `` argument is one of six fixed values, so activity is countable and filterable: - `trigger` - the daemon woke up (a WatchPaths event, a scheduled interval) - `noop` - it ran, but there was nothing to do - `change` - it ran and did work / made a change - `error` - it failed - `load` - the daemon was bootstrapped into launchd (via `daemons load` or an install that delegates to it) - `unload` - the daemon was booted out of launchd Always call `append` guarded, so a logging failure never takes the daemon down with it: ```bash daemons append reconcile change "reconciled 3 drifted keys" 2>/dev/null || : ``` The `2>/dev/null || :` swallows any failure (jq missing under the daemon's minimal PATH, a full disk, a read-only log dir) - the record is best-effort, and the daemon's real work proceeds regardless. For a large or multi-line detail (a captured command output, say), pass `--detail-stdin` in place of the detail argument and pipe the payload in: ```bash some-command 2>&1 | daemons append reconcile error --detail-stdin 2>/dev/null || : ``` Newlines and tabs in the detail round-trip intact: the record stays one physical line, with the detail JSON-escaped inside it. ## Reading and filtering (`log` and `query`) `log` renders records for humans - one header line per record (` `), with any further detail lines indented beneath. Name a single daemon, or use `--all` to merge every daemon's records in timestamp order: ``` $ daemons log reconcile 2026-07-16T04:30:12Z reconcile CHANGE reconciled 3 drifted keys ``` Because timestamps are ISO-8601 UTC they sort lexically, which is how `-a`/`--all` interleaves daemons correctly. Add `-f`/`--follow` to follow the log as new records land, like `tail -f`: ```bash daemons log --all -f ``` `query` is the machine-readable counterpart: it emits the raw JSONL records that survive its filters, so you can pipe them onward. Unlike `log --all` (which merge-sorts every daemon's records by timestamp), `query --all` emits records grouped by daemon, in log-file order - not globally time-sorted. Pipe through `jq -s 'sort_by(.ts)'` if you need one global time order across daemons. **Keep one event type** with `-e`/`--event`: ```bash daemons query reconcile --event error ``` **Keep recent records** with `-s`/`--since`, which accepts three forms: - a relative span, `NNN[smh]` - `1h`, `30m`, `90s` (that long before now) - a bare date, `YYYY-MM-DD` - midnight UTC that day - a full ISO-8601 UTC timestamp - used as-is ```bash daemons query --all --event error --since 1h ``` **Reshape the output** by piping matches through a jq expression with `-j`/`--jq`: ```bash daemons query reconcile --event change --jq '.detail' ``` A bare `log` or `query` with no name (and no `-a`/`--all`) defaults to all daemons. Querying a daemon that has never logged is not an error - it simply prints nothing and exits 0. ## Health-checking (`check`) `check` is a gate: it reads the registry and exits nonzero, printing a loud alert to stdout, for any daemon that is not loaded in launchd, points at a script that no longer exists, or whose last launchd run exited nonzero. ``` $ daemons check [daemons] com.example.backup not loaded in launchd! $ echo $? 1 ``` Because it exits nonzero only on a problem and is silent when everything is healthy, it drops cleanly into a login-shell startup snippet or a monitoring job: ```bash daemons check || echo "a daemon needs attention - run: daemons status" ``` ## Loading and unloading (`load` and `unload`) `load` and `unload` drive `launchctl` directly, so you don't need to remember the domain/label/plist incantation for a daemon you already registered. `load` always reloads: it boots the daemon out first (ignoring "not loaded", since there's nothing to boot out on a first load), then bootstraps it fresh from its plist. That makes it safe to re-run after editing a plist or a script - the old instance is gone before the new one starts. The plist path is resolved by precedence: the `--plist` flag, then the registry's `plist` column, then convention derived from the domain and label - `gui/$UID/` daemons resolve to `~/Library/LaunchAgents/