cli-anything-siyuan

# cli-anything-siyuan CLI harness for [SiYuan](https://github.com/siyuan-note/siyuan) (思源笔记), a local-first knowledge management and note-taking application. This CLI connects to a running SiYuan kernel via its HTTP API (`http://127.0.0.1:6806`) and provides structured access to notebooks, documents, blocks, search, and export. ## Prerequisites - SiYuan must be running (Settings → About shows the API token) - Python 3.10+ - Install: `pip install cli-anything-siyuan` or `pip install -e .` from agent-harness/ ## Command Groups ### notebook — Notebook management | Subcommand | Description | |------------|-------------| | `list` | List all notebooks | | `create <name>` | Create a new notebook | | `rename <id> <name>` | Rename a notebook | | `remove <id>` | Delete a notebook | | `open <id>` | Open a notebook | ### doc — Document management | Subcommand | Description | |------------|-------------| | `create <notebook> <path> [--md "content"]` | Create a document | | `list <notebook> [path]` | List documents | | `tree <notebook> [--path / --depth]` | Show doc tree | | `get <id>` | Get document path by ID | | `rename <id> <title>` | Rename a document | | `remove <id>` | Delete a document | ### block — Block operations | Subcommand | Description | |------------|-------------| | `insert <data> [--previous / --parent]` | Insert a block | | `update <id> <data>` | Update a block | | `delete <id>` | Delete a block | | `get <id>` | Get block kramdown source | | `children <id>` | Get child blocks | ### Other commands | Command | Description | |---------|-------------| | `sql <stmt>` | Execute SQL on the block database | | `search <query>` | Full-text search across blocks | | `export md <doc-id>` | Export document as Markdown | | `tag list` | List all tags | | `version` | Show SiYuan kernel version | | `status` | Show connection and session status | | `repl` | Start interactive REPL | ## Agent Guidance - Always use `--json` for machine-readable output - Power search: use `sql "SELECT * FROM blocks WHERE content LIKE '%keyword%'"` for SQL-level access - Document IDs look like `20210817205410-2kvfpfn` (timestamp-based) - API token can be found in SiYuan Settings → About - Connection defaults: `http://127.0.0.1:6806` ## Examples ```bash # List notebooks (JSON) cli-anything-siyuan --json notebook list # Create a document with Markdown (--md flag, watch shell escaping) cli-anything-siyuan doc create nb1 /projects/new --md "## Title\n\nContent" # Create a document — pipe Markdown via stdin (avoids shell escaping) # PowerShell here-string (literal, no escaping needed): @' ## Title Content with `backticks` and (parentheses) and "quotes" '@ | cli-anything-siyuan doc create nb1 /projects/new --md - # Bash heredoc: # cat <<'EOF' | cli-anything-siyuan doc create nb1 /projects/new --md - # ## Title # Content with `backticks` and (parentheses) # EOF # SQL search cli-anything-siyuan sql "SELECT id, content FROM blocks WHERE content LIKE '%meeting%' LIMIT 5" # Export cli-anything-siyuan export md doc123 # Enter REPL cli-anything-siyuan ``` ## Error Handling - Connection errors: check that SiYuan is running and the API token is correct - API errors: returned as `{"code": N, "msg": "..."}` — check the message field - Auth errors: verify the token in `~/.siyuan-cli.json` or `SIYUAN_TOKEN` env var