This page is the documentation home for Wiki CLI (wiki on PyPI and npm as wazootech-wiki): the semantic knowledge toolchain for Markdown wikis — validate with SHACL and JSON Schema, infer and query with SPARQL, and publish static HTML. It compiles wikis into RDF and sits beneath note apps and LLM-assisted workflows — progressive enhancement, not a migration.

pip install wazootech-wiki
wiki --help

Install options: PyPI (pip install wazootech-wiki), npm (wazootech-wiki on npm → wiki on PATH), or zero-install (npx wazootech-wiki / uvx wazootech-wiki — same subcommands as wiki). See Getting Started.

Quickstart

pip install wazootech-wiki
mkdir my-wiki && cd my-wiki
wiki init
wiki check
wiki lint
wiki serve

See Getting Started for a full walkthrough.

What wiki is

• The compiler / validator / query engine for Markdown knowledge bases with semantic frontmatter
• An OOTB wiki builder — links, navigation, SHACL and JSON Schema checks, SPARQL, and static HTML from a folder of .md files
• A memory layer — ingest or watch an existing wiki without owning the editor
• Interop-first — works alongside Obsidian, LLM Wiki setups, and any Markdown editor

Adoption path: wiki init → wiki check → wiki serve, then add lint, query, render, and build as the wiki matures.

Wiki CLI is intentionally batteries-included for semantic Markdown wikis: validation, formatting, querying, rendering, exporting, building, and local preview belong together. The boundary is not "minimal CLI only"; the boundary is "semantic wiki toolchain, not editor/app automation."

What wiki is not

• The primary editor or daily note-taking surface
• A replacement for Obsidian, Logseq, or another wiki UI
• A note app clone, CMS, or authenticated multi-user web product
• An auth layer — local-first CLI and static publish; see deferred scope in Wiki CLI templates below
• A vault automation CLI for daily notes, note append/read workflows, task lists, tags, plugin development, or Obsidian app control
• A replacement for shell tools, Git, Pandoc, or editor-native commands

Humans and agents keep writing where they already write. wiki makes that content trustworthy (SHACL, JSON Schema, and conventions), searchable (SPARQL + OWL-RL), and publishable (static HTML, JSON-LD, Turtle, optional read-only SPARQL over wiki serve).

Memory layer and ingestion

Rather than owning your editor or data store, Wiki functions as a read-only memory layer over your wiki. It parses, indexes, and queries the Markdown documents on your filesystem without mutating them or locking you into a proprietary format.

• Ingestion: The CLI reads YAML/JSON frontmatter and HTML microdata from your files, compiling them into an in-memory RDF graph that can be queried with SPARQL or verified against SHACL shapes and JSON Schema bindings.
• Watching: Running wiki serve --watch instructs the CLI to watch the wiki directory. Any edits you make in your preferred editor are immediately processed, updating the graph in the background and keeping your preview server synchronized.

Toolchain vs authoring surface

This separation is intentional: the strongest differentiator is the machine layer (SHACL, OWL-RL, SPARQL, typed HTML) that most note apps do not provide. Wiki avoids competing with editor-centric tools while making incremental adoption obvious.

When an existing primitive already owns a workflow, Wiki CLI integrates rather than replaces it. Obsidian CLI owns Obsidian app/vault automation; Git owns history and collaboration; shell tools own generic file/process composition; Pandoc and document tools own non-semantic document conversion.

wiki link --fix-broken supports link hygiene for publishable wikis. wiki link --apply is optional wiki-gardening: useful when desired, but not required for validation, publishing, or Obsidian compatibility.

Interop-first workflows

Obsidian

Run wiki against the folder that contains wiki.yml or wiki.yaml. Use Shell Commands for on-save wiki check, hotkey wiki render, or wiki serve --watch for preview. Details: Obsidian integration and Dataview integration.

LLM wikis

Treat the wiki as a compounding codebase agents maintain over time. Structured frontmatter and link conventions make SPARQL and SHACL meaningful on agent output. Pattern overview: LLM Wiki.

Plain Markdown

No Obsidian or agent stack required. wiki init scaffolds a wiki; conventions are documented in Style Guide.

