Troubleshooting

Things that go wrong, and what to do. Each entry is Symptom → Diagnosis → Fix. Use the table of contents to jump; most issues resolve in one or two steps.

Dead-link warnings for pages I haven’t written yet
zetl reason prints an error about not being compiled in
zetl --at ... fails or is not recognised
.obsidian/ or .claude/ contents aren’t indexed
Terminal viewer shows a single pane instead of two
zetl serve won’t start on port 3000
My hooks aren’t running
Safe-mode blocks my hooks
zetl index feels slow on a large vault
Collaborative edits conflict or look stale
I lost my passkey
Capability-URL reader errors
Getting a useful bug report

Dead-link warnings for pages I haven’t written yet

Symptom. zetl check reports [[Future Note]] as a dead link, even though you intended to write that page later.

Diagnosis. Not a bug. zetl flags every [[wikilink]] whose target doesn’t yet exist as a dead link — that’s the definition. Many people use this as a “stub list” of pages to write.

Fix.

Create the target page (even as a one-liner) when you’re ready.
If you want to suppress a cluster of planned stubs, put them under a folder that’s ignored: add the folder to .zetlignore with gitignore-style syntax.
Scope a check to ignore them for a single run: zetl check --fail-on error only fails on syntax/SPL errors, not dead links.

See Finding Orphans and Dead Links for the full workflow.

`zetl reason` prints an error about not being compiled in

Symptom. Running zetl reason status prints a message explaining that the reasoning feature isn’t compiled in, and exits non-zero.

Diagnosis. zetl’s reasoning layer is gated behind a Cargo feature flag to keep the core binary small. Your install didn’t enable it.

Fix. Reinstall with the reason feature:

cargo install --path . --features reason

See Installation for the complete feature matrix. The same pattern applies to the history, semantic, and mcp flags.

`zetl --at ...` fails or is not recognised

Symptom. zetl --at "3 days ago" links "Some Page" fails or acts as if --at were ignored.

Diagnosis. Time-travel queries require the history feature.

Fix.

cargo install --path . --features history

History uses jj-backed snapshots stored in .zetl/jj/ — not your repo’s .git/. Once installed, --at works on every read-only subcommand. See Time Travel.

`.obsidian/` or `.claude/` contents aren’t indexed

Symptom. Files under .obsidian/, .claude/, .vscode/, or similar dot-directories don’t appear in search, backlinks, or the graph.

Diagnosis. zetl skips directories whose name starts with . by default. This keeps editor metadata, agent working files, and VCS internals out of your knowledge graph.

Fix. Two options:

Include all hidden directories for one run: zetl index --include-hidden.
Re-include a specific dotdir permanently by negating it in .zetlignore:

# .zetlignore at vault root
!.obsidian/

Run zetl --verbose index to see which paths were skipped and why. See Configuration for the full precedence stack.

Terminal viewer shows a single pane instead of two

Symptom. zetl view "Some Page" opens a single-column layout instead of the two-pane reader with context cards on the right.

Diagnosis. Your terminal is narrower than 60 columns. The two-pane viewer falls back to single-pane in narrow windows.

Fix. Resize the terminal to at least 60 columns (80+ is more comfortable). You can also adjust the main-pane width:

zetl view "Some Page" --main-width 60

See Terminal Viewer for keybindings and layout options.

`zetl serve` won’t start on port 3000

Symptom. zetl serve exits with an address-in-use error.

Diagnosis. Another process is bound to port 3000.

Fix. Pick a different port:

zetl serve --port 8080

If you want to know which process is holding 3000: lsof -i :3000 on macOS/Linux. See Web Server.

My hooks aren’t running

Symptom. You added a script to .zetl/hooks/post-build, but zetl build completes without running it.

Diagnosis. Almost always one of three things:

The file isn’t marked executable.
The file is named incorrectly (no extension — just the lifecycle name).
It’s not in the right directory (.zetl/hooks/ for vault, .zetl/themes/<theme>/hooks/ for theme).

Fix.

chmod +x .zetl/hooks/post-build
zetl hook list            # verify discovery
zetl hook run post-build  # manually invoke with real context

zetl hook list prints every hook zetl sees, with the source (vault or theme) and the lifecycle name. If your hook isn’t listed, zetl isn’t seeing it. See Lifecycle Hooks.

