Watch Command
zetl watch starts a persistent process that monitors the vault for file changes and emits graph-level events as NDJSON on stdout.
Usage
# Start watching (NDJSON events on stdout)
zetl -d ./my-vault watch
# Custom debounce interval
zetl watch --debounce 500
# Execute a command on each change
zetl watch --exec "zetl check --fail-on error"
Flags
| Flag | Default | Description |
|---|---|---|
--debounce <ms> | 200 | Debounce interval for batching rapid changes |
--exec <cmd> | none | Command to invoke after each re-index |
Event types
Events are emitted as NDJSON (one JSON object per line). The event vocabulary mirrors the Diff Command output schema:
| Event | Description |
|---|---|
index_ready | Initial index complete, watching started |
page_added | New page appeared |
page_removed | Page deleted |
link_added | New wikilink appeared |
link_removed | Wikilink removed |
orphan_gained | Page became orphaned |
orphan_resolved | Orphan page got an incoming link |
dead_link_added | New dead link appeared |
dead_link_resolved | Dead link target now exists |
index_updated | Re-index cycle complete (summary) |
How it works
zetl uses OS-level file system events (via the notify crate) to detect changes. When a .md file changes, zetl debounces the event, incrementally re-indexes only the affected files using the Merkle Tree change detection from architecture/Cache, and emits events only when the graph actually changes.
Agent integration
The NDJSON stream is designed for consumption by AI agents and automation scripts. Pipe it to tools like jq or feed it into an incremental reasoning loop.
See also: CLI Reference, Diff Command, SPEC-008 Watch Mode