Three capabilities of the CLI

Design rationale for silence, pipes, and flat subcommands: Design philosophies.

Ecosystem templates

GitHub template repositories in the wazootech org sit at the edges of the toolchain — publish surfaces, query UIs, and starter vaults — while Wiki CLI owns the semantic layer (Design philosophies). This section is the canonical registry.

Artifact contract

External templates consume Wiki CLI outputs — they do not replace the compiler:

• wiki.yml / wiki.yaml — config root; wiki.inputs, graph.*, site.*
• wiki export — JSON-LD, Turtle, TriG, and other RDF serializations
• wiki build — static HTML under site.base_url

Retired slugs

Do not use these in new prose: sparql-service-template (→ wiki-templates/yasgui); wiki-virtuoso-template (→ folded into wiki-templates/yasgui); wiki-obsidian-quartz-template, obsidian-quartz-template (→ wiki-templates/quartz); bare nextjs-template, mintlify-template, astro-template (→ wiki-templates/*); wiki-template, llm-wiki-template, wiki-yasgui-template, wiki-nextjs-template, wiki-quartz-template, wiki-cocoindex-template, wiki-mintlify-template, wiki-astro-template (all retired — use wiki-templates/<subdir> instead).

Features

• Check — SHACL and JSON Schema integrity, route safety, layout frontmatter (wiki check)
• Lint — broken links, filename pattern, and heading conventions (wiki lint)
• Link — repair broken internal links and optionally insert suggested links as wiki-gardening (wiki link)
• Fmt — mdformat for markdown (wiki fmt)
• Query — SPARQL with OWL-RL and optional --pretty Rich tables (wiki query, Graph Cache)
• Graph list — inspect root and source named graphs for SPARQL GRAPH provenance (wiki graph)
• MCP — read-only query-first MCP server for local agents (wiki mcp)
• Render — live tables from inline SPARQL (wiki render)
• Build / serve — static site, local preview, and optional read-only SPARQL endpoint (wiki build, wiki serve)
• Export — JSON-LD and RDF serializations (wiki export)
• Install — fetch and lock external data sources (wiki install)
• Update — check locked sources for newer commits (wiki update)
• Remove — delete a source from wiki.yml, cache, and lockfile (wiki remove)
• Init — scaffold wiki.yml (wiki init)
• Upgrade — PyPI updates (wiki upgrade)

Supported file formats

Input pipelines

Wiki CLI processes files through two distinct pipelines. Files in wiki.inputs are classified as either documents (frontmatter parsed, IRI derived from file path, link-checked) or raw RDF sources (loaded directly via rdflib, no document processing):

Document pipeline

Markdown files are parsed via the Linked Markdown protocol: the YAML/JSON frontmatter between --- delimiters is extracted as the data dict, and the body text is optionally added to the graph via content_predicate. Data-only documents (.yaml, .yml, .json, .toml) skip the body split — the entire file is the data.

All document formats have their @context auto-populated with wiki: and foaf: default prefixes if none is present. An explicit @id or id key in frontmatter overrides the file-path-based IRI (Linked Markdown).

Raw RDF pipeline

Files with raw RDF extensions are parsed directly by rdflib using the format mapped from their extension. They bypass all document processing — no route registration, no link validation, no frontmatter coercion. They contribute triples to the same graph but are invisible to wiki export (which operates on documents) and wiki link.

Important nuance: .jsonld is raw RDF (rdflib json-ld format) — it is NOT a wiki document. It does not get a document IRI, does not go through ensure_context(), and is not subject to link checking. A .json file with the same content is a wiki document and follows the frontmatter pipeline. These are disjoint processing paths.

Output formats

Key nuances

• .jsonld vs .json — Different pipelines for the same data shape. See raw RDF pipeline note above.
• N3 is output-only — Notation3 (.n3) is available for wiki export and wiki query CONSTRUCT results but is not recognized as an input graph source extension.
• @context auto-injection — Document files that lack an @context key get default wiki: and foaf: prefixes injected. If @context is present as a dict, those defaults are merged in.
• Only .md carries body text — Data-only formats cannot carry a body literal in the graph; the entire file content is the data dict.
• Inline ```turtle ``` blocks — Any fenced code block with turtle language inside a .md file is parsed as Turtle RDF and merged into the wiki graph. This is separate from SPARQL result blocks.
• .toml is a document format — TOML files under wiki.inputs are treated as data-only wiki documents, subject to @context injection and route generation.

Related

• Linked Markdown — document-to-RDF protocol and IRI resolution
• RDF — RDF data model and serialization references
• Individual format pages: Turtle, TriG, N-Triples, N-Quads, RDF/XML, Notation3, JSON-LD

Agent skills

Procedural knowledge for coding agents: Wiki Skills (skills/wiki/ in the repository).

Start here

• Getting Started — install, wiki init, first check and serve
• Wiki Configuration — wiki.yml / wiki.yaml options
• Style Guide — frontmatter, shapes, internal links, SPARQL blocks
• Graph Cache — in-process RDF graph reuse
• Design Philosophies — silence is golden, pipes, flat commands

Global Options

These options apply to config-loading subcommands (check, lint, link, query, mcp, render, build, export, serve, fmt, install, remove). init and upgrade do not load a config file.

-c, --config PATH

Path to wiki.yml, wiki.yaml, wiki.json, or a directory containing one of those files. Defaults to the current directory (.).

Example:

wiki -c docs/wiki.yml check

--wiki-inputs PATH (repeatable)

Override or extend wiki.inputs from config for a single invocation. Relative paths resolve against the config file directory. Useful for one-off queries against a subdirectory.

Example:

wiki --wiki-inputs ./wiki --wiki-inputs ./imported query "SELECT * WHERE { ?s ?p ?o } LIMIT 5"

Command reference

Each subcommand has a dedicated page:

Global flags: -c, --wiki-inputs.

Publishing

• Deploying to GitHub Pages — CI workflow for this site
• Obsidian Integration — Shell Commands plugin workflows

Managing drift and schema evolution

A common challenge in text-based memory bases is metadata drift—especially when files are updated programmatically by external LLM agents. The Wiki CLI provides two strategies to keep a compounding codebase clean over long periods:

Automated cleaning harness

To prevent drift mechanically, you can wire a local Git hook or CI workflow that executes the following checks in order:

1. wiki fmt: Auto-formats Markdown structures and standardizes YAML frontmatter layout.
2. wiki lint --strict: Flags broken links, non-conforming filename patterns, and heading casing warnings as hard errors.
3. wiki check --strict: Ensures frontmatter conforms to SHACL shapes and bound JSON Schema documents (wazoo:jsonSchema).

Resilient schema evolution

Enforcing schemas on text databases can become problematic as structures evolve. The Wiki CLI avoids schema rigidity using semantic web principles:

• Additive RDF properties: Since frontmatter is compiled into a graph, new or unconstrained keys do not cause parsing failures. They are ingested as open-world triples that can be queried or ignored.
• Decoupled validation: SHACL and JSON Schema validation are diagnostic steps, not execution blockers. Files with invalid schemas can still be compiled, parsed, and queried.
• Class-scoped shapes: Shapes target specific classes (e.g., sh:targetClass schema:TechArticle). Introducing a new document type only requires writing a new shape constraint, leaving legacy documents untouched.
• Namespace contexts: Properties map to URIs via graph.context in Wiki Configuration. You can rename or alias fields at the config layer without physically editing every source document.

Design

The CLI follows a flat, scriptable surface and Design Philosophies (silent success, composable stdout). For programmatic use from Python or TypeScript, see Wiki Programmatic API.

Pattern context

This repository implements the LLM Wiki pattern for Personal Knowledge wikis. Examples in the wild include Farzapedia and coverage from Andrej Karpathy.

Similar agent memory filesystem approaches include Supermemory SMFS, Letta MemFS, and Agent Memory Filesystems.

For a standardized agent workspace (typed graph, loop, blast-radius review), see Vivary.

Repository

• Source and issues: github.com/wazootech/wiki
• Wiki CLI templates — all templates live in the wiki-templates monorepo

Background

• Semantic Web — RDF, Turtle, OWL, and related formats
• Software Application Shape — SHACL shape for SoftwareApplication pages (including this page)