siyuan-cli 1.2.0

CLI tool + MCP server + Agent Skills for SiYuan Note (思源笔记) — zero deps, permission system, workspace management

SiYuan Agent Tools

中文

CLI tool, MCP server, and AI Agent Skills for SiYuan Note. Pure Python, zero dependencies. Compatible with Claude Code, Codex, OpenCode, and Hermes.

---

Install

pip install siyuan-cli

Or the one-command installer:

curl -fsSL https://raw.githubusercontent.com/xingrove/siyuan-skills/main/scripts/install.sh | bash

---

Quick Start

siyuan config url http://127.0.0.1:6806
siyuan config token your-api-token

siyuan stats          # verify connectivity

Token location: SiYuan Desktop → Settings → API; for Docker, in conf.json.

---

CLI Reference

Documents & Blocks

Command	Description
siyuan create /path [content]	Create a note (--file / --stdin supported)
siyuan read /path	Read document content
siyuan delete /path [--id]	Delete a note
siyuan tree [notebook]	Document tree
siyuan doc rename <title>	Rename document
siyuan doc move <paths...> [--to-notebook]	Move documents
siyuan doc export /path [--id]	Export as Markdown
siyuan doc get-path <id>	Resolve ID to path

Block Operations

Command	Description
siyuan block get <id>	Block info
siyuan block children <id>	Child blocks
siyuan block append <id> -c <content>	Append child block
siyuan block prepend <id> -c <content>	Prepend child block
siyuan block insert <id> -c <content>	Insert block after sibling
siyuan block update <id> -c <content>	Update block
siyuan block delete <id>	Delete block
siyuan block move <id> --parent <pid>	Move block
siyuan block fold <id>	Fold heading
siyuan block unfold <id>	Unfold

Block References & Embeds

Command	Output	Description
siyuan block ref <id>	((id 'title'))	Block reference markup
siyuan block embed <id>	{{embed ((id 'title'))}}	Block embed markup
siyuan block link <id>	siyuan://blocks/id	SiYuan internal link

REF=$(siyuan block ref 20200812220555-lj3enxa)
siyuan create "/article" "As mentioned in $REF..."

Notebooks, Search & Daily Notes

Command	Description
siyuan notebook list	List notebooks
siyuan notebook create <name>	Create notebook
siyuan notebook remove <id>	Remove notebook
siyuan notebook rename <id> <name>	Rename
siyuan notebook conf <id>	Notebook config
siyuan search <query>	Full-text search
siyuan sql <statement>	SQL query (SELECT only)
siyuan daily-note note	Get or create today's note
siyuan daily-note append <content>	Append to today's note

Tags, Attributes & Assets

Command	Description
siyuan tag list	All tags
siyuan tag blocks <tag>	Find tagged blocks
siyuan attr get <id>	Block attributes
siyuan attr set <id> <key> <val>	Set attribute
siyuan asset upload <file>	Upload asset
siyuan file list /data/	List workspace files
siyuan file put <local> <remote>	Upload file

Batch & Utilities

Command	Description
siyuan batch create <file>	Batch create notes
siyuan batch delete <file>	Batch delete notes
siyuan stats	Workspace statistics
siyuan overview	Workspace overview
siyuan health	Diagnostic health check
siyuan backlinks get <id>	Block backlinks
siyuan notify push <msg>	Push notification to UI
siyuan mcp	Start MCP server

---

Global Options

Option	Description
--format pretty|json|compact	Output format
--verbose	Detailed logging
--no-color	Disable colored output
--version	Show version
--yes	Skip confirmation on destructive ops
--dry-run	Preview without applying
@file:/path	Read content from file
@stdin	Read content from stdin

Read-only mode: SIYUAN_READ_ONLY=true siyuan <cmd> blocks all writes.

---

Multi-Server

siyuan workspace add hk --url http://server:6806 --token xxx
siyuan workspace use hk
siyuan workspace list

---

Permission System

siyuan permission deny --endpoint "*remove*"   # Block all deletes
siyuan permission ask --endpoint "*delete*"    # Ask before delete
siyuan permission list                          # Show rules

---

MCP Server

siyuan-mcp

23 tools: CRUD, search, SQL, block refs/embeds, tags, attributes, health checks. Works with Claude Desktop, Cursor, and any MCP client.

---

Agent Skills

Agent	Install
OpenCode	git clone https://github.com/xingrove/siyuan-skills.git ~/.opencode/skills/siyuan-skills
Codex CLI	cp -r skills/* ~/.codex/skills/
Hermes	cp -r skills/* ~/.hermes/skills/
npx	npx skills add https://github.com/xingrove/siyuan-skills

Skill	Description
siyuan-cli	Operate SiYuan via CLI
siyuan-api	Direct REST API calls
siyuan-markdown	SiYuan-flavored Markdown reference

---

Configuration

Priority: SIYUAN_URL / SIYUAN_TOKEN env vars > active workspace > ~/.siyuan/config.json

{"url": "http://127.0.0.1:6806", "token": "your-token"}

Optional keyring storage:

pip install keyring
siyuan keyring-set your-token
siyuan keyring-unset

---

Community project, not official.