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

Need	Command
Just page names	`list`
Full graph structure	`export`
Summary statistics	Stats Command
Query specific links	Links Command

Backlinks

Linked Pages

Agent Ergonomics

Status: Accepted

Context

SPEC-003 Agent Ergonomics documents findings from running zetl as an LLM agent would — systematically exercising every command and checking for friction points.

Findings and fixes

P0 — Bugs

Empty search query panic — zetl search "" crashed instead of returning an empty result. Fixed to return {"results": []}.
Plain-text errors — errors were emitted as plain text even in JSON mode. Fixed with ADR-003 JSON Errors.

P1 — Quality

Duplicate results — links and backlinks returned the same page multiple times. Fixed with ADR-004 Link Dedup.
UTF-8 safety — context extraction could split multi-byte characters. Fixed with character-boundary-aware slicing.

P2 — New capabilities

zetl list — page enumeration for agent discovery workflows. See List and Export Commands.
search --path — restrict search to a subdirectory. See Search Command.
zetl export — full graph adjacency list for external consumption. See List and Export Commands.

Design principle

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.

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.

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

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.

SPEC-003 Agent Ergonomics

SPEC-003: Agent Ergonomics

Documents findings from running zetl as an LLM agent would — systematically exercising every command and identifying friction points. See Agent Ergonomics for the decision record.

(given spec-003-documented)
(given agent-ergonomics-audited)

Findings

P0 — Bugs

Finding	Issue	Fix
FINDING-001	Empty search query panic	Return `{"results": []}`
FINDING-002	Plain-text errors in JSON mode	ADR-003 JSON Errors

P1 — Quality

Finding	Issue	Fix
FINDING-004	Duplicate link results	ADR-004 Link Dedup
FINDING-005	Duplicate backlink results	ADR-004 Link Dedup
FINDING-006	UTF-8 context splitting	Character-boundary-aware slicing

P2 — New capabilities

Requirement	Command	Purpose
REQ-019	`zetl list`	Page enumeration for agent discovery
REQ-020	`search --path`	Restrict search to subdirectory
REQ-021	`zetl export`	Full graph adjacency list

Design principles established

Agents consume stdout as JSON — errors must be structured
Non-zero exit codes signal failure
Page enumeration (list) is essential for agent bootstrapping
Deduplication at the output layer keeps the internal graph faithful

Impact

These fixes made zetl significantly more reliable as an agent building block. The JSON by Default philosophy, structured errors, and non-zero exit codes all trace back to this spec.