obsidian-cli

Obsidian CLI

官方 Obsidian CLI（于 2026 年 2 月随 v1.12 发布）可让你通过终端控制 Obsidian 的所有功能。它通过 IPC 与正在运行的 Obsidian 桌面实例通信。

需要查看特定命令组的命令标志、输出格式或子命令时，请阅读 references/command-reference.md。该文档涵盖全部 130 多个命令，并在开头提供了目录。

前置条件

要求	详情
Obsidian Desktop	v1.12.0+
已启用 CLI	设置 → 命令行界面 → 切换为开启
Obsidian 正在运行	CLI 必须在桌面应用运行时才能工作（IPC）

平台说明

• macOS / Linux：在设置中启用 CLI 后，obsidian 二进制文件会自动注册到 PATH 中。
• Windows：需要在 Obsidian.exe 同一目录下放置 Obsidian.com 重定向文件。必须使用普通用户权限运行——管理员终端会导致静默失败。
  • 如果带参数的冒号子命令（property:set、daily:append 等）返回退出码 127，请检查 Obsidian.com 是否与 Obsidian.exe 位于同一目录。如果缺失，说明安装程序已过时——请从 obsidian.md/download 下载最新版本并重新安装。
  • Git Bash / MSYS2 用户：Bash 会将 obsidian 解析为 GUI 程序 Obsidian.exe，而不是 CLI 程序 Obsidian.com，即使存在 Obsidian.com，带冒号和参数的命令仍会以退出码 127 失败。请创建一个包装脚本，参见“故障排除”。
• 无头 Linux：使用 .deb 软件包（不要使用 snap）。在 xvfb 下运行。命令前加上 DISPLAY=:5（或你的 xvfb 显示编号）。如果作为服务运行，请确保设置 PrivateTmp=false。

语法

所有参数均使用 key=value 语法。包含空格的值需要加引号。

obsidian <command> [subcommand] [key=value ...] [flags]

多个 Vault

将特定 Vault 设为第一个参数，即可指定目标 Vault：

obsidian "My Vault" daily:read
obsidian "Work Notes" search query="meeting"

如果省略，CLI 会以最近活动的 Vault 为目标。

命令概览

CLI 提供 130+ 个命令，分为以下组：

组	主要命令	用途
files	read, create, append, prepend, move, rename, delete, files, folders, file, random	笔记的 CRUD 操作和文件发现
daily	daily, daily:read, daily:append, daily:prepend, daily:path	每日笔记操作
search	search, search:context	全文搜索；search:context 返回匹配的行
properties	properties, property:read, property:set, property:remove, aliases	Frontmatter/元数据管理
tags	tags, tag	标签列表、计数和筛选
tasks	tasks, task	任务查询、筛选和切换
links	backlinks, links, unresolved, orphans, deadends	图谱和链接分析
bookmarks	bookmarks, bookmark	列出和添加书签
templates	templates, template:read, template:insert	模板列表、渲染和插入
plugins	plugins, plugin, plugin:enable, plugin:disable, plugin:install, plugin:uninstall, plugins:restrict	插件管理
sync	sync, sync:status, sync:history, sync:read, sync:restore, sync:deleted	Obsidian Sync 操作
themes	themes, theme, theme:set, theme:install, theme:uninstall	主题管理
snippets	snippets, snippets:enabled, snippet:enable, snippet:disable	CSS 片段管理
commands	commands, command, hotkeys, hotkey	按 ID 执行 Obsidian 命令；查看快捷键
bases	bases, base:query, base:views, base:create	Obsidian Bases（v1.12+ 数据库功能）
history	history, history:list, history:read, history:restore	文件版本恢复（File Recovery 插件）
workspace	workspace, tabs, tab:open	工作区布局和标签页管理
diff	diff	比较本地与同步的文件版本
dev	eval, dev:screenshot, dev:debug, dev:console, dev:errors, dev:css, dev:dom, devtools	开发和调试工具
vault	vault, vaults, version, reload, restart	库信息和应用控制
other	outline, wordcount, recents	实用命令

快速参考 — 最常用命令

读取和写入笔记

obsidian read path="folder/note.md"
obsidian create path="folder/note" content="# New Note"
obsidian create path="folder/note" template="meeting-notes"
obsidian append path="folder/note.md" content="New paragraph"
obsidian prepend path="folder/note.md" content="Top content"
obsidian move path="old/note.md" to="new/note.md"
obsidian delete path="folder/note.md"
obsidian delete path="folder/note.md" permanent

每日笔记

obsidian daily                          # Open today's daily note
obsidian daily:read                     # Print content of today's note
obsidian daily:append content="- [ ] New task"
obsidian daily:prepend content="## Morning Notes"

搜索

obsidian search query="project alpha"
obsidian search query="TODO" path="projects" limit=10
obsidian search query="meeting" format=json   # Returns JSON array of file paths
obsidian search query="urgent" case

属性和标签

obsidian properties path="note.md"
obsidian property:set path="note.md" name="status" value="active"
obsidian property:read path="note.md" name="status"
obsidian property:remove path="note.md" name="draft"
obsidian tags counts sort=count
obsidian tag name="project/alpha"

任务

obsidian tasks                          # All tasks (done + todo) — same as tasks all in v1.12
obsidian tasks all                      # All tasks (done + todo)
obsidian tasks done                     # Completed only
obsidian tasks daily                    # Tasks in today's daily note
obsidian task path="note.md" line=12 toggle
obsidian tasks | grep "\[ \]"           # Workaround: filter to incomplete only