Safe-mode blocks my hooks

Symptom. Running with --safe-mode, hooks that normally work are skipped.

Diagnosis. Expected. --safe-mode skips every vault hook unconditionally and only runs theme hooks that are explicitly declared in the theme’s [[theme.hooks]] manifest table. It’s the intended posture for previewing untrusted vaults.

Fix. Two paths:

If you trust the vault, drop --safe-mode.
If you’re writing a theme that should work under safe-mode, declare each hook in theme.toml:

[[theme.hooks]]
stage = "transform"
extension_id = "callouts"
summary = "Render :::note blocks as styled callouts"

See Render Pipeline Hooks and docs/hook-security.md in the source tree for the full security model.

`zetl index` feels slow on a large vault

Symptom. Index times climb as the vault grows.

Diagnosis. The cache is two-tier: mtime first, then BLAKE3 content hash. Unchanged files should be skipped almost instantly on subsequent runs. If every index is slow, either the cache is being bypassed or every file really has changed.

Fix.

Don’t use --no-cache unless you genuinely need a full rescan (e.g. after upgrading zetl across a cache-format bump). It forces every file to re-parse.
Run with -v or -vv to see per-file scan decisions:

zetl --verbose index
# → [zetl] scan: skipped .obsidian reason=dotdir
# → [zetl] scan: cached hit Some Page.md

Check for a tool that’s rewriting mtimes on every file (some sync clients do this). Those invalidate the first-tier cache on every run; the hash tier still saves reparsing, but the file list scan grows.

Collaborative edits conflict or look stale

Symptom. In --collab mode, your edits don’t appear for another user, or you see a version from an hour ago.

Diagnosis. CRDT merges are eventual. If the WebSocket dropped (network blip, laptop sleep), the two sides resync on reconnection. A stale render usually means a browser tab missed reconnection.

Fix. Refresh the page. The CRDT state on disk is authoritative. If a refresh doesn’t help, confirm the server is still running and the WebSocket reconnected (browser devtools → Network → WS).

For longer outages, every save in collab mode auto-commits to git with author attribution, so nothing is lost — you can git log the vault to reconstruct. See Co-editing.

I lost my passkey

Symptom. You’ve cleared browser data, changed devices, or lost your hardware key, and you can’t sign in to the collab server.

Diagnosis. Passkeys are device-bound. The 12-word BIP39 mnemonic printed when you ran --init-owner is the recovery path.

Fix. Open /auth/recovery on the running server, enter your display name and the 12-word phrase, and register a new passkey when prompted. See Passkeys and Accounts.

If you never saved the mnemonic: another admin on the same vault can re-invite you. If you were the only admin, the vault files are still on disk — you can stand up a fresh collab server on the same directory and re-bootstrap as owner.

Capability-URL reader errors

Symptom. You opened a capability-URL static site and the shim renders a red error banner — “signature did not verify”, “could not decrypt”, etc.

Diagnosis. These errors are thrown by the in-browser shim before any decryption happens. They’re described in detail in docs/reader-troubleshooting.md in the source tree. The short version: most of them mean contact your wiki operator, not fix your browser.

Fix. The single rule: never override a signature check or paste secrets into a console on a wiki operator’s advice. Close the tab and contact them. Quote the error kind (the slug after err-) and the URL prefix before #. See Capability URLs.

Getting a useful bug report

When filing an issue, include:

zetl --version           # binary version
zetl check --json        # current vault health as structured data
zetl stats               # counts and cache stats

Also note:

Which feature flags were enabled at install (--features reason,history,...). This is the single most useful piece of context — many “missing command” reports are feature-flag mismatches.
OS and architecture (uname -a on macOS/Linux).
Whether the bug reproduces from a fresh clone or only in your existing vault.
The exact command you ran and its full output (stdout + stderr).

File issues at https://codeberg.org/anuna/zetl. For questions that aren’t bugs — “does zetl do X?” — check FAQ first.

Backlinks

FAQ ×2
Index

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

Configuration

Every knob zetl exposes: environment variables, ignore files, theme.toml, and the .zetl/ state directory. Nothing here is required — zetl runs on a bare directory of Markdown with zero configuration. Read this page when you want to change defaults.

Environment variables

zetl-specific variables are prefixed ZETL_. The binary also honours NO_COLOR (a de-facto standard).

