siyuan-cli

name	siyuan-cli
description	Manage SiYuan Note with the `siyuan` CLI. Use this whenever the user mentions SiYuan, notebooks, documents, blocks, or wants to query/update a SiYuan knowledge base.
metadata	{"version":"{{VERSION}}"}

SiYuan CLI

Agent-first CLI for SiYuan Note. This SKILL is the entry point; built-in docs provide task playbooks (siyuan doc list/read).

Bootstrap

siyuan --help
siyuan workspace which

If siyuan is missing: npm install -g @frostime/siyuan-cli. If skill version differs from CLI version: siyuan skill install, then siyuan skill read. If no workspace is configured: siyuan doc read recipes/connect-workspace.md. If URL/token/workspace are unknown: stop and ask user.

Command discovery

Docs = decision map. --help = parameter syntax.

siyuan api <id> --help       # params, INPUT SOURCES, examples
siyuan tool <id> --help      # params, examples, behavior
siyuan api list              # endpoints + classification/severity labels
siyuan tool list             # tools
siyuan doc list              # docs + real paths

Before using @file:/@stdin/@env: on a parameter, check --help → INPUT SOURCES. If absent, use literal or whole-payload -j/-f. Doc paths here are read via siyuan doc read <path>.

Safety anchors

#	Rule
1	Confirm workspace before content work; never silently switch for writes.
2	Write only to stable id / resolved root_id; never title/keyword/hpath alone.
3	Non-append writes require get-block-info + bounded get-block-content --showId true.
4	Smallest safe surface: append → block update → batch update → guarded brute-edit.
5	CONTENT_FILTERED / truncation = valid but incomplete; don't infer absence.
6	--yes is not a safety check; use only after target verified + action intended.
7	api raw bypasses schema/resource guards/response filtering; one-off only.
8	Approval browser auto-open may be debounced; parse every APPROVAL_PENDING stderr event, not browser opens.

Small localized edit with known block ids
  → tool update-block (preserves custom attrs)

Broad/complex/text-level edit
  → brute-edit <doc-id> --check true
    SAFE   → --dry-run → inspect → --yes
    UNSAFE → checkpoint-doc → block-level fallback

checkpoint-doc = recovery material, not permission to bypass unsafe check.

Ask user when: no token/URL · wrong workspace · multiple plausible write targets · destructive operation lacks confirmation · daily-note notebook unknown.

Mode gate

• Fast path: read/list/search, or create/append with explicit stable target.
• Slow path: edit existing content; target is title/keyword/hpath; affects multiple blocks/document block; may regenerate ids; destructive/approval-gated.

Canonical input patterns

Check --help INPUT SOURCES first.

# heredoc (bash) / here-string (PowerShell @'...'@): parameter supports stdin
siyuan api block.appendBlock --parentID <id> --data @stdin --yes <<'EOF'
Content here.
EOF

# @file: parameter supports file
siyuan tool update-block --blocks @file:./updates.json --yes

# pipe: parameter supports stdin
cat query.sql | siyuan api query.sql --stmt @stdin

# whole payload: all commands support -j / -f
siyuan api attr.setBlockAttrs -j '{"id":"<id>","attrs":{"custom-key":"value"}}'
siyuan api attr.batchSetBlockAttrs -f ./attrs.json --yes

Hot paths

Append

Use block.appendBlock with §Canonical input patterns. Daily note example:

# Notebook id must be known; if unknown, list notebooks or ask.
siyuan api block.appendDailyNoteBlock --notebook <notebook-id> --data @stdin --yes <<'EOF'
Entry.
EOF

Search/read

siyuan api filetree.searchDocs --k "<keyword>"    # candidates; verify before writing
siyuan tool get-block-info <id>                   # identity, meta data (ref, toc, child etc.)
siyuan tool search-backlinks <target-id>          # inbound refs; redirects first-block hits by default
siyuan tool get-block-content <id> --range children --limit 50
siyuan tool get-block-content <id> --range context --limit 7 --showId true
siyuan tool locate-block --id <doc-id> --pattern "%keyword%"  # SQL LIKE, not regex

Update known block

Fast command, slow pre-flight. Required: workspace confirmed; stable block id; current content inspected; user intent maps exactly to block. Else read recipes/edit-content.md.

siyuan tool update-block --blocks @stdin --yes <<'EOF'
[{"id":"<block-id>","data":"Replacement."}]
EOF

⚠️ Do NOT use raw block.updateBlock / block.batchUpdateBlock — they erase custom attributes. Always use tool update-block.

Error triage

Exit	Meaning	Action
0	success	parse stdout
1	general/kernel/approval/not found	read stderr JSON
2	config/workspace	siyuan workspace which
3	network/kernel down	ask user to start SiYuan
4	auth/token	ask user for token
5	permission denied	siyuan workspace which

stderr = diagnostics; stdout = result.

Routing

Need	Read / do
workspace connect/debug	siyuan doc read recipes/connect-workspace.md
config schema (behavior, rawApi, defaults, project-file)	siyuan doc read cli-usage/workspace-config.md
locate user-named doc/block	siyuan doc read recipes/find-target.md
read content ranges/paging/ids	siyuan doc read recipes/read-content.md
reference/backlink navigation	siyuan doc read recipes/read-content.md + siyuan doc read siyuan-guide/sql-query-guide.md
edit/move/delete/batch/create	siyuan doc read recipes/edit-content.md
daily notes	siyuan doc read siyuan-guide/dailynote-model.md
block/path/sql model	siyuan doc read siyuan-guide/siyuan-block.md
permissions/approval config	siyuan doc read cli-usage/permission.md
custom API/tool extension	siyuan doc read cli-usage/extension.md
deep CLI mechanics: flags, input-source edge cases, stdout/stderr, Approval Center, MSYS	siyuan doc read cli-usage/cli-overview.md

Layer choice

Shape	Prefer
normal note work	CLI + recipes
one known endpoint	registered api
multi-step operation	tool
one-off missing endpoint	api raw
repeated missing endpoint	API extension
repeated multi-call workflow	tool extension
user policy/defaults/templates	downstream Agent SKILL

First response rules

• Content tasks: use installed siyuan; do not inspect repo source unless modifying siyuan-cli internals.
• User-named targets: recipes/find-target.md first.
• Writes beyond append-only: also recipes/edit-content.md.

Domain rules

• Block is primary; document = container block (type='d').
• Stable addressing: id > root_id > path; never hpath/title as stable key.
• parent_id = hierarchy; root_id = owning doc; box = notebook.
• Non-document block path/hpath describes containing document.
• SQL: always LIMIT; narrow with root_id/box/type before fuzzy LIKE.

Gotchas

• Windows Git Bash/MSYS rewrites leading / paths → MSYS_NO_PATHCONV=1 ... or //path.
• --showId true injects @@id@@type markers; never use them as brute-edit source/search text.
• Endpoint choice: registered > api raw; avoid long-lived rawApi.allow: ["*"].

Internals

For extension typing: siyuan doc read cli-usage/extension.md, then inspect installed dist/shared/schema.d.mts.

GitHub: siyuan-cli · SiYuan kernel API