Metadata-Version: 2.4
Name: siyuan-cli
Version: 1.7.0
Summary: CLI tool and Agent Skills for SiYuan Note
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
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
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 Skills

Agent Skills for [SiYuan Note](https://github.com/siyuan-note/siyuan) — the self-hosted, block-based note-taking platform.

These skills follow the [Agent Skills specification](https://agentskills.io/specification) so they can be used by any skills-compatible agent, including Claude Code, Codex, OpenCode, and Hermes.

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

---

## Skills

| Skill | Description |
|-------|-------------|
| [siyuan-cli](skills/siyuan-cli) | Create, read, search, and manage notes using the `siyuan` CLI tool (recommended) |
| [siyuan-api](skills/siyuan-api) | Call the SiYuan REST API directly with curl — no CLI needed |
| [siyuan-markdown](skills/siyuan-markdown) | How to write SiYuan-flavored Markdown with block references, tags, and embeds |

---

## Quick Start

### Install via pip (any platform)

```bash
pip install git+https://github.com/RowanGrove/siyuan-skills.git
```

Or from a local clone:

```bash
git clone https://github.com/RowanGrove/siyuan-skills.git
cd siyuan-skills
pip install .
```

### Or use the one-command installer

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

What it does:
1. Downloads `siyuan-cli.py` to `/usr/local/bin/siyuan` (or `~/.local/bin`)
2. Auto-detects API token from common SiYuan config paths
3. Writes `~/.siyuan/config.json` so it works immediately
4. Runs `siyuan stats` to verify

If auto-detection didn't find your SiYuan config:

```bash
siyuan config set token "your-api-token"
```

> **Where's the token?** SiYuan Desktop → Settings → API → Token.
> Docker/1Panel: `conf.json → api.token` (accessible via Web UI or container exec).

### Switch between instances

```bash
# Local Desktop (default)
siyuan stats

# Hong Kong server (one-off)
SIYUAN_URL=http://your-server:6806 siyuan list-notebooks

# Save a different default
siyuan config set url "http://192.168.1.100:6806"
siyuan config set token "other-token"
```

### Encrypted token storage (optional)

```bash
pip install keyring
siyuan keyring-set "your-api-token"    # Store token in OS keyring
siyuan keyring-unset                   # Remove token from keyring
```

### Install the skills for your AI agent

**OpenCode:**
```bash
git clone https://github.com/RowanGrove/siyuan-skills.git ~/.opencode/skills/siyuan-skills
```

**Codex CLI:**
```bash
cp -r skills/* ~/.codex/skills/
```

**Claude Code:**
Add the `skills/` directory to your project's `.claude/skills/` folder.

**Hermes Agent:**
```bash
cp -r skills/* ~/.hermes/skills/
```

**Via npx skills:**
```bash
npx skills add https://github.com/RowanGrove/siyuan-skills
```

---

## CLI Reference

All commands available via `siyuan <command> [subcommand] [options]`.

```
# Documents (flat — legacy, shorter)
siyuan create <path> [content]      Create a note
siyuan read <path>                  Read note content
siyuan delete <path> [--id]         Delete a note (by path or block ID)
siyuan export <path> [--id]         Export note by path (deprecated) or --id
siyuan tree [notebook_id]           Show document tree

# Documents (hierarchical — richer)
siyuan doc create <path> [content]  Create a note
siyuan doc read <path>              Read note content
siyuan doc delete <path>            Delete a note
siyuan doc export <path>            Export note as Markdown
siyuan doc export --id <id>         Export note by block ID
siyuan doc tree [notebook_id]       Show document tree
siyuan doc rename <title> [--id|--path]  Rename a document
siyuan doc move <paths...> [--to-notebook]  Move document(s)
siyuan doc get-path <id>            Resolve block ID to path

# Search & SQL
siyuan search <query>               Full-text search
siyuan sql <statement>              Query the blocks table

# Notebooks
siyuan list-notebooks               List notebooks (alias)
siyuan notebook list                List notebooks with icons & status
siyuan notebook create <name>       Create a notebook
siyuan notebook remove <id>         Remove a notebook (irreversible)
siyuan notebook rename <id> <name>  Rename a notebook
siyuan notebook conf <id>           Get notebook configuration
siyuan notebook set-conf <id> k=v   Update notebook configuration
siyuan notebook open <id>           Open a notebook
siyuan notebook close <id>          Close a notebook

# Blocks
siyuan block get <id>               Get block info
siyuan block children <id>          Get child blocks
siyuan block insert <parent> -c     Insert block after sibling
siyuan block prepend <id> -c        Prepend block as first child
siyuan block append <id> -c         Append block as last child
siyuan block update <id> -c         Update block content
siyuan block delete <id>            Delete a block
siyuan block move <id> --parent     Move a block
siyuan block fold <id>              Fold (collapse) a block
siyuan block unfold <id>            Unfold (expand) a block
siyuan block transfer-ref <f> <t>   Transfer block references
siyuan backlinks get <id>            Find backlinks for a block
siyuan backlinks breadcrumb <id>     Get breadcrumb path for a block

# Tags
siyuan tag list                     List all tags
siyuan tag blocks <tag>             Find blocks with a tag
siyuan tag rename <old> <new>       Rename a tag (unavailable on 3.6.x — use Web UI)
siyuan tag remove <tag>             Remove a tag (unavailable on 3.6.x — use Web UI)

# Assets
siyuan asset upload <file>          Upload an asset file
siyuan asset list                   List uploaded assets

# Attributes
siyuan attr get <id>                Get block attributes
siyuan attr set <id> <k> <v>        Set block attribute

# Templates
siyuan template render <id> <path>  Render a template file
siyuan template render-sprig <str>  Render a Sprig template string

# File operations (workspace files)
siyuan file get <path> [-o out]     Read file from workspace
siyuan file put <local> <dest>      Write file to workspace
siyuan file remove <path>           Delete a workspace file
siyuan file rename <a> <b>          Rename a workspace file
siyuan file list <dir>              List workspace directory

# Export
siyuan export-resources <paths...>  Export files/folders as zip archive
siyuan export-resources --name <n>  Custom zip file name

# Notifications
siyuan notify push <msg>            Push notification to SiYuan UI
siyuan notify push-err <msg>        Push error notification

# Batch operations
siyuan batch create <file>          Create docs from JSONL file
siyuan batch delete <file>          Delete docs listed in JSONL
siyuan batch tag <file>             Tag blocks listed in JSONL
siyuan batch export <file>          Export docs listed in JSONL

# Config & Stats
siyuan config                       Show CLI connection config
siyuan config set <key> <val>       Save CLI config (url|token)
siyuan config-get [key]             Read SiYuan server config value
siyuan keyring-set <token>          Store token in OS keyring
siyuan keyring-unset                Remove token from keyring
siyuan stats                        Show workspace statistics

# Overview
siyuan overview                      Workspace overview (notebooks, recent docs, stats)

# Daily note
siyuan daily-note note               Get or create today's daily note
siyuan daily-note append <content>   Append content to today's daily note

# Permission management
siyuan permission list                List all permission rules
siyuan permission check <endpoint>    Check if an endpoint is allowed
siyuan permission allow|deny|ask      Add a permission rule
  --endpoint <pattern>  Endpoint glob (e.g. *remove*)
  --notebook <id>       Restrict to notebook
  --path <pattern>      Restrict to path

# Workspace management
siyuan workspace list                List saved SiYuan instances
siyuan workspace which               Show current workspace
siyuan workspace add <name>          Add or update a workspace
  --url <url>          SiYuan instance URL
  --token <token>      API token
siyuan workspace use <name>          Switch to a workspace
siyuan workspace remove <name>       Remove a workspace

# MCP server
siyuan mcp                           Start MCP protocol server (JSON-RPC over stdio)

# Global flags
--format pretty|json|compact         Output format (default: pretty)
--json                               Shortcut for --format json (overrides --format)
--verbose, -v                        Enable debug logging
--log-file <path>                    Write logs to file
--no-color                           Disable ANSI color output (also respects NO_COLOR env)
--version                            Show version number
```

Config resolution order: `SIYUAN_*` env var > system keyring > `~/.siyuan/config.json` > `/tmp/siyuan_token`

---

## Agent Workflows

Once the CLI and skills are installed, your agent can:

| Task | Example prompt |
|------|---------------|
| Create a note | "在思源建一个笔记，记录今天的会议" |
| Read notes | "帮我读一下技术笔记里的部署记录" |
| Search | "搜一下思源里关于 API 的内容" |
| List notebooks | "看看我有哪些笔记本" |
| Stats | "思源现在有多少笔记了？" |
| Export | "把这个笔记导出来" |
| Batch import | "把这批文档批量导入思源" |

---

## Architecture

```
┌──────────────────────────────────────────────────────────┐
│                     Agent                                 │
│  ┌──────────────┐    SSH / direct      ┌──────────────┐  │
│  │  SKILL.md     │ ──── instructs ──▶  │  siyuan CLI  │  │
│  │  guides the   │                     │  (package)   │──┼──▶ SiYuan API
│  │  agent        │ ◀─── returns ────  │              │  │     (port 6806)
│  └──────────────┘                     └──────────────┘  │
│                                                    │
│  Config: ~/.siyuan/config.json + system keyring     │
│  Env:    SIYUAN_URL, SIYUAN_TOKEN                   │
└──────────────────────────────────────────────────────────┘

Package internals:

  siyuan_cli/
  ├── __init__.py          # Package metadata (version 1.7.0)
  ├── __main__.py          # `python -m siyuan_cli` entry point
  ├── cli.py               # CLI entry with argparse (all subcommands)
  ├── client.py            # SiYuanClient class (lazy config, retry, error handling)
  ├── config.py            # Config resolution: env → keyring → file → /tmp
  ├── exceptions.py        # SiYuanError hierarchy (8 exception types)
  ├── permissions.py       # Permission engine (allow/deny/ask rules)
  ├── utils.py             # escape_sql, validate_path, validate_id, logging, output formatting
  ├── workspace.py         # Multi-instance workspace profiles
  └── commands/
      ├── asset.py         # Upload/list assets
      ├── attr.py          # Block attribute get/set
      ├── backlinks.py     # Block backlinks, breadcrumb
      ├── batch.py         # Batch create/delete/tag/export
      ├── block.py         # Block CRUD, fold, transfer-ref, siblings
      ├── config_cmd.py    # Config show/set, keyring-set/unset
      ├── daily_note.py    # Daily note get/append
      ├── doc.py           # Document CRUD, rename, move, get-path
      ├── export_cmd.py    # Export MD, export resources as zip
      ├── file_cmd.py      # Workspace file ops (get/put/remove/rename/list)
      ├── notebook.py      # Notebook list/create/remove/rename/open/close/conf
      ├── notify.py        # Push notifications to SiYuan UI
      ├── overview.py      # Workspace overview (notebooks + recent + stats)
      ├── search.py        # Full-text search + SQL queries
      ├── stats.py         # Workspace statistics
      ├── tag.py           # Tag list/blocks/rename/remove
      ├── template.py      # Render template / Sprig string
      └── workspace_cmd.py # Workspace add/list/use/remove/which
  siyuan_mcp/
  ├── __init__.py          # Package metadata (version 1.7.0)
  └── server.py            # MCP JSON-RPC 2.0 server (15 tools)
```

The `siyuan` CLI is a pure Python 3 package (stdlib only — no pip required for basic usage). The agent runs it via SSH (remote) or directly (local).

---

## Repository Structure

```
siyuan-skills/
├── siyuan_cli/                  # Package source
│   ├── __init__.py
│   ├── __main__.py
│   ├── cli.py
│   ├── client.py
│   ├── config.py
│   ├── exceptions.py
│   ├── permissions.py
│   ├── utils.py
│   ├── workspace.py
│   └── commands/
│       ├── asset.py
│       ├── attr.py
│       ├── backlinks.py
│       ├── batch.py
│       ├── block.py
│       ├── config_cmd.py
│       ├── daily_note.py
│       ├── doc.py
│       ├── export_cmd.py
│       ├── file_cmd.py
│       ├── notebook.py
│       ├── notify.py
│       ├── overview.py
│       ├── search.py
│       ├── stats.py
│       ├── tag.py
│       ├── template.py
│       └── workspace_cmd.py
├── siyuan_mcp/                  # MCP server
│   ├── __init__.py
│   └── server.py
├── scripts/
│   ├── siyuan-cli.py            # Thin wrapper → siyuan_cli package
│   └── install.sh               # One-command installer
├── skills/
│   ├── siyuan-cli/SKILL.md      # CLI tool usage (recommended)
│   ├── siyuan-api/SKILL.md      # Direct API calls via curl
│   └── siyuan-markdown/SKILL.md # SiYuan markdown syntax
├── references/
│   └── api-endpoints.md         # All known API endpoints
├── tests/                       # 115 unit tests
│   ├── test_config.py
│   ├── test_utils.py
│   ├── test_exceptions.py
│   └── test_client.py
├── .claude-plugin/              # Plugin marketplace registration
├── .github/workflows/ci.yml     # CI: ruff lint, mypy, pytest
├── CHANGELOG.md
├── CONTRIBUTING.md
├── pyproject.toml               # pip packaging config
└── README.md
```

## Compatibility

| Agent/Platform | Status | Notes |
|----------------|--------|-------|
| Claude Code | ✅ Confirmed | Skills spec v1 compatible |
| Codex CLI | ✅ Confirmed | Standard SKILL.md format |
| OpenCode | ✅ Confirmed | Auto-discovers SKILL.md files |
| Hermes Agent | ✅ Confirmed | Skills installed and tested |
| Cursor | ⚠️ Untested | Should work via skills spec |

## Development

```bash
git clone https://github.com/RowanGrove/siyuan-skills.git
cd siyuan-skills

# Install dev dependencies
pip install -e ".[dev]"

# Run checks
ruff format --check siyuan_cli/ siyuan_mcp/ scripts/ tests/
ruff check siyuan_cli/ siyuan_mcp/ scripts/siyuan-cli.py tests/
mypy siyuan_cli/ siyuan_mcp/
python -m pytest tests/ -v
```

See [CONTRIBUTING.md](CONTRIBUTING.md) for full development guide.

## Comparison

Similar projects exist in the SiYuan ecosystem. Here's how they compare:

| Dimension | **siyuan-skills** | frostime/siyuan-cli | siyuan-note/siyuan-agent-mcp |
|-----------|------------------|---------------------|------------------------------|
| Language | **Python** | TypeScript / Node.js | TypeScript / Node.js |
| Runtime | Python 3 (stdlib) | Node.js (9 npm deps) | Node.js (2 npm deps) |
| Install | `pip install` or `curl \| bash` | `npm install -g` | `npx` |
| Interface | **Agent Skills + CLI + API docs** | Agent Skills only | MCP protocol only |
|| Permission system | ✅ rule-based (allow/deny/ask) | ✅ allow/deny/approval rules | ✅ read-only mode + hidden tools |
|| Dry-run | ✅ select commands | ✅ all write commands | ✅ some tools |
|| Test coverage | **115 tests**, mypy strict, CI | None visible | N/A |
| Output format | `--format pretty\|json\|compact` | `--json` (basic) | JSON (MCP native) |

**Which one should you use?**

| You need… | Recommendation |
|-----------|---------------|
| Python-native CLI, zero deps | **siyuan-skills** — no Node.js required, works everywhere Python runs |
| Security / permission control | **siyuan-skills** or **frostime/siyuan-cli** — both have rule-based access control now |
| MCP protocol integration (Claude Desktop, Cursor) | **siyuan-agent-mcp** — native MCP, no CLI wrapper |
| Skills spec (Claude Code, Codex, OpenCode, Hermes) | **siyuan-skills** or **frostime/siyuan-cli** — both support Agent Skills |
| Complete toolset (CLI + API docs + markdown syntax) | **siyuan-skills** — only project with all three skill formats |
| Lightweight with engineering quality | **siyuan-skills** — 115 tests, mypy strict, zero dependencies |

## License

MIT
