Siyuan CLI

SiYuan CLI

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

Bootstrap

siyuan-cli --help
siyuan-cli workspace which

If siyuan-cli is missing: npm install -g @frostime/siyuan-cli. Always invoke this package as siyuan-cli; on SiYuan 3.7.0 or later, siyuan may resolve to SiYuan's native CLI instead. If skill version differs from CLI version: siyuan-cli skill install, then siyuan-cli skill read. If no workspace is configured: siyuan-cli 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-cli api <id> --help       # params, INPUT SOURCES, examples
siyuan-cli tool <id> --help      # params, examples, behavior
siyuan-cli api list              # endpoints + classification/severity labels
siyuan-cli tool list             # tools
siyuan-cli 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-cli doc read <path>.

Safety anchors

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   → checkpoint-doc once → --dry-run → inspect → --yes
    UNSAFE → block-level fallback

Before a group of high-risk edits, call checkpoint-doc explicitly once. Do not
repeat it for later edits in the same group; brute-edit never creates a
checkpoint automatically. A checkpoint is recovery material, not permission
to bypass an 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-cli api block.appendBlock --parentID <id> --data @stdin --yes <<'EOF'
Content here.
EOF

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

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

# whole payload: all commands support -j / -f
siyuan-cli api attr.setBlockAttrs -j '{"id":"<id>","attrs":{"custom-key":"value"}}'
siyuan-cli 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-cli api block.appendDailyNoteBlock --notebook <notebook-id> --data @stdin --yes <<'EOF'
Entry.
EOF

Search/read

siyuan-cli api filetree.searchDocs --k "<keyword>"    # candidates; verify before writing
siyuan-cli tool get-block-info <id>                   # identity, meta data (ref, toc, child etc.)
siyuan-cli tool search-backlinks <target-id>          # inbound refs; redirects first-block hits by default
siyuan-cli tool get-block-content <id> --range children --limit 50
siyuan-cli tool get-block-content <id> --range context --limit 7 --showId true
siyuan-cli 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-cli 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

stderr = diagnostics; stdout = result.

Routing

Layer choice

First response rules

• Content tasks: use installed siyuan-cli; 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-cli doc read cli-usage/extension.md, then inspect installed dist/shared/schema.d.mts.

GitHub: siyuan-cli · SiYuan kernel API