obsidian-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

obsidian-cli - Control Obsidian from the Terminal

obsidian-cli - 从终端控制 Obsidian

Keyword:
obsidian cli
·
obsidian uri
·
obsidian daily note command
·
obsidian plugin reload cli
Use this skill for the official desktop CLI. If the user needs sync without the desktop app, that is Obsidian Headless, not this skill.

Obsidian CLI is the official command line interface for controlling a running Obsidian app from the terminal. It supports single commands, an interactive TUI, vault and file targeting, note operations, search, tags, tasks, and developer commands. Official docs also link it closely with the

obsidian://

URI protocol for cross-app automation.

关键词:
obsidian cli
·
obsidian uri
·
obsidian daily note command
·
obsidian plugin reload cli
本技能适用于官方桌面端 CLI。如果用户需要在无桌面应用的情况下同步，属于 Obsidian Headless 的范畴，不适用本技能。

Obsidian CLI 是官方提供的命令行接口，可用于从终端控制运行中的 Obsidian 应用。它支持单命令执行、交互式 TUI、vault 和文件定向操作、笔记操作、搜索、标签、任务以及开发者命令。官方文档也明确说明它和

obsidian://

URI 协议深度关联，可用于跨应用自动化。

When to use this skill

何时使用本技能

Enable and verify the official Obsidian CLI registration

Run one-shot commands such as

obsidian help

obsidian daily

obsidian read

, or

obsidian search

Open the interactive TUI with autocomplete and history
Target a specific vault with
```
vault=<name>
```
or
```
vault=<id>
```
Target a specific note with
```
file=<name>
```
or
```
path=<path>
```
Copy command output with
```
--copy
```
Use developer commands for plugin and theme work such as
```
devtools
```
,
```
plugin:reload
```
,
```
dev:screenshot
```
, and
```
eval
```
Launch or generate
```
obsidian://
```
URIs for open, new, daily, unique, search, and callback-based workflows

启用并验证官方 Obsidian CLI 的注册状态

运行单次命令，例如

obsidian help

、

obsidian daily

、

obsidian read

或

obsidian search

打开带自动补全和历史记录功能的交互式 TUI
通过
```
vault=<名称>
```
或
```
vault=<id>
```
指定特定 vault
通过
```
file=<名称>
```
或
```
path=<路径>
```
指定特定笔记
配合
```
--copy
```
参数复制命令输出结果
使用面向插件和主题开发的开发者命令，例如
```
devtools
```
、
```
plugin:reload
```
、
```
dev:screenshot
```
和
```
eval
```
启动或生成
```
obsidian://
```
URI，用于打开、新建、每日笔记、唯一笔记、搜索和基于回调的工作流

Instructions

使用指南

Step 1: Enable and verify the CLI

步骤 1：启用并验证 CLI

Use the official app flow first:

Upgrade to the installer and early access versions required by the docs
In Obsidian, go to
```
Settings -> General
```
Enable
```
Command line interface
```
Follow the prompt to register the CLI

Run the local helper:

bash

bash scripts/install.sh

What to remember:

The docs currently say CLI usage requires the Obsidian
```
1.12
```
installer
The same page also says to upgrade to the latest installer
```
1.11.7
```
and the latest early access
```
1.12.x
```
The app must be running, or the first CLI command launches it
Linux packaging may need extra symlink or PATH work

Treat those version strings exactly as current official docs, not as inferred packaging logic.

优先使用官方应用内的流程操作：

升级到文档要求的安装包版本和早期访问版本
在 Obsidian 中，进入
```
设置 -> 通用
```
启用
```
命令行接口
```
按照提示完成 CLI 注册

运行本地辅助脚本：

bash

bash scripts/install.sh

注意事项：

目前文档说明使用 CLI 需要 Obsidian
```
1.12
```
版本安装包
同一份文档也要求升级到最新的
```
1.11.7
```
安装包和最新的
```
1.12.x
```
早期访问版本
应用必须处于运行状态，否则第一条 CLI 命令会自动启动应用
Linux 安装包可能需要额外的软链接或 PATH 配置

请严格按照官方当前文档标注的版本号操作，不要自行推断安装逻辑。

Step 2: Choose single-command mode or the TUI

步骤 2：选择单命令模式或 TUI 模式

Run a single command:

bash

obsidian help

Open the terminal interface:

bash

obsidian
help

Use the TUI when the user wants autocomplete, command history, and reverse search. Use single-command mode for scripts, automation, and shell aliases.

运行单次命令：

bash

obsidian help

打开终端交互界面：

bash

obsidian
help

当用户需要自动补全、命令历史和反向搜索功能时使用 TUI 模式。在编写脚本、自动化流程和 shell 别名场景下使用单命令模式。

Step 3: Target the right vault and file

