Metadata-Version: 2.4
Name: siyuan-cli
Version: 1.1.0
Summary: CLI tool + MCP server + Agent Skills for SiYuan Note (思源笔记) — zero deps, permission system, workspace management
Author: Mino
License-Expression: MIT
Project-URL: Homepage, https://github.com/xingrove/siyuan-skills
Project-URL: Repository, https://github.com/xingrove/siyuan-skills
Keywords: siyuan,思源笔记,notes,markdown,pkm,self-hosted,agent-skills
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Text Editors :: Documentation
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: Chinese (Simplified)
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-timeout; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Dynamic: license-file

# SiYuan Agent Tools

[![PyPI](https://img.shields.io/pypi/v/siyuan-cli)](https://pypi.org/project/siyuan-cli/)
[![CI](https://github.com/xingrove/siyuan-skills/actions/workflows/ci.yml/badge.svg)](https://github.com/xingrove/siyuan-skills/actions)
[![Python](https://img.shields.io/pypi/pyversions/siyuan-cli)](https://pypi.org/project/siyuan-cli/)
[![License](https://img.shields.io/pypi/l/siyuan-cli)](LICENSE)
[![Tests](https://img.shields.io/badge/tests-229%20passed-brightgreen)](https://github.com/xingrove/siyuan-skills)

> [中文](README.md)

CLI tool, MCP server, and AI Agent Skills for [SiYuan Note](https://github.com/siyuan-note/siyuan). Pure Python, zero dependencies. Compatible with Claude Code, Codex, OpenCode, and Hermes.

---

## Install

```bash
pip install siyuan-cli
```

Or the one-command installer:

```bash
curl -fsSL https://raw.githubusercontent.com/xingrove/siyuan-skills/main/scripts/install.sh | bash
```

---

## Quick Start

```bash
siyuan config url http://127.0.0.1:6806
siyuan config token your-api-token

siyuan stats          # verify connectivity
```

> Token location: SiYuan Desktop → Settings → API; for Docker, in `conf.json`.

---

## CLI Reference

### Documents & Blocks

| Command | Description |
|---------|-------------|
| `siyuan create /path [content]` | Create a note (`--file` / `--stdin` supported) |
| `siyuan read /path` | Read document content |
| `siyuan delete /path [--id]` | Delete a note |
| `siyuan tree [notebook]` | Document tree |
| `siyuan doc rename <title>` | Rename document |
| `siyuan doc move <paths...> [--to-notebook]` | Move documents |
| `siyuan doc export /path [--id]` | Export as Markdown |
| `siyuan doc get-path <id>` | Resolve ID to path |

### Block Operations

| Command | Description |
|---------|-------------|
| `siyuan block get <id>` | Block info |
| `siyuan block children <id>` | Child blocks |
| `siyuan block append <id> -c <content>` | Append child block |
| `siyuan block prepend <id> -c <content>` | Prepend child block |
| `siyuan block insert <id> -c <content>` | Insert block after sibling |
| `siyuan block update <id> -c <content>` | Update block |
| `siyuan block delete <id>` | Delete block |
| `siyuan block move <id> --parent <pid>` | Move block |
| `siyuan block fold <id>` | Fold heading |
| `siyuan block unfold <id>` | Unfold |

### Block References & Embeds

| Command | Output | Description |
|---------|--------|-------------|
| `siyuan block ref <id>` | `((id 'title'))` | Block reference markup |
| `siyuan block embed <id>` | `{{embed ((id 'title'))}}` | Block embed markup |
| `siyuan block link <id>` | `siyuan://blocks/id` | SiYuan internal link |

```bash
REF=$(siyuan block ref 20200812220555-lj3enxa)
siyuan create "/article" "As mentioned in $REF..."
```

### Notebooks, Search & Daily Notes

| Command | Description |
|---------|-------------|
| `siyuan notebook list` | List notebooks |
| `siyuan notebook create <name>` | Create notebook |
| `siyuan notebook remove <id>` | Remove notebook |
| `siyuan notebook rename <id> <name>` | Rename |
| `siyuan notebook conf <id>` | Notebook config |
| `siyuan search <query>` | Full-text search |
| `siyuan sql <statement>` | SQL query (SELECT only) |
| `siyuan daily-note note` | Get or create today's note |
| `siyuan daily-note append <content>` | Append to today's note |

### Tags, Attributes & Assets

| Command | Description |
|---------|-------------|
| `siyuan tag list` | All tags |
| `siyuan tag blocks <tag>` | Find tagged blocks |
| `siyuan attr get <id>` | Block attributes |
| `siyuan attr set <id> <key> <val>` | Set attribute |
| `siyuan asset upload <file>` | Upload asset |
| `siyuan file list /data/` | List workspace files |
| `siyuan file put <local> <remote>` | Upload file |

### Batch & Utilities

| Command | Description |
|---------|-------------|
| `siyuan batch create <file>` | Batch create notes |
| `siyuan batch delete <file>` | Batch delete notes |
| `siyuan stats` | Workspace statistics |
| `siyuan overview` | Workspace overview |
| `siyuan health` | Diagnostic health check |
| `siyuan backlinks get <id>` | Block backlinks |
| `siyuan notify push <msg>` | Push notification to UI |
| `siyuan mcp` | Start MCP server |

---

## Global Options

| Option | Description |
|--------|-------------|
| `--format pretty\|json\|compact` | Output format |
| `--verbose` | Detailed logging |
| `--no-color` | Disable colored output |
| `--version` | Show version |
| `--yes` | Skip confirmation on destructive ops |
| `--dry-run` | Preview without applying |
| `@file:/path` | Read content from file |
| `@stdin` | Read content from stdin |

**Read-only mode:** `SIYUAN_READ_ONLY=true siyuan <cmd>` blocks all writes.

---

## Multi-Server

```bash
siyuan workspace add hk --url http://server:6806 --token xxx
siyuan workspace use hk
siyuan workspace list
```

---

## Permission System

```bash
siyuan permission deny --endpoint "*remove*"   # Block all deletes
siyuan permission ask --endpoint "*delete*"    # Ask before delete
siyuan permission list                          # Show rules
```

---

## MCP Server

```bash
siyuan-mcp
```

23 tools: CRUD, search, SQL, block refs/embeds, tags, attributes, health checks. Works with Claude Desktop, Cursor, and any MCP client.

---

## Agent Skills

| Agent | Install |
|-------|---------|
| **OpenCode** | `git clone https://github.com/xingrove/siyuan-skills.git ~/.opencode/skills/siyuan-skills` |
| **Codex CLI** | `cp -r skills/* ~/.codex/skills/` |
| **Hermes** | `cp -r skills/* ~/.hermes/skills/` |
| **npx** | `npx skills add https://github.com/xingrove/siyuan-skills` |

| Skill | Description |
|-------|-------------|
| [siyuan-cli](skills/siyuan-cli) | Operate SiYuan via CLI |
| [siyuan-api](skills/siyuan-api) | Direct REST API calls |
| [siyuan-markdown](skills/siyuan-markdown) | SiYuan-flavored Markdown reference |

---

## Configuration

Priority: `SIYUAN_URL` / `SIYUAN_TOKEN` env vars > active workspace > `~/.siyuan/config.json`

```json
{"url": "http://127.0.0.1:6806", "token": "your-token"}
```

Optional keyring storage:

```bash
pip install keyring
siyuan keyring-set your-token
siyuan keyring-unset
```

---

*Community project, not official.*
