SiYuan Note CLI Skill

Command Invocation

First try the globally installed CLI:

siyuan --version

If unavailable, use npx without requiring a global install:

npx siyuan-note-cli --version

Prefer writing commands as npx siyuan-note-cli <command> to avoid environment differences.

Startup Workflow: Read "AI Assistant Guide" First

Whenever this skill is triggered, the first step is to search for and read the SiYuan document named "AI Assistant Guide":

1. Search documents:

   npx siyuan-note-cli search docs "AI Assistant Guide"
   

2. Read the full document by ID:

   npx siyuan-note-cli document get <doc-id>
   

3. If the guide contains Markdown rules, available tool lists, naming conventions, tag systems, database templates, or other instructions, follow them strictly.

If "AI Assistant Guide" is not found, tell the user and continue with the normal operation.

Prerequisites

1. The SiYuan Note client is running, usually at http://127.0.0.1:6806.
2. API token is configured in one of these ways:
   • Environment variables: SIYUAN_API_URL, SIYUAN_API_TOKEN
   • CLI login: npx siyuan-note-cli auth login --url <url> --token <token>
   • Config file: ~/.config/siyuan-cli/config.yml

Best Practices

1. Locate before operating: use search, notebook list, and document list before modifications.
2. Prefer IDs: document and block IDs are more stable than paths.
3. Use structured output: use --format json for batch operations.
4. Confirm dangerous operations: use --force only after confirmation; database operations are experimental and should be used carefully.
5. Verify writes: after write operations, confirm the result with document get or block get.
6. Create new notes by default: unless the user explicitly asks to modify or append to an existing note, create a separate new document.
7. Default to the AgentWork notebook: if the user does not specify a location, write content to the root of the AgentWork notebook. If it does not exist, create it first.

Operation Boundary: Create vs Modify

Core principle: create by default, modify only when explicit. This prevents accidental overwrites or pollution of existing notes.

AgentWork notebook handling:

npx siyuan-note-cli notebook list --format json
npx siyuan-note-cli notebook create "AgentWork"
npx siyuan-note-cli document create <agentwork-id> "Document Name" \
  --title "Title" \
  --file "$TEMP/siyuan-draft.md"

Do not add a leading / to the path; otherwise the CLI may resolve it as a workspace filesystem path.

Writing Notes: Prefer --file, Avoid --content

Markdown content should be passed through a file, not a command-line string. Command-line parsing can damage line breaks and special characters such as backticks, #, and $.

Recommended pattern:

# Windows Git Bash: $TEMP/siyuan-draft.md
# Linux/macOS: /tmp/siyuan-draft.md
# Cross-platform fallback: ${TMPDIR:-/tmp}/siyuan-draft.md

npx siyuan-note-cli document create <notebook-id> "path/document-name" \
  --title "Document Title" \
  --file "$TEMP/siyuan-draft.md"

Avoid this for multi-line Markdown:

npx siyuan-note-cli document create <notebook-id> "path/document-name" \
  --title "Title" \
  --content "# Title\n\nBody **bold**\n\n```python\nprint('hello')\n```"

Incremental Append: One Block at a Time

block append appends only one block per call. If multiple paragraphs are passed, only the first block may be preserved.

npx siyuan-note-cli block append --parent <doc-id> --content "## Section Title"
npx siyuan-note-cli block append --parent <doc-id> --content "Body paragraph."

Do not pass multiple paragraphs in one block append call.

Path Rules

In SiYuan, folders are also documents. Do not add a leading / in any scenario.

Examples:

npx siyuan-note-cli document create <notebook-id> "Document Name" \
  --title "Title" \
  --file "$TEMP/siyuan-draft.md"

npx siyuan-note-cli document create <notebook-id> "Project/Subdir/New Document" \
  --title "Title" \
  --file "$TEMP/siyuan-draft.md"

Common Commands

Connection:

npx siyuan-note-cli auth status
npx siyuan-note-cli auth login --url http://127.0.0.1:6806 --token <token>

Notebooks:

npx siyuan-note-cli notebook list
npx siyuan-note-cli notebook create "Project Management"

Documents:

npx siyuan-note-cli document list <notebook-id> --path / --depth 2
npx siyuan-note-cli document get <doc-id>
npx siyuan-note-cli document create <notebook-id> "path/document-name" \
  --title "Title" \
  --file ./content.md
npx siyuan-note-cli document rename <doc-id> "New Title"
npx siyuan-note-cli document delete <doc-id> --force

Blocks:

npx siyuan-note-cli block get <block-id>
npx siyuan-note-cli block append <doc-id> --content "New paragraph"
npx siyuan-note-cli block update <block-id> --content "Updated content"

Search and query:

npx siyuan-note-cli search docs "Project Plan"
npx siyuan-note-cli search blocks "Key conclusion"
npx siyuan-note-cli query "SELECT * FROM blocks WHERE type='d' LIMIT 10"

Attributes:

npx siyuan-note-cli attr get <block-id>
npx siyuan-note-cli attr set <block-id> custom-status=done custom-priority=high

References

• Command details: references/commands.md
• Workflow examples: references/workflow-examples.md