siyuan-agent (Direct HTTP)

Standalone CLI for SiYuan — direct HTTP API access, no npm dependencies.

Setup

1. Enable SiYuan API token: SiYuan → Settings → About → API token
2. Set the token:

export SIYUAN_TOKEN=your_token_here
export SIYUAN_BASE=http://127.0.0.1:6806   # optional, default shown

(Add these to your ~/.bashrc or ~/.zshrc to persist.)

You don't need to use the CLI yourself. Just tell your agent to read this SKILL.md — it will use this tool automatically.

Commands

Read

Write (requires write=true)

SQL Safety

The sql command only allows SELECT statements. Non-SELECT queries are rejected with an error.

Write Protection

Write operations (insertBlock, updateBlock, deleteBlock) require write=true.

The call command requires write=true for non-read paths (export, asset upload are treated as write paths).

Hard-Blocked Paths

These notebook operations are blocked and cannot be called:

• /api/notebook/createNotebook
• /api/notebook/removeNotebook
• /api/notebook/renameNotebook
• /api/notebook/closeNotebook
• /api/notebook/saveNotebookConf

Usage Examples

# Search
node siyuan.js search query=keyword

# Read a block
node siyuan.js getBlock id=20260321111240-o5xe15o

# Get document
node siyuan.js getDoc id=20260321111240-o5xe15o

# Get child blocks
node siyuan.js getChildren id=20260321111240-o5xe15o

# SQL query
node siyuan.js sql "SELECT id, type, content FROM blocks WHERE content LIKE '%keyword%' LIMIT 5"

# Write operation
node siyuan.js updateBlock id=20260321111240-o5xe15o data="New content" write=true

# Direct API call
node siyuan.js call path=/api/notebook/lsNotebooks '{}'

Files

siyuan.js   — CLI entry point (native fetch, no deps)
lib/api.js  — HTTP API caller