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.

zetl list --json | jq -r '.pages[].title'

zetl stats

Counts: files, links, orphans, dead links, plus the most-linked pages. --top <N> sets how many leaders to print (default 10).

zetl links

Forward links from a page. See Following Links.

Key flags: --depth <N> (traverse N hops), --context <N> (include N characters of surrounding text), --fuzzy (case-insensitive partial page-name match), --with-conclusions (SPL conclusions each linked page contributes; requires reason).

zetl links "Zettelkasten Method"
zetl links "Zettelkasten Method" --depth 2

zetl backlinks

Same flags as zetl links, but inbound. See Backlinks.

zetl backlinks "Zettelkasten Method" --context 60

zetl check

Validate vault health: dead links, orphans, syntax errors, SPL diagnostics, and SPL drift. See Finding Orphans and Dead Links.

Key flags: --dead-links, --orphans, --syntax, --spl, --drift (show only that category), --fail-on error|warning (CI gate), --theme <NAME> (for hook-discovery).

zetl check
zetl check --dead-links --fail-on error

zetl search

Full-text search across vault content. See Searching.

Key flags: --limit <N> (default 50), --context <N> (default 40), --case-sensitive, --path <GLOB> (restrict to matching files), --near <PAGE> with --depth <N> (restrict to pages within N link-hops of PAGE), --semantic and --hybrid (require --features semantic).

zetl search "wikilink"
zetl search "API" --near "Backend Overview" --depth 2
zetl search "memory" --hybrid --limit 20

zetl similar

SimHash locality-sensitive title match. See Similar Pages.

Key flags: --threshold <N> (max Hamming distance, default 12), --limit <N> (default 10).

zetl path

Shortest link path between two pages. See Following Links.

Key flag: --max-depth <N> (default 10).

zetl path "Quick Start" "Capability URLs"

zetl export

Dump the full link graph — pages + edges — to JSON. Pipe into Gephi, Obsidian Canvas, or your own tooling.

zetl blocks

List the Merkle blocks of a page, or resolve a block by its BLAKE3 hash.

zetl blocks "Zettelkasten Method" --type heading
zetl blocks --resolve 0f3ac1

zetl view

Xanadu-style two-pane terminal reader. See Terminal Viewer.

Key flags: --main-width <pct> (30–80, default 58), --context-lines <N> (1–20, default 5). Run without a page name to open a picker.

zetl serve

Local web server. See Web Server.

Key flags: --port <PORT> (default 3000), --theme <NAME>, --public <DIR> (files that override generated pages), --collab (multi-user), --init-owner / --owner-name <NAME> (first-time collab bootstrap), --hostname <HOST> (WebAuthn relying-party; env: ZETL_HOSTNAME), --server-key-seed <MNEMONIC> (deterministic keys; env: ZETL_SERVER_KEY_SEED), --git-poll-interval 30s, --safe-mode (only theme-declared hooks run).

zetl serve
zetl serve --collab --init-owner --owner-name Jo
zetl serve --port 8080 --theme fountain

zetl build

Generate a static HTML site. See Static Site Export.

Key flags: -o, --out-dir <DIR> (default dist), --theme <NAME>, --public <DIR>, --site-url <URL> (absolute og:image URLs), --safe-mode, --strict-parsers (promote mixed-parser warnings to errors).

zetl build
zetl build --theme docs --site-url https://notes.example

zetl watch

Watch the vault for changes and emit NDJSON graph events. See Watching for Changes.

Key flags: --debounce <MS> (default 150, min 10, max 5000), --exec <CMD> (shell command run once per event with the event JSON on stdin), --exclude, --include-hidden.

zetl watch --exec 'jq .type'

zetl diff

Graph-level diff against a git ref or jj change-ID.

Key flags: --from <REF> or --since <DATE>, --filter pages|links|orphans|dead-links.

zetl diff --from HEAD~5
zetl diff --since "last monday" --filter dead-links

zetl theme

Manage themes. See Customising the Look.

Subcommands:

