Rust for CLI

zetl is written in Rust. This was a deliberate choice driven by the requirements of a CLI tool that handles large vaults and complex reasoning.

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

Why Rust

Type safety — the Scanner, Link Graph, and Reasoning Engine involve complex data flows. Rust’s type system catches entire classes of bugs at compile time.
Single binary — cargo install produces one executable with no runtime dependencies. Users don’t need Python, Node, or a JVM.
Fast startup — CLI tools that take hundreds of milliseconds to start feel sluggish. Rust’s zero-cost abstractions keep startup instant even on large vaults.
Memory safety — no garbage collector pauses, no null pointer surprises. Important when processing thousands of files.

Trade-offs

Slower to iterate during development compared to a scripting language
The Feature Gates mechanism adds build complexity
Compile times are non-trivial

These trade-offs are acceptable for a tool meant to be installed once and used daily.

Dependencies

Key crates: clap (CLI parsing), petgraph (Link Graph), pulldown-cmark (Scanner), ratatui (TUI), spindle-core / spindle-parser (Reasoning Engine).

See also: Feature Gates, JSON by Default, Local-first Design

Backlinks

Linked Pages

Local-first Design

Local-first Design

zetl never modifies your files. It is strictly read-only against the vault.

(given read-only-vault-access)
(given disposable-cache)

Principles

Read-only — zetl only reads Markdown and .spl files. It never writes to, renames, or deletes vault content.
Disposable cache — the .zetl/ directory contains only derived data (the Link Graph index and Reasoning Engine theory cache). Deleting it loses nothing; zetl index regenerates it.
No network — zetl makes no network calls. Everything runs locally.
No lock-in — your vault is plain Markdown with optional Spindle Lisp blocks. Removing zetl leaves your files untouched.

Why this matters

Users trust zetl with their knowledge base — years of accumulated notes. A tool that might corrupt, reformat, or accidentally delete files would be a non-starter. Read-only access removes that risk entirely.

The Cache is the only thing zetl writes, and it lives in a clearly-marked directory that can be gitignored.

Compatibility

This design means zetl works alongside Obsidian, Logseq, Foam, Dendron, or any editor. Multiple tools can read the same vault simultaneously without conflict.

See also: Cache, Scanner, Rust for CLI

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

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 Wikilinks, Graph Queries, Search, Vault Diagnostics, and the TUI — but not 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 Defeasible Reasoning
Spindle Lisp is a niche feature — progressive disclosure serves users better

Install with reasoning

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

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

Scanner

The scanner is zetl’s entry point for understanding a vault. It walks every Markdown file and standalone .spl file, extracting Wikilinks and Spindle Lisp blocks in a single pass.

Wikilink extraction

The scanner recognises all common wikilink forms:

[[Page]] — basic link
[[Page|alias]] — aliased link
[[Page#heading]] — heading anchor
[[Page^block-id]] — block reference
![[Page]] — embed

Extracted links feed into the Link Graph for query and traversal.

SPL extraction

Fenced code blocks tagged ```spl are extracted verbatim, along with their source file and line number. Standalone .spl files anywhere in the vault are also picked up. Both feed into the Reasoning Engine with full Provenance.

(given wikilink-extraction)
(given spl-extraction)

Implementation

Built on pulldown-cmark for Markdown parsing and ignore for .gitignore-aware file walking. The scanner is deliberately read-only — see Local-first Design.

See also: Cache, Link Graph, Reasoning Engine

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