Cli Anything Siyuan

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

doc — Document management

block — Block operations

Other commands

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