mcpField
C
cli-anything-siyuan

cli-anything-siyuan

github.com/hkudsProductivity57.6k201 installsUpdated 5w ago
Repository

About cli-anything-siyuan

A command-line harness for managing SiYuan notebooks, documents, and blocks through its local HTTP API. It is aimed at users and agents that need structured access to note operations, search, SQL, and Markdown export.

Key features

  1. 01Manage notebooks and documents
  2. 02Insert, update, delete, and inspect blocks
  3. 03Search block content and run SQL
  4. 04Export documents as Markdown
  5. 05JSON output and interactive REPL

Use cases

  1. 01Create and organize SiYuan notes from scripts
  2. 02Search notes or inspect block data
  3. 03Export a document to Markdown

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/hkuds/cli-anything --skill cli-anything-siyuan

After installing, type/cli-anything-siyuanin Claude Code to confirm it loaded.

Details

From the project README

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
SubcommandDescription
listList 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
SubcommandDescription
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
SubcommandDescription
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
CommandDescription
sql <stmt>Execute SQL on the block database
search <query>Full-text search across blocks
export md <doc-id>Export document as Markdown
tag listList all tags
versionShow SiYuan kernel version
statusShow connection and session status
replStart 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

Comments

Markdown supported