wiki

name	wiki
description	Indexed knowledge bases with command-line tools for agents.
disable-model-invocation	true

Wiki

A wiki is a structured, indexed knowledge base organized as a folder tree with _index.md files. Each folder has an index that links to its children (subfolders and pages), and a content section below a *** delimiter for user-authored notes.

Initialize a wiki in the current project and configure integrations:

• wiki init — scaffold a new wiki with a root index
• wiki config — install Obsidian plugins and the git merge driver
• wiki trust — authorize a wiki to run its .wiki/wiki.py hook

Maintain indexes as files are added and removed:

• wiki lint — validate structure and flag issues
• wiki update — sync index links with the filesystem
• wiki new — create an indexed folder with an authored desc and content

Browse structure, search across content, and read entries:

• wiki map — print an indented tree overview
• wiki search — rank relevant pages with SQLite FTS5
• wiki match — match content with regex
• wiki read — read a named entry

Usage

Install the CLI from PyPI if it is not already on your PATH:

pipx install plasma-wiki

(pip install or uv tool install work too.)

Then run commands directly:

wiki <command> ...

Run wiki --help for a list of commands, and wiki <command> --help for full option descriptions.

Working at scale

A wiki is many small, independent pages, so wiki work parallelizes well and is often too large for one context. Default to sub-agents and dynamic workflows rather than authoring or auditing page by page yourself:

• Fan out sub-agents. When seeding or expanding a wiki, give each independent page — or each source to research and digest — to its own sub-agent, then run wiki update once to stitch the new pages into the indexes. Update adds and repairs index link rows and frontmatter only — it never linkifies mentions in page prose, so author [[...]] cross-links by hand.
• Drive sweeps with a dynamic workflow. When auditing, relinking, or restructuring an existing wiki, pipeline its pages through a workflow so each is read, revised, and verified on its own — slow pages never block fast ones.

Conventions

• .wiki/ is the tool's namespace. Every root carries a .wiki/ directory holding settings.json — the file that declares the wiki root; wiki init writes it and wiki update restores a missing one — plus the derived word-counts and ranked-search caches and the staged Obsidian config. Never author content there; the walk skips dot-directories by construction.
• Exclusions are configurable. Beyond the built-ins (dot-paths, symlinks, _index.md), gitignore-style globs in exclude.patterns in .wiki/settings.json exclude whole subtrees from indexing — never walked, scaffolded, or linted, though wiki read still serves them. The enclosing git repository's ignore rules fence the same way, with no configuration: what the repo ignores is not wiki content, so a stray driver output beside tracked pages is never adopted, minted an _index.md, or linked — delete or fence residue rather than letting update sweep it in. A wiki whose own root is gitignored is exempt.
• Name validation is configurable. By default the wiki rejects only structural characters (/, \, *, [, ], |, #), a leading dot, non-printable names, and the reserved _index stem — spaces, dashes, and unicode all pass. Stricter rules (e.g. ASCII identifiers) are opt-in per wiki via naming.validate in .wiki/settings.json (seed it at creation with wiki init --settings); wiki init and wiki lint enforce whatever policy is set.
• Timestamps are tool-owned and configurable. wiki update writes both stamps when a file gains frontmatter, keeps created: from then on, and rewrites updated: on every actual write — never hand-edit them; an edit goes undetected unless the value stops parsing under the configured format, which wiki lint fails. created/updated default to UTC in %Y-%m-%dT%H:%M:%SZ; set timestamp.timezone (an IANA name) and timestamp.format (a strftime string) in .wiki/settings.json to change them — use rather than a literal for a non-UTC zone.