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?

No. The graph features — wikilinks, backlinks, search, blocks, embeds, the web UI, collab — require no Lisp at all. Spindle Lisp (SPL) is an optional reasoning layer gated behind --features reason. Write plain Markdown, run plain zetl, and you never touch SPL.

If you’re curious: What is SPL.

Can I use zetl without a git repo?

Yes. zetl never requires .git/. If you enable the history feature, temporal snapshots use jj stored in .zetl/jj/ — a separate VCS from your repo’s .git/. You can have both, either, or neither. In collab mode, saves auto-commit to a git repo if one exists; without one, edits still persist to disk and through the CRDT.

See Snapshots Under the Hood.

Does zetl support Windows?

zetl is written in portable Rust and targets Linux, macOS, and Windows. Build from source with a Rust toolchain. Some collab-mode features (passkey flows, WebSocket behaviour) are most exercised on Linux and macOS; file an issue if a Windows-specific rough edge bites.

See Installation.

How big a vault does zetl scale to?

zetl uses incremental caching — a two-tier (mtime + BLAKE3 hash) index — so re-runs only reparse changed files. Real-world scaling numbers aren’t published; in practice the design aim is “your vault, however big it grows, stays snappy”. If you hit a slow spot, Troubleshooting has a section on it and the issue tracker wants to hear.

Can multiple people use the same vault?

Two models:

Live collab server — run zetl serve --collab and invite collaborators with passkeys. Edits sync in real time through a CRDT engine; every save auto-commits to git with author attribution. See Running a Team Server.
Shared git repo — commit your vault to git and let collaborators clone, edit, and push as they would any other text repo. zetl doesn’t care whether the file on disk came from a human, a collaborator, or a merge commit.

You can combine the two.

What’s the difference between a lifecycle hook and a render-pipeline hook?

Lifecycle hooks run at coarse events — pre-build, post-build, on-save, etc. They get the whole vault context as JSON on stdin, run once per event, and are ideal for tasks like generating an RSS feed or posting to a webhook.

Render-pipeline hooks run inside the build, per page, at one of three fine-grained stages — pre-parse, transform, or post-render. They’re persistent subprocesses speaking a JSON-lines protocol, operate on a typed AST, and are the right tool for custom Markdown extensions, callouts, or pandoc integration.

Details: Lifecycle Hooks and Render Pipeline Hooks.

Is there a plugin marketplace?

Not yet. Two things take the pressure off until there is:

zetl ships first-class adapters for Pandoc, mdBook, and remark — three huge existing plugin ecosystems. You can run a Pandoc Lua filter as a render-pipeline hook with a four-line manifest.
The hook authoring CLI (zetl hook new/test/watch) makes writing your own a few-minute task, not a weekend project.

See Plugin Ecosystems.

What about AI agents?

zetl exposes graph, search, and reasoning as typed tools over the Model Context Protocol. Build with --features mcp, run zetl mcp over stdio or HTTP, and issue scoped delegate tokens to your agent.

See MCP Server and Plugin Ecosystems.

Is zetl free?

Yes. zetl is released under AGPL-3.0-or-later. The source is at https://codeberg.org/anuna/zetl.

Where does zetl store its data?

Everything zetl writes lives in .zetl/ next to your vault:

your-vault/
  Some Page.md
  Another.md
  .zetl/
    index/        # link graph, content-addressable blocks
    jj/           # history snapshots (with --features history)
    themes/       # custom themes
    hooks/        # lifecycle and render-pipeline hooks
    collab/       # auth, CRDT state (in --collab mode)

All of it is disposable. Delete .zetl/ and your notes are untouched; a fresh zetl index rebuilds the cache from scratch. See Configuration.

Backlinks

Troubleshooting ×2
Index

Linked Pages

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

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

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.

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.

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

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.

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

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

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.

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:

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.

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

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"

FAQ