Obsidian CLI

Obsidian 作为广受好评的开源 Markdown 笔记工具，近期推出了全新的命令行工具——Obsidian CLI。这款工具能让你直接从终端控制 Obsidian，轻松实现脚本编写、操作自动化以及与外部工具的集成，尤其适配 AI 开发场景的需求（目前该功能仅限付费用户提前体验）。

简单来说，Obsidian CLI 就是 Obsidian 的命令行界面，你在 Obsidian 图形界面中能完成的所有操作，都可以通过终端命令实现。不仅如此，它还内置了专属的开发者命令，支持访问开发者工具、检查元素、截图、重载插件等，覆盖日常使用与开发调试全场景。

使用前提：版本与权限要求

Obsidian CLI 并非所有用户都能立即使用，需满足以下条件：

1. 版本要求：需升级到 Obsidian 1.12 或更高版本（需先更新 Obsidian 安装程序至 1.11.7 版本，再升级到 1.12.x 早期访问版本）；
2. 权限要求：目前处于早期访问阶段，仅向拥有 Catalyst 许可证的付费用户开放；
3. 注意事项：早期访问阶段的命令语法、功能可能会调整，建议先小范围测试使用。

安装启用：三步完成配置

升级到指定版本后，按以下步骤启用 Obsidian CLI：

1. 打开 Obsidian，进入「设置 → 通用」；
2. 找到并开启「命令行界面」选项；
3. 按照页面提示完成 Obsidian CLI 的注册流程。

Windows 系统额外操作：需运行专属的 .com 文件（Catalyst 成员可在 Obsidian 官方 Discord 社群获取）；若遇到启用失败，可参考官方「故障排除」文档排查问题。

快速上手：两种使用方式

Obsidian CLI 的核心要求是：使用时 Obsidian 应用需处于运行状态（若未运行，首次执行命令会自动启动应用）。它支持两种使用模式，适配不同操作习惯：

1. 直接运行单条命令

无需打开终端界面，直接执行单个指令，适合快速完成单次操作：

# 示例：查看所有可用命令的帮助文档
obsidian help

2. 进入终端用户界面（TUI）

输入 obsidian 即可进入交互式 TUI，后续命令无需重复输入 obsidian 前缀，支持自动补全、命令历史记录、反向搜索（Ctrl+R 触发）等便捷功能，所有快捷键可参考官方「键盘快捷键」说明：

# 第一步：打开 TUI
obsidian
# 第二步：在 TUI 中直接输入命令（无需前缀）
help

实用示例：日常使用+开发者调试

Obsidian CLI 的命令覆盖日常笔记管理与开发者调试，以下是高频使用场景示例：

1. 日常笔记操作（小白也能快速上手）

# 打开今日的每日笔记
obsidian daily

# 给每日笔记追加待办任务
obsidian daily:append content="- [ ] 买菜"

# 搜索知识库中包含“会议笔记”的内容
obsidian search query="会议笔记"

# 读取当前打开的活动文件内容
obsidian read

# 列出每日笔记中的所有待办任务
obsidian tasks daily

# 基于“Travel”模板创建名为“巴黎之旅”的新笔记
obsidian create name="巴黎之旅" template=Travel

# 统计知识库中所有标签的出现次数
obsidian tags counts

# 对比 README 文件第1版和第3版的差异
obsidian diff file=README from=1 to=3

2. 开发者专用（插件/主题开发调试）

专为插件、主题开发者设计的命令，支持自动化测试、调试，适配 AI 代理式编码工具：

# 打开 Obsidian 开发者工具
obsidian dev:open

# 重载正在开发的“my-plugin”社区插件
obsidian plugin:reload id=my-plugin

# 将应用界面截图并保存为 screenshot.png
obsidian dev:screenshot path=screenshot.png

# 在应用控制台执行 JS 代码（示例：查看知识库文件数量）
obsidian dev:eval code="app.vault.getFiles().length"

核心用法：参数、标志与路径指定

想要灵活使用 Obsidian CLI，需掌握以下基础规则：

1. 参数与标志

• 参数：需指定值，格式为 parameter=value，值含空格时用引号包裹，必填参数会标注「required」：

  # 创建名为“Note”、内容为“Hello world”的新笔记
  obsidian create name=Note content="Hello world"
  

• 标志：无值的布尔开关，添加即启用（如 silent 静默执行、overwrite 覆盖文件）：

  # 静默创建笔记并覆盖已有同名文件
  obsidian create name=Note content="Hello" silent overwrite
  

• 多行内容：用 \n 表示换行、\t 表示制表符：

  # 创建包含标题和正文的笔记
  obsidian create name=Note content="# 标题\n\n正文"
  

2. 指定知识库

• 若终端当前目录是知识库文件夹，默认使用该知识库；否则使用当前活动知识库；
• 用 vault=<name> 手动指定知识库（需放在命令最前面）：

  # 使用“Notes”知识库打开每日笔记
  obsidian vault=Notes daily
  # 使用带空格的“My Vault”知识库搜索内容
  obsidian vault="My Vault" search query="test"
  

• TUI 中切换知识库：输入 vault:open <name>。

3. 指定文件

许多命令支持 file 或 path 参数指定文件，未指定时默认使用活动文件：

• file=<name>：按文件名匹配（无需完整路径/扩展名，同 wikilinks 解析规则）；
• path=<path>：需填写从知识库根目录开始的完整路径（如 folder/note.md）。

  # 两种方式均能读取“Templates/Recipe.md”（唯一同名时）
  obsidian read file=Recipe
  obsidian read path="Templates/Recipe.md"
  

4. 复制命令输出

在任意命令后添加 --copy，可将输出结果直接复制到剪贴板：

# 读取文件并复制内容到剪贴板
read --copy
# 搜索“TODO”并复制结果到剪贴板
search query="TODO" --copy