Obsidian CLI

Obsidian CLI Skill

The user has the obsidian CLI installed, which communicates with a running Obsidian instance over a local REST API. Use it to search, read, create, modify, and analyze notes without touching files directly on disk.

When to Use CLI vs Direct File Access

Key principle: Use CLI for discovery and metadata; use direct file access for surgical edits. Combine them for find-then-edit workflows.

CLI Syntax Conventions

obsidian <command> [key=value ...] [bare-flags]

• file= resolves by name like wikilinks (no extension needed): file=Meeting Notes
• path= is an exact vault-relative path: path=Journal/2024-01-15.md
• Quote values with spaces: file="Project Planning", content="Hello World"
• Newlines in content: Use \n — e.g., content="Line 1\nLine 2"
• Bare boolean flags have no value: total, verbose, counts, done, todo
• vault= targets a specific vault: vault="Work Vault"
• format=json for structured/parseable output (prefer this for programmatic use)
• Most commands default to the active file when file=/path= is omitted

Safe vs Destructive Operations

Safe (no confirmation needed)

• All read commands: read, search, search:context, file, files, folders, outline, wordcount, recents
• All list commands: tags, properties, tasks, backlinks, links, orphans, deadends, unresolved, aliases, bookmarks, templates, bases, plugins, themes, snippets, hotkeys, commands, tabs, workspace
• Single-value reads: tag, property:read, daily:read, daily:path, template:read, random:read, vault, vaults, version, history, history:list, history:read, diff, publish:list, publish:site, publish:status, base:query, base:views
• UI navigation: open, daily, search:open, tab:open, web

Mutating (use with normal judgment)

• Content modification: append, prepend, create, daily:append, daily:prepend
• Properties: property:set, property:remove
• Tasks: task with toggle/done/todo/status=
• Bookmarks: bookmark
• Templates: template:insert
• Bases: base:create

Destructive (confirm with user first)

• delete — moves to trash (or permanent with permanent flag)
• move, rename — changes file location/name
• history:restore — overwrites current file with historical version
• plugin:install, plugin:uninstall, plugin:enable, plugin:disable — changes plugin state
• theme:install, theme:uninstall, theme:set — changes theme
• snippet:enable, snippet:disable — changes CSS snippets
• plugins:restrict — toggles restricted mode
• publish:add, publish:remove — affects published site
• reload, restart — disrupts the running app
• command — executes arbitrary Obsidian commands

Core Command Patterns

Search & Discovery

# Full-text search
obsidian search query="project planning" format=json

# Search with line context (shows matching lines)
obsidian search:context query="TODO" path=Projects limit=10

# Count matches
obsidian search query="meeting" total

# List all markdown files in a folder
obsidian files folder=Projects ext=md

# Recently opened files
obsidian recents

Reading Notes

# Read by wikilink name
obsidian read file="Meeting Notes"

# Read by exact path
obsidian read path="Journal/2024-01-15.md"

# Get file metadata
obsidian file file="My Note"

# Show heading outline
obsidian outline file="My Note" format=json

# Word count
obsidian wordcount file="My Note"

Writing & Modifying Notes

# Create a new note
obsidian create name="New Note" content="# New Note\n\nContent here"

# Create from template
obsidian create name="Meeting 2024-01-15" template="Meeting Template"

# Append to a note
obsidian append file="My Note" content="\n## New Section\n\nAdded content"

# Prepend to a note
obsidian prepend file="My Note" content="Important update at the top\n"

Properties (Frontmatter)

# List all properties across the vault with counts
obsidian properties counts sort=count format=json

# Read a specific property from a file
obsidian property:read name=status file="My Project"

# Set a property
obsidian property:set name=status value=active file="My Project"

# Set a date property
obsidian property:set name=due value=2024-03-15 type=date file="My Task"

# Set a list property
obsidian property:set name=tags value="[work, urgent]" type=list file="My Note"

# Remove a property
obsidian property:remove name=draft file="Published Post"

# Show properties for a specific file
obsidian properties file="My Note" format=yaml

Tags

# List all tags with counts, sorted by frequency
obsidian tags counts sort=count format=json

# Get info about a specific tag
obsidian tag name=project verbose

# Count how many times a tag is used
obsidian tag name=work total

