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.

See also: Install, Quick Start, JSON by Default

Backlinks

Linked Pages

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)

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 (see ADR-003 JSON Errors)
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 and View Command provide richer interactive experiences.

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.

; Serving both audiences is a design principle
(normally r-dual-audience
  (and json-default-output tui-complete seven-views)
  serves-both-audiences)

See also: CLI Reference, ADR-003 JSON Errors, Agent Ergonomics

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

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

ADR-003 JSON Errors

ADR-003: JSON Errors on Stdout

Status: Accepted

Context

When zetl encounters an error (e.g., page not found, empty search query), how should it report it? The initial implementation wrote plain-text errors to stderr, which broke agent parsing of JSON output.

This was discovered during the agent ergonomics audit — see Agent Ergonomics and SPEC-003 Agent Ergonomics.

Decision

When --format json is active (the default), errors are written as structured JSON to stdout. Diagnostic messages (verbose logging, timing) remain on stderr.

(given structured-errors)
(given nonzero-exit-codes)

Error format

{
  "error": "page not found: Nonexistent",
  "suggestion": "did you mean: Nonfiction?"
}

Rationale

Agents parse stdout as JSON; a plain-text error on stdout breaks the parser
Structured errors include actionable fields (suggestions, affected files)
Non-zero exit codes signal failure to shell scripts and CI
stderr remains available for human-readable diagnostics

Reason Commands

Reason Commands

zetl reason exposes the Reasoning Engine through eight subcommands. All require --features reason at build time — see Feature Gates.

(given reason-status-done)
(given reason-explain-done)
(given reason-why-not-done)
(given reason-require-done)
(given reason-what-if-done)
(given reason-conflicts-done)
(given reason-export-done)
(given reason-provenance-done)

Commands

`reason status`

What does the vault’s combined concepts/Spindle Lisp theory conclude? Filter by polarity (--positive, --negative), strength (--definite, --defeasible), or literal name (--literal "release*").

`reason explain <literal>`

Why does a conclusion hold? Produces a proof tree tracing the derivation through rules back to facts, with full concepts/Provenance (file, line, page). Output as JSON, table, natural language, or Graphviz dot.

`reason why-not <literal>`

Why can’t something be proved? Identifies missing facts, blocked rules, or active defeaters. This is the inverse of explain — useful for understanding gaps in the vault’s knowledge.

`reason require <literal>`

What facts would make a goal provable? Abductive reasoning — finds the minimal sets of missing facts. Useful for answering “what would it take to make release-candidate true?”

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

Build Command

zetl build generates a static HTML site from your vault, with the same look and feel as Serve Command minus the edit button and save functionality.

Usage

zetl -d ./my-vault build                  # generates dist/
zetl -d ./my-vault build --out-dir site   # custom output directory

Flags

Flag	Default	Description
`--out-dir <path>`	`dist`	Output directory for the generated site

Output structure

dist/
  index.html              # vault overview with stats and page grid
  page/
    Some Page/index.html   # one page per note
    Another/index.html

Features

Rendered Markdown with syntax highlighting
Backlink lists on each page
Transclusion panels with SVG bridge connectors
Page grid on the index page
Clean URLs (/page/Scanner/ instead of /page/Scanner.html)

Deployment

The output can be uploaded to any static host:

GitHub Pages
Netlify
S3 + CloudFront
Any web server

Serve Command

zetl serve starts a local web server for browsing the vault in a browser.

Usage

zetl -d ./my-vault serve              # http://localhost:3000
zetl -d ./my-vault serve --port 8080

Flags

Flag	Default	Description
`--port N`	3000	Port to listen on

Features

The web UI provides:

Rendered pages — Markdown rendered to HTML with syntax highlighting
Sidebar — page list with search/filter
Backlink list — pages linking to the current page
Transclusion panel — forward-link excerpt cards with SVG bridge connectors, mirroring the View Command design
Inline editing — edit a page in the browser and save; zetl re-indexes on save

Relationship to other viewers

Viewer	Interface	Read-only?
`zetl tui`	Terminal (multi-view dashboard)	Yes
`zetl view`	Terminal (two-pane reader)	Yes
`zetl serve`	Browser (full web UI)	No (inline editing)
`zetl build`	Static HTML (deployable)	Yes

Design

The server uses the same Link Graph and architecture/Cache as all other commands. The transclusion panel implements the same Xanadu-inspired design as View Command, but with SVG bridge connectors instead of terminal graphics. See Xanadu Lineage for the design philosophy.

See also: CLI Reference, Build Command, View Command, TUI

View Command

zetl view is a Xanadu-inspired two-pane reader for focused page navigation. See Xanadu Lineage for the design philosophy.

Usage

zetl view "Scanner"               # open a specific page
zetl view                         # open the page picker
zetl view "Scanner" --context-lines 10 --main-width 60

Flags

Flag	Default	Description
`--context-lines N`	5	Lines shown per context card (1–20)
`--main-width pct`	58	Percentage of terminal width for the main pane (30–80)

Layout

The screen is divided into three columns:

