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:

bash

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#

CommandDescriptionsearch query=<kw>Full-text searchsearchByNotebook query=<kw> notebook=<id>Search in specific notebookgetDoc id=<blockID>Get documentgetBlock id=<blockID>Get single blockgetChildren id=<blockID>Get child blocksbacklinks id=<blockID>Find backlinksoutline id=<blockID>Get document outlinesql "SELECT ..."Execute SELECT-only SQLexportMd id=<docID>Export doc to markdowncall path=/api/... '{}'Any API endpoint directly

Write (requires write=true)#

CommandDescriptioninsertBlock parentID=<id> data="<content>" write=trueInsert blockupdateBlock id=<id> data="<content>" write=trueUpdate blockdeleteBlock id=<id> write=trueDelete block

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#

bash

# 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#

text

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