Obsidian CLI: Why Your AI Agent Just Got 70,000× Cheaper to Run

Obsidian 1.12 shipped a CLI. Buried in a changelog full of CSS tweaks and file explorer fixes, this is the feature I care about most.

I have about 400 notes in my Obsidian vault, synced via Syncthing to a Linux box where AI agents run against it daily. Claude Code, OpenClaw, custom scripts. They search for context, check what links where, pull facts out of my daily notes. And until this week, all of that happened through grep and reading files one at a time.

The cost of grep

Here’s the thing about letting an AI agent loose on a folder of markdown files: it doesn’t know anything about your vault’s structure. No backlinks, no tags, no graph. Just text.

Robert Cincotta benchmarked this on his vault (4,663 files, the kind of vault that makes you wonder if you have a problem):

• Finding orphan notes with grep: 15.6 seconds. With the CLI: 0.26 seconds.
• Searching the vault: grep needs 1.95s, CLI does it in 0.32s.
• The token math is where it gets wild. Orphan detection through MCP file reads burns roughly 7 million tokens. The CLI returns the same answer for about 100. That’s not a typo.

This isn’t about grep being slow. It’s that grep doesn’t know what Obsidian knows. The CLI talks to the same search index that Obsidian itself uses, the one that makes cmd+shift+F feel instant. Grep starts from zero every time.

What you get

The CLI requires Obsidian to be running (it queries the app’s indexes, not the files directly). Still early access, but here’s what works:

Search that actually understands your vault:

obsidian search "kubernetes deployment" --vault MyVault

Tags, properties, backlinks, link hierarchy. The same results you’d see in Obsidian’s search bar, piped to stdout.

Graph queries from the terminal:

obsidian backlinks "Project Alpha" --vault MyVault
obsidian orphans --vault MyVault

Without this, getting backlink data means opening every file, parsing wikilinks, building a graph in memory. I’ve watched Claude Code do exactly that. It works, technically. It also costs a fortune and takes forever.

Daily notes without date math:

obsidian daily:prepend "- Met with client about Q2 roadmap" --vault MyVault

Prepend to today’s note. Don’t care what the filename is or what date format you configured.

How much of Obsidian does this cover?

I’ve been thinking about this in tiers. Filesystem access alone gets an agent maybe 40% of what Obsidian knows. Raw markdown, nothing else.

The REST API plugin bumps that to maybe 55%. You get search and some metadata, but it’s another plugin to maintain and it breaks more often than I’d like.

The CLI lands around 85%. What’s missing is purely visual: canvas rendering, the graph view animation, live preview styling. If it’s structural or queryable, the CLI has it.

In practice this means I can ask Claude Code to find project-related notes with no incoming links and get an answer before I finish reaching for my coffee. Before, that question cost millions of tokens and several minutes of file scanning.

The constraints

You need Obsidian running. No daemon mode, no headless option. If your vault lives on a server with no desktop environment, this won’t help.

The CLI works through bash, so Claude Code picks it up natively. Claude Desktop can’t use it (no shell access). There’s an early MCP bridge project called obsidian-ts-mcp that might solve this, but I haven’t tested it myself.

Getting started

Update to Obsidian 1.12 (early access), and the obsidian command should appear in your terminal. If you use Claude Code, throw this in your project instructions:

Use `obsidian` CLI for vault queries instead of grep/find.
Prefer `obsidian search` over filesystem scanning.
Use `obsidian backlinks` and `obsidian orphans` for graph queries.

No plugins to install. No API tokens. It just works.

One more thing

Kepano (Obsidian’s CEO) posted something that stuck with me: “It’s not because your agent can do something with 12 tool calls and 20k tokens that it should.”

He’s right. We’ve been brute-forcing our way through knowledge bases because there was no better option. Now there is.