Obsidian

obsidian — Obsidian vault management

Overview

An Obsidian vault is a folder of markdown files with a .obsidian/ config directory. The OBSIDIAN_VAULT environment variable must point to the vault root. All operations are filesystem-based — Obsidian detects changes automatically when running.

Obsidian Sync

Obsidian watches the vault directory for filesystem changes. When Obsidian is running, any file you create, edit, or delete is picked up and synced automatically (if Obsidian Sync or a sync plugin is configured). Never modify anything inside .obsidian/ directly.

Filesystem operations

Read a note

bashCopy code
cat "$OBSIDIAN_VAULT/path/to/note.md"

List notes

bashCopy code
# All notes
find "$OBSIDIAN_VAULT" -name '*.md' -not -path '*/.obsidian/*'

# Notes in a specific folder
ls "$OBSIDIAN_VAULT/folder/"*.md

Create a note

bashCopy code
cat > "$OBSIDIAN_VAULT/path/to/note.md" << 'EOF'
---
tags: [topic]
---

Note content here.
EOF

Edit a note (append)

bashCopy code
echo "New content" >> "$OBSIDIAN_VAULT/path/to/note.md"

Edit a note (overwrite)

bashCopy code
cat > "$OBSIDIAN_VAULT/path/to/note.md" << 'EOF'
Replacement content.
EOF

Search by content

bashCopy code
grep -rl "search term" "$OBSIDIAN_VAULT" --include='*.md' | grep -v '.obsidian/'

Search by filename

bashCopy code
find "$OBSIDIAN_VAULT" -name '*keyword*' -name '*.md' -not -path '*/.obsidian/*'

Move / rename

bashCopy code
mv "$OBSIDIAN_VAULT/old/path.md" "$OBSIDIAN_VAULT/new/path.md"

Note: Moving or renaming files does not automatically update [[wikilinks]] pointing to that note. If the note is linked from others, update those references manually or rely on Obsidian's built-in rename refactoring (which only works when Obsidian performs the rename via its UI).

Delete a note

bashCopy code
rm "$OBSIDIAN_VAULT/path/to/note.md"

Manage folders

bashCopy code
mkdir -p "$OBSIDIAN_VAULT/new/folder"
rmdir "$OBSIDIAN_VAULT/empty/folder"

Tags, links, and metadata

Find notes with a tag

bashCopy code
grep -rl '#tagname' "$OBSIDIAN_VAULT" --include='*.md' | grep -v '.obsidian/'

Find notes linking to a page

bashCopy code
grep -rl '\[\[Page Name\]\]' "$OBSIDIAN_VAULT" --include='*.md' | grep -v '.obsidian/'

Find backlinks to a note

bashCopy code
# Find all notes that link to "My Note"
grep -rl '\[\[My Note\]\]' "$OBSIDIAN_VAULT" --include='*.md' | grep -v '.obsidian/'

Read frontmatter

bashCopy code
sed -n '/^---$/,/^---$/p' "$OBSIDIAN_VAULT/path/to/note.md"

Write frontmatter

When creating notes, include YAML frontmatter between --- markers at the top of the file:

yamlCopy code
---
tags: [tag1, tag2]
aliases: [alternate-name]
date: 2024-01-15
---

Conventions

• Wikilinks: Use [[Note Name]] to link between notes. For sections: [[Note Name#Section]].
• Tags: Use #tag inline or in frontmatter tags: [tag1, tag2].
• Frontmatter: YAML between --- markers at the top of each file. Used for tags, aliases, dates, and custom metadata.
• Daily notes: Typically stored in a daily/ or Daily Notes/ folder with YYYY-MM-DD.md naming.
• Attachments: Images and files typically go in an attachments/ or assets/ folder.
• Never touch .obsidian/: This directory contains Obsidian's configuration, plugins, and theme data. Modifying it directly can corrupt settings.