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

Level	Source	Scope
1	Hardcoded	`.git/`, `.zetl/`, `node_modules/`. Always excluded. Not negatable.
2	Dotdir default	Any top-level directory whose name starts with `.` (`.claude/`, `.obsidian/`, `.cache/`, …). Disable with `--include-hidden`.
3	`.gitignore`	Standard git rules, walked from the vault root.
4	`.zetlignore`	Same syntax as `.gitignore`. zetl-specific overrides of the above.
5	`--exclude <PATTERN>`	Gitignore-syntax, repeatable on the CLI. Overrides everything except level 1.

A .zetlignore negation (!drafts/notes.md) also overrides the level-2 dotdir default, letting you pull single files out of otherwise-excluded dot-directories without changing git’s behaviour.

Dotfiles at the top level (e.g. .editorconfig) are not excluded by the level-2 rule — only directories.

`theme.toml`

Themes live at .zetl/themes/<name>/theme.toml for installed themes, or bundled inside the binary at build time. See Customising the Look.

`[theme]`

Key	Purpose
`name`	Theme name. Matches the directory name.
`version`	SemVer.
`description`	Optional one-line description.
`author`, `license`, `homepage`, `min_zetl_version`	Metadata. Optional.

`[theme.templates]`

[theme.templates]
overrides = ["base.html", "page.html", "folder.html"]

Tells zetl which template files this theme provides. Anything not listed falls back to the default theme.

`[[theme.hooks]]`

Array-of-tables declaring hooks shipped under the theme’s hooks/ directory. Under --safe-mode, only declared hooks run; everything else (and every vault hook) is skipped.

[[theme.hooks]]
stage = "transform"
extension_id = "callouts"
ecosystem = "pandoc"     # optional; SPEC-033
summary = "Expand GFM admonitions into styled blockquotes"

[theme.hooks.contract]
preserves = ["Wikilink", "Embed"]
idempotent = true

stage is pre-parse, transform, or post-render. extension_id matches the hook executable’s filename stem (minus any \d+- ordering prefix).

`[spa]`

[spa]
enabled = true

Enables the persistent-shell SPA navigation module in the default theme. The element carrying data-zetl-volatile is swapped on same-origin <a> clicks instead of triggering a full reload. Sidebar and graph stay mounted.

`[graph]`

[graph]
placement = "docked"     # "docked" | "tabs" | "stacked"

graph_inline = true at the top level opts the theme into inlined graph JSON on every render (the page’s local graph is serialised into the template context).

`[vendor.*]`

Pinned client-side assets — sigma, graphology, graphology-layout-forceatlas2. Each entry locks a version, source URL, bundled filename, SHA-256, and license. zetl build fails loudly if an asset hash doesn’t match.

The `.zetl/` directory

zetl never writes to your Markdown files. Everything it caches, derives, or persists lives under .zetl/ at the vault root. Safe to delete — it’ll rebuild.

Path	Contents
`.zetl/index.json`	Cached link graph. `zetl index` writes it.
`.zetl/theory.json`	Compiled SPL theory (requires `reason`).
`.zetl/search/`	Tantivy BM25 index (one segment per `.fast`/`.idx`/`.store`/etc. shard).
`.zetl/search/vectors/`	Semantic-search embeddings (requires `semantic`).
`.zetl/history/`	Snapshot metadata JSON files (requires `history`).
`.zetl/jj/`	Jujutsu repo backing the silent snapshots (requires `history`).
`.zetl/themes/`	Installed (non-bundled) themes.
`.zetl/hooks/`	Vault-local hook executables and their sidecar manifests (`<name>.<ext>.toml`).
`.zetl/collab/server.key`	Multi-user signing key. Derived from `ZETL_SERVER_KEY_SEED` when set.
`.zetl/crdt/`	Peritext CRDT documents, one per page under `--collab`.
`.zetl/users/`	Per-user records (passkey credentials, roles).
`.zetl/models/`	Cached ONNX models + tokenisers (semantic search, agents).
`.zetl/caps/`	Capability-URL cohorts, grants, and pairing nonces.

Add .zetl/ to your .gitignore unless you have a specific reason to commit the cache (e.g. reproducible search-index tests).

Backlinks

Linked Pages

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:

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.

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/

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

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.

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

Configuration

Environment variables

Read by the CLI

Exported to hooks

Ignore files

theme.toml

[theme]

[theme.templates]

[[theme.hooks]]

[spa]

[graph]

[vendor.*]

The .zetl/ directory

Related