我用 [[Obsidian]] 管理笔记库已经好几年了，日记、技术笔记、读书摘录、项目文档全部塞在里面。但有一个事情一直让我觉得别扭——每次想在终端里快速记个想法，或者用脚本批量处理笔记的时候，都得绕一大圈。直接改 Markdown 文件虽然可以，但双链不会更新，属性不会同步到索引，改完还得回到 Obsidian 里手动刷新才能看到变化。这种”从后门溜进去”的感觉总是让人不太放心。
2026 年 2 月 27 日，[[Obsidian]] 1.12.4 正式发布，带来了官方的命令行界面（CLI）。这一次，前门终于打开了。
Obsidian CLI 是什么
Obsidian CLI 是内置在 Obsidian 桌面应用中的命令行工具，不需要单独安装，也不需要付费的 Catalyst 许可证（正式版 1.12.4 对所有用户免费开放）。它在 2026 年 2 月 10 日的 1.12.0 版本中作为 Early Access 功能首次亮相，随后在 2 月 27 日的 1.12.4 中正式面向所有用户开放。
理解 Obsidian CLI 有一个关键的设计原则：它是 Obsidian 应用的「遥控器」，而不是一个独立的无头工具。当你在终端执行一条 CLI 命令时，这条命令会通过 Obsidian 的内部 API 传递给正在运行的 Obsidian 实例来执行。如果 Obsidian 没有在运行，CLI 会自动启动它。
这个设计带来了一个非常重要的好处：通过 CLI 做的所有操作，和你在 Obsidian 图形界面里做的效果完全一致。移动文件时双链会自动更新，修改属性时索引会立刻同步，创建笔记时模板会正确应用。过去那些直接操作 Markdown 文件带来的链接失效、索引不同步的问题，在 CLI 这里根本不存在。
安装和配置
整个设置过程不到五分钟。
首先确保你的 Obsidian 已经更新到 1.12.4 或更高版本。打开 Obsidian，进入 Settings → General → Command line interface，开启这个选项，然后点击「Register CLI」。
在 macOS 上，需要把 Obsidian 的可执行文件路径添加到 PATH 中。编辑 ~/.zshrc，加入一行：
export PATH="$PATH:/Applications/Obsidian.app/Contents/MacOS"
保存后执行 source ~/.zshrc，然后在终端里输入：
obsidian version
如果能看到版本号输出，就说明配置成功了。Windows 和 Linux 用户需要把对应的二进制路径添加到系统环境变量中，具体路径可以参考官方文档。
命令体系概览
Obsidian CLI 提供了超过一百条命令，覆盖了 Obsidian 中几乎所有的操作。这些命令按照功能分成了若干大类：
文件操作
这是最基础也是最常用的一类命令，涵盖了笔记的增删改查。
# 查看 Vault 的文件夹结构
obsidian folders
# 列出某个文件夹下的所有文件
obsidian files folder="Zettelkasten"
# 读取一篇笔记的内容
obsidian read file="Zettelkasten/日本株主優待"
# 创建一篇新笔记
obsidian create name="Draft/新想法" content="# 今天的灵感"
# 在笔记末尾追加内容
obsidian append file="Draft/新想法" content="\n\n刚刚看到一个有意思的项目"
# 移动笔记（自动更新所有双链）
obsidian move file="Draft/新想法" to="Zettelkasten/新想法"
# 删除笔记
obsidian delete file="Draft/过期文档"
其中 move 命令是最让我兴奋的，因为它会自动重写所有引用了这个文件的双链。过去用脚本移动文件的时候，最头疼的就是到处修链接，现在一条命令就搞定了。
属性管理
frontmatter 属性的批量操作在过去需要写正则表达式或者用插件，现在直接就能在命令行里完成。
# 查看一篇笔记的所有属性
obsidian properties file="Zettelkasten/Obsidian"
# 设置属性
obsidian property:set file="Draft/新想法" property="category" value="产品体验"
# 删除属性
obsidian property:remove file="Draft/新想法" property="tagline"
# 读取特定属性值
obsidian property:read file="Draft/新想法" property="tags"
搜索
CLI 的搜索功能分为两种模式，一种是路径搜索，一种是带上下文的全文搜索。
# 搜索文件路径
obsidian search query="CLI"
# 带上下文的全文搜索（类似 grep）
obsidian search:context query="Obsidian CLI" limit=10
标签管理
标签的批量重命名是一个杀手级功能。想象一下你有几百篇笔记用了 #日本生活 这个标签，现在想改成 #japan-life，一条命令就能完成全库替换。
# 列出所有标签
obsidian tags
# 查看某个标签下的所有文件
obsidian tag tag="#obsidian"
# 批量重命名标签
obsidian tags:rename from="#旧标签" to="#新标签"
链接分析
这组命令帮助你了解知识库的链接结构和健康状况。
# 查看某篇笔记的反向链接
obsidian backlinks file="Zettelkasten/Obsidian"
# 查看某篇笔记的外部链接
obsidian links file="Zettelkasten/Obsidian"
# 找出所有未解析的链接（指向不存在的笔记）
obsidian unresolved
# 找出所有孤立笔记（没有任何链接指向它们）
obsidian orphans
# 找出所有死胡同笔记（没有链接指出去的笔记）
obsidian deadends
日记
如果你有写日记的习惯，这组命令会特别顺手。
# 打开今天的日记
obsidian daily
# 在日记末尾追加内容
obsidian daily:append content="- [ ] 整理 CLI 学习笔记"
# 读取今天的日记内容
obsidian daily:read
# 获取今天日记的文件路径
obsidian daily:path
其他命令
除了上面这些，CLI 还支持插件管理、模板操作、主题切换、Bases 查询、书签管理、Publish 和 Sync 操作、工作区管理等等。甚至还有一组开发者命令，可以执行 JavaScript 代码、截图、打开开发者工具。
# 列出所有已安装的插件及版本
obsidian plugins
# 启用/禁用插件
obsidian plugin:enable plugin="dataview"
obsidian plugin:disable plugin="dataview"
# 应用模板
obsidian template:insert file="Draft/新想法" template="Jekyll Template"
# 执行任意 JavaScript
obsidian eval code="app.vault.getFiles().length"
# 获取笔记的字数统计
obsidian wordcount file="Draft/新想法"
命令语法
Obsidian CLI 的命令语法很简洁：
obsidian <command> [param=value] [flag]
参数使用 key=value 的格式，标志（flag）直接写名字，不需要 -- 前缀。唯一的例外是 --copy（将输出复制到剪贴板），它需要 -- 前缀。
如果你有多个 Vault，可以用 vault 参数指定操作哪一个：
obsidian vault="我的知识库" search query="TODO"
TUI 模式
除了直接在命令行输入命令，CLI 还内置了一个 TUI（Terminal User Interface）模式。直接输入 obsidian 不带任何参数就会进入 TUI，它提供了一个类似图形界面的交互体验，可以用键盘浏览文件、搜索内容、查看属性，对于不想记命令的人来说是一个很友好的入口。
实际使用场景
命令本身并不复杂，关键在于怎么把它们组合起来解决实际问题。下面分享几个我觉得特别有价值的场景。
快速捕获想法
在终端里工作的时候，突然冒出一个想法，不想切换到 Obsidian 打断当前的工作流。一条命令就能把想法追加到指定的笔记里：
obsidian daily:append content="- [ ] 研究一下 Obsidian Headless 的用法"
甚至可以把它包装成一个 shell 函数，放到 .zshrc 里：
note() {
obsidian daily:append content="- $*"
}
之后只需要输入 note 研究一下 Obsidian Headless 的用法 就行了。
知识库健康检查
可以写一个简单的脚本，定期检查知识库的状态：
#!/bin/bash
echo "=== Vault 健康报告 ==="
echo "文件总数: $(obsidian eval code='app.vault.getFiles().length')"
echo ""
echo "未解析链接:"
obsidian unresolved
echo ""
echo "孤立笔记:"
obsidian orphans
echo ""
echo "死胡同笔记:"
obsidian deadends
把这个脚本配合 cron 定期运行，每周一的早晨自动把报告追加到日记里：
# crontab -e
0 9 * * 1 obsidian daily:append content="$(bash ~/scripts/vault-health.sh)"
批量属性处理
假如你有一批笔记需要统一添加某个属性，CLI 配合简单的脚本就能完成：
# 给所有带有 #obsidian 标签的笔记添加 category 属性
obsidian tag tag="#obsidian" | while read file; do
obsidian property:set file="$file" property="category" value="工具"
done
与 AI 工具集成
这可能是 CLI 最有想象力的使用方向。通过 CLI，AI 工具可以直接读写你的知识库，而不需要通过复杂的 MCP 插件或者 REST API。
比如让 AI 搜索你的笔记、提取相关内容、生成摘要，然后写回一篇新的笔记——整个流程可以用 CLI 命令串起来。社区里已经有人在用 [[Claude]] Code 配合 Obsidian CLI 做笔记的批量格式化、内容整理，甚至自动化的知识图谱维护。
外部数据导入
定期把外部数据源的内容导入到 Obsidian 中，比如天气信息、财务数据、RSS 摘要等：
# 把今天的天气追加到日记
weather=$(curl -s "wttr.in/Tokyo?format=3")
obsidian daily:append content="\n## 天气\n$weather"
Obsidian Headless：无头客户端
除了 CLI 之外，Obsidian 团队在同一天还发布了 [[Obsidian]] Headless，这是一个独立的 Node.js 工具，用于在没有桌面应用的环境下执行 Obsidian Sync 和 Obsidian Publish 操作。
npm install -g obsidian-headless
通过 ob 命令可以登录账号、同步 Vault、管理 Publish 站点。它最大的用途是在服务器环境中实现自动化同步和发布，比如在 CI/CD 流程中自动发布笔记到 Obsidian Publish 站点。
需要注意的是，Headless 和 CLI 是两个不同的工具。CLI 是 Obsidian 桌面应用的遥控器，需要图形界面环境；Headless 则是一个独立的命令行程序，专注于 Sync 和 Publish 服务，不需要桌面环境。
已知限制
Obsidian CLI 虽然强大，但也有一些需要注意的限制：
Obsidian 必须在运行中。CLI 是遥控器，不是独立工具。虽然执行命令时会自动启动 Obsidian，但这意味着它依赖桌面环境，无法在纯命令行的服务器上使用。
顺序执行速度有限。每条命令都要和 Obsidian 应用通信，如果需要批量处理几千个文件，逐条执行 CLI 命令会比较慢。这种场景下直接用 Python 脚本操作文件可能更高效（当然就失去了链接自动更新的好处）。
没有简单的撤销机制。通过 CLI 执行的操作和在 GUI 里执行效果一样，但 CLI 没有提供批量撤销的功能。批量操作之前建议先做好备份，或者配合 Git 进行版本控制。
最后
Obsidian CLI 的出现标志着 Obsidian 从一个「好用的编辑器」进化成了一个「可编程的知识操作系统」。对于习惯在终端工作的人来说，这意味着可以在不离开终端的情况下完成笔记的创建、搜索和管理；对于喜欢自动化的人来说，这打开了一扇通往无限可能的大门——定时任务、数据导入、AI 集成，所有这些都可以通过标准的命令行工具链来实现。
最让我感到欣慰的是 Obsidian 团队的设计选择：让 CLI 走 Obsidian 的内部 API，而不是简单地操作文件系统。这保证了通过 CLI 做的每一个操作都和在 GUI 里做的一样安全可靠，链接完整性、索引同步这些关键问题都得到了妥善处理。虽然这个设计意味着必须运行 Obsidian 桌面应用，但对于绝大多数用户来说，这是一个合理的取舍。
如果你还没有升级到 1.12.4，我建议尽快更新。即使你不打算写什么复杂的自动化脚本，光是 obsidian daily:append 这一条命令——在终端里随手记个想法——就已经值回升级的全部成本了。另外如果搭配上 OpenClaw 来使用的话，效率大增。