# Siyuan CLI

> 操作思源笔记的 CLI 工具。当用户要求管理思源笔记的笔记本、文档、块、标签、搜索、SQL 查询、导入导出、资源、同步，或配置 auth、AI chat、MCP Server 时使用此 skill。

- Skill: `justcyl/siyuan-cli` (Agent Skill)
- Install (CLI): `npx skillmds@latest add justcyl/siyuan-cli`
- Raw SKILL.md: https://api.skillmd.com/api/skills/justcyl/siyuan-cli/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Data & Analytics
- Author: justcyl (https://skillmd.com/u/justcyl)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/justcyl/siyuan-cli

---


# siyuan-cli 使用指南

可执行文件：全局命令 `siyuan-cli`
全局选项：`--format json` 输出 JSON；支持 `--output/-o <file>` 的命令可导出到文件

## 前置条件

思源笔记实例需已运行，默认地址为 `http://127.0.0.1:6806`。首次使用或连接失败时，先执行：

```bash
siyuan-cli auth login --url http://127.0.0.1:6806 --token <api-token>
siyuan-cli auth status
```

API token 在思源笔记「设置 -> 关于 -> API token」获取。不要在回复中展示用户的 token。

## 笔记本

```bash
siyuan-cli notebook list                              # 列出所有笔记本
siyuan-cli notebook list --closed                     # 包含已关闭
siyuan-cli notebook create "名称"                      # 创建
siyuan-cli notebook rename <nb> "新名"                  # 重命名
siyuan-cli notebook open <nb>                          # 打开
siyuan-cli notebook close <nb>                         # 关闭
siyuan-cli notebook delete <nb> -F                     # 删除（-F 强制）
siyuan-cli notebook getconf <nb>                       # 获取配置
siyuan-cli notebook setconf <nb> --sort 1              # 设置配置
```

`<nb>` 支持笔记本名称（模糊匹配）或笔记本 ID。

## 文档

```bash
siyuan-cli document list <nb>                          # 列出文档（depth=1）
siyuan-cli document list <nb> --depth 0                # 全部展开
siyuan-cli document list <nb> --path "/技术"           # 指定路径
siyuan-cli document get <nb> <doc-path>                # 获取 Markdown 内容
siyuan-cli document get <nb> <doc-path> -o output.md   # 导出到文件
siyuan-cli document outline <doc-id>                   # 大纲（支持 doc-id 或 nb/path）
siyuan-cli document createMd <nb> --title "标题" --content "# 标题\n内容"
siyuan-cli document createMd <nb> --file readme.md --path "/目录"
siyuan-cli document rename <nb> <path> "新名"
siyuan-cli document move <nb> <src> <dest>             # 支持跨笔记本：nb2:/path
siyuan-cli document copy <nb> <doc-path>
siyuan-cli document delete <nb> <doc-path>
siyuan-cli document daily --notebook <nb>              # 创建今日日记
siyuan-cli document history <nb> <path>                # 查看历史
siyuan-cli document history --query "关键词"            # 搜索历史
siyuan-cli document rollback --notebook <nb> --to <history-path>  # 回滚
```

## 搜索与查询

```bash
siyuan-cli search doc "关键词"                          # 按标题搜索
siyuan-cli search block "关键词"                        # 全文搜索块内容
siyuan-cli search block "关键词" --notebook <nb> -l 50  # 限定范围和数量
siyuan-cli query "SELECT id, content FROM blocks WHERE content LIKE '%关键词%'" -o result.json
```

SQL 仅限 SELECT。blocks 表常用字段：`id, type, content, hpath, box, created, updated`。

## 块

```bash
siyuan-cli block get <block-id>
siyuan-cli block source <block-id>                     # kramdown 源码
siyuan-cli block update <block-id> --content "新内容"
siyuan-cli block append <doc-id> --content "## 新段落"   # 也支持 nb/path
siyuan-cli block delete <block-id> --force
```

`block append` 的 `--type` 参数：`markdown`（默认）或 `dom`。

## 标签

```bash
siyuan-cli tag list
siyuan-cli tag search "关键词"
siyuan-cli tag add <doc-id> --tag "标签1" --tag "标签2"  # 支持 doc-id 或 nb/path
siyuan-cli tag remove <doc-id> --tag "标签"
```

## 导入导出

```bash
siyuan-cli export doc <doc-id|nb> [path] --format html -o output.html
siyuan-cli export doc <doc-id|nb> [path] --format md
siyuan-cli export notebook <nb> --format md -o ./backup/
siyuan-cli export notebook <nb> --format sy -o ./backup/
siyuan-cli import md <file-or-dir> --notebook <nb> --path "目标路径"
siyuan-cli import sy <file-or-dir> --notebook <nb>
```

## 资源与同步

```bash
siyuan-cli asset upload <file>
siyuan-cli asset list <doc-id|nb> [path]
siyuan-cli asset unused                                # 未使用资源
siyuan-cli asset clean -F                              # 清理未使用资源
siyuan-cli sync status
siyuan-cli sync now
```

## 其他

```bash
siyuan-cli fav "收藏内容"                              # 收藏到"我的收藏"笔记本
siyuan-cli auth status                                # 查看连接状态
siyuan-cli auth logout                                # 清除连接配置
siyuan-cli config list                                 # 查看配置
siyuan-cli config get <key>                            # 获取配置项
siyuan-cli config set <key> <value>                    # 设置配置项
siyuan-cli chat "问题"                                 # 基于笔记内容单轮问答
siyuan-cli chat                                        # 进入多轮对话
siyuan-cli mcp                                         # 启动 stdio MCP Server
siyuan-cli version                                     # 版本信息
```

AI 对话需要额外配置兼容 OpenAI 的模型服务：

```bash
siyuan-cli config set ai.base_url <base-url>
siyuan-cli config set ai.api_key <api-key>
siyuan-cli config set ai.model <model>
```

MCP 客户端配置示例：

```json
{
  "mcpServers": {
    "siyuan": {
      "command": "siyuan-cli",
      "args": ["mcp"]
    }
  }
}
```

## 注意事项

- 笔记本/文档路径支持名称模糊匹配和 ID 精确匹配
- 文档路径用人类可读格式（如 `java面试/AI/index`），不用 `.sy` 后缀
- `--output/-o` 自动使用 JSON 格式
- `--format json` 为全局选项，放在命令前
- 删除操作建议加 `-F/--force` 避免交互确认阻塞
- `document history --query` 可搜索全局历史，不限定笔记本
- 涉及删除、回滚、清理资源、同步等会改变数据的命令，执行前向用户确认目标和范围
- 不要泄露 `api_token`、`ai.api_key` 或配置文件中的其他凭据