Read by the CLI

Variable	Equivalent flag	Purpose
`ZETL_DIR`	`-d, --dir`	Default vault root.
`ZETL_FORMAT`	`-f, --format`	`json`, `table`, or `auto`.
`ZETL_NO_CACHE`	`--no-cache`	Force full rescan.
`NO_COLOR`	`--no-color`	Disable ANSI colour.
`ZETL_HOSTNAME`	`--hostname` (on `serve --collab`)	WebAuthn relying-party hostname.
`ZETL_SERVER_KEY_SEED`	`--server-key-seed` (on `serve --collab`, `derive-ssh-key`)	BIP39 mnemonic for deterministic key derivation in ephemeral deployments.
`ZETL_CAP_SITE_URL`	`--site-url` (on `cap invite`)	Canonical site URL for capability-URL rendering.
`ZETL_CAP_PAIR_PHRASE`	`--phrase` (on `cap pair`)	Pinned SPAKE2 phrase; test-harness hook.

Pass any of these once in your shell profile and skip the corresponding flag forever.

Exported to hooks

Every hook zetl launches inherits these:

Variable	Value
`ZETL_HOOK`	Hook name (e.g. `post-build`, `callouts`).
`ZETL_VAULT_ROOT`	Absolute path to the vault.
`ZETL_THEME`	Active theme name. Empty string if no theme.
`ZETL_VERSION`	zetl binary version (e.g. `0.5.0`).
`ZETL_AST_SCHEMA_VERSION`	AST schema version (SemVer, e.g. `1.0.0`). Independent of `ZETL_VERSION`.
`ZETL_MODE`	`build` or `serve`.
`ZETL_OUT_DIR`	Build output directory. Empty string under `serve`.
`ZETL_VERBOSE`	`true` / `false`.
`ZETL_HOOK_PATH`	Absolute path to the hook executable. Render-pipeline only.
`ZETL_EXTENSION_ID`	Hook extension id (filename stem, minus `\d+-` ordering prefix). Render-pipeline only.
`ZETL_HOOK_DEPTH`	Nesting depth; zetl increments on every child invocation to detect runaway recursion.
`ZETL_AT`	Time expression passed via `--at`. Set only when time-travel is active.

Pin your hook against ZETL_AST_SCHEMA_VERSION, not ZETL_VERSION — the AST schema changes far less often. See Render Pipeline Hooks.

Persistent-mode hooks also receive both versions in their JSON init message, alongside a capability probe. See tools/zetl-ast-reference.md in the source tree for the wire protocol.

Ignore files

zetl layers five sources of file-exclusion. Later layers override earlier ones except for level 1 (which is absolute).

CLI Overview

Every zetl subcommand at a glance, with the flags writers actually use. This page is the reference — the linked how-to pages give the narrative.

Run zetl <cmd> --help for the authoritative flag list for any command. This guide tracks zetl v0.5.0.

Global flags

Every subcommand honours these, wherever they make sense.

Flag	Env var	Purpose
`-d, --dir <DIR>`	`ZETL_DIR`	Vault root. Default: `.` (current directory).
`-f, --format <FORMAT>`	`ZETL_FORMAT`	`json` / `table` / `auto`. Auto picks table for a TTY, JSON for a pipe.
`--json`	—	Shorthand for `-f json`.
`--no-cache`	`ZETL_NO_CACHE`	Ignore the cached index; force a full rescan.
`--no-color`	`NO_COLOR`	Disable ANSI colour.
`-q, --quiet`	—	Suppress non-essential output.
`-v, --verbose`	—	Increase verbosity. Repeatable (`-vv`).
`--no-input`	—	Disable interactive prompts; fail if input is needed.
`--at <TIME-EXPR>`	—	Query the vault at a historical point. Requires `--features history`. See Time Travel.
`-V, --version`	—	Print zetl version.

Subcommand summary

