Obsidian 终于有命令行了：v1.12 CLI 完整技术解析

这件事社区要了将近五年。

Obsidian 论坛上"支持 CLI"的功能请求帖从 2020 年就开始有人顶，每隔几个月就有人来评论"还没有吗"。
2026 年 2 月 10 日，v1.12.0 Early Access 版本悄悄附上了一行更新日志：Added a command line interface。

没有大张旗鼓，但开发者社区的反应不小——尤其是在做 AI Agent 的那批人。

1. 它能干什么

用一句话概括：让任何外部程序都能操作你的 Obsidian vault，不需要打开 GUI，不需要写插件。

支持两种使用模式：

1.1. 单命令模式

在终端里直接执行，适合脚本和自动化：

obsidian create name="会议记录 2026-02-20" template=Meeting
obsidian append file="会议记录 2026-02-20" content="- 决议：下周提交方案"
obsidian search query="AI Agent" format=json

1.2. 交互式 TUI 模式

直接输入 obsidian 无参数启动，进入一个带有自动补全（Tab）、命令历史（↑↓）、反向搜索（Ctrl+R）的终端界面。
适合探索和临时操作，也意味着可以通过 SSH 在远程机器上操作 vault。

2. 命令体系：100+ 个命令，按域分组

Obsidian CLI 的命令按功能域组织，覆盖了 vault 的几乎所有操作层面。

2.1. 文件操作

最核心的一组，增删改查全覆盖：

obsidian files folder=Notes ext=md total   # 列出 Notes 文件夹下所有 md 文件并统计数量
obsidian create name="新笔记" template=Blog # 用模板创建文件
obsidian read file=Recipe                   # 读取文件（支持 wiki 链接格式）
obsidian read path="Cooking/Recipe.md"      # 或用精确路径
obsidian append file=Recipe content="- Add salt\n- Stir"
obsidian prepend file=Recipe content="# 更新版"  # 在 frontmatter 之后插入
obsidian move file=OldNote to=Archive/      # 移动文件
obsidian delete file=OldNote permanent      # 永久删除（不进回收站）

文件定位支持两种方式：file= 走 wiki 链接解析逻辑（同名优先当前文件夹），path= 走 vault 根目录的精确路径。

2.2. 属性操作

直接读写 frontmatter 字段：

obsidian properties file=Article           # 列出所有属性
obsidian property:set file=Article key=status value=done
obsidian property:remove file=Article key=draft

这对 AI 写笔记时维护元数据很有用——它能精确操作单个字段，而不是整体重写文件。

2.3. 搜索

obsidian search query="机器学习"                    # 全文搜索
obsidian search query="tag:#project" format=json   # 结构化输出
obsidian search query=term --copy                   # 结果复制到剪贴板

v1.12.2 把原来的 search 命令拆成了 search（返回结果）和 search:context（返回结果+上下文行），方便 AI 工具判断相关性。

2.4. 链接与图谱分析

obsidian backlinks file=概念笔记     # 查看反向链接
obsidian links file=概念笔记          # 查看出链
obsidian orphans                      # 找所有孤立笔记（无链接）
obsidian unresolved                   # 找所有悬空链接

对维护笔记库健康度很实用。

2.5. Daily Notes 操作

obsidian daily                         # 打开今天的日记
obsidian daily:append content="- [ ] 完成报告"  # 追加任务
obsidian daily:prepend content="今日目标：..."
obsidian daily:path                    # 返回今天日记的预期路径（v1.12.2 新增）

daily:path 这个命令专门为脚本设计——你可以在 shell 里获取到今天日记的路径，再用 cat 或其他工具继续处理。

2.6. Bases 数据库视图

obsidian bases                         # 列出所有 base 文件
obsidian base:query file=Projects format=json  # 查询结果以 JSON 返回
obsidian base:query file=Projects format=csv   # 或 CSV

Bases 是 Obsidian 内置的类数据库功能。
CLI 能查询 Bases 视图并以结构化格式输出，这意味着你可以把 Obsidian 当一个轻量级数据库来用，外部脚本读取结果做进一步处理。

2.7. 版本历史与恢复

obsidian history file=Recipe           # 查看文件版本列表
obsidian history:read file=Recipe version=2   # 读取某个历史版本
obsidian history:restore file=Recipe version=2  # 恢复到某个版本

