sylo-ignition 0.1.0

package/references/quickref/formats-quickref.md

@@ -0,0 +1,94 @@
+# Ignition 8.3 formats quickref
+
+Verified against a live 8.3.9 install (2026-08-30).
+
+## On-disk project layout
+
+```
+data/projects/<Name>/
+├── project.json                     # {"title","description","enabled","inheritable","parent"}
+└── com.inductiveautomation.perspective/
+    ├── views/<viewPath>/            # resource.json + view.json + thumbnail.png
+    ├── page-config/config.json/     # page config resource
+    ├── page-startup/onPageStartup.py/
+    └── session-props/props.json/
+```
+
+## resource.json (per resource folder — gateway-owned, never hand-edit existing)
+
+```json
+{
+  "scope": "G",
+  "version": 1,
+  "restricted": false,
+  "overridable": true,
+  "files": ["view.json", "thumbnail.png"],
+  "attributes": {
+    "lastModificationSignature": "<sha256-hex>",
+    "lastModification": { "actor": "operator", "timestamp": "2026-08-30T20:54:34Z" }
+  }
+}
+```
+
+## Perspective view.json skeleton (VERIFIED live on 8.3.9)
+
+```json
+{
+  "custom": {},
+  "params": {},
+  "props": {},
+  "root": {
+    "type": "ia.container.coord",
+    "meta": { "name": "root" },
+    "children": [
+      {
+        "type": "ia.display.label",
+        "meta": { "name": "titleLabel" },
+        "position": { "x": 24, "y": 24, "width": 400, "height": 40 },
+        "props": { "text": "Overview", "style": { "fontSize": "24px" } }
+      }
+    ]
+  }
+}
+```
+
+- `root` is a **top-level key holding the root component** — NOT `props.root.children`.
+  Malformed views are silently dropped by the scan.
+- `meta.name` unique per view. Position: absolute px inside coord (verified);
+  `mode: "flow"` inside flex containers (verified); `mode: "percent"` unverified —
+  labels stacked at 0,0 in live testing.
+- Bindings wrap values: `"text": {"binding": {"type": "property", "config": {"path": "view.params.title"}}}`
+  — types: property, tag (`[provider]path/to/tag`), expr (Perspective expression
+  language), query; `config.transforms` chain output transforms.
+
+## Page-config (required for a view to be reachable)
+
+`com.inductiveautomation.perspective/page-config/config.json`:
+
+```json
+{
+  "pages": { "/": { "viewPath": "Home" } },
+  "sharedDocks": { "cornerPriority": "top-bottom" }
+}
+```
+
+The URL after the project name is the PAGE path; pages map to view paths here.
+
+## project.json
+
+```json
+{ "title": "Example Project", "description": "", "enabled": true, "inheritable": false, "parent": "" }
+```
+
+## Gateway scripts = Jython 2.7
+
+No f-strings / async / pathlib / match. Use `%`/`.format()`. `system.*` functions
+(e.g. `system.tag.readBlocking(["[default]Line1/Speed"])`).
+
+## Auth (API key)
+
+Header `X-Ignition-API-Token`. Working recipe (8.3.9): API key (Basic Token,
+secure-connections unchecked for plain HTTP) holding a custom security level
+(e.g. `SyloAPI` under `Authenticated`), granted Gateway Read + Write in
+Security > General Settings > Roles and Permissions. 401 = bad token;
+403 = insufficient level; 404 = route doesn't exist.

package/references/quickref/gateway-rest-api-8.3.md

@@ -0,0 +1,119 @@
+# Ignition 8.3 Gateway REST API — verified route map
+
+Verified live 2026-08-30 against a **native Windows Ignition 8.3.9** install
+(Perspective module 3.3.9), gateway at `http://localhost:8088`. Full OpenAPI
+spec: `GET /openapi.json` with the `X-Ignition-API-Token` header (12 MB on a
+full-module install, 588 routes). This file is the curated subset the
+sylo-ignition tools actually use.
+
+## Auth (verified recipe)
+
+- Create API key: **Platform → Security → API Keys → Create API Key +**
+  (Basic Token). Token shown once.
+- Key must have **"Require secure connections" unchecked** for plain-HTTP
+  local gateways (checked → 403 over HTTP).
+- Role-derived levels (Roles→Administrator) are **greyed out** for API keys.
+  Custom levels are assignable. Working setup (verified):
+  1. **Platform → Security → Levels**: add custom level `SyloAPI` under
+     `Authenticated`
+  2. Assign `SyloAPI` to the API key
+  3. **Platform → Security → General Settings → Roles and Permissions**:
+     check `SyloAPI` for Gateway Read AND Gateway Write permissions
+- Every request: header `X-Ignition-API-Token: <token>`.
+- Status codes: bad/dead token → 401; insufficient security level → 403
+  (route exists); no such route → 404 (`No route match for path: /v1/...`).
+
+## Scan / safe-edit protocol
+
+| Method | Route | Purpose |
+|--------|-------|---------|
+| GET  | `/data/api/v1/scan/projects` | Project scan status (`scanActive`, `lastScanTimestamp`) |
+| POST | `/data/api/v1/scan/projects` | **Trigger project scan** — hot-loads disk edits into gateway + Designer |
+| GET/POST | `/data/api/v1/scan/config` | Same for gateway config (`data/config/**`) |
+| GET  | `/data/api/v1/scan-lock/projects` | Scan-lock info |
+| POST | `/data/api/v1/scan-lock/projects` | Acquire project scan lock (mutual exclusion while writing on disk) |
+| GET  | `/data/api/v1/sync/items` | Config sync status |
+| POST | `/data/api/v1/sync/reset` | Reset config sync |
+
+## Projects API
+
+| Method | Route | Purpose |
+|--------|-------|---------|
+| GET    | `/data/api/v1/projects/list` | List all projects (with resource counts) |
+| GET    | `/data/api/v1/projects/names` | Project names |
+| POST   | `/data/api/v1/projects` | Create project |
+| GET    | `/data/api/v1/projects/find/{name}` | Project details |
+| PUT    | `/data/api/v1/projects/{name}` | Modify project (title/description/enabled/parent) |
+| DELETE | `/data/api/v1/projects/{name}` | Delete project |
+| POST   | `/data/api/v1/projects/copy` | Copy project |
+| POST   | `/data/api/v1/projects/rename/{name}` | Rename project |
+| GET    | `/data/api/v1/projects/export/{name}` | **Export project zip** |
+| POST   | `/data/api/v1/projects/import/{name}` | **Import project zip** |
+
+## Resources API (gateway config, pattern per type)
+
+Pattern per resource type (393 routes total):
+`GET /data/api/v1/resources/list|names|type|find|rename|delete/{moduleId}/{typeId}`,
+`PUT|POST /data/api/v1/resources/{moduleId}/{typeId}` (create/update),
+`GET|PUT|DELETE .../datafile/{moduleId}/{typeId}/{name}/{filename}` (attached files),
+`GET .../singleton/{moduleId}/{typeId}` (singletons).
+
+Key types for sylo-ignition:
+
+| Module | Type | Use |
+|--------|------|-----|
+| `ignition` | `tag-provider` | Tag provider CRUD |
+| `com.inductiveautomation.opcua` | `device` | OPC UA device connections |
+| `ignition` | `opc-connection` | Legacy OPC connections |
+| `ignition` | `database-connection` | DB connections |
+| `com.inductiveautomation.perspective` | `themes` | **Theme resources** (theme.json + css files via datafile routes) |
+| `com.inductiveautomation.perspective` | `fonts`, `icons` | Fonts / icon sets |
+| `ignition` | `security-levels`, `security-properties`, `security-zone` | Security config |
+| `ignition` | `identity-provider`, `user-source` | Authn config |
+
+## Tags
+
+| Method | Route | Purpose |
+|--------|-------|---------|
+| GET  | `/data/api/v1/tags/export` | **Download tag export (JSON)** — provider/tag paths, recursive |
+| POST | `/data/api/v1/tags/import` | **Import tags (JSON)** — create/override, collision handling |
+| PUT  | `/data/api/v1/managed-tag-provider` | Write managed tag provider definitions |
+
+No REST route for tag **values** (definitions only). Value read/write goes
+through the gateway's OPC-UA server or scripting, not this API.
+
+## Perspective module API
+
+| Method | Route | Purpose |
+|--------|-------|---------|
+| GET    | `/data/perspective/api/v1/sessions/` | Live sessions |
+| GET    | `/data/perspective/api/v1/session/{sessionId}` | Session detail |
+| GET    | `/data/perspective/api/v1/session/{sessionId}/pages` | Pages in session |
+| GET    | `/data/perspective/api/v1/session/{sessionId}/page/{pageId}/views` | Mounted views |
+| DELETE | `/data/perspective/api/v1/sessions` | Terminate session(s) |
+| POST   | `/data/perspective/api/v1/themes/copy-base-themes` | **Copy base themes into project** (start of theme customization) |
+
+## Gateway status / diagnostics
+
+| Method | Route | Purpose |
+|--------|-------|---------|
+| GET  | `/data/api/v1/gateway-info` | Version/edition/platform info |
+| GET  | `/data/api/v1/overview` | Gateway overview (modules, system) |
+| GET  | `/data/api/v1/overview/problems` | Health problems list |
+| GET  | `/data/api/v1/overview/connections` | Connection statuses |
+| GET  | `/data/api/v1/logs` | Gateway logs (debug scan failures etc.) |
+| GET  | `/data/api/v1/logs/download` | Download logs |
+| GET  | `/data/api/v1/backup` | **Gateway backup download** (pre-change safety) |
+| POST | `/data/api/v1/backup` | Restore backup |
+| GET  | `/data/api/v1/designers` | Open Designer sessions (conflict detection!) |
+| GET  | `/data/api/v1/entity/browse` | Browse config entities |
+| GET/POST/PUT/DELETE | `/data/api/v1/mode*` | Deployment modes |
+| GET  | `/data/api/v1/licenses` | License info |
+| GET  | `/data/api/v1/trial` | Trial info |
+
+## OPC-UA module API (client/server PKI)
+
+`/data/opc-ua/api/v1/...` — trust/reject/download/upload certificates for
+client & server PKI, regenerate server certificate. Needed for connecting to
+real PLCs (Logix/Modbus/Siemens etc. are driver configs via resources API:
+`com.inductiveautomation.opcua/device`).