Command	Description	Feature flag
`index`	Build or refresh the link index	—
`list`	List every page in the vault	—
`stats`	Summary counts and most-linked pages	—
`links`	Forward links from a page	—
`backlinks`	Backlinks to a page	—
`check`	Dead links, orphans, syntax, SPL diagnostics	—
`search`	Full-text search (BM25, optional semantic)	`semantic` for `--semantic`/`--hybrid`
`similar`	SimHash title matches	—
`path`	Shortest link path between two pages	—
`export`	Dump the full link graph	—
`blocks`	List or resolve Merkle blocks	—
`view`	Two-pane terminal reader	—
`serve`	Local web server	—
`build`	Static-site HTML export	—
`watch`	Stream vault changes as NDJSON	—
`diff`	Graph diff against a git ref or snapshot	—
`theme`	List / install / remove / export themes	—
`hook`	Author, test, and inspect hooks	—
`ecosystem`	Probe Pandoc / mdBook / remark runtimes	`ecosystems-v1`
`ast`	Inspect or diff zetl-ext AST	—
`agent`	Run an agent-lifecycle hook	—
`invite`	Multi-user invitation token	collab (built-in)
`agent-token`	Derive a headless API token	collab
`derive-ssh-key`	Derive an SSH ed25519 key from a mnemonic	collab
`cap`	Capability-URL static sharing operations	—
`reason`	SPL queries over the vault	`reason`
`mcp`	Start an MCP server	`mcp`
`delegate`	Issue a delegate JWT	`mcp`
`completions`	Emit a shell completion script	—
`man`	Emit a roff(7) man page	—

zetl index

Scan the vault and write the cached link index to .zetl/index.json. Incremental by default; --no-cache forces a full rescan.

Key flags: --exclude <PATTERN> (repeatable gitignore syntax), --include-hidden (walk .claude/, .obsidian/, etc.).

zetl index
zetl -d ~/notes index --exclude 'drafts/**'

zetl list

Enumerate every page zetl can see. Useful in pipes.

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

FAQ

Answers to questions people actually ask before they install zetl. Each answer is short; follow the link for depth.

Does zetl modify my files?

No. zetl treats vault files as read-only. The only directory zetl writes to is .zetl/ at the vault root — the index, semantic model cache, optional jj snapshots, and (in collab mode) the auth and CRDT state all live there. The whole .zetl/ directory is disposable: delete it, rerun zetl index, and you’re back where you started.

See Local-first and Vaults.

Is zetl compatible with Obsidian / Logseq / Foam / Dendron?

Yes. zetl shares the [[wikilink]] syntax those tools use. Point zetl at an existing Obsidian or Logseq vault and zetl index just works — nothing in .obsidian/ or logseq/ is touched. You can keep editing in your current tool and use zetl for search, reasoning, history, or static-site export.

Import-specific notes live at Migrating from Obsidian.

Can I use zetl offline?

Yes. Everything — parsing, graph queries, reasoning, the web UI, collab, the terminal reader — runs locally. The only network activity by default is the optional one-time semantic-model download when you first use semantic search; everything else is file-system-local. You can use zetl on a plane.

See Local-first.

Do I need to learn Lisp to use zetl?

Capability URLs

Capability mode is zetl’s answer to: “I want to share my wiki with a dozen friends, read-only, without running a server, but I don’t want the whole internet reading it.” The output is a plain static site — hostable on any CDN, any S3 bucket, any sftp’d directory — where access is gated by a secret in the URL fragment. No accounts, no server-side auth, nothing to rotate but the URLs themselves.

If you want multi-user editing, you want Running a Team Server. Capability mode is for publishing.

The idea in one paragraph

Each page is encrypted at build time with a cohort-specific key. Invite URLs look like https://wiki.example.com/welcome.html#k=<base64-secret>. The #fragment — by design of the HTTP spec — is never sent to the server. The reader’s browser, executing a small JavaScript shim, pulls the key out of the fragment, decrypts the page locally, and verifies a vault-level Ed25519 signature so nobody can serve them a forged page. Revocation is per-cohort: you rotate the cohort’s salt and re-deploy, old URLs stop decrypting.

Formal spec: see docs/capability-mode.md in the zetl repo.

Setting up a capability site

1. Generate the keys

zetl cap genkey

This prints two secrets to stdout, exactly once:

ZETL_CAP_SECRET — the 48-byte content-encryption secret.
ZETL_CAP_SIGNING_KEY — the Ed25519 vault-signing private key.

Capture them somewhere safe (a secret store, a password manager, a sealed envelope). You’ll need ZETL_CAP_SECRET on every build and ZETL_CAP_SIGNING_KEY whenever you rotate the signing key.

