siyuan-cli 1.6.0__py3-none-any.whl

siyuan_cli/__init__.py

@@ -0,0 +1,7 @@
+"""siyuan-cli — SiYuan Note command-line tool.
+
+Package for interacting with SiYuan Note's HTTP API.
+Create, read, search, and manage notes, blocks, tags, and assets.
+"""
+
+__version__ = "1.6.0"

siyuan_cli/__main__.py

@@ -0,0 +1,5 @@
+"""Entry point for `python3 -m siyuan_cli`."""
+
+from siyuan_cli.cli import main
+
+main()

siyuan_cli/cli.py

@@ -0,0 +1,422 @@
+"""CLI argument parser and main entry point for siyuan-cli."""
+
+import argparse
+import logging
+import sys
+
+from siyuan_cli import __version__
+from siyuan_cli.commands.asset import cmd_asset
+from siyuan_cli.commands.attr import cmd_attr as cmd_attr_fn
+from siyuan_cli.commands.batch import cmd_batch
+from siyuan_cli.commands.block import cmd_block
+from siyuan_cli.commands.config_cmd import (
+    cmd_config,
+    cmd_config_get,
+    cmd_keyring_set,
+    cmd_keyring_unset,
+)
+from siyuan_cli.commands.doc import (
+    cmd_create,
+    cmd_delete,
+    cmd_doc,
+    cmd_list_notebooks,
+    cmd_read,
+    cmd_tree,
+)
+from siyuan_cli.commands.doc import (
+    cmd_export as cmd_export_doc,
+)
+from siyuan_cli.commands.export_cmd import cmd_export as cmd_export_fn
+from siyuan_cli.commands.file_cmd import cmd_file
+from siyuan_cli.commands.notebook import cmd_notebook
+from siyuan_cli.commands.notify import cmd_notify
+from siyuan_cli.commands.search import cmd_search, cmd_sql
+from siyuan_cli.commands.stats import cmd_stats
+from siyuan_cli.commands.tag import cmd_tag
+from siyuan_cli.commands.template import cmd_template
+from siyuan_cli.exceptions import SiYuanError
+from siyuan_cli.utils import set_json_mode
+
+
+def create_parser() -> argparse.ArgumentParser:
+    """Build the argument parser with all subcommands."""
+    p = argparse.ArgumentParser(
+        prog="siyuan",
+        description="SiYuan Note command-line tool",
+        epilog="See https://github.com/RowanGrove/siyuan-skills",
+    )
+    p.add_argument("--json", action="store_true", help="JSON output")
+    p.add_argument("-v", "--verbose", action="store_true", help="Debug logs")
+    p.add_argument("--log-file", help="Write logs to file instead of stderr")
+    p.add_argument("--version", action="version", version=f"siyuan {__version__}")
+
+    sub = p.add_subparsers(dest="command", required=True)
+
+    # ─────────────────────  LEGACY FLAT COMMANDS (backward compatible)  ────────────
+
+    # config
+    cf = sub.add_parser("config", help="Show or set connection config")
+    cf.add_argument("set", nargs="*", metavar="key val", help="Set config key (url|token)")
+
+    # list-notebooks
+    sub.add_parser("list-notebooks", help="List all notebooks (alias for 'notebook list')")
+
+    # create
+    cr = sub.add_parser("create", help="Create a document")
+    cr.add_argument("path", help="Document path, e.g. /folder/Note")
+    cr.add_argument("content", nargs="?", default="", help="Markdown content")
+    cr.add_argument("--notebook", "-n", help="Notebook ID (default: first)")
+
+    # read
+    rd = sub.add_parser("read", help="Read a document")
+    rd.add_argument("path", help="Document path")
+    rd.add_argument("--notebook", "-n", help="Notebook ID")
+
+    # delete
+    dl = sub.add_parser("delete", help="Delete a document (by path or --id)")
+    dl.add_argument("path", help="Document path (or any value if --id)")
+    dl.add_argument("--notebook", "-n", help="Notebook ID")
+    dl.add_argument("--id", help="Delete by block ID instead of path")
+
+    # search
+    sr = sub.add_parser("search", help="Full-text search")
+    sr.add_argument("query", nargs="+", help="Search terms")
+    sr.add_argument("--limit", "-l", type=int, default=10, help="Max results")
+
+    # sql
+    sq = sub.add_parser("sql", help="Run SQL query")
+    sq.add_argument("statement", nargs="+", help="SELECT statement")
+
+    # tree
+    tr = sub.add_parser("tree", help="Show document tree")
+    tr.add_argument("notebook", nargs="?", default="", help="Notebook ID")
+
+    # config-get
+    cg = sub.add_parser("config-get", help="Read SiYuan server config value")
+    cg.add_argument("key", nargs="?", default=None, help="Dot-notation key")
+
+    # stats
+    sub.add_parser("stats", help="Workspace statistics")
+
+    # export (legacy — by path)
+    ex = sub.add_parser("export", help="Export document as Markdown (by path)")
+    ex.add_argument("path", help="Document path")
+    ex.add_argument("--notebook", "-n", help="Notebook ID")
+
+    # tag-list
+    sub.add_parser("tag-list", help="List all tags (alias for 'tag list')")
+
+    # ─────────────────────  TAG  ─────────────────────
+    tp = sub.add_parser("tag", help="Tag management (list/blocks/rename/remove)")
+    tsub = tp.add_subparsers(dest="action", required=True)
+    tsub.add_parser("list", help="List all unique tags")
+    tb = tsub.add_parser("blocks", help="Find blocks with a tag")
+    tb.add_argument("tag", help="Tag name (without #)")
+    trn = tsub.add_parser("rename", help="Rename a tag across all blocks")
+    trn.add_argument("old", help="Old tag name")
+    trn.add_argument("new", help="New tag name")
+    trm = tsub.add_parser("remove", help="Remove a tag from all blocks")
+    trm.add_argument("tag", help="Tag name to remove")
+
+    # ─────────────────────  ASSET  ─────────────────────
+    ap = sub.add_parser("asset", help="Asset management (upload/list)")
+    asub = ap.add_subparsers(dest="action", required=True)
+    au = asub.add_parser("upload", help="Upload a file as asset")
+    au.add_argument("file", help="Path to local file")
+    au.add_argument("--dir", default="/assets/", help="Asset directory (default: /assets/)")
+    al = asub.add_parser("list", help="List assets")
+    al.add_argument("--limit", "-l", type=int, default=50, help="Max results")
+    al.add_argument("--offset", "-o", type=int, default=0, help="Result offset")
+    al.add_argument("--filter", "-f", help="Filter by name")
+
+    # ─────────────────────  ATTR  ─────────────────────
+    ap2 = sub.add_parser("attr", help="Block attribute management (get/set)")
+    a2sub = ap2.add_subparsers(dest="action", required=True)
+    a2g = a2sub.add_parser("get", help="Get block attributes")
+    a2g.add_argument("id", help="Block ID")
+    a2s = a2sub.add_parser("set", help="Set block attributes")
+    a2s.add_argument("id", help="Block ID")
+    a2s.add_argument("key", help="Attribute key (e.g. custom-myattr)")
+    a2s.add_argument("value", help="Attribute value")
+
+    # ─────────────────────  BLOCK  ─────────────────────
+    bp = sub.add_parser(
+        "block",
+        help="Block operations: get/children/insert/prepend/append/"
+        "update/delete/move/fold/unfold/transfer-ref",
+    )
+    bsub = bp.add_subparsers(dest="action", required=True)
+
+    bg = bsub.add_parser("get", help="Get block info via SQL")
+    bg.add_argument("id", help="Block ID")
+    bc = bsub.add_parser("children", help="Get child blocks")
+    bc.add_argument("id", help="Parent block ID")
+    bi = bsub.add_parser("insert", help="Insert a block after a sibling")
+    bi.add_argument(
+        "parent_id", nargs="?", default="", help="Parent block ID (used if --previous is empty)"
+    )
+    bi.add_argument("-c", "--content", required=True, help="Block markdown content")
+    bi.add_argument("--previous", help="Previous sibling block ID (higher priority)")
+    bp1 = bsub.add_parser("prepend", help="Prepend block as first child")
+    bp1.add_argument("id", help="Parent block ID")
+    bp1.add_argument("-c", "--content", required=True, help="Block markdown content")
+    bp2 = bsub.add_parser("append", help="Append block as last child")
+    bp2.add_argument("id", help="Parent block ID")
+    bp2.add_argument("-c", "--content", required=True, help="Block markdown content")
+    bu = bsub.add_parser("update", help="Update a block's content")
+    bu.add_argument("id", help="Block ID")
+    bu.add_argument("-c", "--content", required=True, help="New markdown content")
+    bd = bsub.add_parser("delete", help="Delete a block")
+    bd.add_argument("id", help="Block ID")
+    bm = bsub.add_parser("move", help="Move a block")
+    bm.add_argument("id", help="Block ID to move")
+    bm.add_argument("--parent", "-p", default="", help="New parent block ID")
+    bm.add_argument("--previous", default="", help="Previous sibling ID (higher priority)")
+    bf = bsub.add_parser("fold", help="Fold (collapse) a heading block")
+    bf.add_argument("id", help="Block ID")
+    buf = bsub.add_parser("unfold", help="Unfold (expand) a block")
+    buf.add_argument("id", help="Block ID")
+    btr = bsub.add_parser("transfer-ref", help="Transfer block refs to another block")
+    btr.add_argument("from_id", help="Source def block ID")
+    btr.add_argument("to_id", help="Target block ID")
+    btr.add_argument(
+        "--ref-ids", nargs="*", default=None, help="Specific ref block IDs (omit for all)"
+    )
+
+    # ─────────────────────  TEMPLATE  ─────────────────────
+    tpl = sub.add_parser("template", help="Template rendering")
+    tsub2 = tpl.add_subparsers(dest="action", required=True)
+    tr = tsub2.add_parser("render", help="Render a template file")
+    tr.add_argument("id", help="Block ID of the calling document")
+    tr.add_argument("path", help="Absolute path to template file on SiYuan server")
+    trs = tsub2.add_parser("render-sprig", help="Render a Sprig template string")
+    trs.add_argument("template", help="Template string with Sprig syntax")
+
+    # ─────────────────────  NOTIFY  ─────────────────────
+    nt = sub.add_parser("notify", help="Push notifications to SiYuan UI")
+    nsub = nt.add_subparsers(dest="action", required=True)
+    np = nsub.add_parser("push", help="Push an info notification")
+    np.add_argument("msg", help="Message text")
+    np.add_argument(
+        "--timeout", type=int, default=7000, help="Display duration in ms (default: 7000)"
+    )
+    npe = nsub.add_parser("push-err", help="Push an error notification")
+    npe.add_argument("msg", help="Error message text")
+    npe.add_argument(
+        "--timeout", type=int, default=7000, help="Display duration in ms (default: 7000)"
+    )
+
+    # ─────────────────────  NOTEBOOK  ─────────────────────
+    nb = sub.add_parser(
+        "notebook",
+        help="Notebook management: list/create/remove/rename/open/close/conf",
+    )
+    nbsub = nb.add_subparsers(dest="action", required=True)
+    nbsub.add_parser("list", help="List notebooks (with icons and status)")
+    nbc = nbsub.add_parser("create", help="Create a notebook")
+    nbc.add_argument("name", help="Notebook name")
+    nbr = nbsub.add_parser("remove", help="Remove a notebook (irreversible)")
+    nbr.add_argument("id", help="Notebook ID")
+    nbrn = nbsub.add_parser("rename", help="Rename a notebook")
+    nbrn.add_argument("id", help="Notebook ID")
+    nbrn.add_argument("name", help="New notebook name")
+    nbo = nbsub.add_parser("open", help="Open a notebook")
+    nbo.add_argument("id", help="Notebook ID")
+    nbc2 = nbsub.add_parser("close", help="Close a notebook")
+    nbc2.add_argument("id", help="Notebook ID")
+    nbcf = nbsub.add_parser("conf", help="Get notebook configuration")
+    nbcf.add_argument("id", help="Notebook ID")
+    nbsc = nbsub.add_parser("set-conf", help="Set notebook configuration")
+    nbsc.add_argument("id", help="Notebook ID")
+    nbsc.add_argument(
+        "overrides", nargs="+", help="key=value overrides (e.g. dailyNoteSavePath=...)"
+    )
+
+    # ─────────────────────  DOC (new hierarchical)  ─────────────────────
+    dc = sub.add_parser(
+        "doc",
+        help="Document management: create/read/delete/rename/move/tree/get-path",
+    )
+    dcsub = dc.add_subparsers(dest="action", required=True)
+
+    dcr = dcsub.add_parser("create", help="Create a document")
+    dcr.add_argument("path", help="Document path")
+    dcr.add_argument("content", nargs="?", default="", help="Markdown content")
+    dcr.add_argument("--notebook", "-n", help="Notebook ID")
+
+    dcread = dcsub.add_parser("read", help="Read a document")
+    dcread.add_argument("path", help="Document path")
+    dcread.add_argument("--notebook", "-n", help="Notebook ID")
+
+    dcdel = dcsub.add_parser("delete", help="Delete a document")
+    dcdel.add_argument("path", nargs="?", default="", help="Document path")
+    dcdel.add_argument("--id", help="Delete by block ID")
+    dcdel.add_argument("--notebook", "-n", help="Notebook ID")
+
+    dcex = dcsub.add_parser("export", help="Export document as Markdown")
+    dcex.add_argument("path", help="Document path")
+    dcex.add_argument("--notebook", "-n", help="Notebook ID")
+
+    dct = dcsub.add_parser("tree", help="Show document tree")
+    dct.add_argument("notebook", nargs="?", default="", help="Notebook ID")
+
+    dcrn = dcsub.add_parser("rename", help="Rename a document")
+    dcrn.add_argument("--id", help="Document block ID (ID-based rename)")
+    dcrn.add_argument("--path", help="Document path (path-based rename)")
+    dcrn.add_argument("--notebook", "-n", help="Notebook ID (for path-based)")
+    dcrn.add_argument("title", help="New document title")
+
+    dcmv = dcsub.add_parser("move", help="Move document(s) to another location")
+    dcmv.add_argument("paths", nargs="+", help="Source document path(s)")
+    dcmv.add_argument("--to-notebook", help="Target notebook ID")
+    dcmv.add_argument("--to-path", default="/", help="Target folder path (default: /)")
+    dcmv.add_argument("--by-id", action="store_true", help="Interpret paths as IDs")
+
+    dcgp = dcsub.add_parser("get-path", help="Get human-readable or storage path from ID")
+    dcgp.add_argument("id", help="Block or document ID")
+    dcgp.add_argument("--storage", action="store_true", help="Get storage path instead of hpath")
+    dcgp.add_argument("--hpath", action="store_true", help="Get human-readable path (default)")
+
+    # ─────────────────────  FILE  ─────────────────────
+    fl = sub.add_parser(
+        "file",
+        help="File operations on SiYuan workspace: get/put/remove/rename/list",
+    )
+    flsub = fl.add_subparsers(dest="action", required=True)
+
+    fg = flsub.add_parser("get", help="Get file content from workspace")
+    fg.add_argument("path", help="Path under workspace (e.g. /data/assets/foo.png)")
+    fg.add_argument("--output", "-o", help="Save to local file instead of stdout")
+
+    fp = flsub.add_parser("put", help="Upload a file to workspace")
+    fp.add_argument("local", help="Local file path")
+    fp.add_argument("path", help="Destination path under workspace")
+
+    fr = flsub.add_parser("remove", help="Remove a file from workspace")
+    fr.add_argument("path", help="Path under workspace")
+
+    frn = flsub.add_parser("rename", help="Rename a file in workspace")
+    frn.add_argument("path", help="Current path")
+    frn.add_argument("new_path", help="New path")
+
+    fls = flsub.add_parser("list", help="List files in a workspace directory")
+    fls.add_argument("path", help="Directory path under workspace")
+
+    # ─────────────────────  EXPORT (hierarchical)  ─────────────────────
+    ex2 = sub.add_parser("export2", help="Export: md <id> or resources <paths...>")
+    ex2sub = ex2.add_subparsers(dest="action", required=True)
+    ex2m = ex2sub.add_parser("md", help="Export document as Markdown by block ID")
+    ex2m.add_argument("id", help="Document block ID")
+    ex2r = ex2sub.add_parser("resources", help="Export files/folders as zip")
+    ex2r.add_argument("paths", nargs="+", help="Path(s) under workspace to export")
+    ex2r.add_argument("--name", help="Zip file name (without .zip)")
+
+    # ─────────────────────  KEYRING  ─────────────────────
+    ks = sub.add_parser("keyring-set", help="Store API token in system keyring")
+    ks.add_argument("token", help="API token to store")
+    sub.add_parser("keyring-unset", help="Remove API token from system keyring")
+
+    # ─────────────────────  BATCH  ─────────────────────
+    bt = sub.add_parser("batch", help="Batch operations: create/delete/tag/export")
+    btsub = bt.add_subparsers(dest="action", required=True)
+
+    bc = btsub.add_parser("create", help="Batch create docs from file/stdin")
+    bc.add_argument("input", help="Input file path or '-' for stdin")
+    bc.add_argument("--notebook", "-n", help="Notebook ID")
+
+    bd = btsub.add_parser("delete", help="Batch delete docs by path from file/stdin")
+    bd.add_argument("input", help="Input file path or '-' for stdin")
+    bd.add_argument("--notebook", "-n", help="Notebook ID")
+    bd.add_argument(
+        "--by-id", action="store_true", help="Input contains block IDs instead of paths"
+    )
+
+    bt2 = btsub.add_parser("tag", help="Batch add/remove tags on blocks from file/stdin")
+    bt2.add_argument("input", help="Input file with block IDs, one per line")
+    bt2.add_argument("--tag", required=True, help="Tag name (without #)")
+    bt2.add_argument(
+        "--action", required=True, choices=["add", "remove"], help="Add or remove the tag"
+    )
+
+    be = btsub.add_parser("export", help="Batch export docs by ID from file/stdin")
+    be.add_argument("input", help="Input file with block IDs, one per line")
+    be.add_argument(
+        "--output", "-o", default="./export", help="Output directory (default: ./export)"
+    )
+
+    return p
+
+
+COMMANDS = {
+    "config": cmd_config,
+    "list-notebooks": cmd_list_notebooks,
+    "create": cmd_create,
+    "read": cmd_read,
+    "delete": cmd_delete,
+    "search": cmd_search,
+    "sql": cmd_sql,
+    "tree": cmd_tree,
+    "config-get": cmd_config_get,
+    "stats": cmd_stats,
+    "export": cmd_export_doc,
+    "tag-list": cmd_tag,
+    "tag": cmd_tag,
+    "block": cmd_block,
+    "asset": cmd_asset,
+    "attr": cmd_attr_fn,
+    "template": cmd_template,
+    "notify": cmd_notify,
+    "notebook": cmd_notebook,
+    "doc": cmd_doc,
+    "file": cmd_file,
+    "export2": cmd_export_fn,
+    "keyring-set": cmd_keyring_set,
+    "keyring-unset": cmd_keyring_unset,
+    "batch": cmd_batch,
+}
+
+
+def setup_logging(verbose: bool = False, log_file: str = "") -> None:
+    """Configure logging.
+
+    Args:
+        verbose: If True, set level to DEBUG instead of WARNING.
+        log_file: If provided, write logs to this file instead of stderr.
+    """
+    level = logging.DEBUG if verbose else logging.WARNING
+    fmt = logging.Formatter(
+        "%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+        datefmt="%Y-%m-%d %H:%M:%S",
+    )
+    root = logging.getLogger("siyuan")
+    root.setLevel(level)
+
+    handler = logging.FileHandler(log_file) if log_file else logging.StreamHandler(sys.stderr)
+    handler.setFormatter(fmt)
+    root.addHandler(handler)
+
+
+def main(argv: list[str] | None = None) -> None:
+    """Entry point for siyuan CLI."""
+    parser = create_parser()
+    args = parser.parse_args(argv)
+
+    set_json_mode(args.json)
+    setup_logging(args.verbose, getattr(args, "log_file", ""))
+
+    try:
+        handler = COMMANDS.get(args.command)
+        if handler:
+            handler(args)
+    except SiYuanError as e:
+        print(e.friendly(), file=sys.stderr)
+        sys.exit(1)
+    except Exception as e:
+        logger = logging.getLogger("siyuan")
+        logger.debug("Unhandled exception", exc_info=True)
+        print(f"Unexpected error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

siyuan_cli/client.py

@@ -0,0 +1,175 @@
+"""SiYuan HTTP API client with lazy config and connection reuse."""
+
+import json
+import logging
+import time
+import urllib.error
+import urllib.request
+from typing import Any, Optional
+
+from siyuan_cli.config import resolve_base, resolve_token
+from siyuan_cli.exceptions import (
+    AuthError,
+    ConflictError,
+    NetworkError,
+    RateLimitError,
+    ServerError,
+    SiYuanError,
+)
+
+logger = logging.getLogger("siyuan")
+
+API_TIMEOUT = 15
+MAX_RETRIES = 3
+
+
+class SiYuanClient:
+    """Reusable SiYuan API client with lazy config resolution.
+
+    Usage:
+        client = SiYuanClient()
+        result = client.call("notebook/lsNotebooks")
+
+    Or with explicit config:
+        client = SiYuanClient(base_url="http://...", token="...")
+    """
+
+    def __init__(self, base_url: Optional[str] = None, token: Optional[str] = None):
+        self._base_url = base_url
+        self._token = token
+        self._ready = False
+
+    def _ensure_config(self) -> None:
+        """Lazy-load config on first use."""
+        if not self._ready:
+            if self._base_url is None:
+                self._base_url = resolve_base()
+            if self._token is None:
+                self._token = resolve_token()
+            self._ready = True
+
+    def call(self, endpoint: str, data: Optional[dict] = None) -> dict[str, Any]:
+        """Make an API call with retry for transient errors.
+
+        Args:
+            endpoint: API endpoint path (e.g. "notebook/lsNotebooks").
+            data: JSON-serializable request body (POSTed).
+
+        Returns:
+            Parsed JSON response dict.
+
+        Raises:
+            AuthError: On 401 responses.
+            NetworkError: On connection failures after retries.
+            ConflictError: On 409 responses.
+            RateLimitError: On 429 responses.
+            ServerError: On 5xx responses.
+            SiYuanError: On other failures.
+        """
+        self._ensure_config()
+        url = f"{self._base_url}/api/{endpoint}"
+        body = json.dumps(data).encode() if data else b"{}"
+
+        for attempt in range(MAX_RETRIES + 1):
+            t0 = time.time()
+            try:
+                req = urllib.request.Request(
+                    url,
+                    data=body,
+                    method="POST",
+                    headers={
+                        "Authorization": f"Token {self._token}",
+                        "Content-Type": "application/json",
+                    },
+                )
+                with urllib.request.urlopen(req, timeout=API_TIMEOUT) as resp:
+                    elapsed = int((time.time() - t0) * 1000)
+                    logger.debug("→ %s 200 (%dms)", endpoint, elapsed)
+                    return json.loads(resp.read())
+
+            except urllib.error.HTTPError as e:
+                elapsed = int((time.time() - t0) * 1000)
+                resp_body = e.read().decode(errors="replace")[:200]
+                logger.debug("→ %s %d (%dms) %s", endpoint, e.code, elapsed, resp_body[:60])
+
+                if e.code == 401:
+                    raise AuthError(
+                        "Authentication failed. Check your API token.\n"
+                        "  Run: siyuan config set token <your-token>"
+                    )
+                if e.code == 404:
+                    return {"code": 404, "msg": f"Endpoint not found: {endpoint}"}
+                if e.code == 409:
+                    raise ConflictError(f"Resource conflict: {resp_body[:100]}")
+                if e.code == 429:
+                    raise RateLimitError("Too many requests, please wait")
+                if e.code >= 500:
+                    raise ServerError(f"Server error ({e.code}): {resp_body[:100]}")
+                if e.code in (502, 503, 504) and attempt < MAX_RETRIES:
+                    wait = 2**attempt
+                    logger.warning(
+                        "→ %s %d, retry %d/%d in %ds",
+                        endpoint,
+                        e.code,
+                        attempt + 1,
+                        MAX_RETRIES,
+                        wait,
+                    )
+                    time.sleep(wait)
+                    continue
+                return {"code": e.code, "msg": e.reason, "body": resp_body}
+
+            except urllib.error.URLError as e:
+                reason = str(e.reason) if hasattr(e, "reason") else str(e)
+                logger.debug("→ %s NET_ERROR: %s", endpoint, reason)
+                if attempt < MAX_RETRIES:
+                    wait = 2**attempt
+                    logger.warning(
+                        "→ %s connection: %s, retry %d/%d in %ds",
+                        endpoint,
+                        reason,
+                        attempt + 1,
+                        MAX_RETRIES,
+                        wait,
+                    )
+                    time.sleep(wait)
+                    continue
+                raise NetworkError(f"Cannot connect to {self._base_url}: {reason}")
+
+            except Exception as e:
+                logger.debug("→ %s ERROR: %s", endpoint, e)
+                if attempt < MAX_RETRIES:
+                    time.sleep(2**attempt)
+                    continue
+                raise SiYuanError(str(e), "UNKNOWN")
+
+        raise NetworkError(f"Request to {endpoint} failed after {MAX_RETRIES} retries")
+
+
+# Module-level singleton for backward compatibility
+_client: Optional[SiYuanClient] = None
+
+
+def get_client() -> SiYuanClient:
+    """Get or create the shared SiYuanClient singleton.
+
+    Returns:
+        A configured SiYuanClient instance (lazy config).
+    """
+    global _client
+    if _client is None:
+        _client = SiYuanClient()
+    return _client
+
+
+def api_call(endpoint: str, data: Optional[dict] = None) -> dict[str, Any]:
+    """Backward-compatible wrapper — delegates to SiYuanClient singleton.
+
+    Args:
+        endpoint: API endpoint path (e.g. "notebook/lsNotebooks").
+        data: JSON-serializable request body (POSTed).
+
+    Returns:
+        Parsed JSON response dict.
+    """
+    return get_client().call(endpoint, data)

siyuan_cli/commands/__init__.py

@@ -0,0 +1 @@
+# commands package