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"

Run zetl with no -d and no ZETL_DIR, and it uses the current directory.

You can have many vaults

A vault is just a folder, so you can keep as many as you like — one for research, one for journaling, one for client work — each with its own .zetl/ cache and its own graph. They do not share any state. Switching is just cd or -d.

Some people keep one enormous vault and lean on folders plus tags; others keep several small ones. Neither is wrong. See Organising Your Vault.

What a vault is not

Not a database. Your notes are flat files. Open them in any editor; edit them with any tool.
Not a format. zetl reads the Markdown you already have. No special syntax is required. Wikilinks and frontmatter are optional.
Not locked in. If you stop using zetl tomorrow, you still have a directory of Markdown files. Everything zetl added is in .zetl/.

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

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

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

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: