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