Passkeys and Accounts

zetl doesn’t do passwords. Instead, every collab account is backed by one or more WebAuthn passkeys — Touch ID, Face ID, Windows Hello, a YubiKey, or any FIDO2 authenticator. A 12-word BIP39 recovery phrase is the break-glass fallback, and the same phrase deterministically derives the collab server’s signing key and a git SSH key.

Why passkeys

Passwords get phished, reused, and leaked. Passkeys are bound to the origin (so a phishing site can’t steal them), require a local user gesture (touch, face, PIN), and never leave your device in usable form. For a small team vault, this is the right default: lower operational burden than password-plus-2FA, and nothing to leak in a database breach.

Registering on first login

The first time you open a collab server, you log in by display name (e.g. Alice) and then register a passkey. The browser prompts whatever authenticator is available — Touch ID on a Mac, Windows Hello on a PC, a hardware key, or a phone acting as a security key.

Subsequent logins are one tap. No username/password fields.

You can register multiple passkeys on one account — laptop Touch ID, phone Face ID, a YubiKey in a drawer. If one device dies, the others still work. Manage them from /_admin/passkeys in the web UI.

Recovery

If you lose access to every passkey — laptop stolen, phone dead, YubiKey at the bottom of a river — you recover using your 12-word phrase:

Open /auth/recovery on the server.
Enter your display name and the 12 words.
zetl issues a fresh session and deletes all your existing passkeys.
Register a new passkey on whatever device you’re on now.

Write the phrase down when you first see it. Don’t type it into a browser extension. Don’t email it to yourself. Paper in a drawer, or a line in your password manager, is the sweet spot for a small team.

Co-editing

When two people open the same page in a --collab vault, their edits merge without conflicts. Under the hood zetl uses a Peritext CRDT engine over WebSocket: every keystroke is a small op that both clients apply in the same causal order, so the document converges no matter who’s typing where. Think Google Docs, but local-first and committed to git.

What you see as a user

Open a page in the web UI. If someone else is editing it, you see their cursor as a coloured caret with their display name floating above it. Your edits and theirs interleave in real time. There’s no “save” button — everything is continuously streamed to the server.

A small idle period (a few seconds of quiet, or navigating away) triggers an auto-commit: zetl writes the page to disk and runs git commit with the author set to the person whose session made the last edits. If Alice and Bob were both editing, the commit message notes both contributors.

This means your vault’s git log is an authentic editing history. You can git blame a line and find out who wrote it. You can revert a page with git revert. The CRDT layer is an editing affordance; the source of truth is still Markdown on disk, tracked by git.

Crash recovery

Between auto-commits, in-flight edits live in a write-ahead log at .zetl/collab/wal/. If the server dies mid-edit — process killed, power cut, container restarted — the WAL is replayed on next startup so nothing is lost. You shouldn’t ever need to think about this, but it’s why zetl serve --collab can take an extra second to come up after a hard crash.

If you deploy in an ephemeral container where .zetl/collab/wal/ vanishes on redeploy, your CRDT merge state is gone. Auto-commit frequency is your backstop: most “in-flight” edits are short-lived, and anything older than a few seconds is in git already. For long-lived containers you can persist the WAL directory on a volume.

External edits still work

The server polls git every 30 seconds (tunable via --git-poll-interval on serve) for commits that landed outside the UI — a git pull in a terminal, a push from another machine, a hook that rewrote a page. Those changes show up in the editor without anyone refreshing. If you’re actively editing when an external change lands on the same page, zetl merges at the CRDT layer just as it would for a second live user.

Authorship and git

Render Pipeline Hooks

Transform a page mid-build by mutating a typed AST rather than its serialised form. Unlike the around-the-build Lifecycle Hooks, render-pipeline hooks run on every matching page as it moves through the renderer — callouts, custom blocks, link rewrites, banner injection, citation expansion, anything that needs to touch structure.

Hooks live under .zetl/hooks/<stage>.d/ (or .zetl/themes/<name>/hooks/<stage>.d/ for theme-bundled ones) and stay resident for the duration of a build via a JSON-lines protocol over stdin/stdout. No per-page subprocess spawn, no shell fork on every paragraph.

The three stages

