SiYuan 3.8.8 常用 CLI 命令与工具详解

目标：系统讲清 SiYuan 3.8.8 内核自带的命令行工具——同一个内核二进制 /opt/siyuan/kernel 既是服务进程入口（serve），也是离线 CLI（22 个命令族、79 个子命令，可对工作区做笔记本/文档/块/属性/搜索/SQL/导入导出/快照/文件级全量操作）。全部命令与回显在 Ubuntu 22.04 + v3.8.8 实测环境逐条执行并照抄，含 dry-run 验证、JSON 输出、权限排障实录与「CLI 直写后索引可见性」实测。

一、环境信息

本篇实测环境如下：

操作系统：Ubuntu 22.04 LTS（x86_64）
SiYuan：v3.8.8（kernel --version 实测输出 kernel version 3.8.8）
内核二进制：/opt/siyuan/kernel（约 148MB 单文件，ls -lh /opt/siyuan/kernel 实测）
工作区：/siyuan/workspace/（部署形态见《SiYuan 3.8.8 Docker Compose 部署指南》）
服务状态：内核服务运行中（6806 端口），本篇全部 CLI 命令在服务运行的同时执行并实测成功
测试数据：笔记本「运维手册」（ID 20261022002307-05h9zc6）；本篇的写操作示例在测试笔记本上执行并在结束时清理
命令回显约定：以下全部回显为实测原文；凡输出含时间戳型随机 ID（格式 YYYYMMDDHHmmss-随机串），读者环境必然不同

二、工具概览

2.1 一个二进制，两种形态

kernel 二进制是 SiYuan 的唯一可执行体：不带子命令参数或带 serve 时作为 HTTP 服务运行；带操作子命令时作为离线 CLI 直接读写工作区。根帮助（/opt/siyuan/kernel --help 实测原文）：

SiYuan Kernel v3.8.8. Manage workspace data directly or start the HTTP server.

Usage:
  kernel [command]

Available Commands:
  asset       Manage assets
  attr        Manage block attributes
  block       Block operations
  bookmark    Manage bookmarks
  completion  Generate the autocompletion script for the specified shell
  dailynote   Daily note (dailynote) operations
  database    Manage databases (attribute views)
  document    Manage documents
  export      Export documents
  file        Workspace file operations
  help        Help about any command
  history     Data history
  import      Import files
  inbox       Manage the cloud inbox (clipped shorthands)
  notebook    Manage notebooks
  outline     Document outline (heading tree)
  ref         Backlinks and references
  repo        Data snapshots
  search      Full-text search (blocks, semantic, or asset file contents with --asset)
  serve       Start kernel HTTP server
  sql         Execute SQL query
  sync        Sync data with cloud
  system      System information
  tag         Manage tags
  template    Manage templates
  workspace   Manage SiYuan workspaces

Flags:
      --dry-run            dry run mode: validate and print what would happen without making changes
  -f, --format string      output format: table | json (default "table")
  -h, --help               help for kernel
      --home-dir string    base directory for user configuration (defaults to the system user home)
  -v, --log-level string   log level: off | trace | debug | info | warn | error | fatal (defaults to conf.json system.logLevel)
      --version            version for kernel
  -w, --workspace string   workspace path

Use "kernel [command] --help" for more information about a command.

版本确认：

/opt/siyuan/kernel --version

kernel version 3.8.8

2.2 全局参数表

每个子命令都支持以下全局参数（默认值实测）：

参数	默认值	说明
`-w, --workspace`	（无，必指定）	工作区路径；也可用 `--workspace=` 长格式
`-f, --format`	`table`	输出格式 `table`/`json`，脚本化用 json
`--dry-run`	关闭	校验并打印将要执行的动作，但不真正落盘
`-v, --log-level`	取 `conf.json` 的 `logLevel`	CLI 自身日志级别
`--home-dir`	系统用户 home	用户配置基目录

2.3 命令族总表

22 个命令族按用途分域如下（叶子命令数经 --help 逐一实点）：