Subcommand	Purpose
`zetl theme list`	List bundled + installed themes
`zetl theme install <SOURCE>`	Install from git (`user/repo`, URL, `git@…#ref`); flags: `--path`, `--name`, `--force`
`zetl theme remove <NAME>`	Remove an installed theme
`zetl theme export <NAME>`	Copy a bundled theme into `.zetl/themes/` for customisation; `--force`

zetl hook

Author, test, and inspect hooks. See Lifecycle Hooks and Render Pipeline Hooks.

Subcommand	Purpose
`zetl hook list`	Active hooks for this vault + theme
`zetl hook run <NAME> [-- <EXTRA>...]`	Run a lifecycle hook with real vault context
`zetl hook new <STAGE> <NAME>`	Scaffold a render-pipeline hook; flags: `--lang py\|js\|sh`, `--ecosystem pandoc\|mdbook\|remark`, `--force`
`zetl hook test <NAME>`	Run a hook against its fixture and diff the golden; `--update` regenerates
`zetl hook fixture --from <PAGE> --hook <NAME>`	Capture a vault page into the hook’s fixture dir
`zetl hook watch <NAME>`	Live-reload the hook’s persistent-mode subprocess on source change
`zetl hook coverage`	Per-hook coverage from the most-recent build; `--stage`, `--json`
`zetl hook dry-run <STAGE>/<NAME>`	Print pages the hook’s selector matches; hook is not invoked; `--limit`, `--theme`
`zetl hook capabilities`	Probe every hook’s supported stages + AST types; `--stage`, `--json`

zetl ecosystem

Probe plugin ecosystems. Requires ecosystems-v1 feature flag.

zetl ecosystem check — per-ecosystem detection, version, configured-hook count, reachable plugins. Exits 0 when all configured ecosystems are available. See Plugin Ecosystems.

zetl ast

Inspect the zetl-ext AST for a page or diff two AST JSON documents.

zetl ast sample <FILE> — print canonical AST JSON. --stage pre-parse|transform|post-render chooses which stage’s input to emit (default transform).
zetl ast diff <BEFORE> <AFTER> — tree-aware structural diff; non-zero exit on non-empty diff.

zetl agent

Agent lifecycle integration for LLM / automation hooks.

zetl agent run <NAME> [-- <EXTRA>...] — run an on-agent hook with task context. Flags: --pages <TARGET>..., --budget <TOKENS> (0 = unlimited), --theme.

zetl invite

Generate an invitation token for a collaborator. See Invitations.

Key flags: --as <USER> (inviter), --role reader|editor|admin, --pages <GLOB> (scoped grant), --expires 72h|24h|7d (default 72h), --host, --port (URL generation).

zetl invite --as alice --role editor
zetl invite --as alice --role reader --pages 'projects/*' --expires 7d

zetl agent-token

Derive a headless API token from a BIP39 mnemonic.

zetl agent-token --mnemonic "word1 word2 ... word12"

zetl derive-ssh-key

Derive an SSH ed25519 key from a BIP39 mnemonic. Useful for ephemeral containers where one seed covers the server key and the git SSH key.

zetl derive-ssh-key --mnemonic "word1 ... word12" --out /root/.ssh/id_ed25519

zetl cap

Capability-URL static-site operations. See Capability URLs.

Subcommand	Purpose
`zetl cap genkey`	Emit the content-encryption secret + signing keypair (once)
`zetl cap invite <NAME> --cohort <ID>`	Issue an invitation grant; flags: `--expires`, `--pages <GLOB>`, `--recipient <PUBKEY>`, `--via enrol-page`, `--split-key`, `--site-url`, `--slug`
`zetl cap list`	List issued grants; `--cohort`, `--output`
`zetl cap revoke <GRANT_ID>`	Revoke a grant
`zetl cap rotate --cohort <ID>`	Rotate a cohort’s content-key salt (URLs stay stable)
`zetl cap finalise <GRANT_ID>`	Mark a grant operator-confirmed; `--rotate-grant`
`zetl cap check`	Stale-grant + public-safety audit; `--public-safety`
`zetl cap sweep`	Mark past-expiry grants as revoked
`zetl cap pair`	SPAKE2 pubkey handoff; `--grantor` / `--grantee`, `--peer`, `--phrase`, `--pubkey`
`zetl cap audit-diff [OLD] [NEW]`	Scan a diff for malicious content; `--corpus`, `--corpus-root`
`zetl cap rotate-signing-key`	Rotate the Ed25519 vault-signing key (rebuilds every page)
`zetl cap emergency-shutdown`	Print the takedown checklist (no files changed)

