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

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

Daily Notes

obsidian daily                          # open today's daily note
obsidian daily:read                     # read daily note content
obsidian daily:append content="<text>"  # append to daily note
obsidian daily:prepend content="<text>" # prepend to daily note

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 query="<text>" format=json matches      # structured JSON with line numbers (preferred)
obsidian search query="<text>" matches                  # text format with matching lines

Tip: format=json matches returns [{"file":"path","matches":[{"line":N,"text":"..."}]}] — use this for programmatic search.

Tags & Tasks

obsidian tags all counts                            # list ALL vault tags with counts
obsidian tags all counts sort=count                 # sorted by frequency
obsidian tag name=<tag>                             # files with specific tag
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 task ref="<path>:<line>" toggle            # toggle task status
obsidian task ref="<path>:<line>" done              # mark done

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 orphans                        # files with no incoming links
obsidian deadends                       # files with no outgoing links

Structure

obsidian files folder=<path> ext=md     # list files in folder
obsidian folders                        # list all folders
obsidian outline path=<path>            # heading structure of file

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

Templates

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

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

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.1 (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	Start Obsidian or use file tools
"Unknown command"	CLI version too old	Run `obsidian help` to check available commands
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.

obsidian-cli