域	命令族	能力
内容骨架	`notebook`(6) / `document`(6) / `block`(14)	笔记本、文档、块三级 CRUD 与树操作
元数据	`attr`(3) / `tag`(3) / `bookmark`(4)	块属性、标签、书签
检索	`search` / `sql` / `ref`(3) / `outline`(1)	全文搜索（关键词/查询语法/SQL/正则/语义）、SQL 查询、反链提及、大纲
进出	`import`(3) / `export`(7)	Markdown/.sy.zip/备份包导入；Markdown/HTML/Word/.sy/整库导出
资产	`file`(9) / `asset`(4) / `template`(6)	工作区文件级操作、附件管理、模板管理
版本与同步	`history`(2) / `repo`(9) / `sync`(4)	本地历史、数据仓库快照、云端同步
辅助	`dailynote`(3) / `database`(8) / `inbox`(1) / `system`(1) / `workspace`(2) / `completion`	日记、数据库视图、收集箱、系统信息、工作区、补全脚本

💡 技术拓展：同领域笔记工具的自动化通道常见三类——

通道代表特点
内置 CLI SiYuan kernel CLI、Joplin CLI 本机直接操作数据，无需服务在线，脚本友好
HTTP API SiYuan Kernel API、Trilium ETAPI 远程可调、语言无关，需令牌鉴权
插件 SDK Obsidian、Logseq 界面内扩展，脱离宿主不可用