zetl reason

SPL queries over the vault. Requires --features reason. See Running Queries.

Subcommands (consult zetl reason --help inside a feature-reason build): status, explain, conflicts, why-not, what-if.

zetl mcp

Start a Model Context Protocol server. Requires --features mcp. See MCP Server.

zetl delegate

Issue a delegate JWT for an MCP client. Requires --features mcp.

zetl completions

Print a shell-completion script.

zetl completions zsh > ~/.zsh/completions/_zetl

Supported shells: bash, zsh, fish, elvish, powershell.

zetl man

Print a roff(7) man page. Preview with zetl man | man -l -.

Backlinks

Linked Pages

Frontmatter Fields

Frontmatter is YAML at the very top of a page, fenced by --- lines. zetl reads a handful of reserved keys — everything else passes through untouched for templates, hooks, and search. Nothing is required. A page with no frontmatter at all is valid.

---
title: Zettelkasten Method
tags: [pkm, method, luhmann]
date: 2024-06-03
status: draft
---

# Zettelkasten Method

Niklas Luhmann's slip-box system…

Reserved keys

zetl inspects these during indexing and rendering:

Key	Type	Meaning
`title`	string	Display title. Falls back to the filename stem when absent. Does not rename the file or change its wikilink target.
`parser`	string	Force a specific parser for this page. Values: `commonmark` (default) or `pandoc`. See Writing Pages.
`tags`	list of strings	Surfaced in templates and in `zetl search --path`. Drives the tag cloud.
`description`	string	Plain-text `<meta name="description">` / social-preview text. Falls back to the first paragraph.

No key is mandatory. Omit any of them and zetl infers a sensible default.

Parser selection

The parser: key wins over every other selector. Precedence (highest to lowest):

parser: in the page’s frontmatter
First matching [[parse.rule]] glob in .zetl/config.toml
Top-level [parse] default in .zetl/config.toml
commonmark (zetl’s built-in default)

An unknown parser name (e.g. parser: djot when only commonmark is registered) produces a per-page error and the page is skipped — the rest of the build proceeds. Run zetl ecosystem check to see which parsers are available.

Convention-only keys

The following are conventions, not reserved — zetl does not parse them, but templates and hooks consume them by name. Use whichever match your workflow.

Glossary

Every term used across the zetl guide, in one alphabetised list. Entries link to the primary page where the concept is explained in depth.

A

AST — Abstract syntax tree. zetl uses a canonical schema (zetl-ext AST v1) that every render-pipeline stage receives and returns. Inspect with zetl ast sample. See Render Pipeline Hooks.

B

Backlink — An inbound wikilink. If page A contains [[B]], then B has a backlink from A. Surface with zetl backlinks. See Backlinks.

BLAKE3 — The cryptographic hash zetl uses for content-addressable blocks and the Merkle leaves that feed the incremental cache. Fast, parallelisable, keyed. See Blocks.

Block — A content-addressable unit within a page: a heading, paragraph, code fence, table, blockquote, list, SPL block, or frontmatter. Each block has a BLAKE3 hash. See Blocks.

C

Capability URL — A sharing link with an embedded fragment secret (#k=…) that decrypts a static-built vault client-side. No server required. See Capability URLs.

CRDT — Conflict-free replicated data type. zetl uses Peritext for real-time co-editing so two authors can type into the same paragraph without conflicts or last-writer-wins. See Co-editing.

D

Quick Start

Sixty seconds from install to first result. This page uses the demo-vault/ bundled with the zetl repo — a self-referential knowledge base about zetl itself. Run each command; what you see should match what’s described.

Install zetl

macOS / Linux:

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

Windows: download zetl-windows-x86_64.zip, extract zetl.exe, and add it to your PATH.

The installer puts zetl in ~/.local/bin, generates the man page, and wires up shell completions. Full details, feature flags, and source-build instructions: Installation.

Get the demo vault

Clone the zetl repo to get demo-vault/:

git clone https://codeberg.org/anuna/zetl && cd zetl
ls demo-vault/
# architecture/  concepts/  decisions/  features/  theories/  Demo Script.md ...

Build the index

zetl -d ./demo-vault index

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

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).

