OpenParable
Skip to content
← Back to skills

CLI Anything Siyuan

Apps & Automation
cli-anything-siyuan

CLI Anything Siyuan is an Agent Skill for apps & automation published in the HKUDS/CLI-Anything repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

SiYuan (思源笔记) CLI — manage notebooks, documents, blocks, and search your knowledge base from the terminal.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/HKUDS/CLI-Anything/blob/HEAD/siyuan/agent-harness/cli_anything/siyuan/skills/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/cli-anything-siyuan, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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