siyuan-cli 1.6.0__tar.gz

siyuan_cli-1.6.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RowanGrove
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

siyuan_cli-1.6.0/PKG-INFO

@@ -0,0 +1,265 @@
+Metadata-Version: 2.4
+Name: siyuan-cli
+Version: 1.6.0
+Summary: CLI tool and Agent Skills for SiYuan Note
+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
+Requires-Python: >=3.9
+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 the CLI (one command)
+
+```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).
+
+> **Windows:** The CLI is pure Python 3. Run `py scripts/siyuan-cli.py` or set up a batch alias.
+> Token path: `%USERPROFILE%\.siyuan\config.json` works natively.
+
+### 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"
+```
+
+### 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
+
+```
+# 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>                Export note as Markdown
+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 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
+
+# Tags
+siyuan tag list                     List all tags
+siyuan tag blocks <tag>             Find blocks with a tag
+siyuan tag rename <old> <new>       Rename a tag (SQL-based)
+siyuan tag remove <tag>             Remove a tag (SQL-based)
+
+# 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 export2 md <id>              Export document by block ID
+siyuan export2 resources <paths>    Export files/folders as zip
+
+# Notifications
+siyuan notify push <msg>            Push notification to SiYuan UI
+siyuan notify push-err <msg>        Push error notification
+
+# 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 stats                        Show workspace statistics
+```
+
+Config resolution order: `SIYUAN_*` env var > `~/.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 | "把这个笔记导出来" |
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────┐
+│                    Agent                             │
+│  ┌──────────────┐    SSH / direct     ┌──────────┐  │
+│  │  SKILL.md    │ ──── instructs ──▶  │  siyuan  │  │
+│  │  guides the  │                    │  CLI     │──┼──▶ SiYuan API
+│  │  agent       │ ◀─── returns ─────  │  (Python)│  │    (port 6806)
+│  └──────────────┘                    └──────────┘  │
+│                                                    │
+│  Config: ~/.siyuan/config.json                     │
+│  Env:    SIYUAN_URL, SIYUAN_TOKEN                  │
+└─────────────────────────────────────────────────────┘
+```
+
+The `siyuan` CLI is a single-file Python 3 script (stdlib only — no pip). The agent runs it via SSH (remote) or directly (local). The SKILL.md teaches the agent the available commands.
+
+---
+
+## Repository Structure
+
+```
+siyuan-skills/
+├── .claude-plugin/
+│   ├── marketplace.json          # Plugin marketplace registration
+│   └── plugin.json               # Plugin metadata
+├── 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
+├── scripts/
+│   ├── siyuan-cli.py             # The CLI (single file, no deps)
+│   └── install.sh                # One-command installer
+├── references/
+│   └── api-endpoints.md          # All known API endpoints
+├── README.md
+└── LICENSE (MIT)
+```
+
+## 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 |
+
+## License
+
+MIT

siyuan_cli-1.6.0/README.md

@@ -0,0 +1,247 @@
+# 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 the CLI (one command)
+
+```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).
+
+> **Windows:** The CLI is pure Python 3. Run `py scripts/siyuan-cli.py` or set up a batch alias.
+> Token path: `%USERPROFILE%\.siyuan\config.json` works natively.
+
+### 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"
+```
+
+### 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
+
+```
+# 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>                Export note as Markdown
+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 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
+
+# Tags
+siyuan tag list                     List all tags
+siyuan tag blocks <tag>             Find blocks with a tag
+siyuan tag rename <old> <new>       Rename a tag (SQL-based)
+siyuan tag remove <tag>             Remove a tag (SQL-based)
+
+# 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 export2 md <id>              Export document by block ID
+siyuan export2 resources <paths>    Export files/folders as zip
+
+# Notifications
+siyuan notify push <msg>            Push notification to SiYuan UI
+siyuan notify push-err <msg>        Push error notification
+
+# 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 stats                        Show workspace statistics
+```
+
+Config resolution order: `SIYUAN_*` env var > `~/.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 | "把这个笔记导出来" |
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────┐
+│                    Agent                             │
+│  ┌──────────────┐    SSH / direct     ┌──────────┐  │
+│  │  SKILL.md    │ ──── instructs ──▶  │  siyuan  │  │
+│  │  guides the  │                    │  CLI     │──┼──▶ SiYuan API
+│  │  agent       │ ◀─── returns ─────  │  (Python)│  │    (port 6806)
+│  └──────────────┘                    └──────────┘  │
+│                                                    │
+│  Config: ~/.siyuan/config.json                     │
+│  Env:    SIYUAN_URL, SIYUAN_TOKEN                  │
+└─────────────────────────────────────────────────────┘
+```
+
+The `siyuan` CLI is a single-file Python 3 script (stdlib only — no pip). The agent runs it via SSH (remote) or directly (local). The SKILL.md teaches the agent the available commands.
+
+---
+
+## Repository Structure
+
+```
+siyuan-skills/
+├── .claude-plugin/
+│   ├── marketplace.json          # Plugin marketplace registration
+│   └── plugin.json               # Plugin metadata
+├── 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
+├── scripts/
+│   ├── siyuan-cli.py             # The CLI (single file, no deps)
+│   └── install.sh                # One-command installer
+├── references/
+│   └── api-endpoints.md          # All known API endpoints
+├── README.md
+└── LICENSE (MIT)
+```
+
+## 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 |
+
+## License
+
+MIT

siyuan_cli-1.6.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["setuptools>=64"]
+build-backend = "setuptools.build_meta:__legacy__"
+
+[project]
+name = "siyuan-cli"
+version = "1.6.0"
+description = "CLI tool and Agent Skills for SiYuan Note"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+keywords = ["siyuan", "notes", "markdown", "pkm", "self-hosted"]
+
+[project.urls]
+Homepage = "https://github.com/RowanGrove/siyuan-skills"
+Repository = "https://github.com/RowanGrove/siyuan-skills"
+
+[project.scripts]
+siyuan = "siyuan_cli.cli:main"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pytest-timeout", "ruff>=0.6", "mypy>=1.10"]
+
+[tool.setuptools.packages.find]
+include = ["siyuan_cli", "siyuan_cli.*"]
+
+[tool.ruff]
+target-version = "py39"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "N", "UP", "SIM"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["N802", "N803", "N806"]
+
+[tool.ruff.format]
+quote-style = "double"
+
+[tool.mypy]
+python_version = "3.9"
+strict = false
+ignore_missing_imports = true
+explicit_package_bases = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+timeout = 30

siyuan_cli-1.6.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

siyuan_cli-1.6.0/siyuan_cli/__init__.py

@@ -0,0 +1,7 @@
+"""siyuan-cli — SiYuan Note command-line tool.
+
+Package for interacting with SiYuan Note's HTTP API.
+Create, read, search, and manage notes, blocks, tags, and assets.
+"""
+
+__version__ = "1.6.0"

siyuan_cli-1.6.0/siyuan_cli/__main__.py

@@ -0,0 +1,5 @@
+"""Entry point for `python3 -m siyuan_cli`."""
+
+from siyuan_cli.cli import main
+
+main()