Graph Queries

zetl exposes the Link Graph through several query commands. All output JSON by default — see JSON by Default.

(given forward-links-done)
(given backlinks-done)
(given shortest-path-done)

Commands

`zetl links <page>`

Show all pages that <page> links to. Supports --depth N for multi-hop traversal and --fuzzy for approximate page name matching.

`zetl backlinks <page>`

Show all pages that link to <page>. Same depth and fuzzy options as links.

`zetl path <from> <to>`

Find the shortest chain of Wikilinks connecting two pages. Useful for discovering how ideas relate through intermediate notes.

`zetl export`

Dump the entire Link Graph as JSON — every page and every link.

`zetl list`

List all pages in the vault.

`zetl stats`

Summary statistics: page count, link count, orphan count, and the most-linked pages.

Cross-referencing with reasoning

Add --with-conclusions to links or backlinks to see what 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

See also: Link Graph, Vault Diagnostics, Search, TUI

Backlinks

Link Graphline 36
Link Graphline 30
TUIline 38
Feature Gatesline 24
Vault Diagnosticsline 53
Searchline 47

Linked Pages

TUI

TUI

zetl tui launches an interactive terminal interface for browsing your vault. It is the human-oriented complement to zetl’s JSON by Default output.

Views

(given tui-complete)
(given seven-views)

View	Description
Dashboard	Vault stats and most-linked pages
Pages	Filterable page list
Links	Forward/back link explorer
Search	Full-text search with context
Diagnostics	Dead links, orphans, syntax issues
Page	Rendered Markdown with inline Wikilinks navigation
Graph	Local link graph with depth toggle

Navigation

Tab / Shift+Tab — cycle views
Ctrl+K — quick switcher
j / k — scroll
Enter — follow a wikilink
Backspace — go back

Implementation

Built on ratatui and crossterm. The TUI reads the same Link Graph and Cache as the CLI commands — no separate data path.

See also: Graph Queries, Search, Vault Diagnostics

Search

Search

zetl search provides full-text content search across all Markdown files in the vault. search-history

(given fulltext-search-done)
(given regex-support)

Usage

# Literal text search
zetl -d . search "defeasible"

# Regex search
zetl -d . search "reason(ing|ed)" --regex

# With surrounding context
zetl -d . search "Cache" --context 100

# Case-sensitive
zetl -d . search "SPL" --case-sensitive

# Restrict to a subdirectory
zetl -d . search "given" --path "theories/*"

Content filtering

By default, search skips frontmatter and fenced code blocks to focus on prose. Use --all to search raw file content including Spindle Lisp blocks and YAML frontmatter.

Fuzzy page name matching

For finding pages by name rather than content, use zetl similar:

zetl -d . similar "reasning engine"

This uses SimHash-based similarity to find close matches even with typos.

See also: Graph Queries, TUI, Scanner

Vault Diagnostics

Vault Diagnostics

zetl check validates the vault and reports issues. It examines both the Link Graph and Spindle Lisp content.

(given dead-link-detection)
(given orphan-detection)
(given spl-diagnostics)

Issue types

Dead links

A wikilink that points to a page that doesn’t exist. For example, [[Plugin System]] in this vault is a dead link — there is no Plugin System.md file.

zetl -d . check --dead-links

Orphan pages

Pages with no incoming links — nothing in the vault references them. These may be forgotten drafts or entry points that need a wikilink from somewhere.

zetl -d . check --orphans

Syntax errors

Malformed Wikilinks like unclosed brackets.

Link Graph

zetl builds a directed graph where nodes are pages and edges are Wikilinks. The graph powers all link-based queries: forward links, backlinks, multi-hop traversal, shortest path, and orphan detection.

Data model

Node — a Markdown page, identified by its title (filename without .md)
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 the Cache for incremental re-scans.

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

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 Graph Queries. 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.

See also: Scanner, Graph Queries, Vault Diagnostics

Reasoning Engine

Reasoning Engine

The reasoning engine takes Spindle Lisp extracted by the Scanner from across the entire vault, merges it into a single theory, and computes conclusions using Defeasible Reasoning. Every conclusion carries full Provenance — you can trace any result back to the exact file and line that contributed to it.

Pipeline

Extract — Scanner finds SPL blocks in Markdown fences and .spl files
Parse — spindle-parser converts SPL text into rule objects
Provenance — source file, line number, and page name are attached to each rule and fact
Combine — all rules and facts are merged into a single theory
Validate — check for undefined labels, duplicate definitions
Reason — spindle-core computes conclusions
Annotate — each conclusion is traced back to its proof sources

(given spindle-core-integrated)
(given four-conclusion-types)

Conclusion types

The engine produces four types of conclusion — see Defeasible Reasoning for details:

Tag	Meaning
`+D`	Definitely provable
`-D`	Definitely not provable
`+d`	Defeasibly provable
`-d`	Defeasibly not provable

Feature gate

The reasoning engine is compiled only when --features reason is enabled — see Feature Gates. Without it, zetl reason prints a clear error rather than failing silently.

See also: Reason Commands, Provenance, Spindle Lisp

Spindle Lisp

Spindle Lisp (SPL) is a domain-specific language for expressing Defeasible Reasoning theories. zetl extracts SPL from fenced code blocks in Markdown and from standalone .spl files.

Syntax reference

Facts

(given bird)
(given (not guilty))

Strict rules

Cannot be defeated. If the body holds, the head must hold.

(always r-penguin-is-bird penguin bird)

Defeasible rules

Can be defeated by stronger evidence. The label is optional.

(normally r-birds-fly bird flies)
(normally bird animal)

Defeaters

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.

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

How zetl uses them

The Scanner extracts wikilinks from every Markdown file. The Link Graph stores them as directed edges, enabling:

Forward link queries (zetl links)
Backlink queries (zetl backlinks)
Shortest path computation (zetl path)
Dead link detection (zetl check)

Cross-referencing with logic

When reasoning is enabled, --with-conclusions annotates link results with the Spindle Lisp conclusions that each linked page contributes. This bridges the Link Graph and the Reasoning Engine.

Compatibility

zetl supports the wikilink conventions used by Obsidian, Logseq, Foam, and Dendron. See Local-first Design for the principle that zetl never modifies your files.

JSON by Default

JSON by Default

All zetl commands emit JSON by default. Human-readable output is available via --format table (or --format natural / --format dot for reason explain).

(given json-default-output)
(given structured-errors)
(given nonzero-exit-codes)

Why agent-first

zetl is designed to work both as a human CLI tool and as a building block for AI agents and scripts. JSON output means:

Agents can parse results without scraping tables
Structured errors include error codes, affected files, and suggested fixes
Non-zero exit codes signal failure to shell scripts and CI pipelines
Output is composable with jq, fx, and other JSON tools

Human output

For interactive use, --format table renders results as aligned tables via comfy-table. The TUI provides a richer interactive experience — see TUI.

Both audiences

This dual-output design means a single tool serves both audiences. An agent might run zetl reason status and parse the JSON, while a human runs zetl reason status --format table and reads the output directly.

See also: Rust for CLI, TUI, Reason Commands