步骤 3：定向到正确的 vault 和文件

Vault targeting rules:

If the current working directory is a vault, that vault is used by default
Otherwise, the active vault is used
```
vault=<name>
```
or
```
vault=<id>
```
must be the first parameter before the command

Examples:

bash

obsidian vault=Notes daily
obsidian vault="My Vault" search query="meeting notes"

File targeting rules:

```
file=<name>
```
uses wikilink-style resolution by file name
```
path=<path>
```
requires the exact path from the vault root
If neither is provided, many commands default to the active file

Examples:

bash

obsidian read file=Recipe
obsidian read path="Templates/Recipe.md"

Move the targeting details into references/vault-and-file-targeting.md.

vault 定向规则：

如果当前工作目录是一个 vault，默认使用该 vault
否则使用当前激活的 vault
```
vault=<名称>
```
或
```
vault=<id>
```
必须是命令前的第一个参数

示例：

bash

obsidian vault=Notes daily
obsidian vault="My Vault" search query="meeting notes"

文件定向规则：

```
file=<名称>
```
采用 wiki 链接风格的文件名解析逻辑
```
path=<路径>
```
需要传入从 vault 根目录开始的精确路径
如果两者都未提供，多数命令默认使用当前激活的文件

示例：

bash

obsidian read file=Recipe
obsidian read path="Templates/Recipe.md"

请将定向相关的细节整理到 references/vault-and-file-targeting.md。

Step 4: Use the command families that match the job

步骤 4：使用匹配需求的命令族

Start with the everyday commands:

```
daily
```
```
daily:append
```
```
search
```
```
read
```
```
create
```
```
tags
```
```
tasks
```
```
diff
```

General commands:

```
help
```
```
version
```
```
reload
```
```
restart
```

Developer-oriented commands:

```
devtools
```
```
plugin:reload
```
```
dev:screenshot
```
```
eval
```

These developer commands are especially useful for plugin and theme workflows because the docs explicitly position them for automatic testing and debugging.

See references/commands-and-developer-tools.md for a compact command map.

日常使用优先选择通用命令：

```
daily
```
```
daily:append
```
```
search
```
```
read
```
```
create
```
```
tags
```
```
tasks
```
```
diff
```

基础命令：

```
help
```
```
version
```
```
reload
```
```
restart
```

面向开发者的命令：

```
devtools
```
```
plugin:reload
```
```
dev:screenshot
```
```
eval
```

这些开发者命令对插件和主题开发工作流特别有用，官方文档明确说明它们是为自动化测试和调试设计的。

查看 references/commands-and-developer-tools.md 获取精简的命令映射表。

Step 5: Use flags and output features deliberately

步骤 5：合理使用参数和输出特性

Parameter rules:

Parameters use
```
name=value
```
Wrap values with spaces in quotes
Boolean switches are bare flags such as
```
open
```
or
```
overwrite
```
Use
```
\n
```
for newlines and
```
\t
```
for tabs in content strings

Examples:

bash

obsidian create
obsidian create name=Note content="Hello world"
obsidian create name=Note content="Hello" open overwrite
obsidian create name=Note content="# Title\n\nBody text"

Output helper:

bash

obsidian read --copy
obsidian search query="TODO" --copy

Many listing commands also expose

format=

parameters such as

json

tsv

csv

md

, or

paths

参数规则：

参数采用
```
名称=值
```
格式
带空格的参数值需要用引号包裹
布尔开关是无值参数，例如
```
open
```
或
```
overwrite
```
内容字符串中使用
```
\n
```
表示换行，
```
\t
```
表示制表符

示例：

bash

obsidian create
obsidian create name=Note content="Hello world"
obsidian create name=Note content="Hello" open overwrite
obsidian create name=Note content="# Title\n\nBody text"

输出辅助参数：

bash

obsidian read --copy
obsidian search query="TODO" --copy

很多列表类命令还提供

format=

参数，支持

json

、

tsv

、

csv

、

md

或

paths

等输出格式。

Step 6: Use

obsidian://

URI workflows for external automation

步骤 6：使用

obsidian://

URI 工作流实现外部自动化

The official URI actions include:

```
open
```
```
new
```
```
daily
```
```
unique
```
```
search
```
```
choose-vault
```

Examples:

text

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

Important URI rules:

Encode values properly, especially spaces and
```
/
```
```
path=
```
overrides
```
vault
```
and
```
file
```
```
paneType=tab|split|window
```
controls opening location
```
paneType=window
```
is desktop-only
```
x-success
```
and
```
x-error
```
support callback flows on supported endpoints

Use references/uri-and-callbacks.md for the URI-specific behavior and Hook integration notes.

官方支持的 URI 操作包括：

```
open
```
```
new
```
```
daily
```
```
unique
```
```
search
```
```
choose-vault
```

