Obsidian File History & Recovery
When to Use This Skill
| Use this skill when... | Use the alternative instead when... |
|---|---|
| Recovering an overwritten or accidentally deleted note | Editing a current note — use vault-files |
| Diffing what changed between two versions of a note | Searching the current vault state — use search-discovery |
| Auditing the history of a single file before a destructive edit | Restoring a deleted file from disk-level backups — use OS tools |
Obsidian keeps two parallel version stores:
- File Recovery — local snapshots, configurable in Settings → File Recovery (
history:*). - Sync history — server-side versions, available with Obsidian Sync (
sync:history,sync:read,sync:restore).
diff unifies both: by default it lists every available version (newest = 1)
across both stores. filter=local|sync narrows the source.
Prerequisites
- Obsidian desktop 1.12.7+ installer with CLI enabled
- Obsidian must be running
- File Recovery enabled (Settings → File Recovery) for local history
- Active Obsidian Sync subscription for
sync:*commands
Diff Versions
# List all available versions of the active file
obsidian diff
# List versions of a specific file
obsidian diff file=Recipe
# Compare the latest version (1) to current state
obsidian diff file=Recipe from=1
# Compare two specific versions (newest = 1)
obsidian diff file=Recipe from=2 to=1
# Restrict to one source
obsidian diff file=Recipe filter=local
obsidian diff file=Recipe filter=sync
Local File Recovery
# History entries for a file
obsidian history file=Recipe
# Every file that has local history
obsidian history:list
# Read a specific version (default: version=1, newest)
obsidian history:read file=Recipe version=3
# Open the File Recovery view in the GUI
obsidian history:open file=Recipe
# Restore a previous version (overwrites current)
obsidian history:restore file=Recipe version=3
Sync Version History
# Sync versions for a file
obsidian sync:history file=Recipe
obsidian sync:history file=Recipe total
# Read a specific sync version
obsidian sync:read file=Recipe version=2
# Restore a sync version (overwrites current)
obsidian sync:restore file=Recipe version=2
# Open the sync history view in the GUI
obsidian sync:open file=Recipe
# Files deleted via sync (recoverable)
obsidian sync:deleted
Common Patterns
"Show me what an agent changed since I last reviewed"
# Diff the most recent saved version against the current state
obsidian diff file="Notes/Project" from=1
"Restore yesterday's version after a bad edit"
# 1. List versions to identify the right one (newest = 1)
obsidian history file=Daily/2026-04-29
# 2. Read it to confirm
obsidian history:read file=Daily/2026-04-29 version=2
# 3. Restore
obsidian history:restore file=Daily/2026-04-29 version=2
"Audit history for every file an agent touched in this session"
# Given a list of changed paths in $changed_files
while read -r path; do
echo "=== $path ==="
obsidian diff path="$path" filter=local
done <<< "$changed_files"
Pre-flight before destructive edits
For agentic workflows that overwrite or delete notes, capture the version number first so a restore is one command away:
# Snapshot the current version
obsidian history file="Notes/Important" | head -2
# … perform edit …
# If something breaks:
obsidian history:restore file="Notes/Important" version=2
Agentic Optimizations
| Context | Command |
|---|---|
| List all versions of a file | obsidian diff file=X |
| Diff latest version vs current | obsidian diff file=X from=1 |
| Diff two specific versions | obsidian diff file=X from=2 to=1 |
| Local-only versions | obsidian diff file=X filter=local |
| Read a local version | obsidian history:read file=X version=N |
| Restore a local version | obsidian history:restore file=X version=N |
| Read a sync version | obsidian sync:read file=X version=N |
| Restore a sync version | obsidian sync:restore file=X version=N |
| Files deleted via sync | obsidian sync:deleted |
Related Skills
- vault-files — Read or write the current state of a note
- publish-sync — Sync service status (pause/resume) and published-file workflows
- vault-management — Switch vaults before inspecting their history