Install

zetl requires a Rust toolchain. Install one via rustup if you don’t already have it.

(given single-binary)
(given fast-startup)
(given type-safe)

Basic install (wikilinks only)

make install

This builds a lean binary with wikilink parsing, graph queries, search, TUI, and the web UI — everything except concepts/Defeasible Reasoning.

With reasoning support

cargo install --path . --features reason

The reason feature gate pulls in the concepts/Spindle Lisp runtime (spindle-core). Without it, running zetl reason prints a helpful error instead of failing silently — see Feature Gates for the design rationale.

From source

git clone <repo-url>
cd zetl
make           # fmt + clippy + build + test
make release   # optimized binary

Verify installation

zetl --version
zetl -d ./demo-vault stats

You should see page counts and link statistics from the included Demo Vault.

Backlinks

CLI Referenceline 64
Indexline 17
Quick Startline 53
Quick Startline 3
Compatibilityline 39
Feature Gatesline 41

Linked Pages

Compatibility

zetl works with any Markdown vault that uses [[wikilink]] syntax. It never modifies your files.

(given obsidian-compatible)
(given logseq-compatible)
(given foam-compatible)
(given dendron-compatible)

Supported tools

Tool	Status	Notes
Obsidian	Full support	Standard `[[wikilink]]` syntax, aliases, headings, block references
Logseq	Full support	Wikilinks in Markdown mode
Foam	Full support	VS Code extension using `[[wikilinks]]`
Dendron	Full support	VS Code extension with Markdown wikilinks

What zetl reads

zetl parses [[target]], [[target|alias]], [[target#heading]], [[target^block-id]], and ![[embeds]]. It identifies pages by filename (case-insensitive, .md extension stripped). See concepts/Wikilinks for the full grammar.

What zetl ignores

Frontmatter (YAML between --- fences) — parsed but not treated as links
Code blocks — wikilinks inside fenced code are ignored
Comments — HTML comments are skipped

SPL is optional

concepts/Spindle Lisp embedding is entirely optional. Vaults work fine with just wikilinks — SPL adds reasoning capabilities on top. If you don’t use SPL, commands like zetl links, zetl check, and zetl tui work identically.

The `.zetl/` directory

The index and theory cache are stored in .zetl/ at the vault root. This directory is disposable — delete it any time, and zetl index rebuilds it. Add .zetl/ to your .gitignore. See architecture/Cache.

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.

Quick Start

A five-step tour of zetl’s core capabilities. Assumes you’ve already run Install.

Step 1: Build the index

zetl -d ./demo-vault index

This scans all Markdown files, extracts concepts/Wikilinks and concepts/Spindle Lisp blocks, and builds the link graph. The index is cached in .zetl/ for fast subsequent runs — see architecture/Cache.

Step 2: Explore stats

zetl -d ./demo-vault stats --format table

Shows page count, link count, orphan count, and the most-linked pages. All commands output JSON by default — add --format table for human-readable output. See Stats Command.

Step 3: Validate the vault

zetl -d ./demo-vault check --format table

Reports dead links, orphan pages, syntax errors, and SPL diagnostics. See Check Command.

Step 4: Launch the TUI

Demo Vault

zetl ships with a demo-vault/ directory — a self-referential knowledge base that documents zetl itself using both concepts/Wikilinks and concepts/Spindle Lisp.

What’s inside

The demo vault contains pages across several categories:

architecture/ — architecture/Scanner, Link Graph, architecture/Cache, Reasoning Engine, architecture/Performance
concepts/ — concepts/Wikilinks, concepts/Defeasible Reasoning, concepts/Spindle Lisp, concepts/Provenance
decisions/ — ADR-001 Rust, Feature Gates, JSON by Default, decisions/Local-first Design
features/ — command documentation for graph queries, search, diagnostics, and reasoning
theories/ — standalone .spl files with cross-cutting rules

SPL showcase

The demo vault embeds SPL facts in prose pages (e.g., (given wikilink-extraction) in the Scanner page) and combines them with rules in theories/release-readiness.spl. Running zetl reason status derives conclusions like release-candidate from facts scattered across the vault.

The theories/caching.spl file includes a deliberate conflict that zetl reason conflicts surfaces — two competing rules about cache reasoning results with no superiority relation.

Try it

zetl -d ./demo-vault index
zetl -d ./demo-vault stats --format table
zetl -d ./demo-vault reason explain "release-candidate" --format natural
zetl -d ./demo-vault reason conflicts --format table
zetl -d ./demo-vault serve

This vault vs the demo vault

This zetl-vault/ is a more comprehensive documentation vault. The demo vault is smaller and focused on showcasing features. Both are self-documenting — they use zetl’s own features to describe zetl.

Feature Gates

The Reasoning Engine and all Reason Commands are behind a Cargo feature flag: --features reason. This keeps the default binary lean and the dependency tree small.

(given reason-feature-optional)
(given graceful-degradation)

How it works

In Cargo.toml:

[features]
default = []
reason = ["dep:spindle-core", "dep:spindle-parser"]

Building without the flag produces a binary that handles concepts/Wikilinks, graph queries, Search Command, Check Command, and the TUI — everything except reasoning.

Graceful degradation

When a user runs zetl reason on a binary built without the feature, they get a clear error message explaining how to rebuild with --features reason. This is better than a confusing “unknown command” error.

Why not always include it?

spindle-core and spindle-parser add compile time and binary size
Not every user needs concepts/Defeasible Reasoning
concepts/Spindle Lisp is a niche feature — progressive disclosure serves users better

Progressive disclosure

Spindle Lisp

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

(given spl-documented)

Syntax reference

Facts

Unconditionally true propositions:

(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:

Defeasible Reasoning

Defeasible reasoning is a form of logic where conclusions can be drawn tentatively and later retracted when stronger evidence appears. This is how most real-world reasoning works — we act on the best information available, knowing new facts might change our minds.

(given defeasible-reasoning-documented)

Why it fits knowledge management

Decision documents, architecture records, and project plans all contain reasoning that is provisional. A conclusion like “use Redis” might be well-supported now but defeated by a future license audit. concepts/Spindle Lisp lets you express this directly in your notes, and zetl’s Reasoning Engine computes what follows.

Rule types

Type	Syntax	Meaning
Fact	`(given X)`	X is unconditionally true
Strict	`(always label body head)`	If body, then head — no exceptions
Defeasible	`(normally label body head)`	If body, normally head — can be defeated
Defeater	`(except label body head)`	If body, block head — but don’t assert the opposite

Superiority

When two rules conflict, a superiority relation resolves the tie:

(prefer stronger-rule weaker-rule)

Without a declared preference, the conflict remains unresolved — zetl reason conflicts will flag it. See Reason Commands.

Conclusion tags

Tag	Meaning
`+D`	Definitely provable — strict derivation, no defeating possible
`-D`	Definitely not provable
`+d`	Defeasibly provable — inferred, no active defeaters
`-d`	Defeasibly not provable — blocked or no derivation path