SoftwareApplication

wiki

Infobox

name
wiki
softwareVersion
0.7.0
description
Command-line interface for querying, validating, and publishing semantic markdown wikis.
codeRepository
https://github.com/wazootech/wiki

This page is the documentation home for Wiki CLI (wiki, distributed on 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.

Wiki CLI is published on npm, PyPI, JSR, and GitHub Releases (standalone binaries). See Getting Started for every channel. Install with npm or use a standalone executable:

npm install -g wazootech-wiki
wiki --help

Quickstart

Install Wiki CLI and scaffold a wiki:

npm install -g 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

Layer Role Examples
Authoring surface Create, edit, search, and organize notes Obsidian CLI, Obsidian, VS Code, shell
Wiki CLI semantic layer Compile wiki → RDF graph; check, lint, fmt; query; render; build/serve wiki check, wiki query, wiki build
Existing primitives History, sync, print/PDF, and generic text processing Git, shell tools, Pandoc
Outputs Deployable semantic artifacts GitHub Pages HTML, export files, /api/sparql when enabled

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

Capability Commands Value
Trust check, lint, fmt Integrity contracts and authoring conventions
Intelligence query, mcp, render, export SPARQL, MCP graph access, inline result blocks, RDF serializations
Publish build, serve, link Static site, local preview, wikilink hygiene
Sources install, update, remove Fetch, lock, update, and manage external sources
Provenance graph list Inspect read-only named graph boundaries

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

Ecosystem templates

Wiki CLI ships one starter template, wikipedia — a Wikipedia-themed static site built from Wiki CLI outputs. It sits at the edge of the toolchain (the publish surface) while Wiki CLI owns the semantic layer (Design philosophies). It is one subdirectory of the wiki-templates repository, and this section is the canonical registry. Install it into an empty directory with wiki init --template <name>:

wiki init --template wikipedia
Template Description
wikipedia Wikipedia-themed layout for Wiki CLI-generated sites

New templates are not added to wiki-templates: the other eleven were retired on 2026-10-14 (#64). To propose an integration, open an issue here describing the tool it connects and the Wiki CLI outputs it consumes, following the boundary rule in the wiki-templates contributing guide.

Artifact contract

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

  • wiki.yml / wiki.yaml — config root; wiki.input, 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 (→ the retired yasgui template); wiki-virtuoso-template (→ folded into yasgui); wiki-obsidian-quartz-template, obsidian-quartz-template (→ the retired quartz template); bare nextjs-template, mintlify-template, astro-template; and wiki-template, llm-wiki-template, wiki-yasgui-template, wiki-nextjs-template, wiki-quartz-template, wiki-cocoindex-template, wiki-mintlify-template, wiki-astro-template.

The wiki-templates/templates/ subdirectories those names pointed at — generic, llm-wiki, mintlify, holocron, astro, nextjs, quartz, cocoindex, yasgui, camunda, and workspace-cli — were retired on 2026-10-14 with the reduction to one template (#64). Those paths 404 now, so do not link them; wikipedia is the only template that exists.

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 — Deno Markdown formatter for markdown (wiki fmt)
  • Fix — remove frontmatter that repeats the headline or Git dates the graph derives (wiki fix)
  • 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 — check for Wiki CLI releases (wiki upgrade); steps aside with exit 0 when JSR cannot answer

Supported file formats

Input pipelines

Wiki CLI processes files through two distinct pipelines. Files in wiki.input are classified as either documents (frontmatter parsed, IRI derived from file path, link-checked) or raw RDF sources (parsed directly into the RDF graph, without document processing):

Category Extensions Pipeline Key behavior
Wiki documents .md, .yaml, .yml, .json, .toml Frontmatter → graph Parsed for frontmatter/data; document IRI derived from file path; link-checked and exportable
Data-only documents .yaml, .yml, .json, .toml Frontmatter → graph Subset of wiki documents without a markdown body — entire file is the data dict
Raw RDF sources .ttl, .trig, .nt, .nq, .rdf, .xml, .jsonld RDF/JS parsers → graph Loaded as raw triples; no route, no link checking, no frontmatter pipeline
Inline Turtle Turtle-tagged code fence inside .md RDF/JS parser → graph Parsed and merged into the graph alongside document frontmatter

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.

Each typed document also gets schema:headline from its first # H1 and schema:dateCreated / schema:dateModified from its Git history (or its modification time), unless its frontmatter sets them. These are derived in memory and never written back; see wiki fix.

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 by the Deno RDF/JS stack using the format mapped from their extension. They bypass document processing — no route registration, link validation, or 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, not a wiki document. It does not get a document IRI or document-level context injection, and it 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

Context Formats
wiki export dict (default), json-ld, turtle, xml (deferred), n3, nt, trig, nquads
wiki query table (default), json, csv, tsv, turtle, n3, markdown
Repository docs-theme metadata panel json-ld, turtle, n3, nt, trig, nquads

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.
  • Turtle-tagged code fences — Markdown code fences tagged turtle are parsed as RDF and merged into the wiki graph. This is separate from SPARQL result blocks.
  • .toml is a document format — TOML files under wiki.input are treated as data-only wiki documents, subject to @context injection and route generation.

Agent skills

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

Start here

Global Options

These options apply to all subcommands. Config-driven commands include check, lint, link, query, mcp, render, build, export, serve, fmt, install, remove, update, and graph; init and upgrade run with defaults when no config file exists.

-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

--input PATH (repeatable)

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

Example:

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

Command families

The commands fall into families by what they act on:

Family Commands What they share
Setup and tooling init, upgrade Start a project, or update the CLI itself.
Sources install, update, remove Manage external data sources and wiki.lock.
Audits check, lint Read-only verification of integrity and conventions.
Bulk fixers fmt, fix, link, render Rewrite files across the whole wiki.
File edits file new, file set, file patch, file mv, file rm, with edit for batches Validated, link-aware edits to wiki documents; dry run by default.
File reads file show, file refs Inspect one wiki document file.
Graph query, graph, export The wiki as RDF: SPARQL, named graphs, and export.
Publishing build, serve, mcp Output surfaces: static site, local server, MCP server.

The per-file verbs are grouped under wiki file.

Command reference

Each subcommand has a dedicated page:

command description
wiki_build Generate a static HTML site from the wiki.
wiki_check Integrity checks — SHACL validation, JSON Schema frontmatter, route safety, and layout frontmatter.
wiki_edit Change a wiki through validated, atomic edits instead of hand-written Markdown.
wiki_export Export document frontmatter as RDF or JSON-LD.
wiki_file Create, change, move, delete, or inspect one wiki document file through validated, link-aware edits.
wiki_file_mv Move or rename a page and repoint every link and metadata reference to it, as a validated edit.
wiki_file_new Create a page of a known type, with its required fields first, as a validated edit.
wiki_file_patch Append to, prepend to, or replace a heading's section, the body, or the frontmatter, as a validated edit.
wiki_file_refs List the pages that link to a page and the pages it links to.
wiki_file_rm Delete a page, refusing while other pages link to it unless their links are pruned to plain text, as a validated edit.
wiki_file_set Set or remove one frontmatter field, keeping comments, key order, and value spelling, as a validated edit.
wiki_file_show Describe one page as the engine sees it, with the content hash an edit expects.
wiki_fix Remove frontmatter that repeats a value the graph derives from the page's H1 or Git history.
wiki_fmt Format Markdown wiki pages with native Deno/dprint formatter options.
wiki_graph List read-only RDF named graphs for root and installed source provenance.
wiki_init Scaffold wiki.yml and an empty wiki/ folder for markdown pages.
wiki_install Fetch and lock external data sources declared in wiki.yml.
wiki_link Suggest missing wikilinks and repair unambiguous broken internal links.
wiki_lint Convention audits for broken links, filename patterns, heading style, and internal link style.
wiki_mcp Run an MCP server for querying the wiki graph, with opt-in page-edit tools.
wiki_query Run SPARQL SELECT or CONSTRUCT against the wiki graph.
wiki_remove Remove a data source from wiki.yml, its cache, and wiki.lock.
wiki_render Update inline SPARQL result tables in markdown files.
wiki_serve Local HTTP server for live HTML preview and optional read-only SPARQL endpoint.
wiki_update Check locked sources for newer commits and update wiki.lock.
wiki_upgrade Check for Wiki CLI updates and upgrade supported installations.

Global flags: -c, --input.

Publishing

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 Node.js/TypeScript or directly from Deno, 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 (thin governed contract, typed graph, verification gates), see Vivary.

Repository

Background

Backlinks