Obsidian CLI — Agent Reference

When to Use CLI vs File Tools

Use CLI when you need Obsidian's index or app features:
search, backlinks, links, tags, tasks, properties, bases, templates, orphans, unresolved links

Use file tools (Read/Write/Edit/Grep/Glob) for:
simple file read/write, bulk text replacement, grep across files — no app dependency

Rule of thumb: if Obsidian's index adds value, use CLI. If it's plain text manipulation, use file tools.

Execution

Wrap every CLI call with timeout 30 to prevent Electron IPC hangs:

timeout 30 obsidian <command> [param=value ...] [flag ...]

For commands with large output (base:query, search:context), redirect to avoid stdout truncation:

timeout 30 obsidian base:query path=<path> format=json > /tmp/obs-out.txt 2>&1; cat /tmp/obs-out.txt

Syntax Basics

obsidian <command> [param=value ...] [flag ...]

• Vault targeting: vault="My Vault" as first param, or run from inside vault dir
• File targeting: path=exact/path.md (vault-relative) vs file=name (link-style resolution)
• Params: key=value — quote values with spaces: name="My Note"
• Flags: boolean switches, no = — e.g. silent, overwrite, counts, total
• Multiline: \n for newline, \t for tab in content strings
• Structured output: format=json (search, base:query), format=tsv (properties, tags)
• Clipboard: append --copy to copy output

Key Commands

Read & Write

obsidian read path=<path>                                    # read file content
obsidian append path=<path> content="<text>"                 # append to file
obsidian prepend path=<path> content="<text>"                # prepend after frontmatter
obsidian create name=<name> content="<text>" silent          # create file (safe — won't overwrite)
obsidian create name=<name> template=<template> overwrite silent  # create from template
obsidian move path=<from> to=<to>                            # move/rename file
obsidian rename path=<path> name=<newname>                   # rename file (keeps in same folder)
obsidian delete path=<path>                                  # move to system trash (safe)

Gotchas:

• create without silent opens the file in Obsidian's UI — always add silent during agent operations.
• create doesn't auto-create directories — use mkdir -p via Bash first if the parent folder doesn't exist.
• create with template= may place the file in the template's configured folder, ignoring path=. Verify the actual path with search or files after creation.

Properties (Frontmatter)

obsidian property:set name=<key> value=<val> path=<path>              # set property
obsidian property:set name=<key> value=<val> type=<type> path=<path>  # set with explicit type
obsidian property:read name=<key> path=<path>                         # read one property
obsidian property:remove name=<key> path=<path>                       # remove property
obsidian properties path=<path>                                       # list all properties
obsidian properties path=<path> format=tsv                            # list as TSV (key\tvalue)

Search

obsidian search query="<text>"                                    # search vault (file paths)
obsidian search query="<text>" path=<folder> limit=10             # scoped search
obsidian search query="<text>" format=json                        # JSON array of paths
obsidian search:context query="<text>"                            # search with matching lines
obsidian search:context query="<text>" format=json limit=10       # JSON with line context (preferred)
obsidian search:context query="<text>" path=<folder> case         # scoped, case-sensitive

Tags & Tasks

obsidian tags all counts                            # list ALL vault tags with counts
obsidian tags all counts sort=count                 # sorted by frequency
obsidian tags path=<path>                           # tags in specific file
obsidian tag name=<tag>                             # files with specific tag
obsidian tag name=<tag> verbose                     # files + count
obsidian tasks all todo                              # vault-wide open tasks
obsidian tasks all done                              # vault-wide completed tasks
obsidian tasks daily                                 # tasks from daily note
obsidian tasks path=<path>                           # tasks in file/folder
obsidian tasks all todo verbose                      # grouped by file with line numbers
obsidian tasks all todo format=json                  # JSON output
obsidian task ref="<path>:<line>" toggle            # toggle task status
obsidian task ref="<path>:<line>" done              # mark done
obsidian task ref="<path>:<line>" todo              # mark todo
obsidian task ref="<path>:<line>" status="x"        # set status character