Stage	Payload at the boundary	Typical use
`pre-parse`	raw Markdown string	Frontmatter rewrites, include/import expansion, prelude injection
`transform`	typed AST (`zetl-ast` schema v1)	Callouts, custom blocks, link-graph mutations, ecosystem plugins
`post-render`	HTML fragment string	Banner injection, post-processing, accessibility fixes

Stages run in that order, once per page. A pre-parse hook sees what the author wrote; a transform hook sees the parsed tree; a post-render hook sees the nearly-final HTML.

A hook is two files

Scaffold one with the authoring CLI — it writes the skeleton, a sidecar manifest, and a seeded fixture so zetl hook test passes immediately:

zetl hook new transform callouts                # Python (default)
zetl hook new pre-parse prelude --lang sh       # shell
zetl hook new post-render banner --lang js      # JavaScript

Resulting layout:

.zetl/hooks/transform.d/
  callouts.py            # persistent-mode skeleton (executable)
  callouts.py.toml       # sidecar manifest — composition reads <name>.<ext>.toml
tests/hook-fixtures/callouts/
  input.md
  expected.json          # golden output, seeded so `hook test` passes

The sidecar TOML manifest is where all the interesting configuration lives:

# .zetl/hooks/transform.d/callouts.py.toml
stage = "transform"
mode  = "persistent"
extension_id = "callouts"

[selector]
glob = "**/*.md"
frontmatter = "layout == 'note' && !draft"
content = "re:^> \\[!"          # pages containing callout syntax

[contract]
preserves = ["Wikilink", "Embed"]   # these node types must survive untouched
idempotent = true                    # running twice = running once
may_restructure = false              # pre-parse only; denied at transform
expansion_bound = 2.0                # output ≤ 2× input size

[timeouts]
run_ms = 200

Web Server

zetl serve starts a local web server that renders your vault as a browsable site. You get rendered Markdown, working wikilinks, a live backlink panel, a persistent graph mini-map, and an in-browser editor. It’s the fastest way to actually read — and edit — a vault of more than a handful of notes.

Why run a server

A static export (Static Site Export) shows your vault as it was when you last built it. A terminal viewer (Terminal Viewer) shows one note at a time. zetl serve is what you want between those: a live view of the vault right now, with:

Rendered pages — Markdown, wikilinks, embeds, and code blocks, rendered through Minijinja templates with YAML frontmatter in scope.
Backlinks panel — every page that points here, updated on every save.
Transclusion panel — forward-link excerpts as cards in the right rail, connected to anchors in the main text by SVG bridges (the same Xanadu idea as the terminal viewer).
Live search — full-text search across the vault from a modal.
CodeMirror editor — click Edit, change the note, hit Save. The index rebuilds on save; no reload dance. A delete button is a click away.
Persistent graph mini-map — a Sigma.js WebGL graph of your vault, docked bottom-right, that survives page navigation (no flash, no re-layout).
History strip — when zetl was built with --features history, every page shows when it last changed and links to its timeline. See Page History.

Running it

zetl serve                            # http://localhost:3000
zetl -d ~/notes serve
zetl serve --port 8080
zetl serve --theme paper

Open http://localhost:3000/ to land on the vault index. Wikilinks in rendered pages are clickable. Ctrl-P (or whatever the active theme binds) opens the search modal.

Flags that matter

Flag	Default	Purpose
`-p, --port <PORT>`	`3000`	TCP port.
`--theme <THEME>`	`default`	Theme from `.zetl/themes/<name>/`. See Customising the Look.
`--public <DIR>`	—	Files in this directory override generated pages (good for `robots.txt`, custom error pages).
`--collab`	off	Switches to multi-user mode with passkeys and CRDT sync. See Running a Team Server.
`--safe-mode`	off	Skip every hook except ones declared in the theme.
`--at <TIME-EXPR>`	—	Serve a past snapshot. See Time Travel.
`--exclude <PATTERN>`	—	Gitignore-syntax exclusion, repeatable.

Single-user vs collab

Out of the box, zetl serve is single-user and trusts whoever reaches the port. There’s no login, no accounts; editing works immediately. This is the right mode when the server is on your laptop or behind a VPN.

With --collab, zetl turns into a multi-user server: WebAuthn passkey login, real-time CRDT editing over WebSockets, access control, invitations. That whole stack — bootstrapping an owner, inviting collaborators, deterministic server keys — lives in Running a Team Server.

