zetl — Quick Start

zetl is a command-line tool that turns a folder of Markdown files with [[wikilinks]] into a queryable knowledge graph — with optional defeasible reasoning, vault history, collaborative editing, and an MCP server for AI agents. Your files stay as they are; everything zetl generates lives in a disposable .zetl/ cache next to them.

Source: https://codeberg.org/anuna/zetl. This guide is itself a zetl vault — every page you read is a .md file in this folder.

1. Install

macOS / Linux:

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

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

Build from source (requires a Rust toolchain):

git clone https://codeberg.org/anuna/zetl && cd zetl
make install                                            # core features
cargo install --path . --features "reason,history,mcp"  # everything

You get zetl on your $PATH, a man page, and shell completions. Feature flags, custom install paths: Installation.

2. Get the demo vault

The zetl repo ships with demo-vault/, a self-referential knowledge base about zetl itself — wikilinks and SPL throughout. From your clone:

ls demo-vault/
# architecture/  concepts/  decisions/  features/  theories/  Demo Script.md ...

3. Build the index

zetl -d ./demo-vault index

zetl auto-detects output format: a table in a terminal, JSON when redirected. You’ll see something like:

{
  "files_scanned": 27,
  "links_found": 152,
  "dead_links": 2,
  "diagnostics": 0,
  "elapsed_ms": 28
}

27 files, 152 wikilinks, 2 dead links. The cache lives in demo-vault/.zetl/ and is reused on subsequent runs — zetl only reparses files whose mtime or hash changed.

4. Follow a link

Every Markdown file that mentions [[Scanner]] threads into the graph. Ask what Scanner points at:

zetl -d ./demo-vault links "Scanner"

Forward links from 'Scanner':
+-----+---------+--------------------+------+
| Hop | Source  | Target             | Line |
+===========================================+
| 1   | Scanner | Reasoning Engine   | 30   |
| 1   | Scanner | Link Graph         | 30   |
| 1   | Scanner | Cache              | 30   |
| 1   | Scanner | Local-first Design | 28   |
| 1   | Scanner | Spindle Lisp       | 3    |
+-----+---------+--------------------+------+

Each row is one wikilink, with the line number in the source file.

5. Walk backlinks, two hops

Which notes point at Cache — and which notes point at those notes?

zetl -d ./demo-vault backlinks "Cache" --depth 2

--depth 2 means “include second-hop citations.” Direct backlinks (hop 1) and transitive ones (hop 2) are labelled so you can tell them apart.

6. Open the web UI

zetl -d ./demo-vault serve
# Serving on http://localhost:3000

You get a sidebar with every page, rendered Markdown, a backlink list, a transclusion panel showing excerpts of forward-linked pages, and a mini link-graph widget bottom-right. Edits save straight back to the .md file on disk. Ctrl-C stops the server.

7. Reason over the vault

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

The demo vault has SPL facts and rules sprinkled through its pages — zetl’s reasoning engine pulls them out and draws conclusions.

zetl -d ./demo-vault reason status

Theory: 46 facts, 24 rules, 0 defeaters, 0 superiority relations from 18 files

+-----+---------------------------+-------------------------------+
| Tag | Literal                   | Sources                       |
+=================================================================+
| +D  | backlinks-done            | Graph Queries:11              |
| +D  | fast-startup              | Performance:10                |
| +d  | release-candidate         | (derived)                     |
+-----+---------------------------+-------------------------------+

Tags: +D definitely provable, -D definitely not, +d defeasibly provable, -d defeasibly not. Every conclusion carries a line-numbered provenance trail.

Ask why release-candidate holds:

zetl -d ./demo-vault reason explain "release-candidate" --format natural

That’s the loop

zetl index to scan.
zetl links / zetl backlinks / zetl search to query.
zetl serve or zetl view to read.
zetl reason to draw conclusions (if --features reason).

Read this guide the same way

Everything above works on this vault too. The vault ships with a bundled quickstart theme that redirects / straight here, so pass --theme quickstart (or use the Makefile) when you serve or build:

zetl -d . serve --theme quickstart          # read the guide in a browser
make serve                                  # same, via the bundled Makefile
zetl -d . view Index                        # two-pane terminal reader
zetl -d . build --theme quickstart --out-dir site  # static HTML for any host
zetl -d . check                             # 54 pages, 550 wikilinks, 0 dead

