obsidian-cli

obsidian-cli — 正确选择 Obsidian 桌面自动化方式

当请求实际上是通过终端或 URI 移交来操控 Obsidian 桌面应用，而不是泛指记笔记时，使用此技能。

obsidian-cli 负责官方 CLI 的启用、单次命令/TUI 的使用、通过 vault= / file= / path= 精确指定目标、执行开发者命令、通过官方 obsidian:// 移交，以及在任务实际上属于无头同步、直接写入文件系统或需要更丰富的插件/API 自动化时，诚实地转向其他方案。

遇到特殊情况或请求范围开始扩展时，请先阅读这些支持文档：

• references/intake-packets-and-route-outs.md
• references/installation-and-troubleshooting.md
• references/vault-and-file-targeting.md
• references/commands-and-developer-tools.md
• references/uri-and-callbacks.md

何时使用此技能

• 用户想要启用或验证官方 Obsidian CLI。
• 任务是在运行中的桌面应用上执行 obsidian 单次命令或使用 TUI。
• 工作流需要通过 vault=、file= 或 path= 明确指定库或笔记。
• 用户想要从 Shell 使用每日笔记、搜索、读取、创建、标签、任务、差异或命令面板工作流。
• 用户正在开发 Obsidian 插件/主题，需要使用 plugin:reload、devtools、dev:screenshot、eval 或 command id=...。
• 其他应用、启动器、快捷方式、浏览器或 Agent 循环需要通过官方 obsidian:// URI 移交或处理回调。

何时不使用此技能

• 主要任务是在没有桌面应用的情况下进行无头 Sync/Publish → 转用 Obsidian Headless，而不是此技能。
• 主要任务是在库路径中编辑通用 Markdown 文件 → 直接写入文件系统可能更简单，也更符合实际情况。
• 主要任务需要超出第一方 CLI/URI 能力范围的外部 CRUD/frontmatter/工作区自动化 → 使用 Local REST API 或 Advanced URI 等插件/API 方案，而不要假装官方 CLI 足以满足需求。
• 用户想要独立于 Obsidian 的 Shell 原生笔记后端 → Joplin Terminal、nb 或 zk 等相关笔记 CLI 更合适。

说明

步骤 1：确定主要自动化方式

在查找命令之前，先规范化请求。

obsidian_automation_intake:
  primary_surface: cli-command | cli-tui | cli-developer | uri-handoff | headless-route-out | filesystem-route-out | plugin-api-route-out
  environment: desktop-local | launcher-shortcut | browser-callback | headless-server | unknown
  target_shape: vault-and-note | command-id | uri-action | sync-service | raw-markdown-write
  plugin_dependencies: none | daily-notes | unique-note-creator | plugin-command | unknown

每次运行只使用一种主要方式：

• cli-command — 针对运行中的应用执行单次终端命令
• cli-tui — 使用带有历史记录/自动补全功能的交互式 obsidian Shell
• cli-developer — 插件/主题/开发命令或命令面板执行
• uri-handoff — 从其他应用通过 obsidian:// 执行打开/新建/每日笔记/搜索/钩子回调
• headless-route-out — 无桌面应用时进行 Sync/Publish
• filesystem-route-out — 相比应用控制，直接写入 Markdown 更符合实际情况
• plugin-api-route-out — 第一方 CLI/URI 无法满足所需的自动化需求

不要在一个回答中混用多种主要方式。

步骤 2：使用 CLI 前确认桌面运行环境

请参阅 references/installation-and-troubleshooting.md。

最低要求：

• 已安装 Obsidian 桌面应用
• 已在 Settings -> General -> Command line interface 中启用 CLI
• 当前官方文档要求安装程序版本为 1.12.7+
• 计算机确实可以访问桌面环境；不要强行在 CI 或无头服务器上使用

快速本地检查：

bash scripts/install.sh

如果未安装桌面应用，或任务明确要求无 GUI，请立即切换到 headless-route-out 或 filesystem-route-out。

第 3 步：确保目标选择具有确定性

使用 references/vault-and-file-targeting.md。

规则：

• 以非默认 vault 为目标时，vault=<name> 或 vault=<id> 必须放在命令之前
• 可能存在同名笔记时，优先使用 path=<exact/path.md>
• 仅当接受维基链接风格的解析时，才使用 file=<name>
• 除非任务明确要求交互操作，否则不要依赖当前活动 vault / 活动文件

示例：

obsidian vault="My Vault" search query="meeting notes"
obsidian vault="My Vault" read path="Projects/Roadmap.md"
obsidian vault=Notes command id=editor:focus-top

第 4 步：选择最小且准确的数据包

使用 references/intake-packets-and-route-outs.md。

默认选择：

• CLI 命令数据包：用于读取、搜索、创建、任务、日常工作等需要关注终端输出的场景
• TUI 数据包：用于交互式探索和历史记录
• 开发者数据包：用于重新加载插件、截图、eval 或命令面板执行
• URI 数据包：用于启动器、快捷方式、浏览器回调和应用交接
• 转出数据包：用于无头同步、原始文件写入或插件/API 级自动化

第 5 步：当应用本身是运行时环境时，使用官方 CLI 流程

使用 references/commands-and-developer-tools.md。

安全的首选命令：

obsidian help
obsidian version

常见的一次性流程：