Terminal Viewer

zetl view is a Xanadu-inspired two-pane reader for reading linked notes without leaving the terminal. It exists because most of the time you don’t want a browser — you want to sit with one note, glance at what it points to, and jump onwards when something catches your eye.

Why two panes

When you read a note in a normal editor, forward-links are just names — [[Zettelkasten Method]] tells you nothing about what Zettelkasten Method actually says. Ted Nelson’s original vision for Xanadu put the cited text right next to the citing text, bridged by a visible connector. zetl view does exactly that in a TTY:

Main pane (left) — the note you asked for, rendered as Markdown. Every wikilink is annotated with a numbered anchor glyph [1], [2], [3] in reading order.
Context column (right) — a stack of context cards, one per forward link. Each card shows the first few lines of the linked note, coloured to match its anchor.
Bridge column (middle) — coloured connectors from each [N] anchor to its card, so your eye can follow the citation at a glance.

In terminals narrower than 60 columns the layout collapses to single-pane and context cards become inline footnotes. You lose the bridges but keep the anchors.

Opening a page

zetl view "Zettelkasten Method"      # by page name
zetl view                            # interactive page picker
zetl view "Project Notes" --context-lines 10
zetl view "Project Notes" --main-width 65

With no argument, zetl view launches an interactive picker of every page in the vault — type to filter, Enter to open.

Flags

Flag	Default	Purpose
`--context-lines <N>`	`5`	Lines shown per context card. Range 1–20.
`--main-width <pct>`	`58`	Percent of terminal columns for the main pane. Range 30–80.
`--at <TIME-EXPR>`	—	Read a past snapshot (see Time Travel).
`-d, --dir <DIR>`	`.`	Vault root.

Keybindings

Key	Action
`j` / `k`	Scroll down / up (or cycle anchors in focus mode)
`Ctrl-d` / `Ctrl-u`	Half-page down / up
`g` / `G`	Jump to top / bottom of the note
`Tab`	Toggle between scroll mode and focus mode
`Enter`	Navigate to the focused link
`[` / `]`	Session history: back / forward
`/`	Open the page picker
`?`	Toggle the keybindings overlay
`q`	Quit

Focus mode is what makes the navigation fast. Hit Tab, then j/k steps from one anchor to the next (not one line at a time); the bridge column highlights the selected anchor’s connector; Enter opens that page. [ returns to where you came from, so you can explore breadth-first through a chain of notes and back-track without losing your place.

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.

Finding Orphans and Dead Links

zetl check is the vault-health command. It reports three kinds of problem — dead links, orphan pages, and syntax errors — and optionally a fourth, SPL diagnostics, if you use the reasoning layer. Run it before a big refactor, before a publish, and in CI.

zetl check

Exits non-zero if anything at error level is found. That makes it a drop-in CI step.

The two main health signals

Dead links

A dead link is a [[wikilink]] that points at a page that does not exist. You typed [[Zettelkasten Methog]] and meant [[Zettelkasten Method]]; or you deleted a page without updating the notes that cited it.

zetl check --dead-links

Two ways to fix each one:

Create the page. If the link represents a real idea that deserves a page, the dead link is a prompt: go write the note. This is the positive use of dead links — they are a TODO list generated by your past self.
Rename or delete the link. If the target was a typo, fix the typo. If the idea no longer deserves a page, remove the link or replace it with plain prose.

The zetl similar "Zettelkasten Methog" command (see Similar Pages) pairs naturally with dead-link review: for each dead link, check whether you meant an existing page.

Troubleshooting

Contents

Dead-link warnings for pages I haven’t written yet

zetl reason prints an error about not being compiled in

zetl --at ... fails or is not recognised

.obsidian/ or .claude/ contents aren’t indexed

Terminal viewer shows a single pane instead of two

zetl serve won’t start on port 3000

My hooks aren’t running

Safe-mode blocks my hooks

zetl index feels slow on a large vault

Collaborative edits conflict or look stale

I lost my passkey

Capability-URL reader errors

Getting a useful bug report

Related

Backlinks

`zetl reason` prints an error about not being compiled in

`zetl --at ...` fails or is not recognised

`.obsidian/` or `.claude/` contents aren’t indexed

`zetl serve` won’t start on port 3000

`zetl index` feels slow on a large vault