siyuan-note-cli

A powerful command-line interface for SiYuan Note, built with TypeScript and Node.js.

Compatibility: Tested with SiYuan Note 3.6.5. Some features, especially database (Attribute View) operations, depend on SiYuan's internal APIs and may need updates for newer versions.

Features

• Complete notebook & document management: create, list, rename, move, delete.
• Block-level operations: insert, append, update, delete, move, get Kramdown source.
• Powerful search: full-text search and raw SQL queries.
• Custom attributes: read/write block attributes.
• Asset upload & export: upload files and export documents.
• Experimental database (Attribute View) support: create databases, manage fields and rows.
• AI-ready: bundled Kimi Skill for AI agent integration.
• Multiple output formats: human-readable tables, JSON, YAML.

Installation

From npm (recommended)

npm install -g siyuan-note-cli

Then use either of the provided binaries:

siyuan --version
sy --version

Note: The sy binary name is convenient but may conflict if you have another global package providing a sy command.

From source

git clone https://github.com/mexhfl/siyuan-note-cli.git
cd siyuan-note-cli
npm install
npm run build

Local usage

node ./bin/siyuan.js --version

Global link

npm link
siyuan --version

Quick Start

1. Configure connection

Get your API token from SiYuan: Settings → About → API Token.

siyuan auth login --url http://127.0.0.1:6806 --token <your-token>

Or use environment variables:

export SIYUAN_API_URL=http://127.0.0.1:6806
export SIYUAN_API_TOKEN=<your-token>

2. Verify connection

siyuan auth status

3. List notebooks

siyuan notebook list

4. Create a document

siyuan document create <notebook-id> "/daily/2026-01-15" \
  --title "今日总结" \
  --content "# 今日总结\n\n完成了..."

5. Search

siyuan search docs "项目计划"
siyuan search blocks "关键结论"

Command Overview

siyuan auth [status|login|logout]
siyuan notebook [list|create|rename|delete|open|close]
siyuan document [list|get|create|rename|delete|move|outline]
siyuan block [get|source|children|insert|append|update|delete|move]
siyuan search [docs|blocks]
siyuan query <sql>
siyuan attr [get|set|delete]
siyuan asset upload
siyuan export doc
siyuan sync [status|now]
siyuan config [list|get|set]
siyuan database [list|create|get|delete|field|row|view]

See docs/COMMANDS.md for detailed command reference.

Output Formats

All commands support --format (or -f):

siyuan notebook list --format json
siyuan document get <id> --format yaml

Database Support (Experimental)

SiYuan's database feature (Attribute View) is supported through internal /api/av/* APIs. These commands are marked as experimental and may change with SiYuan updates.

siyuan database create "任务数据库" --notebook <notebook-id>
siyuan database field add <db-id> "状态" --type select
siyuan database row add <db-id> --values "名称=完成设计,状态=已完成"

See docs/DATABASE_EXPERIMENTAL.md for details.

AI Skill

This project includes a Kimi Skill for AI agent integration.

Install the skill:

node scripts/install-skill.js

Or manually copy src/skill/siyuan-note-cli/ to ~/.kimi/skills/siyuan-note-cli/.

See docs/SKILL_USAGE.md for details.

Development

See docs/DEVELOPMENT.md.

Contributing

Contributions are welcome! Please open an issue or pull request on GitHub.

Changelog

See CHANGELOG.md.

License

MIT