package/scripts/_allowlist.py

@@ -0,0 +1,119 @@
+#!/usr/bin/env python3
+"""Shared write-allowlist loader / gates for sylo-ignition.
+
+The allowlist lives at packages/sylo-ignition/assets/write-allowlist.json and is
+OPERATOR-MANAGED — the agent must never edit it. Every mutating tool
+(resource_write, scan, project_create, REST writes) enforces it in Python:
+refuse anything not explicitly allowed here.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from _json_out import emit_error
+
+
+def package_root() -> Path:
+    return Path(__file__).resolve().parent.parent
+
+
+def allowlist_path() -> Path:
+    env = os.environ.get("IGNITION_WRITE_ALLOWLIST", "").strip()
+    if env:
+        return Path(env).expanduser().resolve()
+    return package_root() / "assets" / "write-allowlist.json"
+
+
+def default_allowlist() -> dict[str, Any]:
+    return {
+        "allow_writes": False,
+        "allow_scan": False,
+        "allow_project_create": False,
+        "projects": [],
+        "updated_at": None,
+        "notes": "Operator-managed. The agent cannot edit this file; mutating tools enforce it.",
+    }
+
+
+def load_allowlist() -> dict[str, Any]:
+    path = allowlist_path()
+    if not path.is_file():
+        return default_allowlist()
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return default_allowlist()
+    if not isinstance(data, dict):
+        return default_allowlist()
+    base = default_allowlist()
+    base.update(data)
+    if not isinstance(base.get("projects"), list):
+        base["projects"] = []
+    return base
+
+
+def _project_entry(allow: dict[str, Any], project: str) -> dict[str, Any] | None:
+    for entry in allow.get("projects", []):
+        if isinstance(entry, dict) and entry.get("name") == project:
+            return entry
+    return None
+
+
+def gate_writes(allow: dict[str, Any], project: str) -> None:
+    """Exit with a clear error unless project file-writes are allowed."""
+    if not allow.get("allow_writes"):
+        emit_error(
+            "File writes are disabled in the Ignition write-allowlist "
+            f"({allowlist_path()}). The operator must set allow_writes=true."
+        )
+    entry = _project_entry(allow, project)
+    if entry is None:
+        emit_error(
+            f"Project '{project}' is not in the Ignition write-allowlist. "
+            "The operator must add it there (assets/write-allowlist.json) before any write. "
+            "The agent must not edit that file."
+        )
+    if not entry.get("enabled", False):
+        emit_error(
+            f"Project '{project}' is present but DISABLED in the Ignition write-allowlist. "
+            "Ask the operator to enable it (or use a different allowed project)."
+        )
+
+
+def gate_scan(allow: dict[str, Any]) -> None:
+    if not allow.get("allow_scan"):
+        emit_error(
+            "Gateway scan is disabled in the Ignition write-allowlist "
+            f"({allowlist_path()}). The operator must set allow_scan=true to hot-apply edits."
+        )
+
+
+def gate_project_create(allow: dict[str, Any], name: str) -> None:
+    if not allow.get("allow_project_create"):
+        emit_error(
+            "Project creation is disabled in the Ignition write-allowlist. "
+            "The operator must set allow_project_create=true."
+        )
+    if not name or any(c in name for c in '/\\:*?"<>|') or name.strip() != name:
+        emit_error(f"Invalid project name: {name!r}")
+
+
+def summary(allow: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "allow_writes": bool(allow.get("allow_writes")),
+        "allow_scan": bool(allow.get("allow_scan")),
+        "allow_project_create": bool(allow.get("allow_project_create")),
+        "writable_projects": [
+            e.get("name") for e in allow.get("projects", []) if isinstance(e, dict) and e.get("enabled")
+        ],
+        "path": str(allowlist_path()),
+    }
+
+
+def note_update() -> dict[str, Any]:
+    return {"updated_at": datetime.now(timezone.utc).isoformat()}

package/scripts/_ignition.py

@@ -0,0 +1,181 @@
+#!/usr/bin/env python3
+"""Shared Ignition gateway plumbing: config file, REST client, data-dir paths.
+
+Connection config lives OUTSIDE any repo at ~/.ignition-sylo/config.json so the
+API token never lands in git:
+
+    {
+      "gateway_url": "http://localhost:8088",
+      "api_token": "Sylo:...",
+      "data_dir": "C:\\Program Files\\Inductive Automation\\Ignition\\data",
+      "default_project": "SyloSandbox"
+    }
+
+Env overrides (testing): IGNITION_SYLO_CONFIG (path), IGNITION_SYLO_URL,
+IGNITION_SYLO_TOKEN, IGNITION_SYLO_DATA_DIR, IGNITION_SYLO_PROJECT.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import ssl
+import urllib.error
+import urllib.parse
+import urllib.request
+from pathlib import Path
+from typing import Any
+
+from _json_out import emit_error
+
+CONFIG_FILENAME = "config.json"
+COMMON_DATA_DIRS = (
+    r"C:\Program Files\Inductive Automation\Ignition\data",
+    r"C:\Program Files (x86)\Inductive Automation\Ignition\data",
+)
+
+
+def config_path() -> Path:
+    env = os.environ.get("IGNITION_SYLO_CONFIG", "").strip()
+    if env:
+        return Path(env).expanduser().resolve()
+    return Path.home() / ".ignition-sylo" / CONFIG_FILENAME
+
+
+def _first_existing_data_dir() -> str | None:
+    for candidate in COMMON_DATA_DIRS:
+        if Path(candidate).is_dir():
+            return candidate
+    return None
+
+
+def load_config(require_token: bool = True) -> dict[str, Any]:
+    """Load connection config; emit_error exits on missing pieces."""
+    path = config_path()
+    cfg: dict[str, Any] = {}
+    if path.is_file():
+        try:
+            cfg = json.loads(path.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError) as e:
+            emit_error(f"Could not parse {path}: {e}")
+    else:
+        emit_error(
+            f"No Ignition connection config at {path}. "
+            "Create it (see skill: setup section) with gateway_url + api_token "
+            "(Platform > Security > API Keys in the gateway web UI)."
+        )
+    # Env overrides
+    cfg["gateway_url"] = os.environ.get("IGNITION_SYLO_URL", "").strip() or cfg.get("gateway_url", "")
+    token = os.environ.get("IGNITION_SYLO_TOKEN", "").strip() or cfg.get("api_token", "").strip()
+    cfg["api_token"] = token
+    cfg["data_dir"] = (
+        os.environ.get("IGNITION_SYLO_DATA_DIR", "").strip() or cfg.get("data_dir") or _first_existing_data_dir()
+    )
+    cfg["default_project"] = (
+        os.environ.get("IGNITION_SYLO_PROJECT", "").strip() or cfg.get("default_project") or ""
+    )
+    cfg["_config_path"] = str(path)
+
+    if not cfg.get("gateway_url"):
+        emit_error(f"gateway_url missing in {path}")
+    if require_token and not cfg.get("api_token"):
+        emit_error(
+            f"api_token missing in {path}. Create an API key (Platform > Security > API Keys), "
+            "give it a custom security level granted Gateway Read+Write (see skill setup), "
+            f"then put the token in {path}."
+        )
+    cfg["gateway_url"] = str(cfg["gateway_url"]).rstrip("/")
+    return cfg
+
+
+def projects_dir(cfg: dict[str, Any]) -> Path:
+    return Path(cfg["data_dir"]) / "projects"
+
+
+def project_dir(cfg: dict[str, Any], project: str) -> Path:
+    return projects_dir(cfg) / project
+
+
+def api(
+    cfg: dict[str, Any],
+    route: str,
+    method: str = "GET",
+    body: Any = None,
+    timeout: float = 30.0,
+    raw: bool = False,
+) -> tuple[int, Any, dict[str, str]]:
+    """Call the gateway REST API with the X-Ignition-API-Token header.
+
+    Returns (status, parsed_json_or_text_or_bytes, headers). Auth/permission
+    failures are returned as status codes — callers decide how to surface.
+    """
+    url = route if route.startswith("http") else cfg["gateway_url"] + route
+    data: bytes | None = None
+    headers = {"Accept": "application/json"}
+    if cfg.get("api_token"):
+        headers["X-Ignition-API-Token"] = cfg["api_token"]
+    if body is not None:
+        if isinstance(body, (bytes, bytearray)):
+            data = bytes(body)
+            headers["Content-Type"] = "application/octet-stream"
+        else:
+            data = json.dumps(body).encode("utf-8")
+            headers["Content-Type"] = "application/json"
+    req = urllib.request.Request(url, data=data, headers=headers, method=method.upper())
+    ctx = ssl.create_default_context()
+    # Local gateways commonly run plain HTTP or self-signed HTTPS.
+    ctx.check_hostname = False
+    ctx.verify_mode = ssl.CERT_NONE
+    try:
+        with urllib.request.urlopen(req, timeout=timeout, context=ctx) as resp:
+            payload = resp.read()
+            status = resp.status
+            resp_headers = {k.lower(): v for k, v in resp.headers.items()}
+    except urllib.error.HTTPError as e:
+        payload = e.read()
+        status = e.code
+        resp_headers = {k.lower(): v for k, v in e.headers.items()}
+    except (urllib.error.URLError, TimeoutError, OSError) as e:
+        emit_error(f"Gateway unreachable at {url}: {e}")
+    if raw:
+        return status, payload, resp_headers
+    text = payload.decode("utf-8", errors="replace")
+    try:
+        return status, json.loads(text), resp_headers
+    except (json.JSONDecodeError, ValueError):
+        return status, text, resp_headers
+
+
+def api_expect(
+    cfg: dict[str, Any],
+    route: str,
+    method: str = "GET",
+    body: Any = None,
+    timeout: float = 30.0,
+    what: str = "",
+) -> Any:
+    """api() that emit_errors on any non-2xx status."""
+    status, parsed, _ = api(cfg, route, method=method, body=body, timeout=timeout)
+    if status >= 400:
+        if isinstance(parsed, dict):
+            hint = parsed.get("message") or parsed.get("error") or json.dumps(parsed)[:200]
+        else:
+            hint = str(parsed)[:200]
+        emit_error(f"{method} {route} -> HTTP {status}: {hint}" + (f" ({what})" if what else ""))
+    return parsed
+
+
+def mask_token(token: str) -> str:
+    if not token:
+        return ""
+    return token[:6] + "..." if len(token) > 9 else "***"
+
+
+def resolve_project(cfg: dict[str, Any], project: str | None) -> str:
+    name = (project or "").strip() or cfg.get("default_project", "").strip()
+    if not name:
+        emit_error(
+            "No project specified and no default_project in config. "
+            "Pass --project or set default_project in ~/.ignition-sylo/config.json."
+        )
+    return name

