siyuan-sisyphus-create-edit

Create and Edit SiYuan Content with the CLI

Read the target first, choose the highest-level action that preserves intent, perform one bounded change, then read it again.

Protected writes and readback

For a mutation covered by strict safe writes, call the same action and business arguments with validateOnly=true, use the returned precondition field, and submit the server-issued requestId. Never invent or recycle a hash credential. After the write, reread the exact stable ID or resolved path with enough bounded fields to prove the intended change and continue until the response is complete.

If the connection fails after execution may have started, or the result says outcome_unknown or readback_mismatch, do not retry with a new request ID. Inspect the target and resolve the outcome first. A CLI command, raw MCP payload, or Agent-generated call is not by itself evidence that this coordinator path or its guarantees applied; use the current safety response and runtime help.

Create documents

Use a workspace path for convenient path-based creation:

siyuan-sisyphus fs write --path '/Notebook/Project/Notes' --markdown '# Notes

Initial content.' --json

Use a notebook ID plus notebook-local hpath when low-level control is needed:

siyuan-sisyphus document create --notebook '<notebook-id>' --path '/Project/Notes' --markdown '# Notes' --json

Do not include the notebook name in the low-level hpath.

Edit blocks

siyuan-sisyphus block append --parent-id '<doc-id>' --data-type 'markdown' --data '## New section

Paragraph.' --json

siyuan-sisyphus block insert --previous-id '<block-id>' --data-type 'markdown' --data 'Inserted paragraph.' --json

siyuan-sisyphus block update --id '<block-id>' --data-type 'markdown' --data 'Replacement block content.' --json

Use block update only when replacing the whole block is intended. Prefer a scoped replacement for a small textual change:

siyuan-sisyphus block replace --id '<block-id>' --edit-json '{"old":"draft","new":"final"}' --json