obsidian-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Obsidian CLI — Agent Reference

Obsidian CLI — Agent参考文档

When to Use CLI vs File Tools

何时使用CLI vs 文件工具

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.

使用CLI的场景：当你需要Obsidian的索引或应用功能时，包括：搜索、backlinks、链接、tags、tasks、properties、bases、模板、大纲、orphans、未解析链接

使用文件工具（读取/写入/编辑/Grep/Glob）的场景：简单的文件读写、批量文本替换、跨文件Grep搜索 — 无需依赖Obsidian应用

经验法则：如果Obsidian的索引能带来价值，就使用CLI；如果只是纯文本操作，就使用文件工具。

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

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

Vault定位：将
```
vault="My Vault"
```
作为第一个参数，或在vault目录内运行命令
文件定位：
```
path=exact/path.md
```
（相对于vault的路径） vs
```
file=name
```
（链接式解析）
参数：
```
key=value
```
— 包含空格的值需加引号：
```
name="My Note"
```
标志：布尔开关，无需
```
=
```
— 例如
```
silent
```
、
```
overwrite
```
、
```
counts
```
、
```
total
```
多行内容：在内容字符串中用
```
\n
```
表示换行，
```
\t
```
表示制表符
结构化输出：
```
format=json
```
（搜索、base:query命令），
```
format=tsv
```
（properties、tags命令）
剪贴板：追加
```
--copy
```
参数以复制输出结果

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.

obsidian read path=<path>                                    # 读取文件内容
obsidian append path=<path> content="<text>"                 # 向文件追加内容
obsidian prepend path=<path> content="<text>"                # 在前置元数据后插入内容
obsidian create name=<name> content="<text>" silent          # 创建文件（安全模式 — 不会覆盖现有文件）
obsidian create name=<name> template=<template> overwrite silent  # 基于模板创建文件
obsidian move path=<from> to=<to>                            # 移动/重命名文件
obsidian delete path=<path>                                  # 将文件移至系统回收站（安全操作）

注意事项：

不带
```
silent
```
参数的
```
create
```
命令会在Obsidian界面中打开文件 — 在Agent操作中务必添加
```
silent
```
参数。
```
create
```
命令不会自动创建目录 — 如果父文件夹不存在，需先通过Bash运行
```
mkdir -p
```
命令。
使用
```
template=
```
参数的
```
create
```
命令可能会将文件放置在模板配置的文件夹中，忽略
```
path=
```
参数。创建后请通过
```
search
```
或
```
files
```
命令验证实际路径。

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

obsidian daily                          # 打开今日的每日笔记
obsidian daily:read                     # 读取每日笔记内容
obsidian daily:append content="<text>"  # 向每日笔记追加内容
obsidian daily:prepend content="<text>" # 向每日笔记开头插入内容

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)

obsidian property:set name=<key> value=<val> path=<path>              # 设置属性
obsidian property:set name=<key> value=<val> type=<type> path=<path>  # 显式指定类型设置属性
obsidian property:read name=<key> path=<path>                         # 读取单个属性
obsidian property:remove name=<key> path=<path>                       # 删除属性
obsidian properties path=<path>                                       # 列出所有属性
obsidian properties path=<path> format=tsv                            # 以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.

obsidian search query="<text>"                          # 搜索vault（返回文件路径）
obsidian search query="<text>" path=<folder> limit=10   # 限定文件夹的搜索
obsidian search query="<text>" format=json              # 返回路径的JSON数组
obsidian search query="<text>" format=json matches      # 包含行号的结构化JSON（推荐使用）
obsidian search query="<text>" matches                  # 包含匹配行的文本格式

提示：

format=json matches

[{"file":"path","matches":[{"line":N,"text":"..."}]}]

— 适合程序化搜索场景。

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.

obsidian tags all counts                            # 列出vault中所有标签及计数
obsidian tags all counts sort=count                 # 按使用频率排序标签
obsidian tag name=<tag>                             # 列出包含指定标签的文件
obsidian tasks all todo                              # 全vault范围内的未完成任务
obsidian tasks all done                              # 全vault范围内的已完成任务
obsidian tasks daily                                 # 每日笔记中的任务
obsidian tasks path=<path>                           # 指定文件/文件夹中的任务
obsidian task ref="<path>:<line>" toggle            # 切换任务状态
obsidian task ref="<path>:<line>" done              # 标记任务为完成

注意：不带

all

参数的

tags

命令仅列出当前/指定文件的标签。注意：不带作用域（

all

、

daily

、

path=

）的

tasks

命令默认返回当前文件的任务 — 如需全vault结果，请使用

tasks all

。

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

obsidian backlinks path=<path>          # 文件的入站链接
obsidian backlinks path=<path> counts   # 带计数的入站链接
obsidian links path=<path>              # 文件的出站链接
obsidian unresolved                     # 失效/未解析的链接
obsidian orphans                        # 无入站链接的文件
obsidian deadends                       # 无出站链接的文件

Structure

结构

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

obsidian files folder=<path> ext=md     # 列出文件夹中的文件
obsidian folders                        # 列出所有文件夹
obsidian outline path=<path>            # 文件的标题结构

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 bases                                          # 列出所有.base文件
obsidian base:query path=<path> format=json             # 查询base文件
obsidian base:query path=<path> view=<name> format=json # 查询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 templates                        # 列出可用模板
obsidian template:read name=<name>        # 读取模板源内容
obsidian template:read name=<name> resolve # 填充变量后渲染模板

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

未经用户明确请求，禁止执行以下操作：

```
eval
```
— 任意代码执行
```
delete permanent
```
— 绕过回收站直接删除
```
plugin:install
```
/
```
plugin:uninstall
```
— 修改插件状态
```
dev:cdp
```
— 访问Chrome DevTools协议

优先使用安全操作模式：

使用
```
append
```
/
```
prepend
```
而非覆盖整个文件
不带
```
overwrite
```
标志的
```
create
```
命令是安全的（不会替换现有文件）
在执行批量属性修改、文件移动或删除操作前，需获得用户确认

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)")

obsidian vault                   # 验证CLI连接 — 返回vault名称、路径、文件数量
obsidian version                 # 显示CLI版本（例如："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 version` 执行失败	CLI未安装或未添加至PATH	退而使用文件工具
命令挂起或超时	Obsidian应用未运行	启动Obsidian或使用文件工具
提示"Unknown command"	CLI版本过旧	运行 `obsidian help` 查看可用命令
搜索/标签命令返回空结果	Vault索引未准备就绪	等待片刻后重试，或使用Grep作为替代方案

通用 fallback 方案：如果CLI不可用，使用读取/写入/编辑/Grep/Glob进行文件操作。CLI需要Obsidian桌面版应用处于运行状态。