The itch
By November 2025 I was pointing coding agents at my notes almost as often as at code. My research, project docs and decisions live in an Obsidian vault, and I wanted an agent to search it, pull a note, add a section or fix some frontmatter in the middle of a session.
The Local REST API plugin already exposes the vault over HTTP. It's made for people, though. Responses come back in different shapes, there's no structured search, and "edit the Results section of this note" means fetching the whole file, changing a string and writing it all back. Agents doing that by hand are slow and make mistakes. I wanted a short list of typed operations instead.
What I built
A CLI that gives an agent precise access to a vault. It installs as the obsidian command, and every subcommand returns JSON, so the agent can parse every answer.
- Setup
- Since v0.3, it finds your vaults and their REST ports in Obsidian's own config. No keys or ports to copy.
- Search
- Uses the Omnisearch plugin when it's there and falls back to the REST API.
--metaadds title, frontmatter and tags to each result. - Edits
- PATCH by heading or line number: append, prepend, replace or delete a section and leave the rest of the file alone.
- Frontmatter
- Get, set, merge or delete YAML fields.
title,created_atandupdated_atare filled in automatically. - Big content
--from-fileand--stdin, because shell argument limits are what breaks first with agent-written text.- Shape
- JSON on every command. A standalone binary compiled with Bun, nothing else to install.
I kept the commands small so an agent can chain them, the way you would with Unix tools. Editing one section of a note looks like this:
What happened to it
I expected to touch it now and then. It's now the tool I run the most. Nearly every coding session uses it at least once, to search a note, save a finding or update some metadata. The vault is past a thousand notes and over a hundred megabytes, and most of it was written through this CLI.
- Nov 15, 2025First commit: REST and Omnisearch, file and stdin input, automatic timestamps.
- Dec 17, 2025v0.2.0, with Excalidraw diagram generation: a small DSL that laid out and compiled diagrams.
- Mar 5, 2026Note management commands: inbox, move, stale and stats.
- Jul 18, 2026v0.3 to v0.5: finds vaults and ports by itself, adds tags, find, active, open and search --meta.
One feature didn't work out. The Excalidraw generation was a fun experiment, and I almost never use it. I thought I'd want agents drawing diagrams in my notes, and it turns out I don't.