Siyuan CLI

SiYuan CLI

Use siyuan-cli instead of ad hoc curl calls. It handles config discovery, profile selection, token auth, JSON output, common API error reporting, and local maintenance of official SiYuan API references.

Setup

Install the CLI if it is unavailable:

pipx install git+https://github.com/briqt/siyuan-cli.git

Initialize config:

siyuan-cli init-config
open ~/.config/agent-skills/siyuan-cli/config.json

Set profiles.default.token from SiYuan Settings > About. Set base_url to the current SiYuan API URL if it is not http://127.0.0.1:6806.

The CLI prints [profile: <name>] to stderr on every run and JSON to stdout. Use --profile <name> for alternate SiYuan instances.

Official Docs

Before using an unfamiliar endpoint, read the vendored official docs under references/official/:

rg -n "/api/block/appendBlock|插入后置子块" references/official/API_zh_CN.md
rg -n "/api/block/appendBlock" references/official/API.md
rg -n "appendBlock" references/official/kernel-api-router.go

If the official docs are missing or stale, update them from the SiYuan official GitHub repo:

siyuan-cli update-docs --references-dir <skill-root>/references

When working from this repository root, siyuan-cli update-docs is enough.

Quick Commands

Always prefer dedicated commands over siyuan-cli api. Use siyuan-cli api only for endpoints that have no dedicated command.

Read / Search:

siyuan-cli notebooks
siyuan-cli list-docs --notebook <notebook-id> --path /
siyuan-cli search "关键词" --page-size 10
siyuan-cli sql "SELECT id, content, hpath FROM blocks WHERE content LIKE '%关键词%' LIMIT 20"
siyuan-cli get-block <block-id>
siyuan-cli export-md <doc-id>
siyuan-cli children <block-id>
siyuan-cli doc-outline <doc-id>
siyuan-cli attrs <block-id>
siyuan-cli hpath-by-id <block-or-doc-id>
siyuan-cli ids-by-hpath /path/to/doc --notebook <notebook-id>

sql 默认约 64 行上限：sql（/api/query/sql）不显式写 LIMIT 时只返回约 64 行并静默截断——曾据此误判"某文档树只有 63 个子文档"，实际上百个。枚举/取全量务必加 LIMIT 9999；核总数用 SELECT COUNT(*)（不受行限影响）；COUNT 与枚举条数对不上，几乎一定是行限截断而非数据缺失。

Create:

siyuan-cli create-notebook "Name"
siyuan-cli create-doc --notebook <notebook-id> --path /Inbox/Title --markdown-file note.md
siyuan-cli insert-block --previous-id <block-id> --markdown "Inserted after"
siyuan-cli append-block <parent-id> --markdown "New paragraph"
siyuan-cli prepend-block <parent-id> --markdown-file prepend.md

Update:

siyuan-cli rename-notebook <notebook-id> "New Name"
siyuan-cli rename-doc --id <doc-id> --title "New title"
siyuan-cli update-block <block-id> --markdown-file replacement.md
siyuan-cli set-attrs <block-id> --attrs '{"custom-key":"value"}'

Delete:

siyuan-cli remove-doc --id <doc-id>
siyuan-cli delete-block <block-id>

Assets:

siyuan-cli upload-asset /path/to/image.png --assets-dir /assets/

Use siyuan-cli api <endpoint> --data '{...}' for official endpoints not yet wrapped by a dedicated command. Check the local official docs first so the request payload matches the current API.

Workflow

1. Prefer dedicated commands for all write operations. Quick Commands above lists everything available; siyuan-cli api is only for endpoints without a dedicated command.
2. For lookup, start with search or sql, then read the selected block with get-block.
3. For whole-document reading, prefer export-md <doc-id>; for block-level reading, use get-block and children.
4. For writes, resolve the destination notebook/document/block first. If a default notebook is configured, it may be used for document commands; otherwise pass --notebook.
5. For long Markdown content, write a temporary file in the current workspace and pass --markdown-file.
6. Before replacing or deleting content, read the target block or export the target document and make sure it is unique.
7. In the final answer, describe the note title/path or action result in human terms; include IDs only when useful for later edits.

Note Organization

写入笔记时遵循以下组织原则：

核心方向：笔记应自包含、信息密度优先、最小约束让结构有机生长。触发组织行为的时机：文档过长需要拆分、找不到该往哪写、或用户要求整理结构时。

在思源中的具体应用：

• 自包含：每篇文档独立可理解，标题即摘要，首段即上下文
• 最小约束：不强制固定目录结构，按内容自然归类
• 信息密度优先：写的人花 2 分钟，读的人省 20 分钟
• 单一权威源：同一信息只在一处维护，其他地方用链接引用

实践：

• 新笔记优先追加到已有的主题文档，而非每条都创建新文档
• 文档过长（>200 块）时拆分为子文档
• 用思源的标签和属性替代 frontmatter 的 type/tags 角色
• 需要跨文档导航时，用引用块或嵌入块，而非维护独立索引

完整方法论：加载 knowledge-project skill 查看组织原则、生命周期管理和蒸馏流程的完整定义。若该 skill 不可用，参阅 https://raw.githubusercontent.com/briqt/knowledge-project/master/SKILL.md 。

References

Read references/api-workflows.md for safe sequencing and references/official/ for the current vendored official API docs.