Note: tags without all lists tags for the active/specified file only.
Note: tasks without a scope (all, daily, path=) defaults to the active file — use tasks all for vault-wide results.

Links & Graph

obsidian backlinks path=<path>          # incoming links to file
obsidian backlinks path=<path> counts   # with link counts
obsidian links path=<path>              # outgoing links from file
obsidian unresolved                     # broken/unresolved links
obsidian unresolved counts verbose      # with counts and source files
obsidian orphans                        # files with no incoming links
obsidian deadends                       # files with no outgoing links

Structure & Info

obsidian files folder=<path> ext=md     # list files in folder
obsidian files total                    # file count
obsidian folders                        # list all folders
obsidian file path=<path>               # show file info (size, dates)
obsidian folder path=<path>             # show folder info
obsidian aliases                        # list all aliases in vault
obsidian aliases path=<path>            # aliases for specific file
obsidian wordcount path=<path>          # word and character count
obsidian wordcount path=<path> words    # word count only
obsidian recents                        # recently opened files

Bookmarks

obsidian bookmarks                              # list bookmarks
obsidian bookmarks format=json                  # JSON output
obsidian bookmark file=<path>                   # bookmark a file
obsidian bookmark file=<path> title="<title>"   # bookmark with title
obsidian bookmark search=<query>                # bookmark a search query
obsidian bookmark url=<url>                     # bookmark a URL

Bases

obsidian bases                                          # list .base files
obsidian base:query path=<path> format=json             # query a base
obsidian base:query path=<path> view=<name> format=json # query specific view
obsidian base:views path=<path>                         # list views in a base
obsidian base:create path=<path> name=<name>            # create item in a base

Templates

obsidian templates                        # list available templates
obsidian template:read name=<name>        # read template source
obsidian template:read name=<name> resolve # render with variables filled
obsidian template:insert name=<name>      # insert template into active file

History

obsidian history path=<path>                    # list file history versions
obsidian history:list                            # list files with history
obsidian history:read path=<path> version=1     # read a history version
obsidian history:restore path=<path> version=<n> # restore a history version

Commands

obsidian commands                        # list all available command IDs
obsidian commands filter=<prefix>        # filter by ID prefix
obsidian command id=<command-id>         # execute an Obsidian command

Vaults

obsidian vaults                          # list known vaults
obsidian vaults verbose                  # include vault paths

Sync

obsidian sync:status                     # show sync status
obsidian sync on                         # resume sync
obsidian sync off                        # pause sync

Safety Rules

Never run without explicit user request:

• eval — arbitrary code execution
• delete permanent — bypasses trash
• plugin:install / plugin:uninstall — modifies plugin state
• dev:cdp — Chrome DevTools protocol access
• command id=... — arbitrary command execution
• history:restore — overwrites current file content

Prefer safe patterns:

• Use append / prepend over full file overwrite
• create without overwrite flag is safe (won't replace existing files)
• Confirm with user before bulk property changes, file moves, or deletes

Diagnostics

obsidian vault                   # confirm CLI connection — returns vault name, path, file count
obsidian version                 # show CLI version (e.g. "1.12.2 (installer 1.11.4)")

Error Handling

Symptom	Likely cause	Action
obsidian version fails	CLI not installed or not on PATH	Fall back to file tools
Command hangs or times out	Obsidian app not running, or Electron IPC deadlock	Start Obsidian or use file tools. Always use timeout wrapper
CLI ignores commands after relaunch (macOS)	IPC registration lost on quit+relaunch	Toggle CLI off/on in Settings → General → CLI → Register
"Unknown command"	CLI version too old	Run obsidian help to check available commands
"may require a plugin"	Core plugin disabled	Enable the plugin in Obsidian settings
Empty results from search/tags	Vault index not ready	Wait a moment, retry, or use Grep as fallback

General fallback: if CLI is unavailable, use Read/Write/Edit/Grep/Glob for file operations. The CLI requires the Obsidian desktop app to be running.