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.

What it’s not

Not a server-only SaaS. zetl runs on your machine. There’s no account to sign up for. Team mode is opt-in and self-hosted.
Not a new Markdown flavour. zetl reads the Markdown you already write. Wikilink syntax is the same one Obsidian popularised. YAML frontmatter, headings, code fences, task lists — all standard.
Not a lock-in. zetl never writes to your notes. The index under .zetl/ is a cache; delete it and re-run zetl index, everything comes back. Your .md files are the only durable state.
Not a replacement for your editor. Use whatever you already use — Vim, VS Code, Obsidian, a plain text editor. zetl just queries what’s there.

Next step

If you haven’t installed it yet, go to Installation. Otherwise, spend 60 seconds with Quick Start.

Backlinks

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

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"

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:

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

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