# Tags for a specific file
obsidian tags file="My Note"

Graph & Links

# Find what links TO a note (backlinks)
obsidian backlinks file="My Note" counts format=json

# Find what a note links TO (outgoing)
obsidian links file="My Note"

# Find orphan notes (nothing links to them)
obsidian orphans

# Count orphans
obsidian orphans total

# Find dead-end notes (they link to nothing)
obsidian deadends

# Find broken/unresolved links
obsidian unresolved counts verbose format=json

Tasks

# List all incomplete tasks
obsidian tasks todo

# List completed tasks
obsidian tasks done

# Tasks in a specific file
obsidian tasks file="Project Plan" verbose

# Tasks from daily note
obsidian tasks daily todo

# Count incomplete tasks
obsidian tasks todo total

# Tasks as JSON for processing
obsidian tasks todo format=json

# Toggle a task (by file and line number)
obsidian task file="My Note" line=15 toggle

# Mark a task done
obsidian task file="My Note" line=15 done

# Mark a daily note task done
obsidian task daily line=5 done

Daily Notes

# Read today's daily note
obsidian daily:read

# Get the daily note's file path
obsidian daily:path

# Append to today's daily note
obsidian daily:append content="\n- [ ] New task for today"

# Prepend to daily note
obsidian daily:prepend content="## Morning Update\n\nStarting the day with..."

# Open daily note in Obsidian
obsidian daily

Templates

# List available templates
obsidian templates

# Read a template's content
obsidian template:read name="Meeting Template"

# Read with variables resolved
obsidian template:read name="Meeting Template" resolve title="Q1 Planning"

# Insert template into active file
obsidian template:insert name="Meeting Template"

Bookmarks

# List all bookmarks
obsidian bookmarks format=json

# Bookmark a file
obsidian bookmark file="Important Note"

# Bookmark a heading within a file
obsidian bookmark file="Project Plan" subpath="## Timeline"

# Bookmark a search query
obsidian bookmark search="TODO urgent"

History & Versions

# List history versions for a file
obsidian history file="My Note"

# List all files that have history
obsidian history:list

# Read a specific version
obsidian history:read file="My Note" version=2

# Diff two versions
obsidian diff file="My Note" from=1 to=3

Bases (Obsidian Databases)

# List all base files
obsidian bases

# List views in a base
obsidian base:views file="Tasks DB"

# Query a base view
obsidian base:query file="Tasks DB" view="Active Tasks" format=json

# Create a new item in a base
obsidian base:create file="Tasks DB" name="New Task" content="Task description"

Plugins, Themes, Snippets

# List community plugins with versions
obsidian plugins filter=community versions format=json

# Get info about a specific plugin
obsidian plugin id=dataview

# List enabled plugins
obsidian plugins:enabled

# List installed themes
obsidian themes versions

# Show active theme
obsidian theme

# List CSS snippets
obsidian snippets

Vault Info

# Full vault info
obsidian vault

# Just the vault path
obsidian vault info=path

# Just vault name
obsidian vault info=name

# File and folder counts
obsidian vault info=files
obsidian vault info=folders

# List all known vaults
obsidian vaults verbose

# Obsidian version
obsidian version

Opening Files in Obsidian UI

# Open a file
obsidian open file="My Note"

# Open in new tab
obsidian open file="My Note" newtab

# Open daily note
obsidian daily

# Open search with query
obsidian search:open query="project"

# Execute any Obsidian command
obsidian command id=graph:open

Best Practices

1. Use format=json for structured output — easier to parse and process programmatically
2. Use total for counts — returns just a number instead of listing everything
3. Batch appends — combine multiple items into one content= with \n separators rather than making multiple CLI calls
4. Check before mutating — read the current state before setting properties or modifying content
5. Get vault path dynamically — use obsidian vault info=path rather than hardcoding paths, then combine with Read/Edit for file operations
6. Use file= for convenience, path= for precision — file= is shorter but may be ambiguous if multiple files share a name
7. Use verbose for detailed output — many list commands support verbose for extra context (file paths, counts, types)

Troubleshooting

Full Command Reference

For the complete catalog of all 80+ commands with all options, read: references/command-reference.md (relative to this skill's directory)