Web Server

zetl serve starts a local web server that renders your vault as a browsable site. You get rendered Markdown, working wikilinks, a live backlink panel, a persistent graph mini-map, and an in-browser editor. It’s the fastest way to actually read — and edit — a vault of more than a handful of notes.

Why run a server

A static export (Static Site Export) shows your vault as it was when you last built it. A terminal viewer (Terminal Viewer) shows one note at a time. zetl serve is what you want between those: a live view of the vault right now, with:

Rendered pages — Markdown, wikilinks, embeds, and code blocks, rendered through Minijinja templates with YAML frontmatter in scope.
Backlinks panel — every page that points here, updated on every save.
Transclusion panel — forward-link excerpts as cards in the right rail, connected to anchors in the main text by SVG bridges (the same Xanadu idea as the terminal viewer).
Live search — full-text search across the vault from a modal.
CodeMirror editor — click Edit, change the note, hit Save. The index rebuilds on save; no reload dance. A delete button is a click away.
Persistent graph mini-map — a Sigma.js WebGL graph of your vault, docked bottom-right, that survives page navigation (no flash, no re-layout).
History strip — when zetl was built with --features history, every page shows when it last changed and links to its timeline. See Page History.

Running it

zetl serve                            # http://localhost:3000
zetl -d ~/notes serve
zetl serve --port 8080
zetl serve --theme paper

Open http://localhost:3000/ to land on the vault index. Wikilinks in rendered pages are clickable. Ctrl-P (or whatever the active theme binds) opens the search modal.

Flags that matter

Flag	Default	Purpose
`-p, --port <PORT>`	`3000`	TCP port.
`--theme <THEME>`	`default`	Theme from `.zetl/themes/<name>/`. See Customising the Look.
`--public <DIR>`	—	Files in this directory override generated pages (good for `robots.txt`, custom error pages).
`--collab`	off	Switches to multi-user mode with passkeys and CRDT sync. See Running a Team Server.
`--safe-mode`	off	Skip every hook except ones declared in the theme.
`--at <TIME-EXPR>`	—	Serve a past snapshot. See Time Travel.
`--exclude <PATTERN>`	—	Gitignore-syntax exclusion, repeatable.

Single-user vs collab

Out of the box, zetl serve is single-user and trusts whoever reaches the port. There’s no login, no accounts; editing works immediately. This is the right mode when the server is on your laptop or behind a VPN.

With --collab, zetl turns into a multi-user server: WebAuthn passkey login, real-time CRDT editing over WebSockets, access control, invitations. That whole stack — bootstrapping an owner, inviting collaborators, deterministic server keys — lives in Running a Team Server.

API endpoints

serve exposes a small JSON API on the same port. A brief sample:

Endpoint	Method	Purpose
`/api/pages`	GET	List every page
`/api/pages/{slug}`	GET/PUT/DELETE	Read, update, remove
`/api/search?q=...`	GET	Full-text search
`/api/graph`	GET	Full link graph JSON
`/api/index`	POST	Trigger a reindex

See CLI Overview for the full endpoint list including the collab-only WebSocket and access-request endpoints.

Backlinks

Linked Pages

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.

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.

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/

Terminal Viewer

zetl view is a Xanadu-inspired two-pane reader for reading linked notes without leaving the terminal. It exists because most of the time you don’t want a browser — you want to sit with one note, glance at what it points to, and jump onwards when something catches your eye.

Why two panes

When you read a note in a normal editor, forward-links are just names — [[Zettelkasten Method]] tells you nothing about what Zettelkasten Method actually says. Ted Nelson’s original vision for Xanadu put the cited text right next to the citing text, bridged by a visible connector. zetl view does exactly that in a TTY:

Main pane (left) — the note you asked for, rendered as Markdown. Every wikilink is annotated with a numbered anchor glyph [1], [2], [3] in reading order.
Context column (right) — a stack of context cards, one per forward link. Each card shows the first few lines of the linked note, coloured to match its anchor.
Bridge column (middle) — coloured connectors from each [N] anchor to its card, so your eye can follow the citation at a glance.

In terminals narrower than 60 columns the layout collapses to single-pane and context cards become inline footnotes. You lose the bridges but keep the anchors.

Opening a page

zetl view "Zettelkasten Method"      # by page name
zetl view                            # interactive page picker
zetl view "Project Notes" --context-lines 10
zetl view "Project Notes" --main-width 65

With no argument, zetl view launches an interactive picker of every page in the vault — type to filter, Enter to open.

Flags

Flag	Default	Purpose
`--context-lines <N>`	`5`	Lines shown per context card. Range 1–20.
`--main-width <pct>`	`58`	Percent of terminal columns for the main pane. Range 30–80.
`--at <TIME-EXPR>`	—	Read a past snapshot (see Time Travel).
`-d, --dir <DIR>`	`.`	Vault root.

Keybindings

Key	Action
`j` / `k`	Scroll down / up (or cycle anchors in focus mode)
`Ctrl-d` / `Ctrl-u`	Half-page down / up
`g` / `G`	Jump to top / bottom of the note
`Tab`	Toggle between scroll mode and focus mode
`Enter`	Navigate to the focused link
`[` / `]`	Session history: back / forward
`/`	Open the page picker
`?`	Toggle the keybindings overlay
`q`	Quit

Focus mode is what makes the navigation fast. Hit Tab, then j/k steps from one anchor to the next (not one line at a time); the bridge column highlights the selected anchor’s connector; Enter opens that page. [ returns to where you came from, so you can explore breadth-first through a chain of notes and back-track without losing your place.

Static Site Export

zetl build turns your vault into a folder of plain HTML, CSS, and JavaScript. No runtime, no database, no server process — every page is a file you can upload to any static host. The output looks the same as Web Server minus the editor.

Why build a static site

A static site is the right deliverable when:

You want to publish research notes, a personal wiki, or project docs to the public internet.
You want a vault readable from any browser with zero operational overhead.
You want something to hand to collaborators, reviewers, or your future self that doesn’t depend on the zetl binary being installed.
You want archival: HTML works the same way in 2040 as it does in 2026.

Because nothing on the published site writes back, the edit button is absent and the save/delete endpoints aren’t emitted. Everything else — wikilinks, backlinks, transclusion panels with SVG bridges, the graph widget, full-text search, per-page history (if built with --features history) — lands in the output as static HTML and JSON.

Running it

zetl build                             # writes ./dist/
zetl -d ~/notes build
zetl build --out-dir site              # custom output directory
zetl build --theme paper               # pick a theme
zetl build --site-url https://vault.example    # absolute URLs for social cards

Preview the result locally with any static file server:

python3 -m http.server -d dist 8080

Then open http://localhost:8080/.

Output structure

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.

Page History

Requires --features history at install. See Installation.

Every page in your vault has a life story: when you wrote it, how often you’ve edited it, when each backlink appeared, how stable it’s become. zetl history page and the history UI surface that story.

The command

zetl history page "Zettelkasten Method"

Prints a reverse-chronological list of snapshots that touched the page, with timestamp, change-ID, and a short description of what changed (links added, links removed, content modified). Defaults to 20 entries; --limit goes higher.

zetl history page "Zettelkasten Method" --limit 100
zetl history page "Draft Essay" --json | jq

Case-insensitive on the page name; aliases resolve too.

What’s available in the web UI

When you run zetl serve (or publish with zetl build) against a history-enabled binary, every rendered page gains a visually-light metadata strip under the title:

Last changed 2026-03-18 · stable 28d · history

Web Server

Why run a server

Running it

Flags that matter

Single-user vs collab

API endpoints

Related

Backlinks