# Siyuan CLI

> Operate SiYuan Note / 思源笔记 through a local CLI backed by the official HTTP API. Use when the user asks to search, read, create, append, update, delete, organize, export, or inspect SiYuan notebooks, documents, blocks, attributes, or SQL query results; when they mention 思源笔记, SiYuan, block IDs, notebook IDs, or the local SiYuan API; or when an agent needs durable note capture into SiYuan.

- Skill: `briqt/siyuan-cli` (Agent Skill, multi-file: 8 files)
- Install (CLI): `npx skillmds@latest add briqt/siyuan-cli`
- Raw SKILL.md: https://api.skillmd.com/api/skills/briqt/siyuan-cli/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Data & Analytics
- Author: briqt (https://skillmd.com/u/briqt)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/briqt/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:

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

Initialize config:

```bash
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/`:

```bash
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:

```bash
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:**

```bash
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:**

```bash
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:**

```bash
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:**

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

**Assets:**

```bash
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`.
2. For whole-document reading, prefer `export-md <doc-id>`; for block-level reading, use `get-block` and `children`.
3. 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`.
4. For long Markdown content, write a temporary file in the current workspace and pass `--markdown-file`.
5. Before replacing or deleting content, read the target block or export the target document and make sure it is unique.
6. 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.