cli-anything-siyuan

CLI harness for SiYuan (思源笔记), a local-first knowledge management and note-taking application.

This CLI connects to a running SiYuan kernel via its HTTP API (http://127.0.0.1:6806) and provides structured access to notebooks, documents, blocks, search, and export.

Prerequisites

• SiYuan must be running (Settings → About shows the API token)
• Python 3.10+
• Install: pip install cli-anything-siyuan or pip install -e . from agent-harness/

Command Groups

notebook — Notebook management

Subcommand	Description
list	List all notebooks
create <name>	Create a new notebook
rename <id> <name>	Rename a notebook
remove <id>	Delete a notebook
open <id>	Open a notebook

doc — Document management

Subcommand	Description
create <notebook> <path> [--md "content"]	Create a document
list <notebook> [path]	List documents
tree <notebook> [--path / --depth]	Show doc tree
get <id>	Get document path by ID
rename <id> <title>	Rename a document
remove <id>	Delete a document

block — Block operations

Subcommand	Description
insert <data> [--previous / --parent]	Insert a block
update <id> <data>	Update a block
delete <id>	Delete a block
get <id>	Get block kramdown source
children <id>	Get child blocks

Other commands

Command	Description
sql <stmt>	Execute SQL on the block database
search <query>	Full-text search across blocks
export md <doc-id>	Export document as Markdown
tag list	List all tags
version	Show SiYuan kernel version
status	Show connection and session status
repl	Start interactive REPL

Agent Guidance

• Always use --json for machine-readable output
• Power search: use sql "SELECT * FROM blocks WHERE content LIKE '%keyword%'" for SQL-level access
• Document IDs look like 20210817205410-2kvfpfn (timestamp-based)
• API token can be found in SiYuan Settings → About
• Connection defaults: http://127.0.0.1:6806

Examples

# List notebooks (JSON)
cli-anything-siyuan --json notebook list

# Create a document with Markdown (--md flag, watch shell escaping)
cli-anything-siyuan doc create nb1 /projects/new --md "## Title\n\nContent"

# Create a document — pipe Markdown via stdin (avoids shell escaping)
# PowerShell here-string (literal, no escaping needed):
@'
## Title
Content with `backticks` and (parentheses) and "quotes"
'@ | cli-anything-siyuan doc create nb1 /projects/new --md -

# Bash heredoc:
# cat <<'EOF' | cli-anything-siyuan doc create nb1 /projects/new --md -
# ## Title
# Content with `backticks` and (parentheses)
# EOF

# SQL search
cli-anything-siyuan sql "SELECT id, content FROM blocks WHERE content LIKE '%meeting%' LIMIT 5"

# Export
cli-anything-siyuan export md doc123

# Enter REPL
cli-anything-siyuan

Error Handling

• Connection errors: check that SiYuan is running and the API token is correct
• API errors: returned as {"code": N, "msg": "..."} — check the message field
• Auth errors: verify the token in ~/.siyuan-cli.json or SIYUAN_TOKEN env var