Watching for Changes

Requires --features history at install. See Installation.

zetl watch runs continuously, listens for filesystem events in your vault, and takes a silent snapshot on every meaningful change. If you want every edit captured — not just the ones you thought to commit — this is the command.

The idea

When you’re writing, you don’t want to stop and version your thoughts. You want to keep typing. But later, you’ll want to know what you wrote at 3 AM last Tuesday, or recover the paragraph you deleted in a moment of over-zealous editing.

zetl watch solves this by hooking into the same filesystem events your editor emits on save, debouncing them, and committing a snapshot under .zetl/jj/. No dialog, no prompt, no commit message. Just a quiet paper trail.

Running it

zetl -d ~/notes watch

Leave it in a terminal tab (or under tmux, systemd, launchd, whatever you use). It prints a one-line NDJSON event per change by default; pipe to jq or --quiet it if you don’t care.

zetl watch --quiet
zetl watch | jq -r '.event'

Useful flags

Flag	Default	Purpose
`--debounce <MS>`	`150`	Coalesce rapid saves (your editor’s autosave) into one snapshot. Min 10, max 5000.
`--exec <CMD>`	—	Run a shell command for each event; event JSON arrives on stdin.
`--exclude <PATTERN>`	—	Gitignore-syntax pattern, repeatable. Combines with `.zetlignore`.
`--include-hidden`	off	Also watch `.obsidian/`, `.claude/`, etc. `.git/`, `.zetl/`, `node_modules/` stay excluded.

The --exec flag makes watch a general-purpose trigger: rebuild a preview, push notifications to another tool, fire a webhook. See Lifecycle Hooks for structured pre/post-build hooks — watch --exec is the lightweight sibling.

When to run watch

Good fit:

Your laptop is your vault. You write notes all day and you want every save preserved.
You’re in a research flow and you’ll want to time-travel later (Time Travel).
You’re drafting long-form work and a rolling safety net saves you from destructive edits.

Not a good fit:

CI or batch jobs — snapshots are for human editing sessions, not automation.
Shared vaults on servers where many writers modify files concurrently — use --collab mode instead (see Running a Team Server).
Vaults on network shares with flaky FS events — snapshotting may miss changes or fire spuriously.

What actually happens on a snapshot

Each coalesced event triggers a silent jj snapshot inside .zetl/jj/ — separate from any .git/ directory you keep alongside. Your git log stays clean; your zetl history fills up. See Snapshots Under the Hood for the full picture.

No commit messages, no author prompts, no staging area. The whole thing is designed to stay out of your way while still giving --at something to query.

Interaction with `zetl index`

If you already run zetl index as part of a build pipeline, indexing also writes a snapshot when history is enabled. watch and index snapshots coexist: you’ll see them interleaved in zetl history timeline. Running both is fine — duplicate states are collapsed.

Stopping watch

Ctrl-C. No cleanup needed; the jj store is consistent on every snapshot boundary, not at shutdown.

Backlinks

Linked Pages

Lifecycle Hooks

Git-style scripts that run at defined points during a zetl operation. Drop an executable into .zetl/hooks/ named after a lifecycle point, and zetl invokes it with structured JSON on stdin and a handful of ZETL_* environment variables.

These are separate from the AST-level Render Pipeline Hooks — lifecycle hooks fire around the build, not inside it. Use them to publish an RSS feed after zetl build, notify a chat room on on-save, or run a schema validator on post-check.

Lifecycle points

Hook	Fires	Can abort?
`pre-build`	Before `zetl build` renders pages	Yes
`post-build`	After `zetl build` completes	No (warning on non-zero)
`post-index`	After `zetl index` completes	No
`post-check`	After `zetl check` collects diagnostics	No
`pre-serve`	Before `zetl serve` binds	Yes
`on-save`	After a page is saved via `zetl serve`	No
`on-agent`	When an agent API request arrives	No
`on-access-request`	When a user requests page access (collab mode)	No

“Can abort” means a non-zero exit cancels the parent operation; every other hook just logs a warning and continues.

What a hook receives

stdin — a JSON object with vault metadata, the page list, the link graph, and hook-specific fields (e.g. saved for on-save). If history is enabled, a history object is included.
environment — ZETL_HOOK (the lifecycle name), ZETL_VAULT_ROOT, ZETL_THEME, ZETL_VERSION, plus hook-specific vars: ZETL_OUT_DIR on build hooks, ZETL_PORT on serve hooks.
working directory — the vault root, regardless of where zetl was invoked from.
timeout — 30 seconds wall-clock. A hook that hangs is killed.

Writing a hook

Create an executable file named exactly after the lifecycle point (no extension):

# .zetl/hooks/post-build
#!/bin/bash
# Generate an RSS feed from pages with a `date:` frontmatter field.
set -euo pipefail

jq -r '
  .pages
  | map(select(.frontmatter.date))
  | sort_by(.frontmatter.date) | reverse | .[0:20]
  | map("<item><title>\(.title)</title><pubDate>\(.frontmatter.date)</pubDate></item>")
  | "<rss><channel>\(join(""))</channel></rss>"
' < /dev/stdin > "$ZETL_OUT_DIR/feed.xml"

Then mark it executable:

chmod +x .zetl/hooks/post-build

Page History

Requires --features history at install. See Installation.

Every page in your vault has a life story: when you wrote it, how often you’ve edited it, when each backlink appeared, how stable it’s become. zetl history page and the history UI surface that story.

The command

zetl history page "Zettelkasten Method"

Prints a reverse-chronological list of snapshots that touched the page, with timestamp, change-ID, and a short description of what changed (links added, links removed, content modified). Defaults to 20 entries; --limit goes higher.