Left pane — the current note, rendered with numbered [N] anchor glyphs at each wikilink
Bridge column — color-coded connectors pairing anchors to cards
Right pane — context cards: excerpts from forward-linked pages

In narrow terminals (<60 cols), the view falls back to a single-pane layout.

Keybindings

Key	Action
`j` / `k`	Scroll (or cycle links in focus mode)
`Ctrl-d` / `Ctrl-u`	Half-page scroll
`g` / `G`	Top / bottom of note
`Tab`	Toggle between scroll and focus mode
`Enter`	Navigate to focused link
`[` / `]`	Session history back / forward
`b`	Toggle backlink mode
`/`	Open page picker
`?`	Toggle keybindings help
`q`	Quit

Implementation

Built on ratatui and crossterm, like the TUI. Supports true-color, 8-color, and no-color terminals. See Xanadu View Design for design decisions and SPEC-009 Xanadu View for the full specification.

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 philosophy.

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

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 concepts/Wikilinks navigation
Graph	Local link graph with depth toggle

Navigation

Key	Action
`Tab` / `Shift+Tab`	Cycle views
`Ctrl+K`	Quick switcher
`j` / `k`	Scroll
`Enter`	Follow a wikilink
`Backspace`	Go back
`/`	Search/filter

Implementation

Built on ratatui and crossterm. The TUI reads the same Link Graph and architecture/Cache as the CLI commands — no separate data path. See SPEC-009 Xanadu View for the related two-pane reader.

Relationship to View

The TUI is a multi-view dashboard. For focused reading with visible connections between notes, use View Command instead — it provides a Xanadu-inspired two-pane layout with bridge connectors.

See also: CLI Reference, View Command, Serve Command

Stats Command

zetl stats prints summary statistics about the vault.

Usage

zetl -d ./my-vault stats
zetl stats --top 20 --format table

Flags

Flag	Default	Description
`--top N`	10	Number of most-linked pages to show

Output

The stats include:

pages — total page count
links — total wikilink count
orphans — pages with no incoming links
most_linked — top N pages by incoming link count
vault_content_hash — BLAKE3 root hash of the entire vault (from Merkle Tree)
spl_blocks — total SPL block count
grounded_spl_blocks — SPL blocks with section or explicit grounding
explicitly_grounded_facts — facts with (meta ... (source ...)) references

The vault content hash provides an integrity checkpoint — agents can use it to verify that the vault state hasn’t changed between operations.

See also: CLI Reference, List and Export Commands, Merkle Tree

List and Export Commands

List and Export Commands

Two utility commands for enumerating vault contents.

`zetl list`

Lists all pages in the vault.

zetl -d ./my-vault list

Returns page names and file paths. Useful for agent workflows that need to enumerate available pages before querying them.

Added in response to agent ergonomics findings — see Agent Ergonomics and SPEC-003 Agent Ergonomics.

`zetl export`

Exports the complete Link Graph as JSON — every page and every link.

zetl -d ./my-vault export

The output is a full adjacency list of the vault’s link structure. This enables external tools to consume zetl’s graph data for visualization, analysis, or integration.

Relationship to other commands

Watch Command

zetl watch starts a persistent process that monitors the vault for file changes and emits graph-level events as NDJSON on stdout.

Usage

# Start watching (NDJSON events on stdout)
zetl -d ./my-vault watch

# Custom debounce interval
zetl watch --debounce 500

# Execute a command on each change
zetl watch --exec "zetl check --fail-on error"

Flags

Flag	Default	Description
`--debounce <ms>`	200	Debounce interval for batching rapid changes
`--exec <cmd>`	none	Command to invoke after each re-index

Event types

Events are emitted as NDJSON (one JSON object per line). The event vocabulary mirrors the Diff Command output schema:

Event	Description
`index_ready`	Initial index complete, watching started
`page_added`	New page appeared
`page_removed`	Page deleted
`link_added`	New wikilink appeared
`link_removed`	Wikilink removed
`orphan_gained`	Page became orphaned
`orphan_resolved`	Orphan page got an incoming link
`dead_link_added`	New dead link appeared
`dead_link_resolved`	Dead link target now exists
`index_updated`	Re-index cycle complete (summary)

How it works

zetl uses OS-level file system events (via the notify crate) to detect changes. When a .md file changes, zetl debounces the event, incrementally re-indexes only the affected files using the Merkle Tree change detection from architecture/Cache, and emits events only when the graph actually changes.

Agent integration

The NDJSON stream is designed for consumption by AI agents and automation scripts. Pipe it to tools like jq or feed it into an incremental reasoning loop.

See also: CLI Reference, Diff Command, SPEC-008 Watch Mode

Diff Command

zetl diff computes a graph-level diff against Git history, showing what changed in the link structure between two points in time.

Usage

# Diff against previous commit (default: HEAD~1)
zetl -d ./my-vault diff

# Diff against a specific ref
zetl diff --from main~5

# Diff by date
zetl diff --since "2026-02-01"

# Filter by change category
zetl diff --filter links

Flags

