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

~/.local/bin/zetl                                    # the binary
~/.local/share/man/man1/zetl.1                       # man page (run 'man zetl')
~/.local/share/bash-completion/completions/zetl
~/.local/share/zsh/site-functions/_zetl
~/.local/share/fish/vendor_completions.d/zetl.fish

The prebuilt binaries include the reason, history, and mcp features. See #Feature flags below if you need a different set.

PATH check

The installer warns if ~/.local/bin isn’t on your PATH. If it isn’t:

export PATH="$HOME/.local/bin:$PATH"
# Add to ~/.bashrc, ~/.zshrc, or ~/.config/fish/config.fish to persist

Install from source

Requires a Rust toolchain (rustup.rs).

git clone https://codeberg.org/anuna/zetl && cd zetl
make install

make install builds with core features only and installs to $PREFIX (default ~/.local). For optional features:

# Defeasible reasoning (SPL code blocks)
cargo install --path . --features reason

# Vault history (jj-backed snapshots, --at time travel)
cargo install --path . --features history

# Combine features
cargo install --path . --features "reason,history"

# Everything
cargo install --path . --features "reason,history,semantic,mcp"

Feature flags

Flag	Unlocks
(none)	Wikilink parsing, graph queries, search, `check`, `view`, `serve`, `build`, collaboration, hooks.
`reason`	Running Queries, SPL extraction from Markdown, proof trees, what-if, conflict detection, SPL-based access control.
`history`	Time Travel with `--at "3 days ago"`, Watching for Changes via `zetl watch`, per-page timeline, `vault.history` in templates.
`semantic`	Semantic search via embedding model (alongside full-text).
`mcp`	MCP Server — expose the graph, search, and reasoning to AI agents.

Collaboration (--collab) is always on — no feature flag required. SPL-based access control requires --features reason.

Shell completions

The binary generates completions on demand, in case you want to wire them up manually or use a shell not covered by the installer:

zetl completions bash       > /etc/bash_completion.d/zetl
zetl completions zsh        > ~/.zfunc/_zetl
zetl completions fish       > ~/.config/fish/completions/zetl.fish
zetl completions powershell > $PROFILE/zetl.ps1
zetl completions elvish     > ~/.config/elvish/lib/zetl.elv

Man page:

zetl man > /usr/local/share/man/man1/zetl.1    # install
zetl man | man -l -                            # preview without installing

Verifying the install

zetl --version
# zetl 0.6.1

If that prints, you’re done. Head to Quick Start for your first vault query.

Backlinks

Linked Pages

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.

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.

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

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

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.

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

(page does not exist)