🪨 knapper
A headless CLI for markdown knowledge bases, built for AI agents to drive.
knapper reads and writes the note files directly. No app to launch, no daemon, no server, no index to build, no API keys — one binary, and nothing to install beside it. Nothing it does touches the network, with one deliberate exception: knapper self-update, which only runs when you ask for it by name. It resolves both link syntaxes, [[wikilinks]] and inline, and reads .org files too, so it works on an Obsidian vault, a Foam or Dendron workspace, a Zettelkasten, an org-roam directory, or any folder of notes that has grown links.
knapper backlinks "Projects/thesis.md" # what references this file?
knapper rename "thesis" "dissertation" # rename it — every link follows
knapper tasks --overdue --format json # machine-readable, ready for jqA 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
Your notes are markdown on disk. Your agent is in a terminal — often one with no desktop attached: a cron job, a CI runner, a container, a box you reached over SSH. knapper gives that agent the operations plain shell tools can't do, because they require understanding the structure of a vault:
- 🔗 The link graph — backlinks, links, orphans, hubs, broken-links
- ✂️ Link-safe refactors — rename and move rewrite every inbound link, in both syntaxes
- ✅ Tasks — query and mutate - [ ] checkboxes across the whole tree
- 📇 Frontmatter — get, set, and delete YAML fields from the shell
- 🩺 Vault health — lint finds broken links, orphans, duplicate names, stubs, missing frontmatter
- 🧠 context FILE — everything an LLM needs about one note, in a single call
It is built to survive real vaults: tags are Unicode-aware and nest (#日本語 and #parent/child both work), and one malformed YAML header never aborts a whole-vault scan.
Two tools you might want instead
Honesty first — knapper has two excellent neighbours, and sometimes they are the right choice.
If Obsidian is running, use the official Obsidian CLI (shipped with Obsidian 1.12). It is first-party and talks to the live app, so it reaches things knapper never will: Bases, Sync, Publish, workspaces, file recovery, plugin development. It also covers most of knapper's surface. Its one requirement — its docs state it plainly — is that the app must be running. knapper is for everywhere that isn't true, and for directories that were never an Obsidian vault to begin with.
For full-text search, use ripgrep. knapper deliberately ships no search and no index — rg already won that. knapper covers the structural side rg can't see, and the two compose:
# structure from knapper, text from rg
knapper orphans --format paths | xargs rg -l "TODO"Install
Download the binary for your platform from Releases. It is one file, about 5 MB, with nothing to install alongside it — no interpreter, no virtualenv, no dependency resolution. That is the point: knapper is for machines where you would rather not stand up a runtime.
curl -fsSL https://raw.githubusercontent.com/combinatrix-ai/knapper/main/install.sh | sh