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.
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.
| name | obsidian-vault-manager |
|---|---|
| description | 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. |
Obsidian Vault Manager
Prerequisites
Before performing vault operations:
Verify obsidian-cli is installed:
obsidian-cli --versionIf 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]]
- Install via:
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 (
.mdfiles 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:
- Complete obsidian-cli 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
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
Editafterobsidian-cli print) - Complex search patterns (use
Grepwith vault path) - File pattern matching (use
Globon$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