flowbase-cli 0.1.12__py3-none-any.whl

flowbase_cli/main.py

@@ -0,0 +1,1500 @@
+"""Command line client for the FlowBase OpenAPI."""
+from __future__ import annotations
+
+import argparse
+from http.client import HTTPException as TransportError
+from decimal import Decimal
+import json
+import mimetypes
+import os
+import secrets
+import sys
+from pathlib import Path
+from typing import Any
+from urllib.error import HTTPError, URLError
+from urllib.parse import quote, urlencode
+from urllib.request import Request, urlopen
+
+from flowbase_cli.endpoints import (
+    CATALOGS,
+    AUTHORING,
+    ENDPOINTS,
+    ENDPOINT_BY_KEY,
+    PENDING_MANAGEMENT_OPERATIONS,
+    Endpoint,
+)
+
+DEFAULT_HOST = "http://flowbase.localhost:5001"
+API_PREFIX = "/api/openapi/v1"
+ENV_HOST = "FLOWBASE_HOST"
+ENV_API_KEY = "FLOWBASE_API_KEY"
+
+
+class CliError(Exception):
+    """Expected user-facing CLI failure."""
+
+
+def api_root(host: str) -> str:
+    normalized = host.strip().rstrip("/")
+    if not normalized:
+        raise CliError("Host cannot be empty.")
+    if normalized.endswith(API_PREFIX):
+        return normalized
+    return f"{normalized}{API_PREFIX}"
+
+
+def get_endpoint(key: str) -> Endpoint:
+    try:
+        return ENDPOINT_BY_KEY[key]
+    except KeyError as exc:
+        raise CliError(f"Unknown endpoint: {key}") from exc
+
+
+def load_json_payload(json_text: str | None, json_file: str | None) -> dict[str, Any]:
+    if json_text and json_file:
+        raise CliError("--json and --json-file cannot be used together.")
+    if not json_text and not json_file:
+        return {}
+    try:
+        source = Path(json_file).read_text(encoding="utf-8") if json_file else (json_text or "{}")
+    except OSError as exc:
+        raise CliError(f"Cannot read JSON file: {exc}") from exc
+    try:
+        payload = json.loads(source, parse_float=Decimal)
+    except json.JSONDecodeError as exc:
+        raise CliError(f"Invalid JSON at line {exc.lineno}, column {exc.colno}: {exc.msg}") from exc
+    if not isinstance(payload, dict):
+        raise CliError("JSON payload must be an object.")
+    return payload
+
+
+def require_fields(payload: dict[str, Any], *names: str) -> None:
+    missing = [name for name in names if name not in payload or payload[name] is None]
+    if missing:
+        raise CliError(f"Missing request field(s): {', '.join(missing)}")
+
+
+class OpenApiClient:
+    def __init__(self, host: str, api_key: str | None) -> None:
+        self.root = api_root(host)
+        self.api_key = api_key
+
+    def build_url(
+        self,
+        endpoint: Endpoint,
+        path_params: dict[str, Any] | None = None,
+        query: dict[str, Any] | None = None,
+    ) -> str:
+        path = endpoint.path
+        values = path_params or {}
+        for name in _path_parameter_names(endpoint.path):
+            if name not in values:
+                raise CliError(f"Missing path parameter: {name}")
+            path = path.replace("{" + name + "}", quote(str(values[name]), safe=""))
+        clean_query = {key: value for key, value in (query or {}).items() if value is not None}
+        suffix = f"?{urlencode(clean_query, doseq=True)}" if clean_query else ""
+        return f"{self.root}{path}{suffix}"
+
+    def request(
+        self,
+        endpoint_key: str,
+        *,
+        path_params: dict[str, Any] | None = None,
+        query: dict[str, Any] | None = None,
+        body: dict[str, Any] | None = None,
+        raw_body: bytes | None = None,
+        content_type: str | None = None,
+        accept: str = "application/json",
+    ) -> bytes:
+        endpoint = get_endpoint(endpoint_key)
+        if not self.api_key:
+            raise CliError(f"Missing API key. Set {ENV_API_KEY} or pass --api-key.")
+        url = self.build_url(endpoint, path_params, query)
+        headers = {
+            "Accept": accept,
+            "Authorization": f"Bearer {self.api_key}",
+            "X-FlowBase-Channel": "cli",
+        }
+        if body is not None and raw_body is not None:
+            raise CliError("JSON and raw request bodies cannot be used together.")
+        data = raw_body
+        if body is not None:
+            data = exact_json_dumps(body).encode("utf-8")
+            headers["Content-Type"] = "application/json"
+        elif raw_body is not None and content_type:
+            headers["Content-Type"] = content_type
+        request = Request(url, data=data, headers=headers, method=endpoint.method)
+        try:
+            with urlopen(request, timeout=60) as response:  # noqa: S310 - the user selects the FlowBase host.
+                return response.read()
+        except HTTPError as exc:
+            payload = exc.read().decode("utf-8", errors="replace")
+            raise CliError(f"HTTP {exc.code} for {endpoint.key}: {_error_detail(payload)}") from exc
+        except (OSError, TransportError) as exc:
+            reason = str(exc.reason if isinstance(exc, URLError) else exc)
+            reason = reason.replace(self.api_key, "<redacted>")
+            recovery = (
+                " The write result is unknown; read the resource and its revision before retrying."
+                if endpoint.method not in ("GET", "HEAD")
+                else " Retry the read after checking connectivity."
+            )
+            raise CliError(f"Network error for {endpoint.key}: {reason}.{recovery}") from exc
+
+
+def _path_parameter_names(path: str) -> list[str]:
+    return [part[1:-1] for part in path.split("/") if part.startswith("{") and part.endswith("}")]
+
+
+def _error_detail(payload: str) -> str:
+    try:
+        parsed = json.loads(payload)
+    except json.JSONDecodeError:
+        return payload or "empty response"
+    if isinstance(parsed, dict) and "detail" in parsed:
+        detail = parsed["detail"]
+        return detail if isinstance(detail, str) else json.dumps(detail, ensure_ascii=False)
+    return json.dumps(parsed, ensure_ascii=False)
+
+
+def exact_json_dumps(value: Any) -> str:
+    if value is None:
+        return "null"
+    if value is True:
+        return "true"
+    if value is False:
+        return "false"
+    if isinstance(value, str):
+        return json.dumps(value, ensure_ascii=False)
+    if isinstance(value, Decimal):
+        if not value.is_finite():
+            raise CliError("JSON numbers must be finite.")
+        return format(value, "f")
+    if isinstance(value, int):
+        return str(value)
+    if isinstance(value, float):
+        raise CliError("Binary floating-point values are not accepted.")
+    if isinstance(value, list):
+        return "[" + ",".join(exact_json_dumps(item) for item in value) + "]"
+    if isinstance(value, dict):
+        return "{" + ",".join(
+            f"{json.dumps(str(key), ensure_ascii=False)}:{exact_json_dumps(item)}"
+            for key, item in value.items()
+        ) + "}"
+    raise CliError(f"Unsupported JSON value: {type(value).__name__}")
+
+
+def multipart_upload(path_value: str) -> tuple[bytes, str]:
+    path = Path(path_value)
+    try:
+        content = path.read_bytes()
+    except OSError as exc:
+        raise CliError(f"Cannot read attachment: {exc}") from exc
+    filename = path.name.replace('"', "_").replace("\r", "_").replace("\n", "_") or "file"
+    boundary = f"flowbase-{secrets.token_hex(16)}"
+    content_type = mimetypes.guess_type(filename)[0] or "application/octet-stream"
+    ascii_name = filename.encode("ascii", errors="replace").decode("ascii")
+    disposition = (
+        f'Content-Disposition: form-data; name="upload"; filename="{ascii_name}"; '
+        f"filename*=UTF-8''{quote(filename, safe='')}\r\n"
+    ).encode("ascii")
+    payload = b"".join([
+        f"--{boundary}\r\n".encode("ascii"),
+        disposition,
+        f"Content-Type: {content_type}\r\n\r\n".encode("ascii"),
+        content,
+        f"\r\n--{boundary}--\r\n".encode("ascii"),
+    ])
+    return payload, f"multipart/form-data; boundary={boundary}"
+
+
+def print_output(data: bytes, *, pretty: bool, raw: bool) -> None:
+    text = data.decode("utf-8", errors="replace")
+    if raw:
+        print(text, end="" if text.endswith("\n") else "\n")
+        return
+    try:
+        parsed = json.loads(text)
+    except json.JSONDecodeError:
+        print(text, end="" if text.endswith("\n") else "\n")
+        return
+    indent = 2 if pretty else None
+    separators = None if pretty else (",", ":")
+    print(json.dumps(parsed, ensure_ascii=False, indent=indent, separators=separators))
+
+
+def confirm_change(endpoint: Endpoint, yes: bool) -> None:
+    if not endpoint.requires_confirmation or yes:
+        return
+    if not sys.stdin.isatty():
+        raise CliError("Refusing a state-changing command in non-interactive mode without --yes.")
+    answer = input(f"{endpoint.summary} Continue? [y/N] ").strip().lower()
+    if answer not in {"y", "yes"}:
+        raise CliError("Cancelled.")
+
+
+def client_from_args(args: argparse.Namespace) -> OpenApiClient:
+    host = args.host or os.getenv(ENV_HOST) or DEFAULT_HOST
+    api_key = args.api_key or os.getenv(ENV_API_KEY)
+    return OpenApiClient(host, api_key)
+
+
+def run_request(
+    args: argparse.Namespace,
+    endpoint_key: str,
+    *,
+    path_params: dict[str, Any] | None = None,
+    query: dict[str, Any] | None = None,
+    body: dict[str, Any] | None = None,
+) -> int:
+    endpoint = get_endpoint(endpoint_key)
+    confirm_change(endpoint, getattr(args, "yes", False))
+    data = client_from_args(args).request(endpoint_key, path_params=path_params, query=query, body=body)
+    print_output(data, pretty=args.pretty, raw=args.raw)
+    return 0
+
+
+def handle_organization(args: argparse.Namespace) -> int:
+    return run_request(args, f"organization.{args.organization_action}", query={"query": args.query, "page": args.page} if args.organization_action == "employees" else None)
+
+
+def handle_guide(args: argparse.Namespace) -> int:
+    from flowbase_cli.guide import render
+    print(render(args.format))
+    return 0
+
+
+def handle_docs(args: argparse.Namespace) -> int:
+    if args.docs_action == "example":
+        return handle_docs_example(args)
+    if args.docs_action == "catalogs":
+        return handle_docs_catalogs(args)
+    if args.docs_action == "operations":
+        delivered = [
+            {
+                "key": endpoint.key,
+                "status": "delivered",
+                "operationId": endpoint.operation_id,
+                "method": endpoint.method,
+                "path": endpoint.path,
+                "scope": endpoint.scope,
+                "environments": list(endpoint.environments),
+                "requiresPreflight": endpoint.preflight_operation_id is not None,
+                "requiresConfirmation": endpoint.requires_confirmation,
+                "auditEvent": endpoint.audit_event,
+            }
+            for endpoint in ENDPOINTS
+            if endpoint.scope.startswith("metadata:")
+        ]
+        print(
+            json.dumps(
+                delivered + list(PENDING_MANAGEMENT_OPERATIONS),
+                ensure_ascii=False,
+                indent=2 if args.pretty else None,
+            )
+        )
+        return 0
+    if args.docs_action == "list":
+        payload = [
+            {
+                "key": e.key,
+                "operationId": e.operation_id,
+                "method": e.method,
+                "path": e.path,
+                "scope": e.scope,
+                "environments": list(e.environments),
+                "summary": e.summary,
+                "hasRequestBody": e.request_body is not None,
+                "requiresConfirmation": e.requires_confirmation,
+            }
+            for e in ENDPOINTS
+        ]
+        print(json.dumps(payload, ensure_ascii=False, indent=2 if args.pretty else None))
+        return 0
+    if args.docs_action == "catalogs":
+        return handle_docs_catalogs(args)
+    endpoint = get_endpoint(args.endpoint)
+    payload = {
+        "key": endpoint.key,
+        "operationId": endpoint.operation_id,
+        "method": endpoint.method,
+        "path": endpoint.path,
+        "scope": endpoint.scope,
+        "summary": endpoint.summary,
+        "requiresConfirmation": endpoint.requires_confirmation,
+        "environments": list(endpoint.environments),
+        "preflightOperationId": endpoint.preflight_operation_id,
+        "auditEvent": endpoint.audit_event,
+        "example": endpoint.example,
+        "requestBody": endpoint.request_body,
+        "responseShape": AUTHORING["responseShapes"].get(endpoint.key),
+    }
+    print(json.dumps(payload, ensure_ascii=False, indent=2 if args.pretty else None))
+    return 0
+
+
+def handle_docs_catalogs(args: argparse.Namespace) -> int:
+    if args.name is None:
+        print(
+            json.dumps(
+                sorted(CATALOGS),
+                ensure_ascii=False,
+                indent=2 if args.pretty else None,
+            )
+        )
+        return 0
+    try:
+        payload = CATALOGS[args.name]
+    except KeyError as exc:
+        raise CliError(
+            f"Unknown catalog: {args.name}. Available: {', '.join(sorted(CATALOGS))}"
+        ) from exc
+    print(json.dumps(payload, ensure_ascii=False, indent=2 if args.pretty else None))
+    return 0
+
+
+def handle_docs_example(args: argparse.Namespace) -> int:
+    endpoint = get_endpoint(args.endpoint)
+    body = endpoint.request_body or "{}"
+    target = args.output
+    if target:
+        try:
+            Path(target).write_text(body + "\n", encoding="utf-8")
+        except OSError as exc:
+            raise CliError(f"Cannot write example: {exc}") from exc
+        print(target)
+    else:
+        print(body)
+    return 0
+
+
+def _payload_from_args(args: argparse.Namespace, direct: dict[str, Any], required: tuple[str, ...]) -> dict[str, Any]:
+    payload = load_json_payload(args.json, args.json_file)
+    payload.update({key: value for key, value in direct.items() if value is not None})
+    require_fields(payload, *required)
+    return payload
+
+
+def handle_apps(args: argparse.Namespace) -> int:
+    action = args.apps_action
+    if action == "list":
+        return run_request(args, "apps.list")
+    if action == "get":
+        return run_request(args, "apps.get", path_params={"app_id": args.app_id})
+    if action == "create":
+        body = _payload_from_args(
+            args,
+            {"label": args.label, "key": args.key, "icon": args.icon, "color": args.color},
+            ("label", "key"),
+        )
+        return run_request(args, "apps.create", body=body)
+    if action == "update":
+        body = _payload_from_args(
+            args,
+            {"label": args.label, "icon": args.icon, "color": args.color},
+            ("label", "icon", "color"),
+        )
+        return run_request(args, "apps.update", path_params={"app_id": args.app_id}, body=body)
+    if action == "set-enabled":
+        return run_request(
+            args,
+            "apps.set-enabled",
+            path_params={"app_id": args.app_id},
+            body={"enabled": args.enabled},
+        )
+    if action == "add-objects":
+        ids = [item.strip() for item in (args.object_ids or "").split(",") if item.strip()]
+        if not ids:
+            raise CliError("Provide --object-ids as a comma-separated list.")
+        return run_request(
+            args,
+            "apps.objects.add",
+            path_params={"app_id": args.app_id},
+            body={"objectIds": ids},
+        )
+    if action == "remove-object":
+        return run_request(
+            args,
+            "apps.objects.remove",
+            path_params={"app_id": args.app_id, "object_id": args.object_id},
+        )
+    if action == "set-group":
+        if args.ungrouped:
+            body = {"groupId": None}
+        elif args.group_id is not None:
+            body = {"groupId": args.group_id}
+        else:
+            raise CliError("Provide --group-id or --ungrouped.")
+        return run_request(
+            args,
+            "apps.objects.set-group",
+            path_params={"app_id": args.app_id, "object_id": args.object_id},
+            body=body,
+        )
+    if action == "reorder-objects":
+        body = _payload_from_args(args, {}, ("objectIds",))
+        return run_request(
+            args,
+            "apps.objects.reorder",
+            path_params={"app_id": args.app_id},
+            body=body,
+        )
+    if action == "add-dashboards":
+        ids = [item.strip() for item in args.dashboard_ids if item.strip()]
+        if not ids:
+            raise CliError("Provide at least one dashboard ID.")
+        return run_request(
+            args,
+            "apps.dashboards.add",
+            path_params={"app_id": args.app_id},
+            body={"dashboardIds": ids},
+        )
+    if action == "remove-dashboard":
+        return run_request(
+            args,
+            "apps.dashboards.remove",
+            path_params={"app_id": args.app_id, "dashboard_id": args.dashboard_id},
+        )
+    if action == "set-dashboard-group":
+        if args.ungrouped:
+            body = {"groupId": None}
+        elif args.group_id is not None:
+            body = {"groupId": args.group_id}
+        else:
+            raise CliError("Provide --group-id or --ungrouped.")
+        return run_request(
+            args,
+            "apps.dashboards.set-group",
+            path_params={"app_id": args.app_id, "dashboard_id": args.dashboard_id},
+            body=body,
+        )
+    if action == "reorder-members":
+        body = _payload_from_args(args, {}, ("items",))
+        if not isinstance(body["items"], list):
+            raise CliError("Request field 'items' must be an array.")
+        return run_request(
+            args,
+            "apps.members.reorder",
+            path_params={"app_id": args.app_id},
+            body=body,
+        )
+    return run_request(args, "apps.delete", path_params={"app_id": args.app_id})
+
+
+def handle_dashboards(args: argparse.Namespace) -> int:
+    action = args.dashboards_action
+    if action == "run":
+        return run_request(args, "dashboards.run", path_params={"dashboard_id": args.dashboard_id, "component_id": args.component_id}, body=load_json_payload(args.json, args.json_file))
+    if action == "list":
+        return run_request(args, "dashboards.list")
+    if action == "get":
+        return run_request(args, "dashboards.get", path_params={"dashboard_id": args.dashboard_id})
+    if action == "create":
+        body = _payload_from_args(
+            args,
+            {
+                "label": args.label,
+                "key": args.key,
+                "icon": args.icon,
+                "description": args.description,
+            },
+            ("label", "key"),
+        )
+        return run_request(args, "dashboards.create", body=body)
+    if action == "update":
+        body = load_json_payload(args.json, args.json_file)
+        require_fields(body, "label")
+        return run_request(
+            args,
+            "dashboards.update",
+            path_params={"dashboard_id": args.dashboard_id},
+            body=body,
+        )
+    if action == "copy":
+        return run_request(
+            args,
+            "dashboards.copy",
+            path_params={"dashboard_id": args.dashboard_id},
+        )
+    return run_request(
+        args,
+        "dashboards.delete",
+        path_params={"dashboard_id": args.dashboard_id},
+    )
+
+
+def handle_groups(args: argparse.Namespace) -> int:
+    action = args.groups_action
+    path = {"app_id": args.app_id}
+    if action == "create":
+        body = _payload_from_args(args, {"name": args.name, "icon": args.icon}, ("name",))
+        return run_request(args, "apps.groups.create", path_params=path, body=body)
+    if action == "reorder":
+        body = _payload_from_args(args, {}, ("groupIds",))
+        return run_request(args, "apps.groups.reorder", path_params=path, body=body)
+    if action == "update":
+        path["group_id"] = args.group_id
+        body = _payload_from_args(args, {"name": args.name, "icon": args.icon}, ("name", "icon"))
+        return run_request(args, "apps.groups.update", path_params=path, body=body)
+    path["group_id"] = args.group_id
+    return run_request(args, "apps.groups.delete", path_params=path)
+
+
+def handle_objects(args: argparse.Namespace) -> int:
+    action = args.objects_action
+    if action == "list":
+        return run_request(args, "objects.list", query={"status": args.status})
+    if action == "get":
+        return run_request(args, "objects.get", path_params={"object_id": args.object_id}, query={"status": args.status})
+    if action == "cli-edit-policy":
+        path = {"object_id": args.object_id}
+        if args.objects_cli_edit_policy_action == "get":
+            return run_request(
+                args, "objects.cli-edit-policy.get", path_params=path
+            )
+        body = load_json_payload(args.json, args.json_file)
+        require_fields(body, "baseRevision", "policies")
+        if not isinstance(body["policies"], dict):
+            raise CliError("Request field 'policies' must be an object.")
+        return run_request(
+            args,
+            "objects.cli-edit-policy.update",
+            path_params=path,
+            body=body,
+        )
+    if action == "create":
+        body = _payload_from_args(
+            args,
+            {
+                "label": args.label,
+                "key": args.key,
+                "description": args.description,
+            },
+            ("label", "key", "description"),
+        )
+        return run_request(args, "objects.create", body=body)
+    if action == "update":
+        body = _payload_from_args(
+            args,
+            {
+                "label": args.label,
+                "description": args.description,
+            },
+            ("label", "description"),
+        )
+        return run_request(args, "objects.update", path_params={"object_id": args.object_id}, body=body)
+    return run_request(args, f"objects.{action}", path_params={"object_id": args.object_id})
+
+
+def handle_fields(args: argparse.Namespace) -> int:
+    action = args.fields_action
+    path = {"object_id": args.object_id}
+    if hasattr(args, "field_id"):
+        path["field_id"] = args.field_id
+    if action == "create":
+        body = _payload_from_args(
+            args,
+            {"label": args.label, "key": args.key, "description": args.description},
+            ("label", "key", "description"),
+        )
+        if not body.get("type"):
+            raise CliError(
+                "Missing request field(s): type. "
+                "Pass --json/--json-file with type, typeVersion, permission, and constraints. "
+                "See `flowbase docs catalogs field-types` and `flowbase docs example fields.create`."
+            )
+        return run_request(args, "fields.create", path_params=path, body=body)
+    if action == "update":
+        body = _payload_from_args(args, {"label": args.label, "description": args.description}, ("label", "description"))
+        return run_request(args, "fields.update", path_params=path, body=body)
+    return run_request(args, f"fields.{action}", path_params=path)
+
+
+def handle_views(args: argparse.Namespace) -> int:
+    action = args.views_action
+    path = {"object_id": args.object_id}
+    if hasattr(args, "view_id"):
+        path["view_id"] = args.view_id
+    if action == "list":
+        return run_request(args, "views.list", path_params=path)
+    if action in ("create", "update"):
+        body = load_json_payload(args.json, args.json_file)
+        require_fields(body, "baseRevision", "name", "defaultFieldIds")
+        if not isinstance(body["defaultFieldIds"], list):
+            raise CliError("Request field 'defaultFieldIds' must be an array.")
+        return run_request(args, f"views.{action}", path_params=path, body=body)
+    if action == "reorder":
+        body = load_json_payload(args.json, args.json_file)
+        require_fields(body, "baseRevision", "viewIds")
+        if not isinstance(body["viewIds"], list):
+            raise CliError("Request field 'viewIds' must be an array.")
+        return run_request(args, "views.reorder", path_params=path, body=body)
+    if action == "set-enabled":
+        body = {
+            "baseRevision": args.base_revision,
+            "enabled": args.enabled,
+        }
+        return run_request(args, "views.set-enabled", path_params=path, body=body)
+    return run_request(
+        args,
+        "views.delete",
+        path_params=path,
+        body={"baseRevision": args.base_revision},
+    )
+
+
+def handle_workflows(args: argparse.Namespace) -> int:
+    action = args.workflows_action
+    path = {"object_id": args.object_id}
+    if hasattr(args, "workflow_id"):
+        path["workflow_id"] = args.workflow_id
+    if action == "list":
+        return run_request(args, "workflows.list", path_params=path)
+    if action == "get":
+        return run_request(args, "workflows.get", path_params=path)
+    if action == "executions":
+        return run_request(
+            args,
+            "workflows.executions",
+            path_params=path,
+            query={"result": args.result},
+        )
+    if action in ("create", "update"):
+        body = load_json_payload(args.json, args.json_file)
+        require_fields(body, "label")
+        return run_request(args, f"workflows.{action}", path_params=path, body=body)
+    if action == "reorder":
+        body = load_json_payload(args.json, args.json_file)
+        require_fields(body, "baseRevision", "workflowIds")
+        if not isinstance(body["workflowIds"], list):
+            raise CliError("Request field 'workflowIds' must be an array.")
+        return run_request(args, "workflows.reorder", path_params=path, body=body)
+    if action == "set-enabled":
+        body = {
+            "baseRevision": args.base_revision,
+            "enabled": args.enabled,
+        }
+        return run_request(args, "workflows.set-enabled", path_params=path, body=body)
+    return run_request(
+        args,
+        "workflows.delete",
+        path_params=path,
+        body={"baseRevision": args.base_revision},
+    )
+
+
+def handle_approvals(args: argparse.Namespace) -> int:
+    action = args.approvals_action
+    path = {"object_id": args.object_id}
+    if hasattr(args, "approval_id"):
+        path["approval_id"] = args.approval_id
+    if action in ("list", "get"):
+        return run_request(args, f"approvals.{action}", path_params=path)
+    if action in ("create", "update"):
+        body = load_json_payload(args.json, args.json_file)
+        require_fields(body, "label", "trigger", "displayFieldIds", "nodes", "edges")
+        return run_request(args, f"approvals.{action}", path_params=path, body=body)
+    if action == "reorder":
+        body = load_json_payload(args.json, args.json_file)
+        require_fields(body, "baseRevision", "approvalIds")
+        if not isinstance(body["approvalIds"], list):
+            raise CliError("Request field 'approvalIds' must be an array.")
+        return run_request(args, "approvals.reorder", path_params=path, body=body)
+    if action == "set-enabled":
+        return run_request(
+            args, "approvals.set-enabled", path_params=path,
+            body={"baseRevision": args.base_revision, "enabled": args.enabled},
+        )
+    return run_request(
+        args, "approvals.delete", path_params=path,
+        body={"baseRevision": args.base_revision},
+    )
+
+
+def handle_print_templates(args: argparse.Namespace) -> int:
+    action = args.print_templates_action
+    path = {"object_id": args.object_id}
+    if hasattr(args, "template_id"):
+        path["template_id"] = args.template_id
+    if action in ("list", "get"):
+        return run_request(args, f"print-templates.{action}", path_params=path)
+    if action == "create":
+        body = load_json_payload(args.json, args.json_file)
+        require_fields(body, "name", "html")
+        return run_request(args, "print-templates.create", path_params=path, body=body)
+    if action == "update":
+        body = load_json_payload(args.json, args.json_file)
+        return run_request(args, "print-templates.update", path_params=path, body=body)
+    if action == "reorder":
+        body = load_json_payload(args.json, args.json_file)
+        require_fields(body, "baseRevision", "templateIds")
+        if not isinstance(body["templateIds"], list):
+            raise CliError("Request field 'templateIds' must be an array.")
+        return run_request(args, "print-templates.reorder", path_params=path, body=body)
+    if action == "set-enabled":
+        return run_request(
+            args, "print-templates.set-enabled", path_params=path,
+            body={"baseRevision": args.base_revision, "enabled": args.enabled},
+        )
+    return run_request(
+        args, "print-templates.delete", path_params=path,
+        body={"baseRevision": args.base_revision},
+    )
+
+
+def handle_pages(args: argparse.Namespace) -> int:
+    action = args.pages_action
+    if action == "evaluate":
+        return run_request(args, "pages.evaluate", path_params={"page_id": args.page_id}, body=load_json_payload(args.json, args.json_file))
+    if action == "list":
+        return run_request(
+            args,
+            "pages.list",
+            query={
+                "status": args.status,
+                "objectId": args.object_id,
+                "type": args.type,
+                "keyword": args.keyword,
+                "page": args.page,
+            },
+        )
+    if action == "options":
+        return run_request(args, "pages.options")
+    if action == "get":
+        return run_request(args, "pages.get", path_params={"page_id": args.page_id})
+    if action in ("create", "update"):
+        body = load_json_payload(args.json, args.json_file)
+        require_fields(body, "baseRevision", "page")
+        if not isinstance(body["page"], dict):
+            raise CliError("Request field 'page' must be an object.")
+        return run_request(
+            args,
+            f"pages.{action}",
+            path_params={"page_id": args.page_id} if action == "update" else None,
+            body=body,
+        )
+    return run_request(
+        args,
+        f"pages.{action}",
+        path_params={"page_id": args.page_id},
+        body={"baseRevision": args.base_revision},
+    )
+
+
+def handle_changes(args: argparse.Namespace) -> int:
+    if args.changes_action == "direct-release":
+        client = client_from_args(args)
+        body = {"message": args.message}
+        preflight_data = client.request(
+            "changes.direct-release-preflight",
+            body=body,
+        )
+        try:
+            preflight = json.loads(preflight_data)
+        except json.JSONDecodeError as exc:
+            raise CliError("Direct-release preflight returned invalid JSON.") from exc
+        token = preflight.get("confirmationToken")
+        if not isinstance(token, str):
+            raise CliError("Direct-release preflight did not return a confirmation token.")
+        _print_direct_release_preflight(preflight)
+        endpoint = get_endpoint("changes.direct-release")
+        confirm_change(endpoint, args.yes)
+        data = client.request(
+            "changes.direct-release",
+            body={"message": args.message, "confirmationToken": token},
+        )
+        print_output(data, pretty=args.pretty, raw=args.raw)
+        return 0
+    return run_request(args, f"changes.{args.changes_action}", body={"message": args.message})
+
+
+def handle_versions(args: argparse.Namespace) -> int:
+    if args.versions_action == "show":
+        return run_request(
+            args,
+            "versions.get",
+            path_params={"version_id": args.version_id},
+        )
+    if args.versions_action == "releases":
+        return run_request(args, "releases.list")
+    return run_request(
+        args,
+        "versions.list",
+        query={
+            "q": args.query,
+            "resource": args.resource,
+            "changeType": args.change_type,
+            "releaseStatus": args.release_status,
+            "channel": args.channel,
+        },
+    )
+
+
+def _print_direct_release_preflight(preflight: dict[str, Any]) -> None:
+    print("Production direct-release preflight:", file=sys.stderr)
+    print(f"  Current main: {preflight.get('mainCommit', 'unknown')}", file=sys.stderr)
+    print(f"  Draft revision: {preflight.get('draftRevision', 'unknown')}", file=sys.stderr)
+    print(
+        f"  Changes: {preflight.get('semanticCount', 0)} semantic, "
+        f"{preflight.get('fileCount', 0)} files",
+        file=sys.stderr,
+    )
+    for check in preflight.get("checks", []):
+        if isinstance(check, dict):
+            mark = "OK" if check.get("ok") else "FAIL"
+            print(f"  [{mark}] {check.get('label', '')}", file=sys.stderr)
+    print(f"  RISK: {preflight.get('risk', 'This bypasses test environments.')}", file=sys.stderr)
+
+
+def _environment_confirmation(args: argparse.Namespace, label: str) -> str:
+    value = (args.confirm or "").strip()
+    if not value:
+        if not sys.stdin.isatty():
+            raise CliError(
+                "Refusing to restart without --confirm '<environment name>' in non-interactive mode."
+            )
+        value = input(f"Type {label} to confirm: ").strip()
+    if value != label:
+        raise CliError("Environment confirmation does not match the preflight result.")
+    return value
+
+
+def _print_environment_restart_preflight(preflight: dict[str, Any]) -> None:
+    current = str(preflight.get("currentCommit", "unknown"))
+    main = str(preflight.get("mainCommit", "unknown"))
+    print("Test-environment restart preflight:", file=sys.stderr)
+    print(f"  Environment: {preflight.get('environmentLabel', 'unknown')}", file=sys.stderr)
+    print(f"  Current test version: {current[:7]}", file=sys.stderr)
+    print(f"  Latest production version: {main[:7]}", file=sys.stderr)
+    print(f"  Drafts: {preflight.get('draftCount', 0)}", file=sys.stderr)
+    print(f"  Test records: {preflight.get('recordCount', 0)}", file=sys.stderr)
+    for check in preflight.get("checks", []):
+        if isinstance(check, dict):
+            mark = "OK" if check.get("ok") else "FAIL"
+            print(f"  [{mark}] {check.get('label', '')}", file=sys.stderr)
+    print(
+        f"  RISK: {preflight.get('risk', 'All test configuration and records will be cleared.')}",
+        file=sys.stderr,
+    )
+
+
+def handle_environments(args: argparse.Namespace) -> int:
+    client = client_from_args(args)
+    preflight_data = client.request("environments.restart-preflight")
+    try:
+        preflight = json.loads(preflight_data)
+    except json.JSONDecodeError as exc:
+        raise CliError("Environment restart preflight returned invalid JSON.") from exc
+    _print_environment_restart_preflight(preflight)
+    if not preflight.get("canRestart"):
+        raise CliError("Environment restart preflight failed. Resolve failed checks first.")
+    label = preflight.get("environmentLabel")
+    if not isinstance(label, str) or not label:
+        raise CliError("Environment restart preflight did not return an environment label.")
+    confirm = _environment_confirmation(args, label)
+    endpoint = get_endpoint("environments.restart")
+    confirm_change(endpoint, args.yes)
+    body = {
+        "confirm": confirm,
+        "expectedCurrentCommit": preflight.get("currentCommit"),
+        "expectedMainCommit": preflight.get("mainCommit"),
+        "expectedDraftRevision": preflight.get("draftRevision"),
+        "expectedRecordCount": preflight.get("recordCount"),
+    }
+    if any(value is None for value in body.values()):
+        raise CliError("Environment restart preflight returned incomplete binding state.")
+    data = client.request("environments.restart", body=body)
+    print_output(data, pretty=args.pretty, raw=args.raw)
+    return 0
+
+
+def handle_records(args: argparse.Namespace) -> int:
+    action = args.records_action
+    path = {"object_id": args.object_id}
+    if action == "upload-attachment":
+        body, content_type = multipart_upload(args.file)
+        data = client_from_args(args).request(
+            "records.upload-attachment",
+            path_params={**path, "field_id": args.field_id},
+            raw_body=body,
+            content_type=content_type,
+        )
+        print_output(data, pretty=args.pretty, raw=args.raw)
+        return 0
+    if action == "download-attachment":
+        data = client_from_args(args).request(
+            "records.download-attachment",
+            path_params={
+                **path,
+                "record_id": args.record_id,
+                "attachment_id": args.attachment_id,
+            },
+            accept="application/octet-stream",
+        )
+        try:
+            Path(args.output).write_bytes(data)
+        except OSError as exc:
+            raise CliError(f"Cannot write attachment: {exc}") from exc
+        return 0
+    if hasattr(args, "record_id"):
+        path["record_id"] = args.record_id
+    if action == "list":
+        return run_request(args, "records.list", path_params=path, query={"page": args.page, "viewId": args.view_id})
+    if action == "get" or action == "delete":
+        return run_request(args, f"records.{action}", path_params=path)
+    body = load_json_payload(args.json, args.json_file)
+    require_fields(body, "values")
+    if not isinstance(body["values"], dict):
+        raise CliError("Request field 'values' must be an object.")
+    return run_request(args, f"records.{action}", path_params=path, body=body)
+
+
+def handle_roles(args: argparse.Namespace) -> int:
+    action = args.roles_action
+    if action == "list":
+        return run_request(args, "roles.list", query={"q": args.q or "", "page": args.page})
+    if action == "options":
+        return run_request(args, "roles.options")
+    if action == "get":
+        return run_request(args, "roles.get", path_params={"role_id": args.role_id})
+    if action == "delete":
+        return run_request(args, "roles.delete", path_params={"role_id": args.role_id})
+    body = load_json_payload(args.json, args.json_file)
+    require_fields(body, "name", "permissions")
+    if not isinstance(body["permissions"], dict):
+        raise CliError("Request field 'permissions' must be an object.")
+    if action == "create":
+        return run_request(args, "roles.create", body=body)
+    if "updatedAt" not in body and "updated_at" not in body:
+        raise CliError("Missing request field(s): updatedAt")
+    return run_request(args, "roles.update", path_params={"role_id": args.role_id}, body=body)
+
+
+def add_json_args(parser: argparse.ArgumentParser, *, endpoint_key: str | None = None) -> None:
+    group = parser.add_mutually_exclusive_group()
+    body_help = "Request body as a JSON object."
+    if endpoint_key is not None:
+        endpoint = get_endpoint(endpoint_key)
+        if endpoint.request_body:
+            body_help += f" Example: {endpoint.request_body}"
+    group.add_argument("--json", help=body_help)
+    group.add_argument("--json-file", help="Read the request body from a UTF-8 JSON file.")
+
+
+def add_object_fields(
+    parser: argparse.ArgumentParser,
+    *,
+    include_key: bool,
+    endpoint_key: str | None = None,
+) -> None:
+    parser.add_argument("--label")
+    if include_key:
+        parser.add_argument("--key")
+    parser.add_argument("--description")
+    add_json_args(parser, endpoint_key=endpoint_key)
+
+
+def add_yes(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--yes", action="store_true", help="Skip the interactive confirmation.")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="flowbase", description="FlowBase low-code platform management CLI. Start with: flowbase guide")
+    parser.add_argument("--host", help=f"Environment Base URL. Defaults to ${ENV_HOST} or {DEFAULT_HOST}.")
+    parser.add_argument("--api-key", help=f"API key. Defaults to ${ENV_API_KEY}.")
+    parser.add_argument("--pretty", action=argparse.BooleanOptionalAction, default=True, help="Pretty-print JSON output.")
+    parser.add_argument("--raw", action="store_true", help="Print the response body without JSON formatting.")
+    groups = parser.add_subparsers(dest="group", required=True)
+
+    organization = groups.add_parser("organization", help="Discover employee and department references for approvals.")
+    organization_actions = organization.add_subparsers(dest="organization_action", required=True)
+    employees = organization_actions.add_parser("employees")
+    employees.add_argument("--query", default="")
+    employees.add_argument("--page", type=int, default=1)
+    organization_actions.add_parser("departments")
+    organization.set_defaults(handler=handle_organization)
+
+    guide = groups.add_parser("guide", help="Read the offline product and task guide first.")
+    guide.add_argument("--format", choices=("markdown", "json"), default="markdown")
+    guide.set_defaults(handler=handle_guide)
+
+    docs = groups.add_parser("docs", help="Inspect the offline endpoint catalog.")
+    docs_actions = docs.add_subparsers(dest="docs_action", required=True)
+    docs_actions.add_parser("list")
+    docs_actions.add_parser("operations")
+    docs_catalogs = docs_actions.add_parser(
+        "catalogs",
+        help="List offline authoring catalogs, or dump one by name.",
+    )
+    docs_catalogs.add_argument("name", nargs="?", default=None)
+    docs_show = docs_actions.add_parser("show")
+    docs_show.add_argument("endpoint", choices=sorted(ENDPOINT_BY_KEY))
+    docs_example = docs_actions.add_parser(
+        "example",
+        help="Print or write the representative request body for an endpoint.",
+    )
+    docs_example.add_argument("endpoint", choices=sorted(ENDPOINT_BY_KEY))
+    docs_example.add_argument(
+        "--output",
+        help="Write the JSON body to this file instead of stdout.",
+    )
+    docs.set_defaults(handler=handle_docs)
+
+    apps = groups.add_parser("apps", help="Manage app metadata.")
+    app_actions = apps.add_subparsers(dest="apps_action", required=True)
+    app_actions.add_parser("list")
+    app_get = app_actions.add_parser("get")
+    app_get.add_argument("app_id")
+    app_create = app_actions.add_parser("create")
+    app_create.add_argument("--label")
+    app_create.add_argument("--key")
+    app_create.add_argument("--icon")
+    app_create.add_argument("--color")
+    add_json_args(app_create, endpoint_key="apps.create")
+    app_update = app_actions.add_parser("update", description="Update app appearance. Supply label, icon and color together via flags or JSON; read apps get first.")
+    app_update.add_argument("app_id")
+    app_update.add_argument("--label")
+    app_update.add_argument("--icon")
+    app_update.add_argument("--color")
+    add_json_args(app_update, endpoint_key="apps.update")
+    app_enabled = app_actions.add_parser("set-enabled")
+    app_enabled.add_argument("app_id")
+    app_enabled.add_argument(
+        "--enabled",
+        action=argparse.BooleanOptionalAction,
+        required=True,
+    )
+    add_yes(app_enabled)
+    app_delete = app_actions.add_parser("delete")
+    app_delete.add_argument("app_id")
+    add_yes(app_delete)
+    app_add_objects = app_actions.add_parser("add-objects")
+    app_add_objects.add_argument("app_id")
+    app_add_objects.add_argument("--object-ids", required=True, help="Comma-separated object IDs.")
+    app_remove_object = app_actions.add_parser("remove-object")
+    app_remove_object.add_argument("app_id")
+    app_remove_object.add_argument("object_id")
+    add_yes(app_remove_object)
+    app_set_group = app_actions.add_parser("set-group")
+    app_set_group.add_argument("app_id")
+    app_set_group.add_argument("object_id")
+    app_set_group.add_argument("--group-id", help="Target group ID. Omit with --ungrouped.")
+    app_set_group.add_argument(
+        "--ungrouped",
+        action="store_true",
+        help="Remove the object from its current group in this app.",
+    )
+    app_reorder_objects = app_actions.add_parser("reorder-objects")
+    app_reorder_objects.add_argument("app_id")
+    add_json_args(app_reorder_objects, endpoint_key="apps.objects.reorder")
+    app_add_dashboards = app_actions.add_parser("add-dashboards")
+    app_add_dashboards.add_argument("app_id")
+    app_add_dashboards.add_argument(
+        "dashboard_ids",
+        nargs="+",
+        help="One or more dashboard IDs to associate with the app.",
+    )
+    app_remove_dashboard = app_actions.add_parser("remove-dashboard")
+    app_remove_dashboard.add_argument("app_id")
+    app_remove_dashboard.add_argument("dashboard_id")
+    add_yes(app_remove_dashboard)
+    app_set_dashboard_group = app_actions.add_parser("set-dashboard-group")
+    app_set_dashboard_group.add_argument("app_id")
+    app_set_dashboard_group.add_argument("dashboard_id")
+    app_set_dashboard_group.add_argument("--group-id", help="Target group ID. Omit with --ungrouped.")
+    app_set_dashboard_group.add_argument(
+        "--ungrouped",
+        action="store_true",
+        help="Remove the dashboard from its current group in this app.",
+    )
+    app_reorder_members = app_actions.add_parser("reorder-members")
+    app_reorder_members.add_argument("app_id")
+    add_json_args(app_reorder_members, endpoint_key="apps.members.reorder")
+    apps.set_defaults(handler=handle_apps)
+
+    dashboards = groups.add_parser("dashboards", help="Manage dashboard metadata.")
+    dashboard_actions = dashboards.add_subparsers(dest="dashboards_action", required=True)
+    dashboard_run = dashboard_actions.add_parser("run", help="Run a saved draft component; requires metadata:read and records:read.")
+    dashboard_run.add_argument("dashboard_id")
+    dashboard_run.add_argument("component_id")
+    add_json_args(dashboard_run, endpoint_key="dashboards.run")
+    dashboard_actions.add_parser("list")
+    dashboard_get = dashboard_actions.add_parser("get")
+    dashboard_get.add_argument("dashboard_id")
+    dashboard_create = dashboard_actions.add_parser("create")
+    dashboard_create.add_argument("--label")
+    dashboard_create.add_argument("--key")
+    dashboard_create.add_argument("--icon")
+    dashboard_create.add_argument("--description")
+    add_json_args(dashboard_create, endpoint_key="dashboards.create")
+    dashboard_update = dashboard_actions.add_parser("update")
+    dashboard_update.add_argument("dashboard_id")
+    add_json_args(dashboard_update, endpoint_key="dashboards.update")
+    dashboard_copy = dashboard_actions.add_parser("copy")
+    dashboard_copy.add_argument("dashboard_id")
+    dashboard_delete = dashboard_actions.add_parser("delete")
+    dashboard_delete.add_argument("dashboard_id")
+    add_yes(dashboard_delete)
+    dashboards.set_defaults(handler=handle_dashboards)
+
+    app_groups = groups.add_parser("groups", help="Manage app object groups.")
+    group_actions = app_groups.add_subparsers(dest="groups_action", required=True)
+    group_create = group_actions.add_parser("create")
+    group_create.add_argument("app_id")
+    group_create.add_argument("--name")
+    group_create.add_argument("--icon")
+    add_json_args(group_create, endpoint_key="apps.groups.create")
+    group_reorder = group_actions.add_parser("reorder")
+    group_reorder.add_argument("app_id")
+    add_json_args(group_reorder, endpoint_key="apps.groups.reorder")
+    group_update = group_actions.add_parser("update")
+    group_update.add_argument("app_id")
+    group_update.add_argument("group_id")
+    group_update.add_argument("--name")
+    group_update.add_argument("--icon")
+    add_json_args(group_update, endpoint_key="apps.groups.update")
+    group_delete = group_actions.add_parser("delete")
+    group_delete.add_argument("app_id")
+    group_delete.add_argument("group_id")
+    add_yes(group_delete)
+    app_groups.set_defaults(handler=handle_groups)
+
+    objects = groups.add_parser("objects", help="Manage object metadata.")
+    object_actions = objects.add_subparsers(dest="objects_action", required=True)
+    object_list = object_actions.add_parser("list")
+    object_list.add_argument("--status", choices=("active", "deleted"), default="active")
+    object_get = object_actions.add_parser("get")
+    object_get.add_argument("object_id")
+    object_get.add_argument("--status", choices=("active", "deleted"), default="active")
+    add_object_fields(
+        object_actions.add_parser("create"), include_key=True, endpoint_key="objects.create"
+    )
+    object_update = object_actions.add_parser("update")
+    object_update.add_argument("object_id")
+    add_object_fields(object_update, include_key=False, endpoint_key="objects.update")
+    for action in ("delete", "restore"):
+        item = object_actions.add_parser(action)
+        item.add_argument("object_id")
+        add_yes(item)
+    object_cli_policy = object_actions.add_parser(
+        "cli-edit-policy", help="Read or update user CLI field edit policies."
+    )
+    object_cli_policy_actions = object_cli_policy.add_subparsers(
+        dest="objects_cli_edit_policy_action", required=True
+    )
+    object_cli_policy_get = object_cli_policy_actions.add_parser("get")
+    object_cli_policy_get.add_argument("object_id")
+    object_cli_policy_update = object_cli_policy_actions.add_parser("update")
+    object_cli_policy_update.add_argument("object_id")
+    add_json_args(
+        object_cli_policy_update,
+        endpoint_key="objects.cli-edit-policy.update",
+    )
+    add_yes(object_cli_policy_update)
+    objects.set_defaults(handler=handle_objects)
+
+    fields = groups.add_parser("fields", help="Manage field metadata.")
+    field_actions = fields.add_subparsers(dest="fields_action", required=True)
+    field_create = field_actions.add_parser("create")
+    field_create.add_argument("object_id")
+    add_object_fields(field_create, include_key=True, endpoint_key="fields.create")
+    field_update = field_actions.add_parser("update")
+    field_update.add_argument("object_id")
+    field_update.add_argument("field_id")
+    add_object_fields(field_update, include_key=False, endpoint_key="fields.update")
+    for action in ("delete", "restore"):
+        item = field_actions.add_parser(action)
+        item.add_argument("object_id")
+        item.add_argument("field_id")
+        add_yes(item)
+    fields.set_defaults(handler=handle_fields)
+
+    views = groups.add_parser("views", help="Manage object view metadata.")
+    view_actions = views.add_subparsers(dest="views_action", required=True)
+    view_list = view_actions.add_parser("list")
+    view_list.add_argument("object_id")
+    for action in ("create", "reorder"):
+        item = view_actions.add_parser(action)
+        item.add_argument("object_id")
+        add_json_args(item, endpoint_key=f"views.{action}")
+    view_update = view_actions.add_parser("update")
+    view_update.add_argument("object_id")
+    view_update.add_argument("view_id")
+    add_json_args(view_update, endpoint_key="views.update")
+    view_enabled = view_actions.add_parser("set-enabled")
+    view_enabled.add_argument("object_id")
+    view_enabled.add_argument("view_id")
+    view_enabled.add_argument("--base-revision", required=True, type=int)
+    view_enabled.add_argument(
+        "--enabled",
+        action=argparse.BooleanOptionalAction,
+        required=True,
+    )
+    add_yes(view_enabled)
+    view_delete = view_actions.add_parser("delete")
+    view_delete.add_argument("object_id")
+    view_delete.add_argument("view_id")
+    view_delete.add_argument("--base-revision", required=True, type=int)
+    add_yes(view_delete)
+    views.set_defaults(handler=handle_views)
+
+    workflows = groups.add_parser("workflows", help="Manage object workflow metadata.")
+    workflow_actions = workflows.add_subparsers(dest="workflows_action", required=True)
+    workflow_list = workflow_actions.add_parser("list")
+    workflow_list.add_argument("object_id")
+    workflow_get = workflow_actions.add_parser("get")
+    workflow_get.add_argument("object_id")
+    workflow_get.add_argument("workflow_id")
+    for action in ("create", "reorder"):
+        item = workflow_actions.add_parser(action)
+        item.add_argument("object_id")
+        add_json_args(item, endpoint_key=f"workflows.{action}")
+    workflow_update = workflow_actions.add_parser("update")
+    workflow_update.add_argument("object_id")
+    workflow_update.add_argument("workflow_id")
+    add_json_args(workflow_update, endpoint_key="workflows.update")
+    workflow_enabled = workflow_actions.add_parser("set-enabled")
+    workflow_enabled.add_argument("object_id")
+    workflow_enabled.add_argument("workflow_id")
+    workflow_enabled.add_argument("--base-revision", required=True, type=int)
+    workflow_enabled.add_argument(
+        "--enabled",
+        action=argparse.BooleanOptionalAction,
+        required=True,
+    )
+    add_yes(workflow_enabled)
+    workflow_delete = workflow_actions.add_parser("delete")
+    workflow_delete.add_argument("object_id")
+    workflow_delete.add_argument("workflow_id")
+    workflow_delete.add_argument("--base-revision", required=True, type=int)
+    add_yes(workflow_delete)
+    workflow_executions = workflow_actions.add_parser("executions")
+    workflow_executions.add_argument("object_id")
+    workflow_executions.add_argument("workflow_id")
+    workflow_executions.add_argument("--result", choices=("success", "failure"))
+    workflows.set_defaults(handler=handle_workflows)
+
+    approvals = groups.add_parser("approvals", help="Manage object approval flow metadata.")
+    approval_actions = approvals.add_subparsers(dest="approvals_action", required=True)
+    approval_list = approval_actions.add_parser("list")
+    approval_list.add_argument("object_id")
+    approval_get = approval_actions.add_parser("get")
+    approval_get.add_argument("object_id")
+    approval_get.add_argument("approval_id")
+    for action in ("create", "reorder"):
+        item = approval_actions.add_parser(action)
+        item.add_argument("object_id")
+        add_json_args(item, endpoint_key=f"approvals.{action}")
+    approval_update = approval_actions.add_parser("update")
+    approval_update.add_argument("object_id")
+    approval_update.add_argument("approval_id")
+    add_json_args(approval_update, endpoint_key="approvals.update")
+    approval_enabled = approval_actions.add_parser("set-enabled")
+    approval_enabled.add_argument("object_id")
+    approval_enabled.add_argument("approval_id")
+    approval_enabled.add_argument("--base-revision", required=True, type=int)
+    approval_enabled.add_argument(
+        "--enabled", action=argparse.BooleanOptionalAction, required=True,
+    )
+    add_yes(approval_enabled)
+    approval_delete = approval_actions.add_parser("delete")
+    approval_delete.add_argument("object_id")
+    approval_delete.add_argument("approval_id")
+    approval_delete.add_argument("--base-revision", required=True, type=int)
+    add_yes(approval_delete)
+    approvals.set_defaults(handler=handle_approvals)
+
+    print_templates = groups.add_parser(
+        "print-templates", help="Manage object print template metadata (HTML + data code).",
+    )
+    print_template_actions = print_templates.add_subparsers(
+        dest="print_templates_action", required=True,
+    )
+    print_template_list = print_template_actions.add_parser("list")
+    print_template_list.add_argument("object_id")
+    print_template_get = print_template_actions.add_parser("get")
+    print_template_get.add_argument("object_id")
+    print_template_get.add_argument("template_id")
+    for action in ("create", "reorder"):
+        item = print_template_actions.add_parser(action)
+        item.add_argument("object_id")
+        add_json_args(item, endpoint_key=f"print-templates.{action}")
+    print_template_update = print_template_actions.add_parser("update")
+    print_template_update.add_argument("object_id")
+    print_template_update.add_argument("template_id")
+    add_json_args(print_template_update, endpoint_key="print-templates.update")
+    print_template_enabled = print_template_actions.add_parser("set-enabled")
+    print_template_enabled.add_argument("object_id")
+    print_template_enabled.add_argument("template_id")
+    print_template_enabled.add_argument("--base-revision", required=True, type=int)
+    print_template_enabled.add_argument(
+        "--enabled", action=argparse.BooleanOptionalAction, required=True,
+    )
+    add_yes(print_template_enabled)
+    print_template_delete = print_template_actions.add_parser("delete")
+    print_template_delete.add_argument("object_id")
+    print_template_delete.add_argument("template_id")
+    print_template_delete.add_argument("--base-revision", required=True, type=int)
+    add_yes(print_template_delete)
+    print_templates.set_defaults(handler=handle_print_templates)
+
+    pages = groups.add_parser("pages", help="Manage custom Page metadata.")
+    page_actions = pages.add_subparsers(dest="pages_action", required=True)
+    page_evaluate = page_actions.add_parser("evaluate", help="Evaluate sample rule effects, not visual rendering or record validation.")
+    page_evaluate.add_argument("page_id")
+    add_json_args(page_evaluate, endpoint_key="pages.evaluate")
+    page_list = page_actions.add_parser("list")
+    page_list.add_argument("--status", choices=("active", "deleted"), default="active")
+    page_list.add_argument("--object-id")
+    page_list.add_argument("--type", choices=("create", "detail"))
+    page_list.add_argument("--keyword")
+    page_list.add_argument("--page", type=int, default=1)
+    page_actions.add_parser("options")
+    page_get = page_actions.add_parser("get")
+    page_get.add_argument("page_id")
+    page_create = page_actions.add_parser("create")
+    add_json_args(page_create, endpoint_key="pages.create")
+    page_update = page_actions.add_parser("update")
+    page_update.add_argument("page_id")
+    add_json_args(page_update, endpoint_key="pages.update")
+    for action in ("set-default", "clear-default", "delete", "restore"):
+        item = page_actions.add_parser(action)
+        item.add_argument("page_id")
+        item.add_argument("--base-revision", required=True, type=int)
+        add_yes(item)
+    pages.set_defaults(handler=handle_pages)
+
+    changes = groups.add_parser("changes", help="Commit or release metadata versions.")
+    change_actions = changes.add_subparsers(dest="changes_action", required=True)
+    for action in ("commit", "release", "direct-release"):
+        item = change_actions.add_parser(action)
+        item.add_argument("--message", required=True)
+        add_yes(item)
+    changes.set_defaults(handler=handle_changes)
+
+    versions = groups.add_parser("versions", help="Inspect read-only configuration history.")
+    version_actions = versions.add_subparsers(dest="versions_action", required=True)
+    version_list = version_actions.add_parser("list")
+    version_list.add_argument("--query")
+    version_list.add_argument("--resource")
+    version_list.add_argument(
+        "--change-type",
+        choices=("business-change", "format-migration"),
+    )
+    version_list.add_argument(
+        "--release-status",
+        choices=("released", "unreleased"),
+    )
+    version_list.add_argument(
+        "--channel",
+        choices=("web", "openapi", "cli", "ai", "system-migration"),
+    )
+    version_show = version_actions.add_parser("show")
+    version_show.add_argument("version_id")
+    version_actions.add_parser("releases")
+    versions.set_defaults(handler=handle_versions)
+
+    environments = groups.add_parser("environments", help="Manage the current test environment.")
+    environment_actions = environments.add_subparsers(dest="environments_action", required=True)
+    environment_restart = environment_actions.add_parser("restart")
+    environment_restart.add_argument(
+        "--confirm",
+        help="Exact environment name returned by preflight. Required in non-interactive mode.",
+    )
+    add_yes(environment_restart)
+    environments.set_defaults(handler=handle_environments)
+
+    records = groups.add_parser("records", help="Manage business records.")
+    record_actions = records.add_subparsers(dest="records_action", required=True)
+    record_list = record_actions.add_parser("list")
+    record_list.add_argument("object_id")
+    record_list.add_argument("--page", type=int, default=1)
+    record_list.add_argument("--view-id", help="Select a view returned by views list.")
+    record_get = record_actions.add_parser("get")
+    record_get.add_argument("object_id")
+    record_get.add_argument("record_id")
+    record_upload = record_actions.add_parser("upload-attachment")
+    record_upload.add_argument("object_id")
+    record_upload.add_argument("field_id")
+    record_upload.add_argument("file")
+    record_download = record_actions.add_parser("download-attachment")
+    record_download.add_argument("object_id")
+    record_download.add_argument("record_id")
+    record_download.add_argument("attachment_id")
+    record_download.add_argument("--output", required=True)
+    record_create = record_actions.add_parser("create")
+    record_create.add_argument("object_id")
+    add_json_args(record_create, endpoint_key="records.create")
+    record_update = record_actions.add_parser("update")
+    record_update.add_argument("object_id")
+    record_update.add_argument("record_id")
+    add_json_args(record_update, endpoint_key="records.update")
+    record_delete = record_actions.add_parser("delete")
+    record_delete.add_argument("object_id")
+    record_delete.add_argument("record_id")
+    add_yes(record_delete)
+    records.set_defaults(handler=handle_records)
+
+    roles = groups.add_parser("roles", help="Manage organization roles (production Host only).")
+    role_actions = roles.add_subparsers(dest="roles_action", required=True)
+    role_list = role_actions.add_parser("list")
+    role_list.add_argument("--q", default="", help="Filter by role name.")
+    role_list.add_argument("--page", type=int, default=1)
+    role_actions.add_parser("options")
+    role_get = role_actions.add_parser("get")
+    role_get.add_argument("role_id")
+    role_create = role_actions.add_parser("create")
+    add_json_args(role_create, endpoint_key="roles.create")
+    role_update = role_actions.add_parser("update")
+    role_update.add_argument("role_id")
+    add_json_args(role_update, endpoint_key="roles.update")
+    role_delete = role_actions.add_parser("delete")
+    role_delete.add_argument("role_id")
+    add_yes(role_delete)
+    roles.set_defaults(handler=handle_roles)
+    return parser
+
+
+GLOBAL_FLAGS_WITH_VALUE = ("--host", "--api-key")
+GLOBAL_FLAGS_BOOL = ("--pretty", "--no-pretty", "--raw")
+
+
+def hoist_global_flags(argv: list[str]) -> list[str]:
+    """Allow global flags after the subcommand, which is how AI-generated commands are usually written."""
+    globals_out: list[str] = []
+    rest: list[str] = []
+    index = 0
+    while index < len(argv):
+        arg = argv[index]
+        name = arg.split("=", 1)[0]
+        if name in GLOBAL_FLAGS_WITH_VALUE:
+            if "=" in arg:
+                globals_out.append(arg)
+            else:
+                globals_out.append(arg)
+                if index + 1 < len(argv) and not argv[index + 1].startswith("-"):
+                    index += 1
+                    globals_out.append(argv[index])
+        elif name in GLOBAL_FLAGS_BOOL:
+            globals_out.append(arg)
+        else:
+            rest.append(arg)
+        index += 1
+    return globals_out + rest
+
+
+def main(argv: list[str] | None = None) -> int:
+    raw = list(argv) if argv is not None else sys.argv[1:]
+    args = build_parser().parse_args(hoist_global_flags(raw))
+    try:
+        return args.handler(args)
+    except CliError as exc:
+        print(f"flowbase: error: {exc}", file=sys.stderr)
+        return 1
+
+
+def entrypoint() -> None:
+    raise SystemExit(main())
+
+
+if __name__ == "__main__":
+    entrypoint()