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.

Which commands accept it

Every read-only subcommand. A partial list:

zetl --at "last week" links "Project X"
zetl --at "2024-06-01" stats
zetl --at HEAD~5 check
zetl --at "yesterday" backlinks "Draft"
zetl --at "3 days ago" search "deadline"
zetl --at "last monday" orphans

Commands that write — index, watch with side effects, hooks that mutate files — ignore --at or refuse to run against a historical state. You cannot accidentally edit a past vault.

Typical workflow

zetl stats — current numbers.
zetl --at "last monday" stats — a week ago.
Eye the diff. If something’s interesting, narrow: zetl --at "last monday" links "That Page".
Still interesting? zetl diff --from "last monday" summarises the full graph-level delta.

No checkout, no stash, no branch — the live vault on disk doesn’t move.

Use case: “what did the vault look like when I wrote that blog post?”

You posted an essay on March 3rd. The essay cites five zetl pages. You want to know what those pages said on March 3rd — not their current, evolved state.

zetl --at "2024-03-03" view "Mental Models"
zetl --at "2024-03-03" links "Mental Models"

The view reads from that snapshot’s content; the link graph matches. Export the essay’s sources as they appeared at publication time, so the post’s argument stays reproducible.

When `--at` returns nothing useful

If you installed history late in the vault’s life, snapshots only exist from that point forward. zetl history timeline lists every snapshot on record — your effective floor for time-travel.

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.

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:

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

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

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

Time Travel

Why time-travel your notes

What --at accepts

Which commands accept it

Typical workflow

Use case: “what did the vault look like when I wrote that blog post?”

When --at returns nothing useful

Related

Backlinks

What `--at` accepts

When `--at` returns nothing useful