MCP Server

Expose your vault to AI agents as typed Model Context Protocol tools. Claude Desktop, Cursor, or any MCP-aware agent can then search pages, traverse backlinks, resolve Wikilinks, ask for similar pages, and run reasoning queries — without giving up control of the underlying files.

Requires --features mcp at install time. See Installation.

Why

Agents need structured access to your knowledge. Dumping a vault into a context window loses the graph; scraping files on disk loses the reasoning layer. MCP gives the agent a typed tool surface — search, get_page, links, backlinks, path, similar, check, status, reason — backed by the same index zetl uses itself. You stay local-first; the agent never touches your files directly.

Transports

# stdio — for Claude Desktop, Cursor, and any editor that spawns the server
zetl -d ./my-vault mcp

# HTTP — for remote agents, CI bots, shared deployments
zetl -d ./my-vault mcp --transport http --port 3100

--transport stdio is the default. HTTP binds to 127.0.0.1 by default; pass --insecure to allow a non-loopback bind (don’t do this without a reverse proxy and a delegate token — see below). --cors-origin https://agent.example.com scopes the browser-side surface.

The available tools

Tool	What it does
`search`	Full-text search across the vault
`get_page`	Fetch a page by name — Markdown + frontmatter
`links`	List forward links from a page
`backlinks`	List pages pointing at a page
`path`	Shortest path between two pages in the link graph
`similar`	SimHash-nearest pages (see Similar Pages)
`check`	Run `zetl check` — dead links, orphans
`status`	Reasoning conclusions for a page (requires `--features reason`)
`reason`	Evaluate an SPL query (requires `--features reason`)

The reasoning tools exist only when zetl was built with both mcp and reason features — see What is Defeasible Reasoning for what they return.

Delegate tokens

Running Queries

Once your vault contains some SPL, zetl reason is how you ask questions of it. This page walks the everyday command surface: status, conflicts, export, and provenance.

Requires --features reason at install. See Installation.

`reason status` — the default view

zetl reason status prints every conclusion the combined theory produces, tagged with +D, -D, +d, or -d (see What is Defeasible Reasoning for what those mean).

cd ~/notes
zetl reason status

In a TTY you get a table. Piped or redirected, you get JSON — same data, machine-readable.

Filters

Status output gets long fast. A few flags keep it manageable:

Flag	Shows
`--positive`	Only `+D` and `+d` conclusions
`--negative`	Only `-D` and `-d` conclusions
`--definite`	Only `+D` and `-D` (the strict layer)
`--defeasible`	Only `+d` and `-d` (the soft layer)
`--literal "release*"`	Wildcard filter on the literal name (`*` and `?` supported)

Combine them. “What are all the things my Acme project is currently defeasibly committed to?” becomes:

zetl reason status --positive --defeasible --literal "acme*"

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.

Invitations

New collaborators join a vault via a single-use, signed invitation token. You generate one with zetl invite (or the web UI), send the resulting link by whatever out-of-band channel you prefer, and the recipient uses it exactly once to register a passkey and pick a display name.

Generating an invite from the CLI

The minimal form takes your own username (the inviter) and the role the invitee will have:

zetl invite --as Alice --role editor

This creates the token and copies the full invitation URL to the clipboard. Paste it into Signal, email, a sticky note — whatever gets it to the recipient without a third party logging it along the way.

Three roles are available:

Role	What they can do
`reader`	View pages; no editing, no invitations.
`editor`	View and edit pages; cannot invite new users or change access.
`admin`	Full control, including issuing invitations and managing passkeys.

Scoping an invite to specific pages

By default an invite gives the recipient access to the whole vault at their role. For a contractor who should only touch one project, or a reviewer who only needs to see a single folder, use --pages with a glob:

# A reader who only sees pages under projects/website/
zetl invite --as Alice --role reader --pages "projects/website/*"

