Path Command

zetl path finds the shortest chain of concepts/Wikilinks connecting two pages in the Link Graph.

Usage

zetl -d ./my-vault path "Scanner" "Provenance"

Flags

Flag	Default	Description
`--max-depth N`	10	Maximum path length to search

How it works

zetl performs a breadth-first search on the directed link graph from the source page toward the target. The result is the shortest sequence of pages connecting them.

This is useful for discovering how ideas relate through intermediate notes — a form of knowledge exploration that leverages the graph structure built from wikilinks.

Output

JSON output includes the ordered list of pages in the path and the total hop count. Table output shows the path as an arrow-separated chain.

If no path exists within --max-depth hops, zetl reports that the pages are not connected.

Backlinks

Links Commandline 40
CLI Referenceline 25
Indexline 25
Link Graphline 30

Linked Pages

Link Graph

zetl builds a directed graph where nodes are pages and edges are concepts/Wikilinks. The graph powers all link-based queries.

(given directed-graph)
(given multi-hop-traversal)

Data model

Node — a Markdown page, identified by its title (filename without .md, case-insensitive)
Edge — a wikilink from one page to another, with optional alias, heading, or block reference

The graph is built by the Scanner and cached by architecture/Cache for incremental re-scans.

Resolution

Page names are resolved case-insensitively. When a wikilink target like [[cache]] appears, zetl matches it to Cache.md regardless of casing. For disambiguation between pages with the same name in different directories, use path-qualified links like [[architecture/Cache]].

Queries

Command	Description
`links`	Forward links from a page, with configurable depth
`backlinks`	Pages linking to a target, with depth traversal
`path`	Shortest link path between any two pages
`export`	Full graph as JSON

These are exposed through Links Command, Path Command, and List and Export Commands. With the --with-conclusions flag, link results are cross-referenced with the Reasoning Engine to show what each linked page contributes to the vault’s logic.

Library

Built on petgraph, a Rust graph data structure library. The graph is stored as a flat adjacency list for cache-line efficiency during multi-hop traversal. See Performance.

Links Command

zetl links and zetl backlinks query the Link Graph for forward and backward connections.

Usage

# Forward links — pages that <page> links to
zetl -d ./my-vault links "Scanner"

# Backlinks — pages that link to <page>
zetl -d ./my-vault backlinks "Cache" --depth 2

Flags

Flag	Default	Description
`--depth N`	1	Traverse N hops (1 = direct only)
`--fuzzy`	off	Enable fuzzy page name matching via concepts/SimHash
`--context N`	0	Include N characters of surrounding text
`--with-conclusions`	off	Show SPL conclusions each linked page contributes

Multi-hop traversal

With --depth 2, zetl follows links from the target page AND from every page the target links to (or is linked by). This reveals indirect relationships in the vault’s knowledge structure.

Deduplication

By default, zetl deduplicates results — a page appears once even if multiple links point to it. This is the output-layer deduplication described in ADR-004 Link Dedup.

Cross-referencing with reasoning

Add --with-conclusions to see what concepts/Spindle Lisp conclusions each linked page contributes. This bridges the structural graph with the logical theory from the Reasoning Engine.

zetl -d . links "Cache" --with-conclusions

CLI Reference

zetl is a single binary with subcommands. All commands output JSON by default — see JSON by Default.

Global flags

Flag	Short	Description
`--dir <path>`	`-d`	Vault root directory (default: `.`)
`--format <fmt>`	`-f`	Output format: `json` (default) or `table`
`--no-cache`		Force full rescan, ignore cached index
`--no-color`		Disable colored output
`--quiet`	`-q`	Suppress non-essential output
`--verbose`	`-v`	Increase verbosity (repeat for more: `-vv`)

Commands

Wikilink commands

Command	Description	Reference
`index`	Build or refresh the link index	Index Command
`links <page>`	Query forward links from a page	Links Command
`backlinks <page>`	Query backlinks to a page	Links Command
`path <from> <to>`	Shortest link path between pages	Path Command
`search <query>`	Full-text content search	Search Command
`similar <query>`	Fuzzy page name matching (SimHash)	Similar Command
`check`	Validate vault: dead links, orphans, SPL errors	Check Command
`blocks [page]`	List or resolve Merkle content blocks	Blocks Command
`diff`	Git-backed graph diff	Diff Command
`watch`	NDJSON event stream on file changes	Watch Command
`list`	List all pages	List and Export Commands
`export`	Export complete link graph as JSON	List and Export Commands
`stats`	Vault summary statistics	Stats Command
`tui`	Interactive terminal UI	TUI
`view [page]`	Xanadu-style two-pane reader	View Command
`serve`	Local web server	Serve Command
`build`	Static site export	Build Command

Reasoning commands

Require --features reason at build time. See Feature Gates.

Command	Description	Reference
`reason status`	Current conclusions from vault-wide SPL	Reason Commands
`reason explain <literal>`	Proof tree with provenance	Reason Commands
`reason why-not <literal>`	Why a literal isn’t provable	Reason Commands
`reason require <literal>`	Abductive: what facts are needed	Reason Commands
`reason what-if <spl>`	Hypothetical reasoning	Reason Commands
`reason conflicts`	Unresolved logical contradictions	Reason Commands
`reason export`	Export combined theory	Reason Commands
`reason provenance <literal>`	Trace conclusion to source files	Reason Commands

Exit codes

Code	Meaning
0	Success
1	Error (dead links found with `--fail-on error`, conflicts with `--fail-on-conflicts`, etc.)

Structured JSON errors are written to stdout, not stderr. See ADR-003 JSON Errors.

Wikilinks

Wikilinks are inline references between pages using [[double bracket]] syntax. They are the primary connective tissue in a zetl vault, forming the edges of the Link Graph.

(given wikilink-syntax-documented)

Syntax

Form	Example	Description
Basic	`[[Cache]]`	Link to a page
Aliased	`[[Cache\|caching layer]]`	Display text differs from target
Heading	`[[Cache#Design tension]]`	Link to a specific heading
Block	`[[Cache^summary]]`	Link to a block ID
Embed	`![[Cache]]`	Embed the target page inline
Self-heading	`[[#Syntax]]`	Link to heading in same page

Formal grammar

wikilink     = "[[" target ("#" fragment)? ("|" alias)? "]]"
embed        = "![[" target "]]"
target       = page-name
fragment     = heading | "^" block-id
heading      = text
block-id     = alphanumeric-with-hyphens
alias        = text
page-name    = text (may include "/" for path-qualified links)

Parsing rules

The architecture/Scanner extracts wikilinks from every Markdown file. Wikilinks inside the following zones are ignored:

Fenced code blocks (```)
Inline code (`)
HTML comments ()
YAML frontmatter (--- fences)

Resolution

Page names are matched case-insensitively. [[cache]] resolves to Cache.md. When ambiguity exists (e.g., concepts/SimHash.md and architecture/SimHash.md), use path-qualified links: [[concepts/SimHash]] or [[architecture/SimHash]].