示例：

text

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

URI 重要规则：

正确编码参数值，特别是空格和
```
/
```
字符
```
path=
```
参数会覆盖
```
vault
```
和
```
file
```
参数
```
paneType=tab|split|window
```
控制打开位置
```
paneType=window
```
仅支持桌面端
支持的端点可以通过
```
x-success
```
和
```
x-error
```
实现回调流程

查看 references/uri-and-callbacks.md 获取 URI 专属行为和 Hook 集成说明。

Step 7: Respect the limitations

步骤 7：明确使用限制

CLI automation is for the desktop app, not headless sync
```
daily
```
requires the Daily notes plugin to be enabled
```
unique
```
requires the Unique note creator plugin to be enabled
Linux registration may require manual symlinks, PATH updates, or packaging-specific fixes
Developer commands can change app or plugin state, so use them intentionally

CLI 自动化仅适用于桌面端应用，不适用于无界面同步场景
```
daily
```
命令需要启用每日笔记插件
```
unique
```
命令需要启用唯一笔记创建器插件
Linux 系统注册可能需要手动配置软链接、PATH 或特定安装包的修复操作
开发者命令会修改应用或插件状态，请谨慎使用

Examples

示例

Example 1: Verify CLI registration

示例 1：验证 CLI 注册状态

bash

bash scripts/install.sh

bash

bash scripts/install.sh

Example 2: Open the TUI

示例 2：打开 TUI

bash

bash scripts/run-command.sh

bash

bash scripts/run-command.sh

Example 3: Open today's daily note

示例 3：打开今日的每日笔记

bash

bash scripts/run-command.sh daily

bash

bash scripts/run-command.sh daily

Example 4: Append a task to today's daily note

示例 4：向今日的每日笔记追加任务

bash

bash scripts/run-command.sh daily:append content="- [ ] Buy groceries"

bash

bash scripts/run-command.sh daily:append content="- [ ] Buy groceries"

Example 5: Search a specific vault

示例 5：搜索指定 vault

bash

bash scripts/run-command.sh vault="My Vault" search query="meeting notes"

bash

bash scripts/run-command.sh vault="My Vault" search query="meeting notes"

Example 6: Read a file by name or exact path

示例 6：通过文件名或精确路径读取文件

bash

bash scripts/run-command.sh read file=Recipe
bash scripts/run-command.sh read path="Templates/Recipe.md" --copy

bash

bash scripts/run-command.sh read file=Recipe
bash scripts/run-command.sh read path="Templates/Recipe.md" --copy

Example 7: Reload a plugin you are developing

示例 7：重载你正在开发的插件

bash

bash scripts/run-command.sh plugin:reload id=my-plugin

bash

bash scripts/run-command.sh plugin:reload id=my-plugin

Example 8: Take a screenshot from the app

示例 8：从应用内截取截图

bash

bash scripts/run-command.sh dev:screenshot path=screenshot.png

bash

bash scripts/run-command.sh dev:screenshot path=screenshot.png

Example 9: Open a note via URI

示例 9：通过 URI 打开笔记

bash

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

bash

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

Best practices

最佳实践

Start with
```
obsidian help
```
or the TUI before assuming a command family name.
Put
```
vault=
```
first when you need deterministic multi-vault automation.
Prefer
```
path=
```
when duplicate file names make wikilink-style
```
file=
```
resolution ambiguous.
Use
```
--copy
```
when the result needs to feed another tool or model without extra shell parsing.
Treat developer commands like
```
plugin:reload
```
,
```
eval
```
, and
```
dev:screenshot
```
as operational tools, not casual shortcuts.
Keep CLI automation separate from Headless Sync workflows; they solve different problems.
URI values must be encoded correctly or the action may be misinterpreted.
On Linux, check registration, symlinks, and
```
PATH
```
before assuming the CLI is broken.

在猜测命令族名称之前，优先运行
```
obsidian help
```
或使用 TUI 查询。
如果你需要确定性的多 vault 自动化流程，请将
```
vault=
```
参数放在最前面。
当存在重复文件名导致 wiki 链接风格的
```
file=
```
解析出现歧义时，优先使用
```
path=
```
参数。
当输出结果需要传入其他工具或模型，且不需要额外 shell 解析时，使用
```
--copy
```
参数。
请将
```
plugin:reload
```
、
```
eval
```
、
```
dev:screenshot
```
等开发者命令作为运维工具使用，不要作为日常快捷方式。
请将 CLI 自动化和无界面同步工作流区分开，两者解决的是不同问题。
URI 值必须正确编码，否则操作可能会被错误解析。
在 Linux 系统下，在判定 CLI 故障之前，请先检查注册状态、软链接和
```
PATH
```
配置。

References

参考资料

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

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