laude-institute/headlong/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

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

List notes

# All notes
find "$OBSIDIAN_VAULT" -name '*.md' -not -path '*/.obsidian/*'
 
# Notes in a specific folder
ls "$OBSIDIAN_VAULT/folder/"*.md

Create a note

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

Edit a note (append)

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

Edit a note (overwrite)

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

Search by content

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

Search by filename

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

Move / rename

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

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

Manage folders

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

Tags, links, and metadata

Find notes with a tag

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

Find notes linking to a page

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

Find backlinks to a note

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

Read frontmatter

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:

---
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.