obsidian-vault-manager

Expert in managing Obsidian vaults using obsidian-cli workflows for reading, writing, searching, moving, and organizing notes while preserving wiki-link integrity and vault structure. Automatically activates when working with Obsidian vaults, markdown notes with wiki-links, or when internal link integrity needs to be preserved during file operations.

⭐5stars🔀0forks📁View on GitHub🕐Updated Dec 20, 2025⬇️2downloads

When & Why to Use This Skill

The Obsidian Vault Manager is a specialized Claude skill designed to automate and streamline the management of Obsidian knowledge bases. By leveraging the obsidian-cli, it allows users to read, create, search, and reorganize notes while strictly maintaining the integrity of [[wiki-links]] and the vault's internal structure. It is an essential tool for users who need to perform complex file operations without the risk of breaking bidirectional references or losing metadata.

Use Cases

  • Automated Vault Reorganization: Safely move or rename notes across folders while ensuring all internal wiki-links are automatically updated to prevent broken references.
  • Efficient Knowledge Retrieval: Perform deep content searches and fuzzy name searches to quickly locate and read specific information within a large-scale markdown vault.
  • Structured Note Creation: Generate new notes, daily logs, or project entries with pre-defined templates, including checkboxes, tags, and frontmatter, directly through natural language commands.
  • Link Integrity Maintenance: Preserve the complex web of bidirectional links during bulk file operations that would otherwise be corrupted by standard file system tools.
nameobsidian-vault-manager
descriptionExpert in managing Obsidian vaults using obsidian-cli workflows for reading, writing, searching, moving, and organizing notes while preserving wiki-link integrity and vault structure. Automatically activates when working with Obsidian vaults, markdown notes with wiki-links, or when internal link integrity needs to be preserved during file operations.

Obsidian Vault Manager

Prerequisites

Before performing vault operations:

  1. Verify obsidian-cli is installed:

    obsidian-cli --version
    
  2. If obsidian-cli is unavailable:

    • Install via: npm install -g @johnlindquist/obsidian-cli
    • Fallback: Standard file operations can be used but will NOT preserve wiki-links
    • Warning: Without obsidian-cli, moving notes will break all internal [[wiki-links]]
  3. Verify vault is accessible:

    obsidian-cli print-default
    

Overview

Use obsidian-cli for all Obsidian vault operations. Standard file tools (mv, Write, Edit) break internal links and ignore vault structure. The obsidian-cli tool automatically preserves [[wiki-links]] and maintains vault integrity.

When to Use

This skill activates when:

  • Working with Obsidian vaults (.md files with [[wiki-links]])
  • Moving/renaming notes (links must stay valid)
  • Creating notes with Obsidian-specific syntax (wiki-links, checkboxes, tags)
  • Searching vault content or note names
  • Organizing multiple notes across folders

Don't use for:

  • General markdown editing outside Obsidian vaults
  • Static documentation (no internal links)
  • Single-file markdown operations

Quick Reference

Task Command Notes
Check vault obsidian-cli print-default Always run first
Read note obsidian-cli print "Note Name" Reads by name or path
Create note obsidian-cli create "Name" --content "text" Add --open to launch Obsidian
Update note obsidian-cli create "Name" --content "text" --append Use --overwrite to replace
Move note obsidian-cli move "old/path" "new/path" Auto-updates all links
Search content obsidian-cli search-content "term" Searches note contents
Search names obsidian-cli search Fuzzy search (interactive)
Daily note obsidian-cli daily Create/open today's note

See also:

Core Workflows

Always Check Vault First

# REQUIRED before any operation
obsidian-cli print-default

# Get path for direct file operations if needed
VAULT_PATH=$(obsidian-cli print-default --path-only)

Why: Paths are vault-relative, not repository-relative. Creating files in wrong location breaks vault structure.

Moving/Reorganizing Notes

# ✅ CORRECT: Auto-updates all links
obsidian-cli move "Random Notes/Design" "Projects/Design"

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

Critical: obsidian-cli move updates every link in the vault automatically. Using mv or file operations breaks internal references.

Creating/Updating Notes

# Create new note
obsidian-cli create "Projects/Mobile App" --content "# Mobile App\n\n## Tasks\n- [ ] Task 1"

# Append to existing (safe if file exists)
obsidian-cli create "Daily Log" --content "\n## Update\n- New entry" --append

# Replace existing (use cautiously)
obsidian-cli create "Draft" --content "# Fresh content" --overwrite

Obsidian syntax in --content:

  • Wiki-links: [[Note Name]]
  • Tags: #project
  • Checkboxes: - [ ] Task
  • Newlines: \n

Templates: Use provided note templates as starting points for common note types (daily notes, projects, meetings).

Searching and Organizing

# Find notes mentioning topic
obsidian-cli search-content "API design"

# Read found note
obsidian-cli print "Backend/API Design"

# Reorganize (preserves all links)
obsidian-cli move "Backend/API Design" "Projects/Backend/API Design"

Common Mistakes

Mistake Why Wrong Fix
Using mv to move notes Breaks all [[wiki-links]] to that note Use obsidian-cli move
Using Write tool for notes Creates files outside vault or wrong location Use obsidian-cli create --content
Using Read for vault notes Misses vault context, no search integration Use obsidian-cli print
Not checking vault first Operations fail or create files in wrong place Always run print-default first
Manual link updating with sed Error-prone, misses bidirectional links obsidian-cli move handles automatically
Using absolute paths Breaks when vault moves Use vault-relative paths

When to Use Standard Tools

Use obsidian-cli first. Only use standard tools when:

  • Bulk editing note contents (use Edit after obsidian-cli print)
  • Complex search patterns (use Grep with vault path)
  • File pattern matching (use Glob on $VAULT_PATH/**/*.md)

Always preserve:

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

Integration Pattern

# 1. Check vault
obsidian-cli print-default

# 2. Use obsidian-cli for vault operations
obsidian-cli search-content "search term"
obsidian-cli print "Found Note"

# 3. Use standard tools ONLY when needed
# (e.g., complex editing after reading with obsidian-cli)

Success Criteria

Vault operations succeed when:

  • All [[wiki-links]] remain valid after moves
  • Notes created in correct vault location
  • Markdown and frontmatter preserved
  • Search returns accurate results
  • No broken links or orphaned notes