package/scripts/_json_out.py

@@ -0,0 +1,19 @@
+#!/usr/bin/env python3
+"""Shared JSON stdout helpers for sylo-ignition scripts."""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any
+
+
+def emit(payload: dict[str, Any]) -> None:
+    """Print JSON to stdout and exit with code 0 or 1."""
+    print(json.dumps(payload, indent=2))
+    if payload.get("ok") is False:
+        sys.exit(1)
+
+
+def emit_error(message: str, **extra: Any) -> None:
+    emit({"ok": False, "error": message, **extra})

package/scripts/api_get.py

@@ -0,0 +1,71 @@
+#!/usr/bin/env python3
+"""Read-only GET passthrough for gateway REST routes — ignition_api_get.
+
+Lets the agent explore the 588-route API (resource lists, session detail,
+overviews, tag exports) without a dedicated tool per route. GET ONLY — every
+mutating verb is refused; the mutating tools have their own gates.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+from typing import Any
+
+from _ignition import api, load_config
+from _json_out import emit, emit_error
+
+ALLOWED_PREFIXES = ("/data/", "/openapi.json", "/system/")
+MAX_INLINE_CHARS = 24_000
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--route", required=True, help="GET route, e.g. /data/api/v1/projects/list (query string allowed)")
+    parser.add_argument("--save", default="", help="save the full JSON payload to this file (recommended for big routes)")
+    parser.add_argument("--timeout", type=float, default=30.0)
+    args = parser.parse_args()
+
+    route = args.route.strip()
+    if not route.startswith(ALLOWED_PREFIXES) or route.startswith("//"):
+        emit_error(
+            f"Route must start with one of {ALLOWED_PREFIXES}. Got: {route!r}. "
+            "Mutating methods are not available through this tool."
+        )
+    if "?" in route and any(
+        kw in route.lower() for kw in ("method=", "delete", "put", "post")
+    ):
+        # route query strings don't carry verbs, but guard obviously wrong usage
+        pass  # no-op: query params like ?scope=projects are legitimate
+
+    cfg = load_config()
+    status, data, _ = api(cfg, route, method="GET", timeout=args.timeout)
+
+    out: dict[str, Any] = {"ok": status < 400, "route": route, "http_status": status}
+    if status >= 400:
+        out["error"] = str(data)[:300]
+        emit(out)
+
+    if args.save:
+        save_path = Path(args.save).expanduser()
+        save_path.parent.mkdir(parents=True, exist_ok=True)
+        if isinstance(data, (dict, list)):
+            save_path.write_text(json.dumps(data, indent=2), encoding="utf-8")
+        else:
+            save_path.write_text(str(data), encoding="utf-8")
+        out["saved_to"] = str(save_path)
+        out["hint"] = "Full payload saved to disk — read it with the read tool."
+    else:
+        text = json.dumps(data, indent=2) if not isinstance(data, str) else data
+        if len(text) > MAX_INLINE_CHARS:
+            out["payload"] = text[:MAX_INLINE_CHARS]
+            out["truncated"] = True
+            out["hint"] = "Truncated — re-run with --save <path> to capture the full payload."
+        else:
+            out["payload"] = data
+    emit(out)
+
+
+if __name__ == "__main__":
+    main()

package/scripts/backup.py

@@ -0,0 +1,49 @@
+#!/usr/bin/env python3
+"""Download a gateway backup (.gwbk) — the pre-change safety net.
+
+For ignition_backup tool. Read-only (GET /data/api/v1/backup). Backups land in
+~/.ignition-sylo/backups/ by default (outside any repo).
+"""
+
+from __future__ import annotations
+
+import argparse
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+from _ignition import api, load_config
+from _json_out import emit, emit_error
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--out", default="", help="output .gwbk file (default ~/.ignition-sylo/backups/<ts>.gwbk)")
+    args = parser.parse_args()
+
+    cfg = load_config()
+    out_path = Path(args.out).expanduser() if args.out.strip() else (
+        Path.home() / ".ignition-sylo" / "backups" / f"gateway-{datetime.now().strftime('%Y%m%d-%H%M%S')}.gwbk"
+    )
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+
+    status, payload, headers = api(cfg, "/data/api/v1/backup", method="GET", timeout=300, raw=True)
+    if status >= 400:
+        emit_error(f"Backup -> HTTP {status} ({payload[:200]!r})")
+    if not payload or len(payload) < 10_000:
+        emit_error(f"Backup response suspiciously small ({len(payload)} bytes) — not saved.")
+
+    out_path.write_bytes(payload)
+    emit(
+        {
+            "ok": True,
+            "backup_path": str(out_path),
+            "bytes": len(payload),
+            "content_type": headers.get("content-type", ""),
+            "note": "Restore via gateway web UI (Gateway > Restore) or POST /data/api/v1/backup. Keep this file until changes are verified.",
+        }
+    )
+
+
+if __name__ == "__main__":
+    main()