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) vsfile=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:
\nfor newline,\tfor tab in content strings - Structured output:
format=json(search, base:query),format=tsv(properties, tags) - Clipboard: append
--copyto 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:
createwithoutsilentopens the file in Obsidian's UI — always addsilentduring agent operations.createdoesn't auto-create directories — usemkdir -pvia Bash first if the parent folder doesn't exist.createwithtemplate=may place the file in the template's configured folder, ignoringpath=. Verify the actual path withsearchorfilesafter 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 noteProperties (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 linesTip: 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 doneNote: 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 linksStructure
obsidian files folder=<path> ext=md # list files in folder
obsidian folders # list all folders
obsidian outline path=<path> # heading structure of fileBases
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 viewTemplates
obsidian templates # list available templates
obsidian template:read name=<name> # read template source
obsidian template:read name=<name> resolve # render with variables filledSafety Rules
Never run without explicit user request:
eval— arbitrary code executiondelete permanent— bypasses trashplugin:install/plugin:uninstall— modifies plugin statedev:cdp— Chrome DevTools protocol access
Prefer safe patterns:
- Use
append/prependover full file overwrite createwithoutoverwriteflag 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.