Flag	Default	Description
`--from <ref>`	`HEAD~1`	Git ref to diff against
`--since <datetime>`	none	Find closest commit at or before this date
`--filter <category>`	none	Filter output: `pages`, `links`, `orphans`, `dead_links`

How it works

zetl uses an efficient reconstruction algorithm (see ADR-012 Changed Files Reconstruction):

git diff --name-only identifies changed .md files between the baseline and HEAD
git show retrieves the old content of each changed file
Old content is parsed for wikilinks
Set differences between old and new graphs yield the diff

This scales with the size of the change, not the size of the vault.

Output

The diff reports:

Pages added and removed
Links added and removed
Orphans gained and resolved
Dead links added and resolved

Blocks Command

zetl blocks lists content-addressable Merkle Tree blocks for a page (forward mode) or resolves a block by its BLAKE3 hash prefix (reverse mode).

Usage

# Forward mode: list all blocks for a page
zetl -d ./my-vault blocks "Scanner"

# Filter by type
zetl blocks "Scanner" --type heading

# Reverse mode: resolve a hash to its source
zetl blocks --resolve abc123de

Forward mode

Given a page name, returns all Merkle leaf nodes in document order. Each block includes:

type — Heading, Paragraph, SplBlock, Code, Table, List, Blockquote, Frontmatter
lines — start and end line numbers
hash — BLAKE3 content hash
text — preview of the block content
spl_hashes — for SPL blocks: content_hash and ast_hash (dual hashing)

Block type filter

`--type` value	Matches
`heading`	Heading nodes
`paragraph`	Paragraph nodes
`spl`	SPL code blocks
`code`	Non-SPL code blocks
`table`	Table nodes
`list`	List nodes
`blockquote`	Blockquote nodes
`frontmatter`	YAML frontmatter
`all`	All block types (default)

Reverse mode

Given a hash prefix (minimum 8 hex characters), finds the source location:

zetl blocks --resolve e5f6a7b8

Returns the file, page name, line range, block type, and content. Useful for tracing concepts/Provenance from a hash back to its source.

Check Command

zetl check validates the vault and reports issues across both the Link Graph and concepts/Spindle Lisp content.

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

Usage

zetl -d ./my-vault check
zetl check --dead-links --fail-on error    # CI mode
zetl check --spl                           # SPL diagnostics only
zetl check --drift                         # detect SPL grounding drift

Issue types

Dead links

A wikilink that points to a page that doesn’t exist. For example, [[Plugin System]] would be a dead link if there’s no Plugin System.md file.

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.

Syntax errors

Malformed wikilinks like unclosed brackets.

Similar Command

Similar Command

zetl similar finds pages with names similar to a query string, using concepts/SimHash-based fuzzy matching.

Usage

zetl -d ./my-vault similar "zettelkasen"

Flags

Flag	Default	Description
`--threshold N`	12	Max Hamming distance (lower = stricter)
`--limit N`	10	Max results

How it works

zetl computes a SimHash fingerprint for each page name using character trigrams, then compares the query’s fingerprint against all pages using Hamming distance. Pages within the threshold are returned, sorted by similarity.

This is useful for:

Finding pages despite typos
Discovering pages with similar names that might be candidates for merging
Fuzzy lookup when you don’t remember the exact page title

Relationship to search

similar matches page names. Search Command matches page content. Use similar when you know roughly what a page is called; use search when you know something the page contains.

See also: CLI Reference, concepts/SimHash, architecture/SimHash, Search Command

Search Command

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

(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/*"

Flags

Flag	Default	Description
`--context N`	0	Include N characters of surrounding text
`--limit N`	50	Max results to return
`--regex`	off	Interpret query as a regular expression
`--case-sensitive`	off	Require exact case match
`--all`	off	Search raw content (include frontmatter, code blocks)
`--path <glob>`	none	Restrict results to files matching glob

Content filtering

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

Design decision

zetl uses index-free scanning rather than an inverted index. This trades query speed on very large vaults for zero build-time indexing cost and simpler architecture. See ADR-002 Search Without Index for the rationale.

Fuzzy page name matching

For finding pages by name rather than content, use Similar Command instead:

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.

See also: CLI Reference, Links Command, Link Graph

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

Index Command

zetl index builds or refreshes the link index for a vault.

Usage

zetl -d ./my-vault index

What it does

Scans all .md files in the vault directory (recursively)
Parses each file with pulldown-cmark, extracting concepts/Wikilinks and concepts/Spindle Lisp blocks — see architecture/Scanner
Builds the Link Graph — a directed graph of page-to-page links
Computes Merkle Tree hashes for content-addressable blocks
Writes the index to .zetl/index.json — see architecture/Cache

Incremental behavior

On subsequent runs, zetl uses two-tier cache invalidation:

Tier 1 (mtime): If a file’s modification time hasn’t changed, skip it entirely
Tier 2 (hash): If the mtime changed but the content hash matches, skip reprocessing

This makes re-indexing fast even for large vaults. Use --no-cache to force a full rescan.

Verbose output

With -v, zetl reports scan statistics to stderr: files scanned, files skipped, links found, SPL blocks extracted, and timing.