obsidian-vault-manager

What this skill does

# Obsidian Vault Manager

## Prerequisites

Before performing vault operations:

1. **Verify obsidian CLI is installed:**
   ```bash
   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:**
   ```bash
   obsidian vaults
   ```

3. **Get vault path:**
   ```bash
   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](./references/obsidian-cli-reference.md) - All commands with flags and advanced usage
- [Obsidian Syntax Reference](./references/obsidian-syntax.md) - Wiki-links, tags, frontmatter, and markdown syntax
- [Note Templates](./assets/templates/) - Daily note, project, and meeting templates

## Core Workflows

### Step 1 — Find the Vault

```bash
# 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

```bash
# 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:

```bash
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.):
```bash
obsidian "vault=<name>" read "<existing note name>"
```

### Moving/Reorganizing Notes

```bash
# ✅ 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