Obsidian Vault Manager

Prerequisites

Before performing vault operations:

1. Verify obsidian CLI is installed:

   obsidian --version
   

   The CLI is the native obsidian binary that ships with the Obsidian desktop app — not a separate npm package.

2. List available vaults:

   obsidian vaults
   

3. Get vault path:

   obsidian vault "<name>" info=path
   

Overview

Use obsidian for vault operations that touch links or structure. For creating notes with substantial content (multi-line, frontmatter, etc.), use the Write tool directly after locating the vault path — the CLI's create command strips multi-line content when \n escapes are used.

Quick Reference

Task	Command	Notes
List vaults	obsidian vaults	Always run first
Vault info	obsidian vault "<name>"	Name, path, file count
Vault path	obsidian vault "<name>" info=path	Path only, good for scripting
List folders	obsidian "vault=<name>" folders	Quote vault name if it has spaces
Read note	obsidian "vault=<name>" read "<note name>"	Reads by name (fuzzy)
Create note	obsidian "vault=<name>" create path="folder/name.md" content="$CONTENT"	Use printf to build $CONTENT for multi-line
Overwrite note	obsidian "vault=<name>" create path="..." content="$CONTENT" overwrite
Append to note	obsidian "vault=<name>" append path="<path>" content="<text>"
Move note	obsidian "vault=<name>" move path="old.md" newpath="new.md"	Auto-updates all links
Search content	obsidian "vault=<name>" search query="<term>" [path=<folder>] [format=json]
Daily note	obsidian "vault=<name>" daily	Create/open today's note

See also:

• Complete obsidian Command Reference - All commands with flags and advanced usage
• Obsidian Syntax Reference - Wiki-links, tags, frontmatter, and markdown syntax
• Note Templates - Daily note, project, and meeting templates

Core Workflows

Step 1 — Find the Vault

# List vaults to confirm the name
obsidian vaults

# Get full info (name, path, file count)
obsidian vault "<name>"

# Get just the path (useful for scripting)
VAULT_PATH=$(obsidian vault "<name>" info=path)

Step 2 — Explore Structure

# List folders
obsidian "vault=<name>" folders

# Search for existing notes
obsidian "vault=<name>" search query="<topic>" path=<folder> format=json

Step 3 — Create Notes with Rich Content

Use printf to build the content variable — this correctly handles newlines and multi-line content including frontmatter:

CONTENT=$(printf '---\ntags:\n  - til\nindex: "[[Today I learned]]"\n---\n## Heading\n\nContent here.')
obsidian "vault=<name>" create path="til/2026-04-27 My Note.md" content="$CONTENT"

Look at an existing note first to match local formatting conventions (tag names, frontmatter fields, index backlinks, etc.):

obsidian "vault=<name>" read "<existing note name>"

Moving/Reorganizing Notes

# ✅ CORRECT: Auto-updates all links
obsidian "vault=<name>" move path="Random Notes/Design.md" newpath="Projects/Design.md"

# ❌ WRONG: Breaks all links to this note
mv "vault/Random Notes/Design.md" "vault/Projects/Design.md"

Common Mistakes

Mistake	Why Wrong	Fix
Using obsidian-cli	That's a different npm package — the tool is obsidian	Use obsidian
Using --flags syntax	The CLI uses key=value positional args, not --flags	Use key=value format
create with \n in double-quoted string	Escapes get stripped, content truncated	Use printf to build a $CONTENT variable
Using mv to move notes	Breaks all [[wiki-links]] to that note	Use obsidian move
Not checking existing note format	Each vault has different tagging/frontmatter conventions	Read an existing note first
Using absolute paths in wiki-links	Breaks when vault moves	Use vault-relative paths

When to Use Standard Tools

• Bulk content editing: Use Edit after reading with obsidian read
• Complex search patterns: Use Grep directly on the vault path (use obsidian vault "<name>" info=path to get it)

Always preserve:

• Frontmatter (YAML between ---)
• Obsidian link syntax [[Note]]
• Tag syntax #tag-name
• Markdown structure

Success Criteria

Vault operations succeed when:

• All [[wiki-links]] remain valid after moves
• Notes created in correct vault location with full content intact
• Formatting matches existing notes in the same folder
• No broken links or orphaned notes