obsidian daily
obsidian daily:append content="- [ ] Follow up"
obsidian search query="TODO"
obsidian read path="Inbox/Capture.md"
obsidian create name="Trip to Paris" template=Travel
obsidian tags counts
obsidian tasks daily
obsidian diff file=README from=1 to=3

其他工具需要结果时，使用 --copy：

obsidian read path="Inbox/Capture.md" --copy
obsidian search query="launch checklist" --copy

第 6 步：将开发者命令视为独立模式

开发者命令是正式支持的使用场景，但它们具有状态。

obsidian devtools
obsidian plugin:reload id=my-plugin
obsidian dev:screenshot path=screenshot.png
obsidian eval code="app.vault.getFiles().length"
obsidian commands
obsidian command id=workspace:open-settings

当任务涉及插件/主题开发、命令发现或应用状态检查时，使用此模式。

第 7 步：使用官方 URI 流程进行交接和回调

使用 references/uri-and-callbacks.md。

将这些官方 URI 操作保留在入口处：open、new、daily、unique、search、choose-vault、hook-get-address。

示例：

obsidian://open?vault=my%20vault&file=my%20note
obsidian://new?vault=my%20vault&name=my%20note
obsidian://daily?vault=my%20vault
obsidian://search?vault=my%20vault&query=Obsidian
obsidian://hook-get-address?x-success=myapp://x-callback-url

规则：

• 正确进行百分号编码
• path= 优先于 vault 和 file
• paneType=window 仅限桌面端
• daily 需要 Daily notes 插件
• unique 需要 Unique note creator 插件
• 回调支持因端点而异；如果另一个应用必须在 Obsidian 响应后继续执行，优先使用回调

辅助工具：

bash scripts/open-uri.sh 'obsidian://open?vault=my%20vault&file=my%20note'

第 8 步：当请求发生变化时，转到其他方案

明确说明转出方案：

• 不使用桌面应用进行无头同步/发布 → Obsidian Headless
• 将 Markdown 写入磁盘上的 vault 后结束 → 直接写入文件系统
• 需要更丰富的外部 CRUD/frontmatter/工作区控制 → 使用 Local REST API 或 Advanced URI 等插件/API 工作流
• 需要 shell 原生笔记系统，而不是 Obsidian → Joplin Terminal、nb 或 zk

这项技能的提升，来自快速拒绝不适合的任务，而不是假装每种笔记工作流都适用于此处。

输出格式

使用一个精简的数据包：

• 主要界面 — CLI 命令、TUI、开发者模式、URI 交接或转出方案
• 运行时检查 — 桌面端要求、CLI 启用状态、插件前提条件
• 目标选择 — vault 和笔记目标；必要时说明如何确保确定性
• 推荐命令或 URI — 完成任务所需的最小且准确的命令/URI
• 重要限制 — 编码、插件依赖、仅限桌面端的行为或状态性
• 如果实际是其他类型的任务 — 明确说明转出方案及原因

示例

示例 1：验证官方 CLI 注册

输入：我想第一次使用 Obsidian CLI，应该如何启用并确认？

• 使用 bash scripts/install.sh
• 提及 Settings -> General -> Command line interface
• 内容仅限官方桌面 CLI

示例 2：确定性 vault/路径目标

输入：我想在特定 vault 中搜索并读取特定笔记。file 和 path 有什么区别？

• 说明 vault= 必须放在命令之前
• 对比维基链接风格的 file= 与精确的 path=
• 存在歧义时优先使用精确的 path=

示例 3：开发者循环

输入：我想通过 CLI 重新加载正在开发的 Obsidian 插件，并截取屏幕截图。

• 切换到开发者模式
• 提及 plugin:reload 和 dev:screenshot

示例 4：URI 回调工作流

输入：我想通过外部应用中的 obsidian:// 链接打开笔记、创建新笔记，还能使用回调吗？

• 使用官方的 obsidian://open / obsidian://new
• 说明编码以及 x-success / x-error

示例 5：无桌面应用的同步请求

输入：我想只用 CLI 同步，不使用桌面应用。

• 明确引导用户转向 Obsidian Headless
• 说明 Obsidian CLI 控制的是桌面应用，因此这里不适用

最佳实践

1. 先判断是 CLI 命令、URI 移交还是引导转向，不要从列举所有命令类别开始。
2. 优先使用精确的 vault= + path=，以便 Agent 安全、确定地定位目标。
3. 当实际操作由插件命令执行时，使用 commands / command id=...。
4. 如果其他工具需要结果，请使用 --copy 或结构化输出格式。
5. 将 plugin:reload、eval、dev:screenshot 和 devtools 视为具有特权的开发者操作。
6. URI 答复应明确说明编码、插件前置条件以及仅限桌面应用的回调细节。
7. 不要仅仅因为出现了“Obsidian CLI”这一说法，就通过此技能处理无头/服务器任务。
8. 当特定操作系统的注册行为发生变化时，请根据当前官方文档重新核对安装指南。

参考资料

• references/intake-packets-and-route-outs.md
• references/installation-and-troubleshooting.md
• references/vault-and-file-targeting.md
• references/commands-and-developer-tools.md
• references/uri-and-callbacks.md
• scripts/install.sh
• scripts/run-command.sh
• scripts/open-uri.sh
• Obsidian CLI
• Obsidian URI
• Obsidian Headless