Or open the folder in Obsidian, Logseq, Foam, or Dendron — wikilinks work everywhere.

Where to go next

Backlinks

Glossary

Linked Pages

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?

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.

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

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.

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.

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

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

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.

Access Control

zetl’s access model has two layers. The built-in layer — three roles plus glob-based page scoping — covers the 90% case: readers, editors, admins, optionally confined to a folder. The optional layer — SPL-based deontic rules — lets you express richer policies (“editor everywhere except billing/**”, “read access only between 9:00 and 17:00”) using the same reasoning engine that powers What is defeasible reasoning.

The three roles

Role	View	Edit	Invite	Admin UI
`reader`	yes	no	no	no
`editor`	yes	yes	no	no
`admin`	yes	yes	yes	yes

A user’s role is set on the invitation that brought them in (see Invitations) and can be changed later from /_admin/users. There’s no implicit hierarchy beyond this table — an editor isn’t a superset of admin, they’re just different.

Page scoping with globs

When you issue an invitation you can restrict which pages the recipient reaches at all:

zetl invite --as Alice --role editor --pages "research/**"

The scope is a glob against vault-relative paths. projects/* matches direct children of projects/. projects/** matches everything recursively. You can pass only one --pages at invite time; for more intricate patterns, use deontic rules below.

Pages outside the scope are invisible — not just uneditable. An out-of-scope page won’t appear in search, won’t show up in the graph, and returns 404 if requested by URL. This is a deliberate minimum-surface choice: users don’t learn about documents they can’t touch.

Deontic rules with SPL

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

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

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

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.

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.

What-if and Abduction

Two commands — zetl reason what-if and zetl reason require — let you play with the theory without actually editing it. One asks “what changes if I add this fact?”. The other asks “what facts would I need to prove this goal?”. Both are indispensable when planning.

Requires --features reason at install. See Installation.

`reason what-if` — forward hypotheticals

what-if takes a snippet of SPL, temporarily adds it to the theory, recomputes conclusions, and reports the diff. Your vault files are not touched.

zetl reason what-if "(given acme-legal-cleared)"

Output: every conclusion that changed — literals that newly hold, literals that stopped holding, tags that flipped between +d and -d. The rest is filtered out.

Focus on a specific goal

--goal narrows the diff to a single literal you care about. Answers the question “if I add this, does this become provable?”:

zetl reason what-if "(given acme-legal-cleared)" --goal "acme-ready-to-start"

From a file

Proof Trees

zetl reason explain <literal> shows why a conclusion holds. The output is a proof tree: the rules that fired, the facts they rested on, and any defeaters that were considered. This page is about when and how to read one.

Requires --features reason at install. See Installation.

What a proof tree is

When zetl concludes that some literal holds (or doesn’t), it found — or failed to find — a chain of rules and facts that lead to that literal. A proof tree is that chain laid out as text:

The root is the literal you asked about.
Each node is a rule that fired, labelled with the rule’s name.
Each leaf is a fact (given) or a dead end (a body literal that couldn’t be proved).
Defeaters that were considered — and either won or were overridden — appear alongside the main chain.

Every node carries provenance: the source file, line number, and page name where that rule or fact was written. You can walk from any conclusion back to the exact prose that originated it.

The command

zetl reason explain "acme-ready-to-start"

By default the output is JSON. Three other formats are available via --as:

`--as`	What you get
`json`	Structured proof tree (default)
`table`	A tabular view of nodes, rules, and sources
`natural`	English prose: “The literal X is defeasibly provable because …”
`dot`	Graphviz DOT source — pipe to `dot -Tpng` for a diagram

There is also --depth N (default 10) which caps how deep the tree goes. Unbounded trees in large vaults can be overwhelming; 4 or 5 is usually enough for day-to-day use.

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*"

Writing SPL

Spindle Lisp (SPL) is the small language zetl reads when you ask it to reason over your vault. This page walks through the syntax by example — no formal grammar, just enough to start writing useful theories.

Requires --features reason at install. See Installation.

Where SPL goes

SPL lives in two places:

Fenced code blocks inside any Markdown file, tagged spl.
Standalone .spl files anywhere in the vault.

# Q2 Release

We're tracking the release of the next minor version here.

```spl
(given core-features-done)
(given docs-drafted)
```

zetl merges every spl block and every .spl file across the vault into one combined theory before reasoning. A fact stated on one page can feed a rule defined on another. This is the point — rules and facts can live next to the prose that motivated them.

Facts

A fact is something you assert to be true. Use (given ...):

(given project-approved)
(given has-owner)
(given budget-signed-off)

What is Defeasible Reasoning

A short primer on the kind of logic zetl uses when you ask it to reason over your notes. No symbols, no formal notation — just an explanation of why this flavour of logic suits knowledge work.

Requires --features reason at install. See Installation.

Classical logic: everything is final

In classical logic, facts combine and the conclusion is permanent. If you write down that every bird flies, and that Tweety is a bird, then Tweety flies. Forever. Adding new information can only produce new conclusions — it can never retract one you already made.

That rule works beautifully inside a maths textbook. It breaks almost immediately when you try to write down the actual state of a research project, a release plan, or a set of beliefs you formed over six months of reading. Real knowledge is provisional. You revise it. You hedge. You say “normally X, but not when Y”.

Defeasible logic: conclusions have strength

Defeasible reasoning lets you write rules that are normally true but can be defeated by stronger evidence. In a project-tracking vault you might write:

Normally, a release candidate is ready if core features are done, docs are written, and tests pass.
Except when there is an outstanding critical bug.

Both rules live in the theory at the same time. When zetl reasons over them, the defeater wins if its conditions hold — the release is blocked. If the bug is later fixed, the block lifts and the conclusion flips. You never rewrote the rules; you just added and removed facts.

This is exactly how thinking about ongoing work feels. “We’re on track — unless the client pushes back on the design.” “The proposal is done — except we still need a legal review.” You already reason this way. zetl just gives you a notation for it.

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:

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

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

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.

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/

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.

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

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

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.

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:

Tags and Frontmatter

Tags are how you group pages without forcing them into folders. Frontmatter is how you attach any other structured data — dates, statuses, authors, book ISBNs, whatever your vault needs — that zetl and your templates can both see.

YAML frontmatter basics

Frontmatter is a YAML block at the very top of a page, fenced by ---:

---
title: Seeing Like a State
tags: [book, political-theory, legibility]
author: James C. Scott
year: 1998
status: finished
rating: 5
---

# Seeing Like a State

...

Anything inside the fences is frontmatter; everything after the closing --- is the body. zetl reads frontmatter on every scan and exposes it to templates, search, and hooks. See Frontmatter for the conceptual model and Frontmatter Fields for the reserved-key reference.

Tagging — two syntaxes

zetl recognises tags in two places.

Frontmatter tags. A YAML list under the tags: key:

tags: [rust, cli, reference]

This is the canonical form. Tags here are structured metadata — they’re first-class, they show up in templates, and they don’t clutter your prose.

Inline hashtags. #word tokens inside the body of the page:

Organising Your Vault

zetl is indifferent to how your vault is laid out. Pages resolve by filename, not path, so you can reorganise at any time without breaking links.

No required structure

A handful of layouts people actually use:

Flat. Every page in the vault root. Works surprisingly well up to a few hundred pages. The link graph provides the structure; the filesystem is just a blob.

~/notes/
  Annual Review 2026.md
  Reading List 2026.md
  Scientific Management.md
  Seeing Like a State.md
  Zettelkasten Method.md

Topic-based. Top-level folders by subject.

~/notes/
  Books/
    Seeing Like a State.md
  Essays/
    Legibility and Craft.md
  Journal/
    2026-04-18.md
  Reference/
    SPL Cheatsheet.md

Johnny Decimal. Numbered categories. Good when the topics are stable and you value predictable paths.

~/notes/
  10 Work/
    11 Projects/
    12 Meetings/
  20 Reading/
    21 Books/
    22 Papers/
  30 Personal/

Zettelkasten-style. Timestamped slip-boxes, no folders, atomic notes linked into trails. Works, but not required — zetl is not a Zettelkasten tool, just a link-graph tool.

~/notes/
  202604181423 Legibility as precondition.md
  202604181431 Taylor and Scott in parallel.md

Headings and Blocks

A plain wikilink takes a reader to a page. On a long page, that’s a coarse target — you may have wanted to point at one section, or one sentence. zetl supports both.

Heading links

Use # to point at a heading within a page:

See [[Annual Review 2026#Priorities]] for the three-item list.
The argument is developed in [[Seeing Like a State#Legibility]].

Matching rules:

Case-insensitive. #Priorities, #priorities, and #PRIORITIES all match ## Priorities.
Slugified. Spaces and punctuation are normalised, so #getting started matches ## Getting Started.
Any heading level. # in the link matches ##, ###, and so on — the link just names the heading text.

If multiple headings on a page share the same text, the first one wins. That’s rare in practice; rename one of them if it bites you.

Block ids

When you want to point at something finer than a heading — a definition, a quoted passage, a data row — use a block id. Append ^some-id to the end of the block, then link with [[Page^some-id]]:

The central definition in the book:

> State simplifications are static typifications that abstract
> away from local knowledge in the service of administrative
> control.
> ^legibility-def

From another page:

Scott's definition of legibility — [[Seeing Like a State^legibility-def]] —
maps cleanly onto what Taylor was doing in factories.

Block ids can live on any paragraph, blockquote, list item, code block, or table. Convention:

Embeds and Transclusion

An embed pulls another page’s content into the current page. A plain wikilink just points. An embed quotes — at full resolution, live, without duplicating the source.

The three embed forms

![[Zettelkasten Method]]              # the whole page
![[Zettelkasten Method#History]]       # one section (by heading)
![[Seeing Like a State^legibility-def]] # one block (by block id)

The leading ! is what turns a link into an embed. Everything else mirrors the plain wikilink forms — see Wikilinks.

How embeds render

When you run zetl serve or zetl build, embeds render as transclusion cards in a right-rail panel alongside the main content. The surrounding prose keeps flowing; the embedded material appears next to the paragraph that references it, in its own framed card showing the source page, the quoted region, and a link back to the original.

In the terminal viewer (zetl view), embeds render in the two-pane layout, with the source content expanded where the ![[...]] appears — see Terminal Viewer.

When to embed, when to link

Situation	Use
You’re pointing at related material	plain link `[[...]]`
You want the reader to see the quoted passage without leaving	embed `![[...]]`
You need a definition, claim, or diagram from elsewhere	embed a block `![[Page^id]]`
You’re writing a meta-page (index, reading list, MOC)	mostly links
You’re writing an essay that quotes your own notes	embeds for quoted material

A good heuristic: embed when you’d otherwise be tempted to copy-paste. Embeds stay in sync if the source changes; copies rot.

A worked example

Book Journal/Seeing Like a State.md:

Linking Pages

Links are how your vault stops being a folder of files and starts being a graph. This page covers the everyday workflow of linking — the full syntax reference lives in Wikilinks.

Link as you write

The honest workflow: while drafting a note, when you reach a concept that deserves its own page, just wrap it in double brackets.

The book makes the case that [[Scientific Management]] hollowed out
craft knowledge in a way that [[Seeing Like a State]] would later
describe as legibility.

Two things happen:

If Scientific Management.md already exists, the link resolves — clicking it in zetl view or zetl serve navigates to the page.
If it doesn’t exist, zetl flags it as a dead link but otherwise leaves you alone. The link is a promise, not an error.

Dead links are surfaced by zetl check --dead-links:

$ zetl check --dead-links
Scientific Management — referenced from: Taylorism and its Discontents.md:7

You can create the target page any time. Run zetl index (or let zetl serve re-scan) and the link goes live.

Creating the target page later

This is the rhythm most writers settle into:

Writing Pages

In a zetl vault, one page is one Markdown file. No databases, no sidecar XML, no magic — if you can write a .md file, you can write a zetl page.

The filename is the title

zetl uses the filename (minus .md) as the page title. Title-case filenames with spaces are the convention:

~/notes/
  Zettelkasten Method.md
  Reading List 2026.md
  Meeting with Priya 2026-04-18.md

When another page writes [[Zettelkasten Method]], zetl resolves the link by matching the filename. Slugification happens at render time — the URL becomes /zettelkasten-method/, but your filesystem stays human-readable. Case doesn’t matter for resolution; [[zettelkasten method]] works too.

There is no restriction on where a file lives. Folders are for your eyes, not zetl’s. See Organising Your Vault.

A minimal page

Every page is CommonMark-compatible Markdown with optional YAML frontmatter at the top:

---
title: Reading List 2026
tags: [reading, journal]
status: open
---

# Reading List 2026

Books I want to read this year, with a running note once I finish each.

- [[Gödel, Escher, Bach]] — started January
- [[The Glass Bead Game]] — queued
- [[Seeing Like a State]] — finished March

## Related

- [[Book Journal]]
- [[Annual Review 2026]]

That’s it. No build step, no registration. Save the file; it’s a page. Run zetl list and you’ll see it.

Markdown flavour

Intellectual Heritage

zetl sits at the end of a long line of ideas about how humans extend their memory and organise thought. None of the concepts behind it — linked notes, associative trails, transclusion, graph queries — were invented last decade. This page traces the lineage so you can see what zetl inherits, and what it deliberately leaves out.

The Zettelkasten (16th century – present)

The name “zetl” comes from Zettelkasten — German for “slip-box” or “card file”. It is a note-taking method in which ideas are written on individual slips of paper, each given a unique identifier, and then linked to each other by subject headings or explicit cross-references.

The practice is older than it sounds. Conrad Gessner (1516–1565) invented an early version in which individual notes could be rearranged at will — an explicit break from the bound commonplace book tradition. Thomas Harrison’s “Ark of Studies” (Arca studiorum, c. 1640s) described a small cabinet where notes were attached to metal hooks labelled by subject heading. Carl Linnaeus used standardised paper slips to record research in 1767.

The method’s most famous practitioner was the German sociologist Niklas Luhmann (1927–1998). Starting in 1952–1953, Luhmann built a Zettelkasten of roughly 90,000 index cards. He assigned each card a unique hierarchical number — branching off parent cards using decimal notation — so that new ideas could be inserted anywhere in the structure without renumbering everything. He credited the system with enabling around 50 books and 550 articles. Luhmann described the Zettelkasten not as a filing cabinet but as a “communication partner”: the process of writing new cards and navigating old ones would surface unexpected connections that he had not consciously planned.

The Zettelkasten’s key insight is that a note’s value comes less from its content than from its connections. A note isolated in a folder is static; the same note linked to twenty others becomes part of an emergent structure that can surprise its author.

zetl inherits the vocabulary directly: a vault is a Zettelkasten, a wikilink is a slip-to-slip reference, zetl backlinks gives you Luhmann’s “which cards point here?” lookup.

The Memex (1945)

In July 1945, Vannevar Bush — then head of the US Office of Scientific Research and Development — published an essay called “As We May Think” in The Atlantic. In it he described a hypothetical device he called the Memex:

“A memex is a device in which an individual stores all his books, records, and communications, and which is mechanised so that it may be consulted with exceeding speed and flexibility. It is an enlarged intimate supplement to his memory.”

What is SPL

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

SPL is Spindle Lisp — a small Lisp-family language for writing rules. zetl extracts SPL from your vault and draws conclusions: “if a project is approved and has an owner, it’s ready to start”. This page is a gentle orientation; see Writing SPL for the syntax reference.

Why a second language at all

Most of your vault is prose — the thing humans are good at reading. But some knowledge is best expressed as a rule, not a paragraph. “Any release candidate must have a green test run and up-to-date docs” is easier to write (and check) as a rule than as a checklist you hope to follow.

SPL lets you write those rules inside your notes, alongside the prose they explain. zetl then reasons over all the SPL in the vault at once — a single combined theory — and tells you what follows.

The shape of SPL

SPL is parenthesised. Facts and rules are S-expressions:

(given docs-updated)
(given tests-pass)

(normally r-ready
  (and docs-updated tests-pass)
  release-candidate)

Reading top to bottom: two facts, then a rule named r-ready that says normally, if both facts hold, conclude release-candidate. Run reasoning and zetl will report +d release-candidate — defeasibly proved.

“Normally” is load-bearing. SPL is a defeasible logic: a conclusion can be drawn by default, and then withdrawn when stronger contrary evidence appears. See What is Defeasible Reasoning for what this means and why it matters for knowledge that isn’t strictly mathematical.

Local-first

zetl is local-first. That phrase is doing real work — not “runs locally” and not “offline-capable”, but a specific design stance about whose computer owns your notes. This page is the philosophy; every other design choice in zetl follows from it.

The principles

Your files are the source of truth. Not a database, not a cloud tenant, not a proprietary binary format. A zetl vault is a directory of plain .md files. Whatever any zetl command says about your vault, the Markdown on disk is the authority. If zetl and the files disagree, the files win.

zetl never modifies your Markdown. Indexing, reasoning, rendering, validation — none of these rewrite your notes. Wikilinks stay wikilinks; frontmatter stays whatever YAML you wrote. The only bytes zetl writes are under .zetl/ (its cache) and, optionally, an output directory from zetl build.

Everything in .zetl/ is disposable. Link index, block hashes, snapshot history, reasoning theory — all of it is cache, derived from your files. Delete .zetl/ and zetl index rebuilds it. Commit your vault without it; share vaults across machines by syncing the .md files alone.

Works offline. zetl is a single binary that reads from and writes to your local filesystem. No network is required for any core operation — indexing, searching, viewing, building, reasoning. A machine in airplane mode has the full feature set.

Data outlives the tool. If zetl disappears tomorrow, or if you decide it’s not for you, your vault is still a folder of Markdown files. Open them in any text editor, any other wikilink tool, any static site generator. You did not sign up for a migration problem.

Why this matters for knowledge work

A second brain is only useful if you trust it to still be there in ten years. Most knowledge tools violate at least one of the above: they own the format, they own the storage, they own the sync layer, or they break when offline. The cost compounds — every note you write increases your exposure to someone else’s product decisions.

Local-first flips the dependency. You own the files. Tools like zetl read them and give you views — a graph, a search index, a rendered site, a reasoning layer — without taking ownership. When a better tool comes along, your vault is already portable to it.

What local-first does not mean

Frontmatter

Frontmatter is the YAML block at the top of a Markdown file, fenced by ---. zetl reads it, exposes it in templates, and otherwise gets out of the way. It is entirely optional.

What it looks like

---
title: Zettelkasten Method
tags: [note-taking, knowledge-management]
date: 2026-01-14
status: draft
---
# Zettelkasten Method

The Zettelkasten is a slip-box system...

Everything between the two --- fences is parsed as YAML. Everything after is the page body.

What zetl does with it

Three things, all passive:

Parses it once per page, on indexing.
Makes it available in templates as page.frontmatter.<key>. If you’re theming zetl serve or zetl build, you can read anything you’ve written — {{ page.frontmatter.tags }}, {{ page.frontmatter.status }}, anything. See Customising the Look.
Exposes it to hooks via the vault context, so render-pipeline hooks and lifecycle scripts can make decisions based on metadata.

zetl does not require any specific field. No title, no id, no uuid. Your filename is your page name; the graph builds itself from wikilinks.

What the community uses it for

None of these are built-in — they’re conventions that happen to work:

Field	Use
`tags`	A list for topical grouping; read by themes and `zetl check`-style tooling
`date`	Publication or creation date; often used for journal pages
`status`	`draft`, `published`, `archived` — render differently per status
`aliases`	Alternate names for the same page; used by some themes for search
`author`	For multi-author vaults

A minimal page doesn’t need any of this. A page with no frontmatter at all is completely fine:

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

The Link Graph

zetl thinks about your vault as a directed graph: pages are nodes, wikilinks are edges. Every command you will run — backlinks, path, orphans, export, the graph widget in zetl serve — is a query over this graph. Understanding the model makes the rest of zetl obvious.

What a node is

A node is one page: one .md file in your vault. The node’s identity is its filename (minus .md, case-normalised). The node’s content is what’s between the frontmatter and the end of file. That’s it — no IDs, no database keys.

What an edge is

Every [[wikilink]] you write is an edge from the current page to the target. Edges are directed: A.md writing [[B]] creates an edge A → B, not B → A. Backlinks are the inverse — the set of pages that link at you.

The graph distinguishes:

Plain edges — [[Page]], [[Page|alias]]
Heading edges — [[Page#heading]]
Block edges — [[Page^b3a9f1]], which target a specific block
Embed edges — ![[Page]], same edge, different rendering

All four contribute to forward-links and backlinks. An aliased link is still an edge to Page, not to alias.

Dead links and orphans

Two graph concepts show up often enough to name:

A dead link is an edge whose target has no matching file. The edge exists in the graph; the node on the far end is empty. zetl check --dead-links lists them.
An orphan is a node with no inbound edges — nothing links to it. An orphan may still have outbound links. zetl check --orphans lists them.

Wikilinks

A wikilink is how you point from one note to another by name. zetl parses five shapes of wikilink from your Markdown. This page is the syntax reference; for workflow advice see Linking Pages.

The five shapes

Shape	Example	Purpose
Plain	`[[Zettelkasten Method]]`	Link to a page; display text is the target name
Aliased	`[[Zettelkasten Method\|the slip-box method]]`	Link with custom display text
Heading	`[[Zettelkasten Method#Origins]]`	Link to a specific heading on a page
Block	`[[Zettelkasten Method^b3a9f1]]`	Link to a specific content-addressable block
Embed	`![[Zettelkasten Method]]`	Transclude the target’s content inline (see Embeds and Transclusion)

All five can be combined with a heading or block anchor on the target side: ![[Zettelkasten Method#Origins]] embeds a single section.

How resolution works

When you write [[Some Page]], zetl does not look up a URL or an ID. It looks for a file named Some Page.md in your vault. Specifically:

By filename, not by the # H1 inside the file. The name in brackets must match the file stem.
Case-insensitive. [[some page]], [[SOME PAGE]], and [[Some Page]] all resolve to Some Page.md.
Across subfolders. zetl searches the whole vault tree; you don’t write [[projects/zetl]], just [[zetl]].
Slugified for the web output — Some Page.md becomes /page/some-page/ in zetl serve and zetl build. You never need to think about slugs when writing; that’s what the resolver is for.

If two files share a name across folders, the first match wins and the other is reported as ambiguous by zetl check. Rename one.

Dead links are fine (until they’re not)

A wikilink to a page that does not yet exist is a dead link. zetl does not crash, does not refuse to render, and does not auto-create the file. It records the edge and surfaces it in:

zetl check --dead-links

Many people use this as a to-do list: write what you wish existed, then fill in the targets later. See Finding Orphans and Dead Links.

Vaults

A vault is any directory that contains Markdown files. That is the whole definition. zetl does not own your notes, does not require a config file, and does not need to import anything — point it at a folder and it starts working.

What’s in a vault

A vault is a tree of .md files. Folders are just folders; there is no hidden database beside your notes. The only thing zetl adds is a .zetl/ directory at the vault root, used for caching:

~/notes/
  Zettelkasten Method.md
  projects/
    zetl.md
    daily/
      2026-04-15.md
  .zetl/           <- zetl's cache; safe to delete
    index.json
    blocks/
    theory/        <- only with --features reason
    jj/            <- only with --features history

Everything in .zetl/ is disposable. Delete it and the next zetl index rebuilds it from your files. This matters: your vault is your Markdown, not zetl’s cache. See Local-first.

How zetl walks a vault

When you run zetl index, zetl walks the tree using a layered ignore stack. From lowest to highest precedence:

Layer	Rule
1	Hardcoded: `.git/`, `.zetl/`, `node_modules/` are never scanned
2	Dotdirs like `.obsidian/`, `.vscode/`, `.claude/` are skipped by default (`--include-hidden` disables)
3	`.gitignore` patterns, if present
4	`.zetlignore` at the vault root (gitignore syntax; `!pattern` re-includes)
5	`--exclude PATTERN` CLI flag (repeatable, highest priority)

This means a zetl vault coexists cleanly with a git repo, a node project, an Obsidian workspace, or a Logseq graph. You do not need to rearrange files.

Pointing zetl at a vault

Two ways, and they are equivalent:

# Explicit
zetl -d ~/notes index

# Or set the env var once per shell
export ZETL_DIR=~/notes
zetl index
zetl links "Zettelkasten Method"

Migrating from Obsidian

There is no migration. Point zetl at your Obsidian vault and it works. The two tools read the same Markdown, the same wikilink syntax, and the same YAML frontmatter — your notes are the source of truth for both.

The short version

zetl -d ~/Documents/ObsidianVault index
zetl -d ~/Documents/ObsidianVault serve

Open your vault in Obsidian at the same time. Both read your .md files. Neither locks anything. zetl never writes to your notes — only to a disposable cache under .zetl/.

Syntax compatibility

Every wikilink shape Obsidian uses, zetl parses the same way:

Syntax	Meaning
`[[Zettelkasten Method]]`	Standard link.
`[[Zettelkasten Method\|the method]]`	Aliased display text.
`[[Zettelkasten Method#History]]`	Link to a specific heading.
`[[Zettelkasten Method^abc123]]`	Link to a block by ID.
`![[Book Notes]]`	Embed (transclude) the whole page.
`![[Book Notes#Ch 3]]`	Embed a section.

See Wikilinks for the zetl-specific details (resolution rules, ambiguity handling).

Frontmatter

zetl parses YAML frontmatter the same way Obsidian does. Existing tags, aliases, publish, and anything else you rely on will surface in page.frontmatter.* for templates, and tags flow into Tags and Frontmatter queries. Custom keys — status, project, deadline — are preserved verbatim and available in templates and hooks.

A frontmatter block Obsidian wrote this morning:

---
tags: [research, reading]
aliases: [Adler, How to Read]
status: in-progress
---

Your First Vault

A vault is just a folder of .md files. This page walks you through creating one from scratch — three linked notes, an index, a health check, and a web UI — so you have a feel for vault hygiene before you pour a decade of notes in.

Make the folder

mkdir ~/notes
cd ~/notes

That’s the whole setup. No config files, no database, no init command. zetl treats any folder containing Markdown as a vault.

Create three linked notes

Open your editor and create three files. The content matters less than the wikilinks — we want to see the graph form.

Projects.md:

---
tags: [hub, projects]
---
# Projects

Active work this quarter. My overarching goals for the year live
in [[2026 Goals]]. Day-to-day progress notes accumulate in
[[Daily Journal]].

## Current

- Rewriting the customer onboarding flow
- Writing a long-form piece about [[2026 Goals#writing]]

2026 Goals.md:

---
tags: [planning, goals]
year: 2026
---
# 2026 Goals

Three things I want to get done this year. Progress lives
in [[Daily Journal]], and specific projects are tracked
in [[Projects]].

## Writing

Publish a monthly essay. See [[Projects]] for the current draft.

## Health

Run three times a week.

## Learning

Read one book a month, notes in the journal.

Daily Journal.md:

What is zetl

zetl is a command-line tool that reads a folder of Markdown notes, understands the [[wikilinks]] between them, and lets you query, search, and reason over the resulting graph. Your notes stay on your laptop, in the filesystem, in plain .md files. zetl just reads them.

What it does

Point zetl at a folder of notes and it will:

Parse wikilinks — every [[Zettelkasten Method]], [[Book Notes|my reading list]], [[Daily Journal#2026-04-20]], and ![[Project Brief]] embed.
Build a link graph — who points at whom, how many hops between two pages, which pages have no inbound links.
Answer questions — forward links, backlinks (including multi-hop), shortest path between two pages, orphaned notes, dead links, pages with similar names.
Search content — full-text and regex across the vault, with frontmatter and code-block awareness.
Render the vault — as a terminal viewer (zetl view), a local web server (zetl serve), or a static HTML site (zetl build).
Reason over SPL — optional defeasible-logic layer that reads spl code blocks from your notes and draws conclusions with full provenance. See What is SPL.

A concrete example. You have ~/notes/ with 400 Markdown files. You run:

cd ~/notes
zetl index
zetl backlinks "Zettelkasten Method" --depth 2
zetl check --dead-links

zetl tells you which notes cite Zettelkasten Method directly, which cite those, and flags every [[broken link]] in the vault. No database. No daemon. The cache lives in ~/notes/.zetl/ and is disposable.

Who it’s for

Solo knowledge workers and small teams who:

Already keep notes in plain Markdown and don’t want to migrate.
Use [[wikilinks]] (Obsidian, Logseq, Foam, Dendron, or hand-written — all work).
Want command-line answers about their graph, not just a GUI.
Care about local-first tools that treat your files as source of truth.

With --collab, small teams can co-edit the same vault over WebSocket with passkey auth and real-time CRDT sync. See Running a Team Server.

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

zetl — Quick Start

1. Install

2. Get the demo vault

3. Build the index

4. Follow a link

5. Walk backlinks, two hops

6. Open the web UI

7. Reason over the vault

That’s the loop

Read this guide the same way

Where to go next

Start here if you’re new

Core concepts

Writing

Finding

Reading & rendering

Vault history — requires --features history

Reasoning — requires --features reason

Collaboration

Automation & extensibility

Reference

Help

Backlinks

Vault history — requires `--features history`

Reasoning — requires `--features reason`