Guide LibraryCLI · Complete guide
The Obsidian CLI: Complete Guide — Every Command, TUI Mode & Claude Code Integration
Diagnostic: Why are you stuck? Take the 7-minute audit. Start Quiz…
Diagnostic: Why are you stuck? Take the 7-minute audit. Start Quiz →
Frank Anaya — The Definitive Guide · Updated Feb 28, 2026
The Obsidian CLI:
Every Command. Every Possibility.
Obsidian 1.12.4 ships a full command-line interface — free for every user, no subscription required. This is the only guide that covers everything: setup in 5 minutes, the full TUI walkthrough, all 100+ commands with real examples, and what happens when you wire it to Claude Code.
100+Commands
FreeNo Catalyst
v1.12.4Feb 27, 2026
~35 minFull Read
Obsidian CLIPKMAutomationClaude CodeTerminal
In This Guide
Why This Changes Everything
The Moment Obsidian Became Infrastructure
On February 27, 2026, Obsidian shipped version 1.12.4 to every user on the planet — free, no subscription, no special license. Buried in the release notes was a feature that fundamentally changes your relationship with your knowledge system: a full command-line interface.
The CLI means anything you can do inside Obsidian — creating notes, searching your vault, applying templates, renaming tags across thousands of files — you can now do from a terminal window. That unlocks shell scripts, scheduled automation, and AI tools like Claude Code that can read, write, and reason about your vault without you touching the keyboard. Your PKM system stops being an app you open and becomes infrastructure that works alongside you.
Here’s what we’ll cover: what the CLI is and why it’s different from anything before it, setup for macOS, Windows, and Linux (including the PATH fix that trips up most people), your first five commands to get comfortable, a complete TUI walkthrough, the full command reference organized by what you’re trying to do, ten real automation scripts, and then the most exciting part — pairing it with Claude Code.
The Foundation
What the Obsidian CLI Actually Is
The CLI (Command Line Interface) is a binary that ships inside the Obsidian application. It operates as a client that communicates with your running Obsidian instance — meaning Obsidian must be open for commands to work. When you run a command, the binary sends an instruction to the Obsidian app, which executes it in your vault’s full context: your plugins, your templates, your graph data, your sync status, everything.
This is fundamentally different from third-party scripts that directly modify .md files on disk. The official CLI goes through Obsidian’s runtime — which means operations like move automatically update all internal links, create applies your templates correctly, and properties:set writes valid YAML frontmatter. It’s safe, complete, and canonical.
Without the CLI
- Open Obsidian, click to navigate every time
- Manually copy content from other apps
- Third-party scripts that break links when moving files
- No way to automate template application
- AI tools had no official vault access
- No scripted batch operations on notes
With the CLI
- Create, read, move, tag notes from terminal or scripts
- Pipe any external data directly into your vault
- Native move preserves all links automatically
- Apply templates, set properties, query databases
- Claude Code reads, searches, writes to your vault
- Cron jobs, bash scripts, full automation pipelines
5 Minutes to First Command
Quick Start: Zero to Running
If you’re already on Obsidian 1.12.4 or later, you’re three steps away from running your first command. This section gets you there in five minutes — then the rest of the guide shows you what to do with it.
Step 1 — Update Obsidian
The CLI ships in Obsidian v1.12.4+ (released February 27, 2026). Check your version at Settings → About. If you’re behind, go to Help → Check for updates and install the latest version. The CLI is included automatically — nothing extra to download.
Step 2 — Enable the CLI
In Obsidian: Settings → General → scroll down to the Command line interface section → click Register CLI → toggle it on. Obsidian will attempt to add the binary to your system PATH automatically. Open a new terminal window (important — existing sessions won’t have the updated PATH) and run your first command:
$ obsidian version Obsidian CLI 1.12.4$ obsidian vault My Knowledge Vault
$ obsidian files total 2,847 notes
If those three commands work, you’re set. Skip ahead to TUI Mode or jump directly to the Command Reference. If you see command not found, read the PATH fix section below.
Step 3 — Fix PATH if Needed
The most common setup issue. If Obsidian didn’t add itself to your PATH automatically, here’s the fix for each platform:
# Find the binary — it lives here (capital O in filename) $ ls /Applications/Obsidian.app/Contents/MacOS/ Obsidian obsidian-helperzsh (default on macOS Catalina+) — add to ~/.zshrc
$ echo ‘export PATH=“$PATH:/Applications/Obsidian.app/Contents/MacOS”’ >> ~/.zshrc $ source ~/.zshrc
bash — add to ~/.bash_profile
$ echo ‘export PATH=“$PATH:/Applications/Obsidian.app/Contents/MacOS”’ >> ~/.bash_profile $ source ~/.bash_profile
fish shell
$ fish_add_path /Applications/Obsidian.app/Contents/MacOS
verify it works (macOS is case-insensitive, lowercase works)
$ obsidian version
# Option 1: Add to PATH via System Settings # Search → "Environment Variables" → Path → Edit → New # Add: C:\Users\[Username]\AppData\Local\Programs\Obsidian\Option 2: PowerShell (current session only)
$env:PATH += “;C:\Users$env:USERNAME\AppData\Local\Programs\Obsidian”
CRITICAL: Always use non-admin PowerShell
Win + R → type “powershell” → Enter (NOT “Run as Administrator”)
Admin mode causes empty command outputs — known issue
PS> obsidian version
# Find where Obsidian installed its binary $ find /opt /usr -name "obsidian" -type f 2>/dev/nullCreate a symlink to /usr/local/bin (available to all shells)
$ sudo ln -s /opt/obsidian/obsidian /usr/local/bin/obsidian
OR add to ~/.bashrc
$ echo ‘export PATH=“$PATH:/opt/obsidian”’ >> ~/.bashrc $ source ~/.bashrc
Common Gotcha
Always open a new terminal window after making PATH changes. Existing terminal sessions cache the old PATH and won’t pick up the change — this catches most people who “tried the fix but it didn’t work.”
Start Here — Not With the Full Reference
Your First 5 Commands
The CLI has over 100 commands. That number is intimidating and irrelevant for getting started. Most people who open the full command reference immediately and try to memorize it never actually use the CLI. Here’s a better path: learn five commands that are immediately useful, use them for a week, and let the rest of the guide expand your vocabulary when you need it.
Open Your Vault Browser
Run obsidian with no arguments. This launches TUI mode — a full-screen file browser for your vault. Use arrow keys to navigate, press / to search by name, and Enter to open any note in Obsidian. Press q to quit. This alone replaces dozens of clicks for people who live in the terminal.
Open Today’s Daily Note
Run obsidian daily and Obsidian jumps to today’s daily note — creating it if it doesn’t exist yet. This is the command most daily note users make into an alias or keyboard shortcut within the first day. One word, and your day begins.
Search Your Entire Vault
Run obsidian search query="your topic" to full-text search every note in your vault instantly. The results print to your terminal. Add format=json if you want to pipe results into another tool. This is the command that makes PKM writers immediately understand what the CLI is for.
Capture a Quick Thought
Run obsidian daily:append content="your thought here" to add a line to today’s daily note without opening Obsidian at all. Wire this to a Raycast or Alfred shortcut and you have the fastest capture workflow on your Mac — one hotkey, type, done.
See Your Vault Stats
Run obsidian files total to see how many notes are in your vault, then obsidian tags sort=count to see your most-used tags. These two commands give you an instant health snapshot. They’re also satisfying in a way that’s hard to describe until you see your vault described in numbers for the first time.
# 1. Browse your vault interactively $ obsidian2. Open today’s daily note
$ obsidian daily
3. Search your vault
$ obsidian search query=“PKM”
4. Capture a thought to today’s note (no Obsidian window needed)
$ obsidian daily:append content=“Follow up on this idea later”
5. See your vault stats
$ obsidian files total $ obsidian tags sort=count
If those work, you’re using the CLI. The rest of this guide is about going deeper — TUI mode, the full command reference, automation scripts, and AI integration. But you could stop here and already get real value every day.
Free Download
Get the Obsidian CLI Quick Reference
The commands that matter, organized by workflow — morning setup, search, capture, publishing, vault health. Pre-built as an Obsidian template so it lives in your vault alongside your notes. Part of the free Creator Vault.
No spam. Unsubscribe any time.
Interactive Terminal Interface
TUI Mode: Your Vault Without the Mouse
Run obsidian with no arguments and you launch TUI mode — a full-screen, keyboard-driven interface for your vault. TUI stands for Terminal User Interface. Think of it as a text-based version of the Obsidian sidebar and file explorer, accessible entirely from the keyboard without opening the GUI. It’s especially useful on remote machines, in scripts that need interactive selection, or just when you’re already in the terminal and don’t want to break your flow to grab the mouse.
What TUI Looks Like
Here’s a representation of what you see when TUI launches:
OBSIDIAN — My Knowledge Vault2,847 files
/ Type to search…
📄 Daily Note 2026-02-28Today
📄 Video Script — Obsidian CLI GuideFeb 28
📄 Systems vs Goals ThinkingFeb 26
📄 PKM Framework NotesFeb 25
📄 The Bridge Cohort — IdeasFeb 24
📁 Projects/—
📁 Content/Scripts/—
↑↓Navigate EnterOpen in Obsidian /Search nNew note dDelete rRename qQuit
Every TUI Keyboard Shortcut
TUI mode has two contexts: the file list (default on launch) and the search/command input. Here’s the complete keyboard reference:
↑ / ↓Move between files and folders
EnterOpen selected note in Obsidian
/Focus search bar — start typing to filter
EscClear search / return to file list
nCreate a new note (prompts for name)
dDelete selected file (confirms first)
rRename selected file (inline edit)
TabAutocomplete command or filename
Ctrl+RReverse search through command history
Ctrl+AMove cursor to beginning of line
Ctrl+EMove cursor to end of line
Ctrl+WDelete word backward
Ctrl+CCancel current action / exit
qQuit TUI mode
TUI Search: Filtering Your Vault in Real Time
Press / and the cursor jumps to the search bar. As you type, the file list filters in real time across note titles. This isn’t a full-text search — it’s a fast filename/title filter. For full-text search across note content from the command line, use obsidian search query="..." instead.
# TUI mode — best for: $ obsidian # → Quickly find and open a note you can't quite remember the name of # → Browse vault structure visually # → On a remote machine via SSH where you can't open the GUI # → Creating/renaming/deleting files without opening ObsidianCommand mode — best for:
$ obsidian create name=“New Note” template=“YouTube Script”
→ Scripts and automation (cron jobs, shell scripts)
→ AI tool integration (Claude Code, shell pipelines)
→ Batch operations across multiple files
→ Structured output in JSON/CSV for further processing
TUI on Remote Machines via SSH
One underappreciated use case: if you run a home server or a remote machine with Obsidian installed, TUI mode lets you browse and edit your vault entirely over SSH. No GUI, no VNC, no remote desktop — just ssh yourserver and obsidian.
The Language
Syntax, Targeting & Output Formats
The CLI uses a consistent, readable syntax. Once you understand three rules — key=value parameters, flag switches, and output formats — every command is immediately legible.
# Rule 1: Parameters use key=value (no dashes) obsidian command param=valueRule 2: Values with spaces get quoted
obsidian create name=“My Note Title” content=”# First Heading”
Rule 3: Boolean flags use double-dash
obsidian create name=“Draft” —silent —overwrite
Newlines use \n, tabs use \t
obsidian append file=“Today” content=“Line one\nLine two\n- [ ] Task”
Target by note name (wikilink resolution)
obsidian read file=“Project Alpha”
Target by exact path from vault root
obsidian read path=“Projects/Active/Project Alpha.md”
Target a specific vault when you have multiple
obsidian files vault=“Work Vault”
Output as JSON for scripting
obsidian search query=“meeting” format=json
Copy any output to clipboard
obsidian daily:read —copy
FormatOutputBest Use jsonStructured JSON array/objectScripts, AI tools, APIs, jq pipelines csvComma-separated valuesSpreadsheet import, data analysis mdMarkdown-formatted listPasting into notes, readable terminal output pathsFile paths, one per lineFeeding to other CLI tools (xargs, etc.) yamlYAML formatConfig files, frontmatter-compatible output treeIndented hierarchyFolder structure visualization tsvTab-separatedTerminal processing with awk/cut
The Full Toolkit
Complete Command Reference with Examples
Over 100 commands across twelve categories. Each block below is copy-paste ready.
Files & Folders
Use this when: you want to list notes in a folder, read a note’s content, create a new note, append text to an existing note, move a note (link-safe!), or delete it. These are the bread-and-butter commands you’ll reach for most.
── LIST ────────────────────────────────────────────────────── obsidian files # all files in active vault obsidian files folder=Projects/Active # files in a specific folder obsidian files ext=md format=json # JSON list of markdown files obsidian files total # count notes in vault obsidian folders # list all folders obsidian folders format=tree # hierarchical tree view── READ ────────────────────────────────────────────────────── obsidian read file=“Note Name” # by wikilink name obsidian read path=“Projects/Note.md” # by exact path
── CREATE ──────────────────────────────────────────────────── obsidian create name=“New Note” obsidian create name=“Script” path=Content/ template=“YouTube Script” obsidian create name=“Quick Capture” content=”# Idea\n\ndetails here” —silent obsidian create name=“Existing” content=“new content” —overwrite
── EDIT ────────────────────────────────────────────────────── obsidian append file=“Research” content=“New paragraph appended” obsidian prepend file=“Inbox” content=”- [ ] Urgent item” obsidian append file=“Log” content=“Entry” —inline # no trailing newline
── MOVE / RENAME / DELETE ──────────────────────────────────── obsidian move file=“Draft” to=Archive/2026/ # updates all internal links obsidian delete file=“Old Note” # moves to Obsidian trash obsidian delete file=“Old Note” —permanent
Search
Use this when: you want to find notes by content, tag, property value, or any combination. The search command is one of the most powerful — you can pipe results to scripts, feed them to AI tools, or open results directly in Obsidian.
# Full-text search obsidian search query="building a second brain" obsidian search query="meeting notes" limit=20 format=jsonTag-based (use square brackets)
obsidian search query=“[tag:publish]” obsidian search query=“[tag:project] [tag:active]“
Property-based
obsidian search query=“[status:active]” obsidian search query=“[priority:>3]“
Open search results in Obsidian
obsidian search:open query=“[tag:review]“
Pipe JSON to jq for processing
obsidian search query=“[tag:publish]” format=json | jq ’.[].path’
Daily Notes
Use this when: you use Obsidian’s Daily Notes feature (most people do). These commands are the highest ROI for daily note practitioners — automating morning setup, evening capture, and weekly review all start here.
obsidian daily # open today's note (creates if missing) obsidian daily:read # read today's content obsidian daily:read --copy # copy to clipboard obsidian daily:append content="- [ ] Task" obsidian daily:prepend content="## Morning Intention\n\n" obsidian daily:open date=2026-02-15 # specific date obsidian daily:path # returns path to today's note file
Properties (YAML Frontmatter)
Use this when: you use Obsidian Properties (the YAML metadata at the top of notes) to track status, dates, types, or any structured data. These commands let you read and write properties in batch — the foundation of any automated publishing or tracking workflow.
obsidian properties file="Project Alpha" # read all props obsidian properties:set file="Draft" status=active obsidian properties:set file="Article" published=2026-02-28 type=date obsidian properties:set file="Video" tags="pkm,obsidian" type=tags obsidian properties:remove file="Draft" key=draftAvailable types: text | list | number | checkbox | date | tags
Tags, Links & Backlinks
Use this when: you want to audit your tag usage, find all notes with a specific tag, rename a tag across your entire vault (this is otherwise painful), or explore how your notes connect to each other. The orphans and unresolved commands are vault health essentials.
obsidian tags # all tags in vault obsidian tags sort=count # sorted by frequency obsidian tag tagname=pkm # all notes with #pkm obsidian tags:rename old=meeting new=meetings # rename across entire vaultobsidian links file=“Note” # outgoing links from a note obsidian backlinks file=“Note” # notes that link TO this note obsidian unresolved # broken [[links]] across vault obsidian orphans # notes with zero links
Tasks
Use this when: you track tasks inside Obsidian (checkbox items - [ ]). Pull all open tasks into a JSON list, create tasks from scripts or other tools, or complete them programmatically as part of a workflow. Pairs well with the morning setup script in the Workflows section.
obsidian tasks # all tasks across vault obsidian tasks format=json # JSON for scripting obsidian task:create content="Write newsletter" obsidian task:create content="Client call prep" tags="work,urgent" obsidian task:complete task=task-id
Plugins, Themes & Snippets
Use this when: you’re managing your Obsidian setup — toggling plugins for different workflows, switching themes, or developing your own plugin and need a fast reload cycle. Most users will use these occasionally; plugin developers will use them constantly.
obsidian plugins # list all plugins obsidian plugin:enable id=dataview obsidian plugin:disable id=calendar obsidian plugin:reload id=my-dev-plugin # dev workflow obsidian themes # list available themes obsidian theme:set name="Minimal" obsidian snippets obsidian snippet:enable name="custom-fonts"
Sync, Publish & File History
Use this when: you use Obsidian Sync or Obsidian Publish (paid features). The publish commands are particularly powerful for a scripted content workflow — tag a note as ready, and a script handles the rest. File history lets you restore any version of a note without opening the GUI.
# Obsidian Sync obsidian sync:status obsidian sync:history file="Note" obsidian sync:restore file="Note" version=3Obsidian Publish
obsidian publish:list obsidian publish:add file=“Ready Post” obsidian publish:remove file=“Outdated” obsidian publish:status
Local file version history
obsidian history file=“Note” obsidian history:read file=“Note” version=2 obsidian history:restore file=“Note” version=2
Developer & Eval — The Power Commands
Use this when: you’re building plugins, doing advanced vault automation, or want to run arbitrary logic against Obsidian’s runtime. Skip this section if you’re just starting out — come back when the standard commands feel limiting.
The eval command executes arbitrary JavaScript with full access to Obsidian’s app context — the same runtime your plugins use. This makes the CLI a backdoor to everything Obsidian can do programmatically.
# Execute JavaScript in Obsidian's runtime
obsidian eval code="app.vault.getFiles().length"
obsidian eval code="Object.keys(app.plugins.plugins).join(', ')"
obsidian eval code="app.vault.getFiles().filter(f=>!app.metadataCache.getFileCache(f)?.frontmatter?.reviewed).map(f=>f.path)"
Screenshots for documentation / automated testing
obsidian dev:screenshot path=~/Desktop/vault.png
Console and error monitoring
obsidian dev:console limit=50
obsidian dev:console level=error
obsidian dev:errors
DOM / CSS inspection
obsidian dev:css selector=“.markdown-preview-view”
obsidian dev:dom selector=“.workspace-leaf” total
Plugin dev feedback loop (modify → reload → screenshot)
obsidian plugin:reload id=my-plugin && obsidian dev:screenshot path=test.png
Workflows You Can Run Today
10 Power Workflows with Complete Scripts
Commands are syntax. These are the actual scripts — copy them, adapt them to your vault structure, and run them. Each one solves a real friction point in a PKM workflow.
Workflow 1 — Morning Setup Script
The problem: You open Obsidian every morning to start a daily note from scratch. You also have to manually check yesterday’s note to see what didn’t get done. This script does it all before you even open the app.
#!/bin/bash # Run this every morning — opens daily note pre-populatedTODAY=$(date +%Y-%m-%d) DAY=$(date +%A)
obsidian daily:prepend content=”## $DAY — $TODAY\n\nIntention: \n\nTop 3:\n- [ ] \n- [ ] \n- [ ] \n\n---\n”
Pull yesterday’s unfinished tasks
YESTERDAY=$(date -v-1d +%Y-%m-%d 2>/dev/null || date -d “yesterday” +%Y-%m-%d) obsidian daily:read date=$YESTERDAY | grep ”- [ ]” | while read task; do obsidian daily:append content=“$task (from yesterday)” done
obsidian daily # open in Obsidian echo “Morning setup complete.”
Workflow 2 — Inbox Processing (PARA Auto-Sort)
The problem: Your Inbox folder fills up with unprocessed notes. You tag them as #project, #resource, or #archive when you capture them, but the actual moving to the right PARA folder never happens because it’s tedious to do one by one.
#!/bin/bash # Reads inbox notes as JSON, moves them by tagINBOX=$(obsidian files folder=Inbox/ format=json)
echo “$INBOX” | jq -r ’.[].name’ | while read note; do TAGS=$(obsidian properties file=“$note” format=json | jq -r ‘.tags // [] | join(”,”)’)
if echo "$TAGS" | grep -q "project"; then obsidian move file="$note" to=Projects/Active/ echo "→ Moved $note to Projects" elif echo "$TAGS" | grep -q "resource"; then obsidian move file="$note" to=Resources/ echo "→ Moved $note to Resources" elif echo "$TAGS" | grep -q "archive"; then obsidian move file="$note" to=Archive/ echo "→ Moved $note to Archive" else echo "? $note has no routing tag — skipping" fidone
Workflow 3 — Publish Pipeline (Tag-to-Live)
The problem: You have notes tagged #ready-to-publish that need a published date stamped, a status update, and then pushed to Obsidian Publish. You do this manually for each one. This script handles the whole sequence in one command.
#!/bin/bash # Finds notes tagged #ready-to-publish, stamps the date, and publishesTODAY=$(date +%Y-%m-%d) READY=$(obsidian search query=“[tag:ready-to-publish]” format=json)
echo “$READY” | jq -r ’.[].name’ | while read note; do echo “Publishing: $note” obsidian properties:set file=“$note” published=$TODAY type=date obsidian properties:set file=“$note” status=published obsidian publish:add file=“$note” echo ”✓ $note published” done
echo “Done. $(echo “$READY” | jq length) notes published.”
Workflow 4 — Vault Health Report
The problem: Your vault grows silently. Orphaned notes (no links in or out), broken wikilinks, and tag bloat accumulate over months until the vault feels unmanageable. This script runs a weekly audit and saves the report as a note you can actually act on.
#!/bin/bash # Weekly vault health — run every SundayTOTAL=$(obsidian files total) ORPHANS=$(obsidian orphans format=json | jq length) BROKEN=$(obsidian unresolved format=json | jq length) TOP_TAGS=$(obsidian tags sort=count limit=5 format=md)
REPORT=”# Vault Health — $(date +%Y-%m-%d)\n\nTotal notes: $TOTAL\nOrphaned notes: $ORPHANS\nBroken links: $BROKEN\n\n## Top Tags\n$TOP_TAGS”
obsidian create name=“Vault Health $(date +%Y-%m-%d)”
path=Reviews/
content=“$REPORT” —overwriteecho “Vault health: $TOTAL notes | $ORPHANS orphans | $BROKEN broken links”
Workflow 5 — External Data → Vault Note via Cron
The problem: You want context in your daily notes — weather, news, data from other tools — but manually adding it every morning is friction you never actually do. Cron + the CLI means your vault fills itself. These two examples show the pattern: fetch data from any source, pipe it into a note.
#!/bin/bash # Fetch weather from wttr.in and append to daily note # Cron: 0 6 * * * /path/to/log-weather.shWEATHER=$(curl -s “wttr.in/Montclair+CA?format=3”)
obsidian daily:append content=“\nWeather: $WEATHER\n”
Another example: log Hacker News top stories
HN_TOP=$(curl -s “https://hacker-news.firebaseio.com/v0/topstories.json” |
jq ’.[0:5][]’ |
xargs -I{} curl -s “https://hacker-news.firebaseio.com/v0/item/{}.json” |
jq -r ’”- [” + .title + ”](” + .url + ”)”’)obsidian create name=“HN Top — $(date +%Y-%m-%d)”
path=Inbox/
content=”# HN Top Stories\n\n$HN_TOP”
Content Creation
Idea → Template in One Command
Alias new-video "Title" → obsidian create name="$1" template="YouTube Script" path=Content/Scripts/ --silent && obsidian read file="$1". Every new video idea opens as a properly structured script template. Zero navigation required.
Raycast / Alfred
Quick Capture via Launcher
Wire Raycast or Alfred to run obsidian daily:append content="{input}". One keyboard shortcut anywhere on your Mac, type a thought, it lands in your daily note. Capture friction reduced to zero.
PKM Maintenance
Bulk Tag Rename
Changed your tagging system? obsidian tags:rename old=meetings new=meeting renames the tag across your entire vault in one command. Previously required a plugin and a nerve-wracking find-and-replace.
Plugin Development
Zero-Mouse Dev Loop
Edit plugin code → obsidian plugin:reload id=my-plugin && obsidian dev:screenshot path=test-$(date +%s).png → review screenshot. Full reload → screenshot feedback loop without touching the mouse or switching windows.
Reflection
Weekly Review Dashboard
Pull all notes modified in the last 7 days (format=json + jq), count completed tasks, list notes moved to Archive, and summarize the week. Create the review note automatically. Your Sunday review begins already half-done.
The Next Level
Pairing the Obsidian CLI with Claude Code
Everything above is powerful. This section is where it becomes genuinely transformative. When you connect Claude Code — Anthropic’s AI agent for the terminal — to your Obsidian vault, you don’t just have a scripting layer. You have an AI collaborator that can read everything you’ve ever written, find connections you’ve missed, generate drafts from your raw notes, and write directly back into your system.
"Your vault becomes a live research partner. Every note you've ever written is instantly retrievable context for your AI."
Setup: obsidian-claude-code-mcp
The bridge is the obsidian-claude-code-mcp plugin, which implements an MCP (Model Context Protocol) server inside Obsidian. Claude Code connects to it via WebSocket automatically.
# Step 1: In Obsidian # Community Plugins → Browse → "Claude Code MCP" → Install → EnableStep 2: For Claude Desktop — add to config
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
{ “mcpServers”: { “obsidian”: { “command”: “npx”, “args”: [“mcp-remote”, “http://localhost:22360/sse”] } } }
Step 3: For Claude Code CLI (simplest)
$ claude # launch Claude Code in terminal
then: /ide → select Obsidian → auto-connects via WebSocket
Step 4: Test it
$ claude “How many notes are in my vault and what are my top 5 tags?” → Your vault contains 2,847 notes. Top tags: #pkm (423), #project (187)…
Workflow: Research Synthesis Pipeline
$ claude "Search my Obsidian vault for everything I've written about the PARA
method and Building a Second Brain. Synthesize the key insights into
a structured outline for a 10-minute YouTube video. Save it as a new
note called 'Script — PARA Deep Dive' in Content/Scripts/ using my
YouTube Script template."
Searching vault… found 47 relevant notes across 6 folders.
Synthesizing themes: PARA structure (12 refs), capture systems (8 refs)…
Creating note with template…
✓ Saved: Content/Scripts/Script — PARA Deep Dive.md
Workflow: Daily Briefing Script
#!/bin/bash TASKS=$(obsidian tasks format=json) DAILY=$(obsidian daily:read)claude “Here are my open Obsidian tasks (JSON): $TASKS
Here is today’s daily note so far: $DAILY
Also read any notes tagged [tag:urgent] in my vault.
Give me a focused briefing: my top 3 priorities today, what I’m most likely to procrastinate on, and one thing I should DELETE from my task list because it’s been there too long. Append the briefing to today’s daily note.”
Workflow: Note → Newsletter Draft
#!/bin/bash NOTE="$1" CONTENT=$(obsidian read file="$NOTE") RELATED=$(obsidian search query="$NOTE" limit=8 format=json)claude “Source note: $CONTENT
Related notes from vault (JSON): $RELATED
Write an 800-word newsletter essay in Frank Anaya’s voice: confident, warm, direct. Lead with the core insight. Use the related notes to add depth. End with one practical takeaway readers can use today. Save as ‘Draft — $NOTE’ in Writing/Drafts/.”
Workflow: Vault Conversation
# Ask Claude to connect ideas across your vault
$ claude "Read 'Systems vs Goals Thinking' and find the 5 most related notes.
What connections am I missing? What should I write about next?"
Surface patterns in your captures
$ claude “Search my vault for everything captured in the last 90 days.
What’s the most recurring theme? Draft a newsletter intro based on it.”
Triage old notes
$ claude “Read the 10 oldest notes in my Someday Maybe folder.
For each: have I referenced it elsewhere? Recommend: develop, archive, or delete.”
Learn From What Goes Wrong
5 Mistakes to Avoid With the Obsidian CLI
Most friction with the CLI comes from the same predictable places. Knowing these in advance means you skip the frustrating loops that everyone else goes through on their own.
Mistake 1
Trying to automate before you understand the commands manually
Run every command you want to automate manually first. Understand what it does and what it outputs. Scripts built on misunderstood commands fail silently and in confusing ways. One week of manual use before scripting saves hours of debugging.
Mistake 2
Using delete --permanent before you trust your scripts
Always test with regular delete (moves to Obsidian trash) first. --permanent is irreversible. Use it only after you’ve run your automation a few times and are confident it’s targeting the right notes. Your vault trash is your safety net — don’t bypass it until you’ve earned that trust.
Mistake 3
Forgetting that Obsidian must be running
The CLI communicates with the live Obsidian app. If Obsidian isn’t open, commands silently fail or return errors. For cron jobs that run in the background, add a check at the top of your script: if Obsidian isn’t running, either start it or log the failure and exit gracefully rather than running partial operations.
Mistake 4
Running eval on code you haven’t read
eval executes real JavaScript in Obsidian’s runtime. Copy-pasting eval scripts from the internet without reading them is a bad habit. When AI tools generate eval code for you, read it before running it. For most use cases — file operations, search, daily notes — you never need eval at all.
Mistake 5
Trying to learn all 100+ commands at once
The CLI has a large surface area by design — it covers every Obsidian feature. You do not need to know all of it. Start with the five commands in the “Your First 5” section. Add one or two commands per week as you encounter the need. The full reference is here when you need a specific capability, not as a curriculum to work through.
Go Deeper
Resources & Related Guides
The ecosystem around the Obsidian CLI is growing fast. These are the essential resources — official documentation, community tools, and further reading on the systems that make the CLI most useful.
Official Resources
Official Docs Obsidian CLI Help Documentation The official reference — platform-specific install guides, troubleshooting, and command index. Release Notes Obsidian v1.12.4 Public Release The official changelog for the public release that shipped the CLI to all users. GitHub obsidian-claude-code-mcp Plugin The MCP bridge that connects Claude Code to your Obsidian vault. Setup instructions and source code. Community Obsidian Forum — CLI Discussion Community questions, workflow ideas, and troubleshooting from Obsidian power users.
From This Site
Pillar Guide Personal Knowledge Management: The Complete Guide The foundational PKM framework the CLI is built to serve — PARA, capture, processing, and output. Free Resource The Creator Vault — Free Download Pre-built Obsidian templates, PARA structure, and AI prompt library — ready to install and use with the CLI. Guide AI for Small Business: Architecture Guide How to build AI into your workflows beyond the vault — tools, systems, and implementation strategy. Video Channel Watch: Obsidian Workflows on YouTube Video walkthroughs of PKM systems, Obsidian setups, and the CLI workflows covered in this guide.
Common Questions
FAQ
Do I need to know how to code to use the Obsidian CLI?
No. The most useful commands — opening your daily note, searching your vault, appending a quick capture — require zero coding knowledge. You type a command, you press Enter, it works. The scripting and automation workflows in this guide use bash, which is readable and learnable in an afternoon. The Claude Code integration requires no coding at all — you describe what you want in plain English.
I’ve never used a terminal before. Where do I even start?
On macOS, open Terminal from your Applications → Utilities folder, or search for it with Spotlight (Cmd+Space → “Terminal”). On Windows, open PowerShell (search “PowerShell” in Start — use the non-admin version). Once open, follow the Quick Start section of this guide. The first command you’ll run is obsidian version — if it prints a version number, you’re set. If it says “command not found,” go to the PATH fix section.
Will using the CLI damage or break my vault?
The official CLI is safe by design — it runs through Obsidian’s full runtime, which means it respects link integrity, templates, and vault settings. The delete command moves notes to Obsidian’s trash (not permanently deleted) by default. The move command preserves all internal links automatically. Start with read-only commands like search, files, and daily:read to get comfortable before writing to your vault.
What’s the minimum I need to learn to get real value today?
Five commands: obsidian (browse your vault), obsidian daily (open today’s note), obsidian search query="topic" (find anything), obsidian daily:append content="thought" (capture without opening the app), and obsidian files total (vault stats). These five give you immediate, daily utility. Everything else in this guide builds from there.
Does the Obsidian CLI require a Catalyst license?
No. As of Obsidian 1.12.4 (released February 27, 2026), the CLI is part of the free public desktop release. No subscription, no Catalyst license, no extra download. Update to 1.12.4 or later and enable it in Settings → General → Command line interface.
Does Obsidian need to be running for CLI commands to work?
Yes. The CLI binary communicates with the running Obsidian app. Obsidian must be open in the background. For fully automated/headless scripts on a server, you’d need Obsidian running as a background process — or use a combination of direct file operations and the CLI for non-runtime operations.
What is TUI mode and when should I use it?
TUI (Terminal User Interface) launches when you run obsidian with no arguments. It’s a full-screen, keyboard-driven file browser for your vault — browse files with arrow keys, search with /, create new notes with n, and open notes in Obsidian with Enter. Use it when you’re already in the terminal and want to navigate your vault without switching to the GUI, or when working on a remote machine via SSH.
How do I fix “command not found” after enabling the CLI?
The most common issue is that the CLI binary wasn’t added to your PATH, or you need to restart your terminal session. See the PATH fix section in this guide for macOS, Windows, and Linux instructions. On macOS, the fix is adding /Applications/Obsidian.app/Contents/MacOS to your ~/.zshrc or ~/.bash_profile.
Does the move command update internal Obsidian links?
Yes — this is one of the biggest advantages of the official CLI over direct file manipulation. Because the move command runs through Obsidian’s runtime, it triggers the same link-update process as dragging a file in the GUI. All backlinks across your vault are updated automatically.
Is eval safe to use?
The eval command executes arbitrary JavaScript in Obsidian’s runtime — treat it with appropriate care. Only run code you understand or have reviewed. When using AI tools to generate eval scripts, always read the JavaScript before executing it. For most use cases (file counts, metadata queries, filtering), the risk is minimal since it runs in Obsidian’s sandboxed renderer, not your system shell.
Can I use the Obsidian CLI on mobile?
Not directly — the CLI is a desktop-only feature. However, you can use iOS Shortcuts or Android Tasker to trigger shell commands on a Mac or Linux machine running Obsidian in the background, which effectively gives you mobile-initiated vault automation via the CLI.
What’s the difference between the official Obsidian CLI and community tools like obsidian-cli on GitHub?
Community tools (notesmd-cli, mcky/obsidian-cli, etc.) work by directly reading and writing .md files on disk — they don’t communicate with the Obsidian app. The official CLI has access to Obsidian’s full runtime: plugins, templates, graph data, sync, publish, Bases, properties, and more. Moving files with the official CLI preserves all links; community tools don’t. The official CLI is fundamentally more capable and safer for vault operations.
— Free
Take the CLI Reference With You
The Creator Vault includes a pre-built CLI Quick Reference template — every command organized by workflow, ready to paste into your own vault. Plus PARA folders, AI prompts, and more.
Free. No spam. Unsubscribe any time.
Published February 28, 2026 Share on X → Get the Newsletter →
Put it into practice
This guide works best inside the architecture.
The free Creator Vault is the pre-wired system every guide on this site plugs into.
Get the Vault — FreeNext guide
AI for Small Business: The Complete Guide
Diagnostic: Why are you stuck? Take the 7-minute audit. Start Quiz…