zetl history page "Zettelkasten Method" --limit 100
zetl history page "Draft Essay" --json | jq

Case-insensitive on the page name; aliases resolve too.

What’s available in the web UI

When you run zetl serve (or publish with zetl build) against a history-enabled binary, every rendered page gains a visually-light metadata strip under the title:

Last changed 2026-03-18 · stable 28d · history

Snapshots Under the Hood

Requires --features history at install. See Installation.

zetl’s history feature is backed by jj (Jujutsu), a VCS that treats the working copy as the commit. This page explains how snapshots actually work, where they live, and how they interact with the rest of zetl.

Why jj, not git

git is excellent when you want deliberate, human-curated commits with messages and author intent. For a note-taking vault, that ceremony is friction:

You don’t want to git add your notes.
You don’t want to write a commit message every time you fix a typo.
You don’t want your git log to become unreadable.

jj gets out of the way. Every change to the working copy is automatically a new change. There’s no staging area. There are no merge conflicts to resolve by hand during normal use. And critically for zetl, jj has a library API (jj-lib) that lets a host program drive snapshotting without spawning a subprocess.

The tradeoff: jj assumes one user per working copy. For multi-writer scenarios, zetl uses CRDTs (Co-editing), not jj.

Where snapshots live

your-vault/
├── Page One.md
├── Page Two.md
└── .zetl/
    ├── index.db
    └── jj/            ← the snapshot store
        ├── repo/
        └── working_copy/

.zetl/jj/, not .git/. This matters:

Time Travel

Requires --features history at install. See Installation.

--at is a global flag that re-runs any read-only zetl command against a past state of your vault. Last Tuesday’s backlinks, the orphan list from before the big refactor, the link count on the day you published — all one flag away.

Why time-travel your notes

You remember writing about Glass-Steagall in the essay you posted in June, but the page doesn’t mention it any more. Did you delete the link, or did you never write it? Without history, you’d dig through git log (if you even use git on your notes) and eyeball old files. With --at:

zetl --at "2024-06-01" links "Banking Reform"

The graph as it stood that day. Same output format, same flags, same wikilink resolver — just a different snapshot under the hood.

Other uses:

Audit a stable conclusion. zetl --at "last monday" check to confirm the vault was clean when you claimed it was.
Recover a deleted page. zetl --at HEAD~5 view "Lost Thought" shows the full rendered page from five snapshots ago.
Compare statistics across time. zetl --at "3 months ago" stats against zetl stats — a graph-size delta without leaving the shell.
Retrace a thought. When did I first link Zettelkasten Method to Spaced Repetition? zetl --at "90 days ago" backlinks "Spaced Repetition".

What `--at` accepts

Expression	Example	Notes
ISO 8601 date	`--at "2024-01-15"`	Resolves to the latest snapshot on or before that date.
Natural-language relative	`--at "3 days ago"`	Also `"last monday"`, `"yesterday"`, `"2 weeks ago"`.
VCS ref	`--at HEAD~1`	One snapshot before the current tip.
Change-ID prefix	`--at abc12`	jj change-ID, any unique prefix.

Quote expressions that contain spaces — your shell will thank you.

Running a Team Server

zetl’s --collab flag turns zetl serve into a multi-user editing server: passkey login, real-time CRDT co-editing, per-user git commits, and scoped invitations. Everything is in-tree — there’s no feature flag to enable at install time. If you can run zetl serve, you can run a team server.

The shape of a collab vault

A collab vault is a normal Markdown vault plus a .zetl/collab/ directory:

.zetl/collab/server.key — the server’s Ed25519 signing key (for session cookies and invitations).
.zetl/collab/users.db — SQLite store for passkeys, sessions, and invitation nonces.
.zetl/collab/wal/ — write-ahead log for the CRDT engine. Survives crashes.

These files are created on first run. You never edit them by hand.

First run: bootstrap the owner

The very first time you start a collab server, you need to bootstrap an owner account. --init-owner creates one, prints a 12-word recovery phrase, and exits into the normal serve loop:

zetl -d ~/notes serve --collab --init-owner --owner-name Alice

The terminal will print something like:

Owner created: Alice
Recovery phrase (write this down — you will not see it again):

  palm  tornado  ladder  oyster  casual  umbrella
  desert  finger  enlist  brave  coconut  strong

Server listening on http://localhost:3000

Save that phrase. It’s your only way back into the account if you lose your passkey, and zetl will not show it to you a second time. Paper, password manager, encrypted notes file — pick one and commit.

Installation

zetl ships prebuilt binaries for Linux, macOS, and Windows. The installer script handles platform detection, download, and wiring up the man page and shell completions. If you prefer to build from source, that path is documented below too.

Prebuilt binaries (recommended)

macOS and Linux:

curl -fsSL https://files.anuna.io/zetl/latest/install.sh | bash

The script detects your OS and architecture, downloads the right tarball, installs the binary to ~/.local/bin, and generates the man page and shell completions.

Windows:

Download zetl-windows-x86_64.zip from files.anuna.io/zetl/latest, extract zetl.exe, and place it somewhere on your PATH.

Pinning to a specific version

VERSION=0.6.1 curl -fsSL https://files.anuna.io/zetl/latest/install.sh | bash

Custom install location

INSTALL_DIR=/usr/local/bin curl -fsSL https://files.anuna.io/zetl/latest/install.sh | bash

Watching for Changes

The idea

Running it

Useful flags

When to run watch

What actually happens on a snapshot

Interaction with zetl index

Stopping watch

Related

Backlinks

Interaction with `zetl index`