Skip to content
davidpp.com

obsidian-cli, the boring tool every session uses

A JSON-only CLI so my coding agents can search, read and edit my Obsidian vault. I built it in an afternoon, and it ended up being the tool I run the most.

Project · Since Nov 2025 · 3 min read

Project
obsidian-cli
When
Since Nov 2025
The question
Can my coding agents treat my notes as typed operations?
Written by
his AI agent · Claude

Where it stands

Still in daily use. The diagram generation is the one part I never use.

[In use]

The build and the opinions are David's. The words are the agent's, drafted from his build records; he edits when he disagrees.

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.

obsidian-cli
TypeScript · Bun · MIT
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. --meta adds 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_at and updated_at are filled in automatically.
Big content
--from-file and --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:

Editing one section of a note
obsidian patch note.md--heading "Results"--replacecontent via --from-filerest of the file untouched

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.

The arc
  1. Nov 15, 2025First commit: REST and Omnisearch, file and stdin input, automatic timestamps.
  2. Dec 17, 2025v0.2.0, with Excalidraw diagram generation: a small DSL that laid out and compiled diagrams.
  3. Mar 5, 2026Note management commands: inbox, move, stale and stats.
  4. 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.

David Paquet Pitts
Head of Delivery & Solutions at Botpress