SiYuan 三通道齐备且 CLI 与 API 共用同一内核；本篇讲 CLI，HTTP API 用法要点（Token 鉴权、/api/* 端点）在部署指南与配置篇的验证章节已实测出现，深入可按官方 API.md 扩展。本方案自动化优先用 CLI（同机）+ API（跨机）。

通道	代表	特点
内置 CLI	SiYuan kernel CLI、Joplin CLI	本机直接操作数据，无需服务在线，脚本友好
HTTP API	SiYuan Kernel API、Trilium ETAPI	远程可调、语言无关，需令牌鉴权
插件 SDK	Obsidian、Logseq	界面内扩展，脱离宿主不可用

三、前置条件

知道内核二进制路径与工作区路径。服务端部署形态下分别是 /opt/siyuan/kernel 与工作区目录（本篇 /siyuan/workspace/；桌面形态官方 README 说明 CLI 载体为安装目录内 resources/kernel/SiYuan-Kernel，参数用法一致）。
以运行服务的同一系统用户执行。服务进程以 uid 1000 运行时，CLI 也应以该用户运行；混用 root 会在工作区落盘 root 属主文件，导致服务端报权限错误（真实排障全流程见第六章 Q2）。
理解 CLI 是直接操作工作区落盘数据：CLI 写操作即时改 .sy 文件，与「界面编辑」同级；对运行中的服务而言，新文件会在数秒内被索引（实测见第五章）。

四、各工具详解

约定：为省略重复，下文示例统一用 shell 变量（读者可照抄前两行）：

K=/opt/siyuan/kernel
W=/siyuan/workspace/

4.1 notebook：笔记本管理

笔记本是工作区 data/ 下的顶层文件夹。全生命周期实测：

$K -w $W notebook create --name "CLI 生命周期测试"

20261022085620-fw71mfj

创建成功直接返回新笔记本 ID。其余子命令（--help 摘要 + 实测）：

$K -w $W notebook list                      # 列出全部笔记本
$K -w $W notebook rename --id 20261022085620-fw71mfj --name "CLI 测试改名"
$K -w $W notebook close  --id 20261022085620-fw71mfj   # 关闭（不索引不搜索）
$K -w $W notebook open   --id 20261022085620-fw71mfj   # 重新打开
$K -w $W notebook remove --id 20261022085620-fw71mfj   # 删除（慎用）

notebook list 实测回显（close 后再 list，CLOSED 列可见状态）：

ID                      NAME      CLOSED  SORT
20261022002307-05h9zc6  运维手册      false   1
20261022085620-fw71mfj  CLI 测试改名  true    2

notebook list -f json 实测回显（节选）：

[
  {
    "id": "20261022002307-05h9zc6",
    "name": "运维手册",
    "icon": "",
    "sort": 1,
    "sortMode": 15,
    "closed": false,
    "subFileCount": 0,
    "encrypted": false
  }
]

4.2 document：文档管理

$K -w $W document create --notebook 20261022002307-05h9zc6 --title "CLI 实测文档" \
  --markdown "第一段内容，用于验证 CLI 写入。"

20261022084712-it39lz0

document create 支持 --path 指定父文档（默认 / 顶层）、--markdown 初始内容。先 --dry-run 验证动作再真执行：

$K -w $W document create --notebook 20261022002307-05h9zc6 --title "CLI 实测文档" --dry-run

[dry-run] Would create document "CLI 实测文档" in notebook 20261022002307-05h9zc6

列表与详情：

$K -w $W document list --notebook 20261022002307-05h9zc6

ID                      NAME      PATH                        SIZE   COUNT  MTIME
20261022084712-it39lz0  CLI 实测文档  /20261022084712-it39lz0.sy  440 B  0      2026-10-22 08:47:12, now

$K -w $W document get --id 20261022084712-it39lz0

ID:       20261022084712-it39lz0
Type:     NodeDocument
Name:
Box:      20261022002307-05h9zc6
HPath:    /CLI 实测文档
Content:  CLI 实测文档

document get -f json 实测字段更全（节选）：

{
  "box": "20261022002307-05h9zc6",
  "path": "/20261022084712-it39lz0.sy",
  "hPath": "/CLI 实测文档",
  "id": "20261022084712-it39lz0",
  "rootID": "20261022084712-it39lz0",
  "content": "CLI 实测文档",
  "type": "NodeDocument"
}

改名、跨笔记本移动、删除：

$K -w $W document rename --id <文档ID> --title "新标题"
$K -w $W document move   --id <文档ID> --notebook <目标笔记本ID>
$K -w $W document remove --id <文档ID>

4.3 block：块操作（CLI 的核心域）

块（block）是 SiYuan 的最小编辑单元。常用读取：

$K -w $W block get --id 20261022084712-it39lz0

ID:       20261022084712-it39lz0
Type:     NodeDocument
Name:
Box:      20261022002307-05h9zc6
HPath:    /CLI 实测文档
Content:  CLI 实测文档

追加块（返回新块 ID）：

$K -w $W block append --parent 20261022084712-it39lz0 --data "## 追加的段落\n\nCLI 追加的第二段。"

20261022085228-vxmqym9

更新块（改写指定块的内容）：

$K -w $W block update --id 20261022084712-b9fv2vl --data "### 改写后的标题块"

ok

block update 有一个值得注意的参数 --lock-type（--help 原文：reject update when the parsed block type differs from the existing block type）——新内容解析出的块类型与原块不一致时拒绝更新，防止把标题误改成段落。

插入与移动（--previous 指定插到哪个块之后）。实测路径：建带标题的测试文档（--markdown "# 第一段"）后，用 sql "SELECT id, type, content FROM blocks WHERE root_id = '<文档ID>'" 查出文档块（type d）与标题块（type h），分别作 --parent 与 --previous：

$K -w $W block insert --parent 20261022091307-72w8ib4 --previous 20261022091307-987fwei --data "第二段" -f json

{
  "id": "20261022091329-ru7871v"
}

block children 复查，新段落块（type p）已插到标题块之后：

[
  {
    "id": "20261022091307-987fwei",
    "type": "h",
    "subType": "h1",
    "content": "第一段",
    "markdown": "# 第一段"
  },
  {
    "id": "20261022091329-ru7871v",
    "type": "p",
    "content": "第二段",
    "markdown": "第二段"
  }
]

移动（把块挪到另一父块之下）：

$K -w $W block move   --id <块ID> --parent <目标父块ID>

删除与子块枚举：

$K -w $W block delete  --id <块ID>
$K -w $W block children --id 20261022084712-it39lz0

ID                      TYPE  CONTENT
20261022084712-b9fv2vl  h     改写后的标题块
20261022085228-vxmqym9  h     追加的段落\n\nCLI 追加的第二段。

其余读取子命令：kramdown（导出块源码，--mode md|textmark）、stat（字数统计）、dom（编辑器 DOM）、breadcrumb（面包屑）、batch-get/batch-kramdown（--ids id1,id2 批量）。

4.4 attr：块属性

$K -w $W attr set --id 20261022084712-it39lz0 --attr tags=实测,CLI
$K -w $W attr get --id 20261022084712-it39lz0

NAME     VALUE
id       20261022084712-it39lz0
tags     实测,CLI
title    CLI 实测文档
type     doc
updated  20261022085228

--attr name=value 可重复传多对。帮助原文点名的常用自定义属性：icon（Emoji 或图片 URL）、title-img（标题图，须写 CSS background-image 形式）、tags（逗号分隔标签）。批量读用 attr batch-get --ids id1,id2。

4.5 search：全文搜索

$K -w $W search "CLI"

ID                      TYPE          NAME                                                      HPATH
20261022084712-it39lz0  NodeDocument  <mark>CLI</mark> 实测文档                                     /
20261022084712-b9fv2vl  NodeHeading   <mark>CLI</mark> 实测文档\n\n第一段内容，用于验证 <mark>CLI</mark> 写入。  /CLI 实测文档

Showing results 1-2 | 2 blocks matched, 1 pages, 1 documents matched

关键参数（--help 原文要点）：-m/--method 搜索方法 0=keyword 1=query-syntax 2=sql 3=regex 4=semantic；-t/--type 按块类型过滤（可重复）；-n/--notebook 限定笔记本；--asset 转为搜索附件文件内容（配合 --ext pdf --ext docx 过滤类型，--get-asset 取某附件的完整索引文本）；分页 -p/--page（默认 1）-s/--page-size（默认 32）。

4.6 sql：SQL 查询

SiYuan 内置 SQLite 索引库（工作区 temp/siyuan.db），blocks 表可查全部块：

$K -w $W sql "SELECT id, type, content FROM blocks WHERE root_id=\"20261022084712-it39lz0\""

content               id                      type
改写后的标题块               20261022084712-b9fv2vl  h
CLI 实测文档              20261022084712-it39lz0  d
追加的段落\n\nCLI 追加的第二段。  20261022085228-vxmqym9  h

3 row(s)

-l/--limit 控制返回行数（默认 100）。常用表与字段同官方 API 的 SQL 查询域（blocks/attributes/files 等），type 列常见值：d 文档、h 标题、p 段落、l 列表、c 代码块。

4.7 export：导出

export 族有 7 个叶子：md（Markdown）、md-zip（Markdown 打包）、sy（.sy.zip 原生格式）、html、docx（Word，服务端形态不可用）、data（整库备份包）、preview（预览 HTML）。

$K -w $W export md --id 20261022084712-it39lz0 --output /tmp/test-doc.md
cat /tmp/test-doc.md

---
title: CLI 实测文档
date: 2026-10-22T08:47:12+08:00
lastmod: 2026-10-22T08:47:12+08:00
---

# CLI 实测文档\n\n第一段内容，用于验证 CLI 写入。

export md 输出自带 YAML front-matter（title/date/lastmod）。HTML 导出到 stdout：

$K -w $W export html --id 20261022084712-it39lz0 | head -c 200

<div data-subtype="h1" data-node-id="20261022084712-it39lz0" data-type="NodeHeading" class="h1" updated="20261022084712" id="20261022084712-it39lz0" title="CLI 实测文档"><div contenteditable="fals

整库备份：export data 产出完整工作区备份包，适合纳入定时任务（与部署指南第五章的备份策略互补）。

4.8 import：导入

import 族有 3 个叶子：md（Markdown 文件或目录）、sy（.sy.zip）、data（备份包）。服务端形态的界面没有「导入 Markdown」入口（官方限制），但 CLI 通道实测可用：

$K -w $W import md --notebook 20261022002307-05h9zc6 --file /tmp/test-doc.md

ok

实测 ok 返回后，document list 出现导入产生的新文档（ID 20261022084712-bflkwj9，983 B），且随后的导出能完整取回内容——导入真实有效，这条通道补上了服务端形态的功能缺口。

4.9 file：工作区文件级操作

绕过文档模型直接操作工作区文件（路径相对工作区根）：

$K -w $W file list data/
$K -w $W file stat conf/conf.json

NAME                    SIZE  ISDIR  MODTIME
.siyuan                 4096  true   2026-10-22 08:52
20261022002307-05h9zc6  4096  true   2026-10-22 08:47
assets                  4096  true   2026-10-22 00:21
emojis                  4096  true   2026-10-22 00:21
icons                   4096  true   2026-10-22 00:21
plugins                 4096  true   2026-10-22 00:21
public                  4096  true   2026-10-22 00:21

Path:    conf/conf.json
Size:    15708
IsDir:   false
ModTime: 2026-10-22 08:46:36

file find（按 glob 找文件）与 file grep（正则搜文件内容）实测：

$K -w $W file grep --pattern "accessAuthCode" --path conf --context 0

Found 1 lines:

conf/conf.json:379:   "accessAuthCode": "q1w2e3r4",

参数：file find <path> --include "*.sy" --limit 200；file grep --pattern <regex> --path <path> --include <glob> --context N --limit 200。写入用 file write <path> --file <源文件>（默认 stdin），复制/改名/删除对应 copy/rename/delete。

4.10 asset：附件管理

asset stat --path assets/xx.png（单文件信息）、asset unused（列出未被引用的附件）、asset clean（清理，可 --path 指定单个）、asset upload --id <文档ID> --file <本地文件>（上传并挂到文档）。

4.11 history：本地历史

$K -w $W history list -p 1

No history found.

实测工作区无历史记录（历史由编辑器按 generateHistoryInterval 间隔生成，CLI 直写不产生历史条目——做批量改写前应先用 export data 或 repo 快照兜底）。history get --path <历史文件路径> 可取历史内容；history list 的 -t 参数按类型过滤（0=doc-name 1=doc-content 2=asset 3=doc-id 4=database），--op 按 delete/update/create 过滤。

4.12 repo：数据仓库快照

未初始化数据仓库密钥时直接报错（实测原文）：

$K -w $W repo create --memo "D1 实测快照"

Error: Please initialize the data repo key first in [Settings - Account & Sync - Data repo - Data repo key]

按提示在 Web 界面「设置 - 账号与同步 - 数据仓库 - 数据仓库密钥」初始化后，repo 族即可用：create --memo（建快照）、list [-p 页码] [--tag]（列快照）、checkout --id <快照ID>（回滚到快照）、diff（对比两快照）、tag/untag（打/去标签）、purge（清理旧快照）、search（快照内搜文件）、file（文件级快照操作）。快照是 CLI 批量改写前最可靠的安全网。

4.13 sync：云端同步

$K -w $W sync status

Enabled:   false
Mode:      auto
Provider:  SiYuan
Cloud:     main

sync 直接执行为触发一次同步，另有 push（上传）/pull（下载）/status（状态）。同步提供方（官方云/S3/WebDAV/本地）在 conf.json 的 sync 段配置（见《SiYuan 3.8.8 配置参数详解》 5.7 节）。

4.14 template / dailynote / tag / bookmark / ref

template（6 叶）：list/search/get/create（从 Markdown 建模板）/save-as（把文档存为模板）/render（预览渲染）/remove。模板存放于工作区 data/templates/。

dailynote（3 叶）：create --notebook <id>（创建今日日记）、append/prepend --notebook <id> --data|--file（向今日日记尾/首插入内容）——配合 cron 可实现自动打卡式记录。

tag（3 叶）与 bookmark（4 叶）：tag list [--keyword]/tag rename --old --new/tag remove --label；bookmark list/labels/rename --old --new/remove --label。标签由块属性 tags 驱动（4.4 的 attr set tags=实测,CLI 即产生标签）。

ref（3 叶）：backlinks --id <块ID>（反链）、mentions --id <块ID>（提及）、refresh（刷新反链索引），均有 --keyword 过滤与 --sort 排序（编码 0=updated-desc 等 8 种）。

4.15 辅助族速查

命令	作用	关键参数
`outline get --id <文档ID>`	取文档标题树	—
`database keys --av <视图ID>` 等 8 叶	属性视图（数据库）查询与行/字段管理	`--av` 必填
`inbox list [-p 页码]`	收集箱剪藏条目（需官方云）	—
`system current-time`	服务器时间（校时/探活）	实测输出 `2026-10-22T08:52:16+08:00`
`workspace list` / `workspace info`	已注册工作区 / 当前工作区信息	实测 info：`Path: /siyuan/workspace/ Version: 3.8.8 IsValid: true`
`completion bash\|zsh\|fish\|powershell`	生成 shell 补全脚本	按各 shell 说明 source 即可

五、注意事项

dry-run 优先：一切写操作先加 --dry-run 看动作描述（完整实测输出见 4.2：[dry-run] Would create document "CLI 实测文档" in notebook 20261022002307-05h9zc6），确认后再真执行——尤其 notebook remove/document remove/block delete。
CLI 直写后的索引可见性有延迟：实测创建文档后立即 sql 查询返回 No results.，稍候片刻（服务端监听到文件变更并重建索引，秒级）再查即出现结果；脚本化场景在「写后立即查」之间留出间隔或改用 HTTP API 同步通道。
同用户原则：CLI 与运行中服务以同一系统用户执行（见第六章 Q2 的 root 混用事故）。
与运行中服务可并行：实测服务运行期间全部 CLI 读写命令正常，无需停服；但批量改写前仍建议先快照（4.12）。
脚本化用 -f json：table 输出给人看，json 给程序解析（结构见 4.1/4.2 实测样例）。
服务端形态功能差异：export docx 等依赖桌面端能力的导出在服务端不可用；import md 反而是服务端独有价值的通道（界面无此入口）。

六、常见问题

Q1：repo 命令报 Please initialize the data repo key first？

数据仓库密钥未初始化。在 Web 界面「设置 - 账号与同步 - 数据仓库 - 数据仓库密钥」初始化（密钥务必另地备份，丢失即快照不可解密）后重试。

Q2：CLI 用 root 执行后，服务日志持续报 permission denied？

真实排障实录：以 root 执行 document create 等写命令后，工作区出现 root 属主文件（.sy 文档与 temp/queue/push.queue 等），服务进程（uid 1000）无法写，日志每 3 秒刷一条：

E 2026/10/22 08:47:56 push_queue.go:249: clear push queue failed: truncate /siyuan/workspace/temp/queue/push.queue: permission denied

定位：ls -la /siyuan/workspace/temp/queue/ 见属主为 root。修复（改回服务用户属主后自动恢复，实测日志不再新增报错）：

chown -R 1000:1000 /siyuan/workspace

预防：CLI 永远以服务同一用户执行（实测 su siyuan -s /bin/sh -c "/opt/siyuan/kernel -w /siyuan/workspace/ notebook list" 以 uid 1000 运行正常，输出与 root 视角一致；或配置一致的调度用户）。

Q3：sql 查不到刚通过 CLI 写入的数据？

见第五章第 2 条：索引由运行中的服务异步重建，写后立即查会短暂查不到；等待数秒重查，或写操作改走 HTTP API（同步返回）。

Q4：CLI 会跟正在运行的 Web 服务冲突吗？

不会。实测服务运行中完成笔记本/文档/块全生命周期读写（4.1–4.4）均正常。SiYuan 的工作区锁在进程内协调；唯一要避免的是「多个写方同时改同一篇文档」，与多窗口编辑同理。

Q5：如何把 CLI 输出接进脚本？

统一 -f json。例如列出全部笔记本 ID：

$K -w $W notebook list -f json | python3 -c "import json,sys; [print(n['id'], n['name']) for n in json.load(sys.stdin)]"

20261022002307-05h9zc6 运维手册

七、参考链接

官方 GitHub 仓库（Command-line Interface 章节）：https://github.com/siyuan-note/siyuan （查询日期 2026-10-22）
官方 Kernel HTTP API 文档（CLI 之外的自动化通道）：https://github.com/siyuan-note/siyuan/blob/master/docs/API.md （查询日期 2026-10-22）
部署环境与运维命令：《SiYuan 3.8.8 Docker Compose 部署指南》
配置参数与生效机制：《SiYuan 3.8.8 配置参数详解》
认知与选型：《SiYuan 3.8.8 介绍与选型指南》