Following Links

Three commands walk the forward-link graph: zetl links for a page’s neighbours, zetl path for the shortest route between two pages, and zetl export for dumping the whole graph as JSON. Together they turn your vault into a navigable graph you can query from the shell.

`zetl links` — forward neighbours

zetl links "Zettelkasten Method"

Prints every page that Zettelkasten Method links to. This is the complement of Backlinks: forward links are what this page cites; backlinks are what cites it.

Walk further with --depth:

# Direct forward links
zetl links "2026 Research Plan"

# Two hops: pages linked from pages linked from the plan
zetl links "2026 Research Plan" --depth 2

Useful flags:

Flag	Use
`--depth N`	Multi-hop forward traversal
`--context 80`	Show surrounding prose of each link
`--fuzzy`	Tolerate typos in the source page name

See CLI Overview for the rest.

`zetl path` — shortest route between two pages

zetl path "CRDT" "Zettelkasten Method"

CRDT
-> Collaborative Editing
-> Knowledge Management
-> Zettelkasten Method

This answers how is X connected to Y? — a question that comes up constantly when you are trying to explain a decision (“why did I end up thinking about Luhmann while researching CRDTs?”). zetl performs an undirected BFS over wikilinks and returns the first shortest path.

Tune the search with --max-depth N (default 10). Raise it for large vaults where the connection is genuinely distant; lower it to fail fast when you suspect there is no path at all.

zetl path "2026 Research Plan" "Dream Journal 2019-03-04" --max-depth 6
# no path found within 6 hops

No path found is a meaningful answer: these two notes live in disconnected components of your graph, and that is a real fact about your thinking.

`zetl export` — the full graph as JSON

zetl export > graph.json

Writes the entire vault graph: every page, every edge, every frontmatter block. This is the integration point for everything outside zetl — graph-viz tools, AI agents, custom dashboards, academic network analysis scripts.

The schema is stable and documented at CLI Overview. A trimmed view:

{
  "pages": [
    { "name": "Zettelkasten Method", "path": "concepts/Zettelkasten Method.md",
      "frontmatter": { "tags": ["method"] },
      "links_out": ["Luhmann", "Index Card"],
      "links_in":  ["2026 Research Plan", "Note-Taking Comparison"] }
  ],
  "edges": [
    { "from": "Zettelkasten Method", "to": "Luhmann", "kind": "wikilink" }
  ]
}

Practical uses

Graph visualisation. Pipe the export into Gephi, Cytoscape, or any force-directed tool:

zetl export --json \
  | jq '{nodes: [.pages[] | {id: .name}],
         edges: [.edges[] | {source: .from, target: .to}]}' \
  > cytoscape.json

AI agents. Feed the full graph to an agent so it can ground answers in your own note topology. The MCP server (MCP Server) exposes a thinner version of the same data.

Diffing graphs over time. Combine with --at (requires --features history) to compare your graph now vs. a month ago:

zetl export --at "30 days ago" > graph-last-month.json
zetl export > graph-now.json
# whatever diff tool you like

Example: explain a decision

You made a call in 2026 Research Plan to build on CRDTs. A colleague asks why. You retrace the chain:

zetl path "2026 Research Plan" "CRDT"
# 2026 Research Plan
# -> Collaborative Tools Review
# -> Real-time Sync
# -> CRDT

Each hop is a note you wrote with its own reasoning. Open them in order with zetl view and you have the audit trail — not reconstructed from memory, but from the links you dropped as you thought.

Backlinks

Linked Pages

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

Searching

zetl search scans your vault for a string and prints the matches, with context. It is deliberately small: a fast text finder for when you remember a phrase but not which note it lives in.

zetl search "attention is all you need"

No regex engine, no query DSL. If you want regex, pipe the raw index through rg. What zetl gives you instead is graph-aware narrowing.

The two flags you will actually use

Flag	What it does
`--near "Zettelkasten Method"`	Only match pages within `--depth` hops of that page
`--case-sensitive`	Exact case, no folding

--near is the one most people miss. A keyword search over 4,000 notes gives you noise; a search restricted to “notes that cite Zettelkasten Method or one link away” gives you signal.

# Every note mentioning "CRDT" anywhere in the vault
zetl search "CRDT"

# Every note about CRDTs within two hops of my reading list
zetl search "CRDT" --near "2026 Research Plan" --depth 2

Other useful flags:

--path "journal/**" — glob filter on file paths.
--context 120 — widen the snippet from the default 40 characters.
--limit 200 — default is 50; raise for grep-replace workflows.

See CLI Overview for the full list.

JSON when piped

When stdout is a pipe or redirect, zetl search auto-switches to JSON. This is the contract that lets you chain searches into scripts:

The Link Graph

zetl thinks about your vault as a directed graph: pages are nodes, wikilinks are edges. Every command you will run — backlinks, path, orphans, export, the graph widget in zetl serve — is a query over this graph. Understanding the model makes the rest of zetl obvious.

What a node is

A node is one page: one .md file in your vault. The node’s identity is its filename (minus .md, case-normalised). The node’s content is what’s between the frontmatter and the end of file. That’s it — no IDs, no database keys.

What an edge is

Every [[wikilink]] you write is an edge from the current page to the target. Edges are directed: A.md writing [[B]] creates an edge A → B, not B → A. Backlinks are the inverse — the set of pages that link at you.

The graph distinguishes:

Plain edges — [[Page]], [[Page|alias]]
Heading edges — [[Page#heading]]
Block edges — [[Page^b3a9f1]], which target a specific block
Embed edges — ![[Page]], same edge, different rendering

All four contribute to forward-links and backlinks. An aliased link is still an edge to Page, not to alias.

Dead links and orphans

Two graph concepts show up often enough to name:

A dead link is an edge whose target has no matching file. The edge exists in the graph; the node on the far end is empty. zetl check --dead-links lists them.
An orphan is a node with no inbound edges — nothing links to it. An orphan may still have outbound links. zetl check --orphans lists them.

Backlinks

zetl backlinks "Page" lists every page that links to Page. It is the quiet workhorse of a wikilink system — more useful, over time, than the links you write yourself.

zetl backlinks "Zettelkasten Method"

Output: the file path, the line of the match, and (with --context N) a snippet of the surrounding prose.

Why backlinks matter

Forward links are a claim you made at the time of writing. A backlink is every claim anyone ever made that referred back to this idea — including you, six months later, with more context. That asymmetry is the whole research payoff:

You read a paper and start a note on it. A year later the note has eight backlinks: three from project docs, two from meeting minutes, one from a book review. You did not plan any of that. The graph assembled it.
You are revisiting an old concept page. Instead of re-reading it in isolation, you walk its backlinks — every context in which you once found it relevant. That is a research tool disguised as a list.

Forward links (see Following Links) answer what does this page talk about? Backlinks answer what talks about this page? The second question is almost always more interesting for notes older than a few weeks.

Multi-hop with `--depth`

By default zetl backlinks returns direct, one-hop references. --depth N walks the reverse graph:

# Direct backlinks only
zetl backlinks "Zettelkasten Method"

# Every page that reaches "Zettelkasten Method" in up to 3 reverse hops
zetl backlinks "Zettelkasten Method" --depth 3

Depth 2–3 is where the transitive structure gets interesting: you find the notes that cite notes that cite this concept. Depth 5+ tends to return most of your vault — the graph is small-world.

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.

Following Links

zetl links — forward neighbours

zetl path — shortest route between two pages

zetl export — the full graph as JSON

Practical uses

Example: explain a decision

Related

Backlinks

`zetl links` — forward neighbours

`zetl path` — shortest route between two pages

`zetl export` — the full graph as JSON