siyuan-cli

name	siyuan-cli
description	Use when a task mentions siyuan, siyuan-cli, note-taking, thought-note workflows, PKM, 笔记, or 思源笔记 and needs real CLI commands to search notes, inspect notebooks, read or update documents, export content, or automate SiYuan workflows instead of guessing HTTP API calls.

siyuan-cli

Overview

Use this skill when an agent should operate SiYuan through the real CLI in this repository. Prefer direct npx siyuan-cli commands over hand-written API requests for search, document edits, exports, notebook inspection, and other task-oriented note workflows.

This package is intended to be published to npm. Default examples and recommendations should use npx siyuan-cli <command>.

When to Use

• User mentions siyuan, siyuan-cli, 思源笔记, 笔记, note-taking, thought-note, or PKM workflows
• Need real siyuan-cli commands instead of guessed HTTP calls
• Need IDs or structured results from SiYuan for follow-up automation
• Need to read, create, update, append, move, export, or remove note content
• Need notebook, block, tag, file, snapshot, template, notification, SQL, or system operations

Requirements

• Ensure SIYUAN_BASE_URL and SIYUAN_TOKEN are set
• Prefer npm package execution via npx siyuan-cli <command>
• Run from the repository root only when developing or testing the package locally
• Build first if using the repo checkout directly: npm install && npm run build

Recommended npm invocation:

npx siyuan-cli --help

Repo-local invocation:

node dist/src/cli/run.js --help

Optional global invocation if already installed:

npm install -g siyuan-cli
siyuan-cli --help

Quick Reference

Task	Command pattern
Search notes	npx siyuan-cli search --content <text> --json
Read a document	npx siyuan-cli doc get --id <document-id>
Create a document	npx siyuan-cli doc create --notebook <id> --path <path> --content-file <file>
Update a document	npx siyuan-cli doc update --id <document-id> --content-file <file>
Append to a document	npx siyuan-cli doc append --id <document-id> --content <text>
Export Markdown	npx siyuan-cli export markdown --id <document-id> --json
List notebooks	npx siyuan-cli notebook list --json
Run SQL	npx siyuan-cli sql query --statement <sql> --json

Recommended Patterns

• Default to npx siyuan-cli <command> when showing end-user usage because the package is published to npm
• Prefer --json when the result will be consumed by another command or parsed by an agent
• Use search first, then feed returned IDs into doc, export, block, or attr commands
• Use --content-file for larger Markdown updates and --content for short inline edits
• Use npx siyuan-cli <group> --help when you need the exact subcommand surface

Chinese Usage Shortcuts

• 搜索思源笔记 / 搜索笔记 -> npx siyuan-cli search --content <关键词> --json
• 读取笔记 / 读取文档 -> npx siyuan-cli doc get --id <document-id>
• 新建笔记 / 创建文档 -> npx siyuan-cli doc create --notebook <id> --path <path> --content-file <file>
• 更新笔记 / 追加内容 -> npx siyuan-cli doc update ... or npx siyuan-cli doc append ...
• 导出思源笔记 -> npx siyuan-cli export markdown|html|pdf|docx --id <document-id>

Examples:

npx siyuan-cli search --content "roadmap" --json
npx siyuan-cli doc get --id 20260316120000-abc123
npx siyuan-cli doc update --id 20260316120000-abc123 --content-file ./draft.md
npx siyuan-cli export markdown --id 20260316120000-abc123 --json

Safety Notes

• Destructive commands require explicit --yes; do not add it unless the task really intends mutation
• Double-check IDs, labels, and file paths before mutation
• If you need stable IDs from search, rerun with --json
• doc create, doc update, and doc append can upload and rewrite Markdown image links automatically

Common Mistakes

Mistake	Fix
Guessing HTTP endpoints	Use the real siyuan-cli command family first
Forgetting env vars	Export SIYUAN_BASE_URL and SIYUAN_TOKEN before running commands
Parsing human text for IDs	Use --json
Showing global install first	Prefer npx siyuan-cli <command> as the default npm usage
Using destructive commands casually	Omit --yes until the target is verified
Updating large Markdown inline	Prefer --content-file