obsidian-cli

Obsidian CLI — Agent 参考

何时使用 CLI，何时使用文件工具

需要 Obsidian 的索引或应用功能时使用 CLI： 搜索、反向链接、链接、标签、任务、属性、bases、模板、大纲、孤立笔记、未解析链接

以下情况使用文件工具（Read/Write/Edit/Grep/Glob）： 简单的文件读写、批量文本替换、跨文件 grep——无需依赖应用

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

语法基础

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

• 指定仓库：将 vault="My Vault" 作为第一个参数，或从仓库目录内运行
• 指定文件：path=exact/path.md（相对于仓库）与 file=name（按链接样式解析）
• 参数：key=value——值中包含空格时加引号：name="My Note"
• 标志：布尔开关，不带 =——例如 silent、overwrite、counts、total
• 多行内容：在内容字符串中使用 \n 表示换行，使用 \t 表示制表符
• 结构化输出：format=json（search、base:query），format=tsv（properties、tags）
• 剪贴板：追加 --copy 以复制输出

常用命令

读取与写入

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)

注意事项：

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

每日笔记

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

属性（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 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

提示：format=json matches 会返回 [{"file":"path","matches":[{"line":N,"text":"..."}]}]——可用于程序化搜索。

标签与任务

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

注意：不带 all 的 tags 只会列出当前文件或指定文件的标签。 注意：不带作用范围（all、daily、path=）的 tasks 默认针对当前文件——如需查看整个仓库的结果，请使用 tasks all。

链接与关系图

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

模板

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

安全规则

未经用户明确请求，绝不运行：

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

优先采用安全做法：

• 优先使用 append / prepend，避免完整覆盖文件
• 不带 overwrite 标志的 create 是安全的（不会替换现有文件）
• 批量修改属性、移动文件或删除文件前，先向用户确认

诊断

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 version 失败	未安装 CLI，或 CLI 不在 PATH 中	改用文件工具
命令挂起或超时	Obsidian 应用未运行	启动 Obsidian，或使用文件工具
“Unknown command”	CLI 版本过旧	运行 obsidian help 检查可用命令
搜索或标签结果为空	仓库索引尚未就绪	稍等片刻后重试，或使用 Grep 作为备用方案

通用备用方案：如果 CLI 不可用，请使用 Read/Write/Edit/Grep/Glob 进行文件操作。CLI 需要 Obsidian 桌面应用正在运行。