开发和自动化

obsidian eval code="app.vault.getFiles().length"
obsidian dev:screenshot path="folder/screenshot.png"  # Path must be vault-relative
obsidian dev:debug on                                 # Required before dev:console
obsidian dev:console limit=20
obsidian dev:errors

TUI 模式

不带参数运行 obsidian，会启动交互式 TUI（终端用户界面）：

按键	操作
↑↓	浏览文件
Enter	打开文件
/	搜索
n	创建新文件
d	删除文件
r	重命名文件
q	退出

常见 Agent 模式

每日日志自动化

# Append a timestamped entry
obsidian daily:append content="## $(date '+%H:%M') — Status Update
- Completed: feature branch merge
- Next: code review for PR #42
- Blocked: waiting on API credentials"

使用模板和元数据创建笔记

obsidian create path="projects/new-feature" template="project-template"
obsidian property:set path="projects/new-feature.md" name="status" value="planning"
obsidian property:set path="projects/new-feature.md" name="created" value="$(date -I)"
obsidian daily:append content="- Started [[projects/new-feature|New Feature]]"

库分析脚本

obsidian files total                    # Total file count
obsidian tags counts sort=count         # Most used tags
obsidian tasks | grep "\[ \]"          # Incomplete tasks across vault
obsidian orphans                        # Notes needing integration
obsidian unresolved                     # Broken links to fix

搜索并提取内容以供 AI 处理

obsidian search query="meeting notes" format=json | jq '.[]'
obsidian read path="meetings/standup.md" | grep "Action item"

同步管理

obsidian sync:status                    # Check sync health
obsidian sync:history path="important.md"  # Version history
obsidian sync:restore path="important.md" version=3  # Rollback

执行 Obsidian 命令

# Find a command ID, then execute it
obsidian commands | grep "graph"
obsidian command id="graph:open"

# Open settings, trigger a plugin action
obsidian command id="app:open-settings"
obsidian command id="dataview:dataview-force-refresh-views"

提示

1. 路径相对于知识库 — 使用 folder/note.md，而不是绝对文件系统路径。
2. create 路径不带 .md — 系统会自动添加扩展名。
3. move 需要完整的目标路径，包括 .md 扩展名。
4. 支持管道操作 — 纯文本输出可与 grep、awk、sed、jq 配合使用。
5. JSON 输出 — 在 search 中使用 format=json，即可获得文件路径的 JSON 数组。files 命令不支持 JSON 输出。
6. stderr 噪声 — 无头环境中的 GPU/Electron 警告无害；可用 2>/dev/null 过滤。
7. daily:prepend 会在 frontmatter 后插入内容，而不是插入到字节 0 处。
8. 使用 eval，可针对 Obsidian API（app.*）运行任意 JavaScript。
9. template:insert 会将内容插入 Obsidian UI 中当前激活的文件 — 它不接受 path= 参数。如果没有打开文件，则会返回 Error: No active editor. Open a file first.。若要通过 CLI 根据模板创建文件，请改用 obsidian create path="..." template="..."。
10. property:set 会将列表值存储为字符串 — value="tag1, tag2" 写入的是字面上的逗号分隔字符串，而不是 YAML 数组。要设置正确的数组字段，请直接编辑笔记的 frontmatter（例如，通过 read → 修改 → create --force），或使用 eval 调用 Obsidian API。
11. eval 要求 JavaScript 为单行 — 内联传入多行 JS 会因 token 错误而失败。请改为将脚本写入临时文件：

    cat > /tmp/obs.js << 'JS'
    var files = app.vault.getMarkdownFiles();
    files.length;
    JS
    obsidian eval code="$(cat /tmp/obs.js)"
    

12. 在所有环境中，多知识库定位可能无法正常工作 — 在某些配置中，obsidian "My Vault" command 会返回 Error: Command "My Vault" not found。如果出现这种情况，请省略知识库名称（CLI 会定位到最近激活的知识库），并在 Obsidian UI 中手动切换知识库。
13. 冒号子命令不可用时（例如，Windows Git Bash 中没有包装脚本），优先使用不带冒号的替代命令：使用 properties 代替 property:read，使用 obsidian daily:path + append 代替 daily:append。

故障排除

问题	原因	解决方法
输出为空 / 命令挂起	Obsidian 未运行，或使用了管理员终端（Windows）	启动 Obsidian；使用普通权限终端
找不到命令	CLI 未注册到 PATH	在 Settings 中重新启用 CLI；重启终端
Unicode 错误	已在 v1.12.2+ 中修复	更新 Obsidian
定位到错误的知识库	多知识库定位不明确	将知识库名称作为第一个参数传入
找不到 IPC 套接字（Linux）	systemd 中设置了 PrivateTmp=true	设置 PrivateTmp=false
Snap 沙盒限制问题	Snap 限制 IPC	改用 .deb 软件包
多知识库 "Name" command 失败	知识库名称匹配问题	省略知识库名称；定位到最近使用的知识库
property:set 列表值为字符串	CLI 按原样存储值	直接编辑 frontmatter，或使用 eval
冒号 + 参数退出码为 127（缺少 .com）	安装程序过时 — 缺少 Obsidian.com	从 obsidian.md/download 重新安装
冒号 + 参数退出码为 127（Git Bash / MSYS2）	Bash 将 obsidian 解析为 .exe 而非 .com	创建 ~/bin/obsidian 包装脚本：#!/bin/bash / /c/path/to/Obsidian.com "$@"，并将 export PATH="$HOME/bin:$PATH" 添加到 ~/.bashrc