combinatrix-ai/knapper

🪨 knapper

A CLI for personal knowledge management and LLM wikis. No bulky app. Just the CLI.

Your knowledge base is a folder of notes. knapper lets you and your AI agents query, maintain and reorganize it directly from the terminal — on your laptop, over SSH, or in CI. One binary, no desktop app, daemon, server or index required.

It understands [[wikilinks]], markdown, YAML frontmatter, tags and tasks, and reads .org files too. Use it with an existing vault or any linked collection of notes.

knapper backlinks "Projects/thesis.md"   # what references this file?
knapper rename "thesis" "dissertation"   # rename it and update links
knapper tasks --overdue --format json    # what needs attention?

CLI manual · Compatibility · Releases

A knapper is someone who strikes obsidian and flint into usable blades. This one works a directory of markdown into something an agent can wield.

Why this exists

Plain text tools can find words. Maintaining a knowledge base also means understanding how notes, topics, metadata and tasks fit together. knapper brings those operations to the terminal, for people and agents alike:

• 🔎 Structured queries — filter and sort notes by frontmatter, inline fields, tags and computed link counts with query; discover available fields with fields.
• 🔗 The link graph — inspect incoming and outgoing links, find orphans and hubs, and detect broken links to notes, headings and block IDs.
• ✂️ Link-safe refactors — rename and move update links in both syntaxes; move whole directories and preview changes with --dry-run.
• 🩹 Link repair planning — repair-links --dry-run proposes repairs where the filesystem supplies unambiguous evidence.
• 🏷️ Tags and topics — list tags, follow nested topics with backlinks '#tag' and context '#tag', and use demote to turn topic-only wikilinks into tags.
• ✅ Tasks — create, filter and update checkboxes across the tree, with dates, priorities, recurring markers and configurable statuses.

• 📅 Daily notes — create or retrieve a dated note and expand Core Templates or supported Templater date expressions.
• 📇 Frontmatter — read, set and delete typed YAML fields from the shell.
• 🩺 Vault health — find broken links, orphans, duplicate names and stubs; enforce frontmatter and required-heading rules by path or metadata, across the vault or only changed files.
• 🧠 Context for agents — get a note's content and relationships in one call, or focus on a search-hit line with its section and heading outline. JSON output and an embedded agent skill make automation straightforward.
• 🔐 External references — keep knapper:// references in notes and resolve values through separately configured provider commands when needed.

Tags are Unicode-aware (#café and #parent/child both work), and one malformed YAML header never aborts a whole-vault scan. The CLI manual covers all commands, options, configuration and behavioral limits.

Install

curl -fsSL https://raw.githubusercontent.com/combinatrix-ai/knapper/v0.1.0/install.sh | sh

Installs to ~/.local/bin, verifies archive checksums, and registers the embedded skill with supported agent hosts it finds. Release binaries support macOS and Linux on arm64 and x8664. See the installation manual for direct downloads, provenance verification, installer options and source builds.

knapper self-update verifies release provenance and installs updates. Interactive commands check for updates in the background at most once every six hours; set KNAPPERNOUPDATECHECK=1 to disable that check. Notes are not sent. Configured external-reference providers may also use the network.

Quick start

cd ~/your-notes
knapper init             # writes knapper.yaml — defaults are sane
knapper lint             # how healthy is this vault?
knapper tasks --overdue  # what slipped?