# An editor scoped to a specific topic
zetl invite --as Alice --role editor --pages "research/biology/**"

Globs match on the vault-relative path. projects/* matches direct children; projects/** matches everything underneath, recursively. For more expressive rules — “editor on everything except billing/**”, or “editor only between 9–5” — see SPL-based deontic rules in Access Control.

Custom expiry

Plugin Ecosystems

Rather than rewriting every transform in zetl, reuse the ones that already exist. The plugin-ecosystem adapters let a render-pipeline hook delegate to a Pandoc filter, an mdBook preprocessor, or a remark plugin. zetl handles AST translation in both directions; the hook manifest just names the plugin.

If you already have a Lua filter you wrote for an academic paper, or an mdbook-mermaid you use for a book, you can reach for it from a zetl vault without a rewrite.

Declaring an ecosystem hook

Pick the stage, name the ecosystem, point at the plugin. A Pandoc Lua filter in the transform stage:

# .zetl/hooks/transform.d/smallcaps.py.toml
ecosystem = "pandoc"
lua_filter = "filters/smallcaps.lua"   # OR: exec = "pandoc-smallcaps"

stage = "transform"
mode  = "persistent"
extension_id = "smallcaps"

Each ecosystem has its own required/optional manifest fields:

Ecosystem	Required	Optional
`pandoc`	`exec` or `lua_filter`	`args`
`mdbook`	`exec`	`scope = "page" \| "vault"`
`remark`	`package`	`version`, `options`

Pandoc hooks default to the transform stage; mdBook preprocessors run at pre-parse (they operate on raw Markdown); remark targets the transform stage with the mdast AST type. See each ecosystem’s deep-dive guide in the main repo’s docs/ecosystems/ directory for translation details and per-plugin quirks.

Scaffolding

The authoring CLI seeds the right manifest fields (and, for Pandoc, drops a starter identity Lua filter on disk) when you pass --ecosystem:

zetl hook new transform smallcaps --ecosystem pandoc
zetl hook new pre-parse admonish  --ecosystem mdbook
zetl hook new transform math      --ecosystem remark

The generated hook works out of the box: zetl hook test smallcaps will pass against the seeded fixture. From there you edit the filter, add selectors, and tune the behavioural contract like any other pipeline hook.

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

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

Customising the Look

Both Web Server and Static Site Export accept --theme <name>. A theme is a folder under .zetl/themes/<name>/ containing Minijinja templates, static assets, and an optional theme.toml. You only override what you want — everything you don’t ship falls back to the built-in defaults.

Why themes matter

The default theme is deliberately neutral so it works as a starting point, not an endpoint. You will probably want to change at least the colours, the typography, and the name at the top of the sidebar. Most of that is CSS-only: zetl exposes a versioned set of CSS custom properties so you can restyle the graph widget, the shell, and page typography without touching any HTML.

The bigger reason the theming story is careful: zetl’s graph widget is a single, persistent Sigma.js instance that survives page navigation (no flash, no re-layout). Themes that rewrite base.html have to preserve two DOM markers to keep that property — otherwise the graph re-initialises on every click. The contract below is the bargain that makes “persistent graph across a multi-page site” possible.

Creating a theme

Bundled themes are built into the binary. Export one to the vault to start editing:

zetl theme list                        # what's available
zetl theme export default paper        # copies default to .zetl/themes/paper/

Then point serve or build at it:

zetl serve --theme paper
zetl build --theme paper

What lives where

.zetl/themes/paper/
  theme.toml                  # config for SPA, graph, contract version
  base.html                   # master layout (sidebar, modals, scripts)
  index.html                  # vault landing page
  page.html                   # one page view
  folder.html                 # folder index
  help.html                   # /help page
  static/
    theme.css                 # your CSS
    enhance.js                # extra JS (runs per navigation)
    fonts/

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

Static Site Export

zetl build turns your vault into a folder of plain HTML, CSS, and JavaScript. No runtime, no database, no server process — every page is a file you can upload to any static host. The output looks the same as Web Server minus the editor.

Why build a static site

A static site is the right deliverable when:

You want to publish research notes, a personal wiki, or project docs to the public internet.
You want a vault readable from any browser with zero operational overhead.
You want something to hand to collaborators, reviewers, or your future self that doesn’t depend on the zetl binary being installed.
You want archival: HTML works the same way in 2040 as it does in 2026.

Because nothing on the published site writes back, the edit button is absent and the save/delete endpoints aren’t emitted. Everything else — wikilinks, backlinks, transclusion panels with SVG bridges, the graph widget, full-text search, per-page history (if built with --features history) — lands in the output as static HTML and JSON.

Running it

zetl build                             # writes ./dist/
zetl -d ~/notes build
zetl build --out-dir site              # custom output directory
zetl build --theme paper               # pick a theme
zetl build --site-url https://vault.example    # absolute URLs for social cards

Preview the result locally with any static file server:

python3 -m http.server -d dist 8080

Then open http://localhost:8080/.

Output structure

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.

Blocks

zetl breaks every page into blocks — headings, paragraphs, code fences, lists, tables, blockquotes, and SPL fragments — and gives each block a stable hash. This turns a page into a small Merkle tree of content, which is what makes [[Page^block-id]] links work, what makes the incremental cache fast, and what will later make sync possible.

What a block is

A block is the smallest unit of page content zetl tracks. Parsing a page yields a sequence of typed blocks:

Type	Example
`heading`	`## Origins`
`paragraph`	Regular prose, one logical paragraph per block
`code`	A fenced ``` code block (any language)
`spl`	A fenced ```spl block (only with `--features reason`)
`list`	A top-level list; nested items stay inside
`table`	A pipe or grid table
`blockquote`	A `> …` quoted section
`frontmatter`	The YAML header, if present

List what’s in a page:

zetl blocks "Zettelkasten Method"
zetl blocks "Zettelkasten Method" --type heading

Why content-addressable

Every block’s content is hashed with BLAKE3, and the whole page is a Merkle tree with block hashes as leaves. “Content-addressable” means the hash identifies the content, not a location. This has three consequences that matter to you.

1. Block links survive file moves

[[Some Page^b3a9f1]] links to the block whose hash starts with b3a9f1. Rename Some Page.md to Renamed Page.md and the hash doesn’t change — the block is the same content. zetl can still resolve the link. It keeps pointers to what you said, not to where it lived.

Resolve a hash back to its source:

zetl blocks --resolve b3a9f1

Following Links

Three commands walk the forward-link graph: zetl links for a page’s neighbours, zetl path for the shortest route between two pages, and zetl export for dumping the whole graph as JSON. Together they turn your vault into a navigable graph you can query from the shell.

`zetl links` — forward neighbours

zetl links "Zettelkasten Method"

Prints every page that Zettelkasten Method links to. This is the complement of Backlinks: forward links are what this page cites; backlinks are what cites it.

Walk further with --depth:

# Direct forward links
zetl links "2026 Research Plan"

# Two hops: pages linked from pages linked from the plan
zetl links "2026 Research Plan" --depth 2

Useful flags:

Flag	Use
`--depth N`	Multi-hop forward traversal
`--context 80`	Show surrounding prose of each link
`--fuzzy`	Tolerate typos in the source page name

See CLI Overview for the rest.

`zetl path` — shortest route between two pages

zetl path "CRDT" "Zettelkasten Method"

CRDT
-> Collaborative Editing
-> Knowledge Management
-> Zettelkasten Method

Similar Pages

zetl similar "Query" finds pages whose titles are near-matches for the query string. It uses SimHash over page names, which makes it excellent at three things: recovering from typos, spotting duplicate-ish pages you meant to merge, and suggesting links as you type.

zetl similar "Zetelkasten Method"

Zettelkasten Method        (distance 3)
Zettelkasten Workflow      (distance 7)
Luhmann's Method           (distance 11)

The number is Hamming distance on the hash — smaller is more similar. Zero would be identical.

What SimHash does, briefly

SimHash is a locality-sensitive hash: feed it a string, get back a fixed-length binary fingerprint such that similar strings produce similar fingerprints. Unlike a cryptographic hash (where flipping one letter scrambles the whole output), SimHash changes only a few bits when the input changes slightly. Comparing two hashes by Hamming distance — the count of differing bits — gives you a cheap similarity score without storing the originals.

zetl computes one hash per page name at index time. zetl similar then scans them and returns the closest N. No full-text comparison, no embedding model, no network — just arithmetic over bits. It finishes in under a millisecond for vaults of tens of thousands of pages.

The tradeoff: it only sees names. A page titled Dogs and a page titled Canine Companions are not similar to SimHash, even though they are the same topic. For content similarity, use zetl search --semantic (see Searching).

The three flags

Flag	Default	Use
`--threshold N`	`12`	Max Hamming distance to report. Lower = stricter
`--limit N`	`10`	Max results
`--json`	off	Force JSON output

The default threshold of 12 is tuned to catch typos and near-duplicates without flooding the output. Lower it to 6 if you only want obvious matches; raise it to 20 to see the long tail.

When to use it

Searching

zetl search scans your vault for a string and prints the matches, with context. It is deliberately small: a fast text finder for when you remember a phrase but not which note it lives in.

zetl search "attention is all you need"

No regex engine, no query DSL. If you want regex, pipe the raw index through rg. What zetl gives you instead is graph-aware narrowing.

The two flags you will actually use

Flag	What it does
`--near "Zettelkasten Method"`	Only match pages within `--depth` hops of that page
`--case-sensitive`	Exact case, no folding

--near is the one most people miss. A keyword search over 4,000 notes gives you noise; a search restricted to “notes that cite Zettelkasten Method or one link away” gives you signal.

# Every note mentioning "CRDT" anywhere in the vault
zetl search "CRDT"

# Every note about CRDTs within two hops of my reading list
zetl search "CRDT" --near "2026 Research Plan" --depth 2

Other useful flags:

--path "journal/**" — glob filter on file paths.
--context 120 — widen the snippet from the default 40 characters.
--limit 200 — default is 50; raise for grep-replace workflows.

See CLI Overview for the full list.

JSON when piped

When stdout is a pipe or redirect, zetl search auto-switches to JSON. This is the contract that lets you chain searches into scripts:

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.

Orphans

Backlinks

zetl backlinks "Page" lists every page that links to Page. It is the quiet workhorse of a wikilink system — more useful, over time, than the links you write yourself.

zetl backlinks "Zettelkasten Method"

Output: the file path, the line of the match, and (with --context N) a snippet of the surrounding prose.

Why backlinks matter

Forward links are a claim you made at the time of writing. A backlink is every claim anyone ever made that referred back to this idea — including you, six months later, with more context. That asymmetry is the whole research payoff:

You read a paper and start a note on it. A year later the note has eight backlinks: three from project docs, two from meeting minutes, one from a book review. You did not plan any of that. The graph assembled it.
You are revisiting an old concept page. Instead of re-reading it in isolation, you walk its backlinks — every context in which you once found it relevant. That is a research tool disguised as a list.

Forward links (see Following Links) answer what does this page talk about? Backlinks answer what talks about this page? The second question is almost always more interesting for notes older than a few weeks.

Multi-hop with `--depth`

By default zetl backlinks returns direct, one-hop references. --depth N walks the reverse graph:

# Direct backlinks only
zetl backlinks "Zettelkasten Method"

# Every page that reaches "Zettelkasten Method" in up to 3 reverse hops
zetl backlinks "Zettelkasten Method" --depth 3

Depth 2–3 is where the transitive structure gets interesting: you find the notes that cite notes that cite this concept. Depth 5+ tends to return most of your vault — the graph is small-world.

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.

CLI Overview

Global flags

Subcommand summary

zetl index

zetl list

zetl stats

zetl links

zetl backlinks

zetl check

zetl search

zetl similar

zetl path

zetl export

zetl blocks

zetl view

zetl serve

zetl build

zetl watch

zetl diff

zetl theme

zetl hook

zetl ecosystem

zetl ast

zetl agent

zetl invite

zetl agent-token

zetl derive-ssh-key

zetl cap

zetl reason

zetl mcp

zetl delegate

zetl completions

zetl man

Related

Backlinks