obsidian-cli（Obsidian CLI 知识库）

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

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.