2.8. Sync 状态

obsidian sync:status                    # 查看同步状态
obsidian sync:history                   # 同步历史
obsidian sync:restore                   # 从云端恢复

2.9. Publish 操作

obsidian publish:list                   # 列出已发布笔记
obsidian publish:add file=BlogPost       # 发布
obsidian publish:remove file=BlogPost   # 取消发布

3. 开发者向的高级命令

这部分是亮点，也是为什么 AI Agent 方向的开发者特别兴奋的原因。

obsidian eval code="app.vault.getFiles().length"  # 在 app 上下文里执行 JS
obsidian dev:screenshot path=snapshot.png          # 截图（返回 base64 PNG）
obsidian dev:console limit=50 level=error         # 查看控制台报错
obsidian dev:css selector=".markdown-preview-view" # 检查 CSS
obsidian dev:dom selector=".workspace-leaf" total   # 查询 DOM 元素
obsidian dev:debug on                              # 接入 Chrome DevTools 协议

eval 命令可以直接在 Obsidian 的 app 上下文里执行任意 JavaScript，拿到插件 API 的完整能力。
这实际上意味着：任何通过插件 API 能做的事，现在都可以通过 CLI 脚本来做，不需要写一个完整的插件。

4. 输出格式：为脚本集成设计

多数命令支持 format= 参数切换输出格式：

格式 用途
json 结构化，适合被其他程序解析
csv / tsv 表格，导入 Excel 或数据库
md Markdown 列表
yaml 属性默认格式
paths 只返回文件路径
tree 层级结构（outline 和 workspace 默认）

配合 jq、Python、bash pipeline，就能把 Obsidian 接进任何数据处理工作流。

5. 多 vault 和 vault 定向

obsidian vaults                         # 列出所有已知 vault
obsidian vault=工作笔记 search query=项目  # 在指定 vault 里搜索
obsidian vault:open 工作笔记             # 切换到指定 vault

如果当前工作目录本身就是一个 vault，不传 vault= 参数会自动识别。

6. 对 AI Agent 开发者意味着什么

这才是 v1.12 CLI 真正让技术圈兴奋的地方。

在此之前，想让 AI Agent 操作 Obsidian vault，选项很少：

  • 要么装 Local REST API 插件（需要一直开着 Obsidian + 插件，且功能有限）
  • 要么直接操作底层 markdown 文件（绕过 Obsidian 的链接解析、模板系统和属性索引）
  • 要么写一个 Obsidian 插件（需要熟悉插件 API，打包、测试、上架都是摩擦）

现在，一个 AI Agent 可以：

# 搜索相关笔记
obsidian search query="用户需求" format=json | python3 parse.py

# 读取内容
obsidian read file="产品规格" format=md

# 追加 AI 生成的内容
obsidian append file="产品规格" content="$AI_OUTPUT"

# 更新属性
obsidian property:set file="产品规格" key=ai_reviewed value=true

# 追加到今日日记
obsidian daily:append content="AI 完成了产品规格审查"

整个链路不需要 GUI 在场，不需要模拟点击，不需要 OCR，直接走系统调用。
对于跑在服务器或定时任务里的 Agent 来说，这是本质性的改变。

7. 当前限制

使用前需要了解几个约束：

  • 需要 Catalyst 授权（25 美元一次性），目前是 Early Access，稳定版会对所有用户免费开放
  • 需要 Obsidian 应用保持运行，CLI 是客户端，通过 IPC 和 Obsidian 进程通信，不是独立的 vault 操作工具
  • Windows 需要额外文件：Obsidian.com 这个终端重定向器，目前只在 Discord 的 insider 频道分发
  • v1.12.0/1.12.2 仍有一些 bug 正在修复，比如 Unicode 字符支持、Windows 上带冒号的参数处理等

8. 写在最后

Obsidian CLI 不是一个小功能。
它把 Obsidian 从一个"需要人坐在键盘前操作"的 GUI 工具，变成了一个可以被脚本、自动化流程和 AI Agent 调用的可编程知识库。

这件事的深远影响可能需要几个月才会完全显现——等社区里的人把它接进各种工作流、写出各种 recipes，那时候才会真正知道它能做什么。

目前官方文档在 help.obsidian.md/cli，Catalyst 许可在 obsidian.md/pricing 可购买。