Metadata-Version: 2.4
Name: siyuan-cli
Version: 1.7.1
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/RowanGrove/siyuan-skills
Project-URL: Repository, https://github.com/RowanGrove/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/RowanGrove/siyuan-skills/actions/workflows/ci.yml/badge.svg)](https://github.com/RowanGrove/siyuan-skills/actions)
[![Python](https://img.shields.io/pypi/pyversions/siyuan-cli)](https://pypi.org/project/siyuan-cli/)
[![Tests](https://img.shields.io/badge/tests-158%20passed-brightgreen)](https://github.com/RowanGrove/siyuan-skills)

> [中文](README.md)

CLI tool, MCP server, and AI Agent Skills for [SiYuan Note](https://github.com/siyuan-note/siyuan).

Compatible with Claude Code, Codex, OpenCode, and Hermes.

> Like [obsidian-skills](https://github.com/kepano/obsidian-skills) but for SiYuan.

---

## Install

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

Or the one-command installer:

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

## Quick Start

```bash
# Configure
siyuan config set url http://192.168.1.100:6806
siyuan config set token your-api-token

# Verify connectivity
siyuan stats
```

Your API token is in SiYuan Desktop → Settings → API, or in `conf.json` for Docker deployments.

## CLI Reference

### Documents

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

### Notebooks

| 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 |

### Search & SQL

| Command | Description |
|---------|-------------|
| `siyuan search <query>` | Full-text search |
| `siyuan sql <statement>` | Query blocks table |

### Daily Note

| Command | Description |
|---------|-------------|
| `siyuan daily-note note` | Get or create today's note |
| `siyuan daily-note append <content>` | Append to today's note |

### Blocks

| Command | Description |
|---------|-------------|
| `siyuan block get <id>` | Block info |
| `siyuan block children <id>` | Child blocks |
| `siyuan block insert -c <content>` | Insert block |
| `siyuan block delete <id>` | Delete block |
| `siyuan block fold <id>` | Fold heading |
| `siyuan block unfold <id>` | Unfold |

### Tags & Attributes

| Command | Description |
|---------|-------------|
| `siyuan tag list` | All tags |
| `siyuan tag blocks <tag>` | Find tagged blocks |
| `siyuan tag rename <old> <new>` | Rename tag |
| `siyuan attr get <id>` | Block attributes |
| `siyuan attr set <id> <key> <val>` | Set attribute |

### Files & Assets

| Command | Description |
|---------|-------------|
| `siyuan file list /data/` | List workspace files |
| `siyuan file get /path` | Get file content |
| `siyuan file put <local> <remote>` | Upload file |
| `siyuan asset upload <file>` | Upload asset |

### Batch & Other

| 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 notify push <msg>` | Push notification to UI |
| `siyuan backlinks get <id>` | Block backlinks |
| `siyuan mcp` | Start MCP server |

## Multi-Server

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

## Permission System

Control what AI agents can do:

```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
```

15 tools: CRUD, search, SQL, tags, permissions, health check. Compatible with Claude Desktop, Cursor, and any MCP client.

## 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
```

## Agent Skills

Install the skills so your AI agent can operate SiYuan directly:

```bash
# OpenCode
git clone https://github.com/RowanGrove/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/RowanGrove/siyuan-skills
```

| Skill | Description |
|-------|-------------|
| [siyuan-cli](skills/siyuan-cli) | Create, read, search, manage notes via CLI |
| [siyuan-api](skills/siyuan-api) | Raw SiYuan API calls with curl |
| [siyuan-markdown](skills/siyuan-markdown) | SiYuan-flavored Markdown reference |
