/cli-anything-siyuan

name: "cli-anything-siyuan"
description: SiYuan (思源笔记) CLI — manage notebooks, documents, blocks, and search your knowledge base from the terminal.

cli-anything-siyuan

CLI harness for [SiYuan](https://github.com/siyuan-note/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