thingsboard-cli 4.3.1.2__py3-none-any.whl

thingsboard_cli/__init__.py

@@ -0,0 +1,8 @@
+"""ThingsBoard CLI - manage ThingsBoard resources from the terminal."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("thingsboard-cli")
+except PackageNotFoundError:
+    __version__ = "0.0.0-dev"

thingsboard_cli/commands/_pagination.py

@@ -0,0 +1,93 @@
+"""Pagination kwarg coercion helpers.
+
+The tb-pe-client SDK is auto-generated from OpenAPI; many pagination endpoints
+declare ``page_size`` / ``page`` as ``Annotated[str, Field(strict=True)]``
+(string, not int). Passing a Python ``int`` then trips Pydantic's strict
+validation. The CLI's ``IntOption`` flags arrive as ints, so we bridge the gap
+by inspecting the SDK method's signature and casting ints to strings only when
+the annotation actually wants ``str``.
+"""
+
+from __future__ import annotations
+
+import inspect
+import types
+import typing
+from collections.abc import Callable
+from typing import Annotated, Any, Union
+
+
+def _annotation_target(annotation: Any) -> Any:
+    """Extract the underlying type from a possibly-nested annotation.
+
+    Recursively peels ``Annotated[X, ...]`` and unwraps ``Optional`` /
+    ``Union[X, None]`` (in both ``typing.Union`` and ``X | None`` PEP 604
+    forms) to return the first concrete non-``None`` type. Required because
+    the SDK sometimes nests these (e.g. ``Annotated[Annotated[str, Strict] | None, FieldInfo]``).
+    """
+    seen: set[int] = set()
+    while True:
+        # Bail out on accidental cycles.
+        if id(annotation) in seen:
+            return annotation
+        seen.add(id(annotation))
+
+        origin = typing.get_origin(annotation)
+        if origin is Annotated:
+            args = typing.get_args(annotation)
+            if not args:
+                return annotation
+            annotation = args[0]
+            continue
+        if origin is Union or origin is types.UnionType:
+            non_none = [a for a in typing.get_args(annotation) if a is not type(None)]
+            if len(non_none) == 1:
+                annotation = non_none[0]
+                continue
+            return annotation
+        return annotation
+
+
+def coerce_page_kwargs(api_method: Callable[..., Any], kwargs: dict[str, Any]) -> dict[str, Any]:
+    """Cast ``int`` kwargs to ``str`` when the SDK method's signature wants ``str``.
+
+    Handles ``Annotated[str, ...]`` and bare ``str`` annotations. Unknown kwargs
+    and ``None`` values pass through unchanged. ``StrictInt``-annotated params
+    receive ints unchanged.
+
+    The helper is tolerant of bound methods, classmethods, and instance
+    methods - ``inspect.signature`` already strips ``self`` / ``cls`` from
+    bound callables.
+    """
+    try:
+        # eval_str=True resolves string annotations produced by
+        # ``from __future__ import annotations`` (PEP 563) so we get real
+        # types instead of bare strings. Available since Python 3.10.
+        sig = inspect.signature(api_method, eval_str=True)
+    except (TypeError, ValueError, NameError):
+        # Builtins / C-extension callables may not expose a signature, and
+        # eval_str can raise NameError if an annotation references a name
+        # not in scope. In either case we cannot infer types reliably; fall
+        # back to pass-through.
+        try:
+            sig = inspect.signature(api_method)
+        except (TypeError, ValueError):
+            return dict(kwargs)
+
+    params = sig.parameters
+    out: dict[str, Any] = {}
+    for name, value in kwargs.items():
+        param = params.get(name)
+        if param is None or param.annotation is inspect.Parameter.empty:
+            # Unknown kwarg or no annotation - cannot infer; pass through.
+            out[name] = value
+            continue
+        if value is None:
+            out[name] = value
+            continue
+        target = _annotation_target(param.annotation)
+        if target is str and isinstance(value, int) and not isinstance(value, bool):
+            out[name] = str(value)
+        else:
+            out[name] = value
+    return out

thingsboard_cli/commands/alarm.py

@@ -0,0 +1,297 @@
+"""Alarm command group for managing ThingsBoard alarms."""
+
+from __future__ import annotations
+
+import typer
+
+from thingsboard_cli.common.options import (
+    FormatOption,
+    OutputFormat,
+    PageOption,
+    PageSizeOption,
+    ProfileOption,
+    SortOrderOption,
+    SortPropertyOption,
+    TextSearchOption,
+    VerboseHelpOption,
+)
+from thingsboard_cli.common.utils import read_json_input
+from thingsboard_cli.core.client import get_client_from_ctx as _get_client
+from thingsboard_cli.core.output import (
+    error,
+    format_enum_value,
+    render_detail,
+    render_json,
+    render_table,
+    success,
+    warning,
+)
+from thingsboard_cli.core.payload import dict_to_model
+from thingsboard_cli.help import api_docs, handle_verbose_help, is_verbose_help_requested
+
+alarm_app = typer.Typer(no_args_is_help=True)
+
+
+@alarm_app.callback()
+def alarm_callback(ctx: typer.Context, profile: ProfileOption = None) -> None:
+    """Manage ThingsBoard alarms."""
+    if is_verbose_help_requested():
+        return
+    ctx.ensure_object(dict)
+    ctx.obj = {"profile": profile}
+
+
+@alarm_app.command(name="list")
+@api_docs(method=["get_alarms_v2", "get_all_alarms_v2"], controller="alarm")
+def list_alarms(
+    ctx: typer.Context,
+    entity_type: str | None = typer.Option(None, "--entity-type", help="Entity type (e.g. DEVICE, ASSET)."),
+    entity_id: str | None = typer.Option(None, "--entity-id", help="Entity ID (UUID)."),
+    page: PageOption = 0,
+    page_size: PageSizeOption = 20,
+    text_search: TextSearchOption = None,
+    sort_property: SortPropertyOption = None,
+    sort_order: SortOrderOption = None,
+    status_list: str | None = typer.Option(
+        None, "--status-list", help="Comma-separated alarm statuses (ACTIVE, CLEARED, ACK, UNACK)."
+    ),
+    severity_list: str | None = typer.Option(
+        None, "--severity-list", help="Comma-separated severities (CRITICAL, MAJOR, MINOR, WARNING, INDETERMINATE)."
+    ),
+    type_filter: str | None = typer.Option(None, "--type", help="Comma-separated alarm types."),
+    type_list_deprecated: str | None = typer.Option(
+        None,
+        "--type-list",
+        help="Deprecated: use --type instead.",
+        hidden=True,
+    ),
+    types_deprecated: str | None = typer.Option(
+        None,
+        "--types",
+        help="Deprecated: use --type instead.",
+        hidden=True,
+    ),
+    assignee_id: str | None = typer.Option(None, "--assignee-id", help="Filter by assigned user ID (UUID)."),
+    start_time: int | None = typer.Option(None, "--start-time", help="Start timestamp in ms."),
+    end_time: int | None = typer.Option(None, "--end-time", help="End timestamp in ms."),
+    format: FormatOption = OutputFormat.TABLE,
+    verbose_help: VerboseHelpOption = False,
+) -> None:
+    """List alarms. Filter by entity with --entity-type and --entity-id, or list all."""
+    handle_verbose_help(list_alarms, "alarm", verbose_help)
+
+    if (entity_type is None) != (entity_id is None):
+        from thingsboard_cli.core.output import error
+
+        error("--entity-type and --entity-id must be used together.")
+
+    # Reconcile deprecated --type-list / --types aliases with the canonical --type flag.
+    if type_list_deprecated is not None or types_deprecated is not None:
+        warning("--type-list and --types are deprecated; use --type instead.")
+    type_value = type_filter if type_filter is not None else (type_list_deprecated or types_deprecated)
+
+    client = _get_client(ctx)
+
+    kwargs: dict = {"page_size": page_size, "page": page}
+    if entity_type is not None:
+        kwargs["entity_type"] = entity_type
+        kwargs["entity_id"] = entity_id
+    if text_search is not None:
+        kwargs["text_search"] = text_search
+    if sort_property is not None:
+        kwargs["sort_property"] = sort_property
+    if sort_order is not None:
+        kwargs["sort_order"] = sort_order
+    if status_list is not None:
+        kwargs["status_list"] = status_list.split(",")
+    if severity_list is not None:
+        kwargs["severity_list"] = severity_list.split(",")
+    if type_value is not None:
+        kwargs["type_list"] = type_value.split(",")
+    if assignee_id is not None:
+        kwargs["assignee_id"] = assignee_id
+    if start_time is not None:
+        kwargs["start_time"] = start_time
+    if end_time is not None:
+        kwargs["end_time"] = end_time
+
+    result = client.get_alarms_v2(**kwargs) if entity_type is not None else client.get_all_alarms_v2(**kwargs)
+
+    if format == OutputFormat.JSON:
+        render_json(result)
+        return
+
+    items = result.data or []
+    columns = [
+        ("ID", "cyan"),
+        ("Type", ""),
+        ("Severity", ""),
+        ("Status", ""),
+        ("Originator", ""),
+    ]
+    rows = []
+    for a in items:
+        originator = ""
+        if hasattr(a, "originator") and a.originator:
+            originator = str(a.originator.id) if hasattr(a.originator, "id") else str(a.originator)
+        rows.append(
+            [
+                str(a.id.get_id()),
+                a.type if hasattr(a, "type") and a.type else "",
+                format_enum_value(getattr(a, "severity", None)),
+                format_enum_value(getattr(a, "status", None)),
+                originator,
+            ]
+        )
+    render_table(columns, rows, page, result.total_pages or 0, result.total_elements or 0)
+
+
+@alarm_app.command()
+@api_docs(method="get_alarm_by_id", model="AlarmInfo", controller="alarm")
+def get(
+    ctx: typer.Context,
+    alarm_id: str = typer.Argument(..., help="Alarm ID (UUID)"),
+    format: FormatOption = OutputFormat.TABLE,
+    verbose_help: VerboseHelpOption = False,
+) -> None:
+    """Get alarm details by ID."""
+    handle_verbose_help(get, "alarm", verbose_help)
+    client = _get_client(ctx)
+    alarm = client.get_alarm_by_id(alarm_id=alarm_id)
+    if format == OutputFormat.JSON:
+        render_json(alarm)
+        return
+    render_detail(
+        [
+            ("ID", str(alarm.id.get_id())),
+            ("Type", alarm.type if hasattr(alarm, "type") and alarm.type else ""),
+            ("Severity", format_enum_value(getattr(alarm, "severity", None))),
+            ("Status", format_enum_value(getattr(alarm, "status", None))),
+            ("Ack Ts", str(alarm.ack_ts) if hasattr(alarm, "ack_ts") and alarm.ack_ts else "-"),
+            ("Clear Ts", str(alarm.clear_ts) if hasattr(alarm, "clear_ts") and alarm.clear_ts else "-"),
+        ]
+    )
+
+
+@alarm_app.command()
+@api_docs(method="delete_alarm", controller="alarm")
+def delete(
+    ctx: typer.Context,
+    alarm_id: str = typer.Argument(..., help="Alarm ID (UUID)"),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation"),
+    verbose_help: VerboseHelpOption = False,
+) -> None:
+    """Delete an alarm."""
+    handle_verbose_help(delete, "alarm", verbose_help)
+    if not yes:
+        typer.confirm(f"Delete alarm {alarm_id}?", abort=True)
+    client = _get_client(ctx)
+    client.delete_alarm(alarm_id=alarm_id)
+    success(f"Alarm {alarm_id} deleted")
+
+
+@alarm_app.command()
+@api_docs(method="save_alarm", model="Alarm", controller="alarm")
+def save(
+    ctx: typer.Context,
+    json_input: str = typer.Option(..., "--json", help="JSON input (file path, '-' for stdin, or inline)"),
+    verbose_help: VerboseHelpOption = False,
+) -> None:
+    """Create or update an alarm.
+
+    Minimal payload requires ``type``, ``severity`` and ``originator``;
+    ``name``/``status``/``acknowledged``/``cleared`` are auto-filled to match
+    the values the TB server assigns on creation.
+    """
+    handle_verbose_help(save, "alarm", verbose_help)
+    data = read_json_input(json_input)
+
+    # Validate required fields up front so users get a clear CLI error rather
+    # than pydantic's opaque ``Field required`` from ``dict_to_model``.
+    required = ("type", "severity", "originator")
+    missing = [f for f in required if not data.get(f)]
+    if missing:
+        error(f"Missing required field(s): {', '.join(missing)}. Minimal payload requires {', '.join(required)}.")
+
+    data.setdefault("name", data.get("type"))
+
+    # Keep ``status`` consistent with ``acknowledged`` / ``cleared`` instead of
+    # defaulting both independently — otherwise ``{"cleared": true}`` alone
+    # would leave ``status=ACTIVE_UNACK`` (internally inconsistent).
+    if "status" not in data:
+        ack = bool(data.get("acknowledged"))
+        cleared = bool(data.get("cleared"))
+        if cleared and ack:
+            data["status"] = "CLEARED_ACK"
+        elif cleared:
+            data["status"] = "CLEARED_UNACK"
+        elif ack:
+            data["status"] = "ACTIVE_ACK"
+        else:
+            data["status"] = "ACTIVE_UNACK"
+    status = str(data["status"])
+    data.setdefault("acknowledged", "ACK" in status and "UNACK" not in status)
+    data.setdefault("cleared", status.startswith("CLEARED"))
+
+    client = _get_client(ctx)
+    alarm = dict_to_model("Alarm", data)
+    result = client.save_alarm(alarm=alarm)
+    alarm_type = result.type if hasattr(result, "type") and result.type else ""
+    success(f"Alarm '{alarm_type}' saved (ID: {result.id.get_id()})")
+
+
+@alarm_app.command()
+@api_docs(method="ack_alarm", controller="alarm")
+def ack(
+    ctx: typer.Context,
+    alarm_id: str = typer.Argument(..., help="Alarm ID (UUID)"),
+    verbose_help: VerboseHelpOption = False,
+) -> None:
+    """Acknowledge an alarm."""
+    handle_verbose_help(ack, "alarm", verbose_help)
+    client = _get_client(ctx)
+    client.ack_alarm(alarm_id=alarm_id)
+    success(f"Alarm {alarm_id} acknowledged")
+
+
+@alarm_app.command()
+@api_docs(method="clear_alarm", controller="alarm")
+def clear(
+    ctx: typer.Context,
+    alarm_id: str = typer.Argument(..., help="Alarm ID (UUID)"),
+    verbose_help: VerboseHelpOption = False,
+) -> None:
+    """Clear an alarm."""
+    handle_verbose_help(clear, "alarm", verbose_help)
+    client = _get_client(ctx)
+    client.clear_alarm(alarm_id=alarm_id)
+    success(f"Alarm {alarm_id} cleared")
+
+
+@alarm_app.command()
+@api_docs(method="assign_alarm", controller="alarm")
+def assign(
+    ctx: typer.Context,
+    alarm_id: str = typer.Argument(..., help="Alarm ID (UUID)"),
+    user_id: str = typer.Option(..., "--user-id", help="User ID (UUID) to assign the alarm to."),
+    verbose_help: VerboseHelpOption = False,
+) -> None:
+    """Assign an alarm to a user."""
+    handle_verbose_help(assign, "alarm", verbose_help)
+    client = _get_client(ctx)
+    client.assign_alarm(alarm_id=alarm_id, assignee_id=user_id)
+    success(f"Alarm {alarm_id} assigned to user {user_id}")
+
+
+@alarm_app.command()
+@api_docs(method="unassign_alarm", controller="alarm")
+def unassign(
+    ctx: typer.Context,
+    alarm_id: str = typer.Argument(..., help="Alarm ID (UUID)"),
+    verbose_help: VerboseHelpOption = False,
+) -> None:
+    """Unassign an alarm."""
+    handle_verbose_help(unassign, "alarm", verbose_help)
+    client = _get_client(ctx)
+    client.unassign_alarm(alarm_id=alarm_id)
+    success(f"Alarm {alarm_id} unassigned")

thingsboard_cli/commands/alarm_rule.py

@@ -0,0 +1,288 @@
+"""Alarm rule command group for managing ThingsBoard alarm rules."""
+
+from __future__ import annotations
+
+import typer
+from filelock import Timeout as FileLockTimeout
+
+from thingsboard_cli.commands.project import find_project_root
+from thingsboard_cli.common.options import (
+    FormatOption,
+    OutputFormat,
+    PageOption,
+    PageSizeOption,
+    ProfileOption,
+    RemoteOption,
+    SolutionOption,
+    SortOrderOption,
+    SortPropertyOption,
+    TextSearchOption,
+    VerboseHelpOption,
+)
+from thingsboard_cli.common.utils import read_json_input
+from thingsboard_cli.core.client import get_client_from_ctx as _get_client
+from thingsboard_cli.core.local import embed_in_parent_entity, is_local_mode, resolve_solution_dir
+from thingsboard_cli.core.output import (
+    busy_local_write_error,
+    console,
+    error,
+    format_enum_value,
+    render_detail,
+    render_json,
+    render_table,
+    success,
+)
+from thingsboard_cli.core.payload import dict_to_model
+from thingsboard_cli.help import api_docs, handle_verbose_help, is_verbose_help_requested
+
+alarm_rule_app = typer.Typer(no_args_is_help=True)
+
+
+def _entity_type_of(ar: object) -> str:
+    """Return the entity type the alarm rule is bound to.
+
+    Reads ``ar.entity_id.entity_type`` (the *target* entity for the rule). The
+    AlarmRuleDefinition model itself has no top-level ``entity_type`` attribute
+    -- the meaningful entity type lives on the nested ``EntityId``. Returns an
+    empty string when either link is missing.
+    """
+    entity_id = getattr(ar, "entity_id", None)
+    if entity_id is None:
+        return ""
+    return format_enum_value(getattr(entity_id, "entity_type", None))
+
+
+@alarm_rule_app.callback()
+def alarm_rule_callback(ctx: typer.Context, profile: ProfileOption = None) -> None:
+    """Manage ThingsBoard alarm rules."""
+    if is_verbose_help_requested():
+        return
+    ctx.ensure_object(dict)
+    ctx.obj = {"profile": profile}
+
+
+@alarm_rule_app.command(name="list")
+@api_docs(method=["get_alarm_rules", "get_alarm_rules_by_entity_id"])
+def list_alarm_rules(
+    ctx: typer.Context,
+    page: PageOption = 0,
+    page_size: PageSizeOption = 20,
+    text_search: TextSearchOption = None,
+    sort_property: SortPropertyOption = None,
+    sort_order: SortOrderOption = None,
+    entity_type: str | None = typer.Option(None, "--entity-type", help="Filter by entity type (e.g. DEVICE, ASSET)."),
+    entity_id: str | None = typer.Option(None, "--entity-id", help="Entity ID (UUID). Requires --entity-type."),
+    entities: str | None = typer.Option(None, "--entities", help="Comma-separated entity IDs to filter by."),
+    format: FormatOption = OutputFormat.TABLE,
+    verbose_help: VerboseHelpOption = False,
+) -> None:
+    """List alarm rules. Use --entity-type and --entity-id to list rules for a specific entity."""
+    handle_verbose_help(list_alarm_rules, "alarm_rule", verbose_help)
+
+    if entity_id is not None and entity_type is None:
+        error("--entity-id requires --entity-type.")
+
+    client = _get_client(ctx)
+    kwargs: dict = {"page_size": page_size, "page": page}
+    if text_search is not None:
+        kwargs["text_search"] = text_search
+    if sort_property is not None:
+        kwargs["sort_property"] = sort_property
+    if sort_order is not None:
+        kwargs["sort_order"] = sort_order
+
+    if entity_id is not None:
+        kwargs["entity_type"] = entity_type
+        kwargs["entity_id"] = entity_id
+        result = client.get_alarm_rules_by_entity_id(**kwargs)
+    else:
+        if entity_type is not None:
+            kwargs["entity_type"] = entity_type
+        if entities is not None:
+            kwargs["entities"] = entities.split(",")
+        result = client.get_alarm_rules(**kwargs)
+
+    if format == OutputFormat.JSON:
+        render_json(result)
+        return
+
+    items = result.data or []
+    columns = [
+        ("ID", "cyan"),
+        ("Name", ""),
+        ("Entity Type", ""),
+        ("Created", ""),
+    ]
+    rows = []
+    for ar in items:
+        rows.append(
+            [
+                str(ar.id.get_id()),
+                ar.name if hasattr(ar, "name") and ar.name else "",
+                _entity_type_of(ar),
+                str(ar.created_time) if hasattr(ar, "created_time") and ar.created_time else "",
+            ]
+        )
+    render_table(columns, rows, page, result.total_pages or 0, result.total_elements or 0)
+
+
+@alarm_rule_app.command()
+@api_docs(method="get_alarm_rule_by_id", model="AlarmRuleDefinition")
+def get(
+    ctx: typer.Context,
+    alarm_rule_id: str = typer.Argument(..., help="Alarm rule ID (UUID)"),
+    format: FormatOption = OutputFormat.TABLE,
+    verbose_help: VerboseHelpOption = False,
+) -> None:
+    """Get alarm rule details by ID."""
+    handle_verbose_help(get, "alarm_rule", verbose_help)
+    client = _get_client(ctx)
+    ar = client.get_alarm_rule_by_id(alarm_rule_id=alarm_rule_id)
+
+    if format == OutputFormat.JSON:
+        render_json(ar)
+        return
+
+    render_detail(
+        [
+            ("ID", str(ar.id.get_id())),
+            ("Name", ar.name if hasattr(ar, "name") and ar.name else ""),
+            ("Entity Type", _entity_type_of(ar)),
+            ("Created", str(ar.created_time) if hasattr(ar, "created_time") and ar.created_time else ""),
+        ]
+    )
+
+
+@alarm_rule_app.command()
+@api_docs(method="save_alarm_rule", model="AlarmRuleDefinition")
+def save(
+    ctx: typer.Context,
+    json_input: str = typer.Option(..., "--json", help="JSON input (file path, '-' for stdin, or inline)"),
+    remote: RemoteOption = False,
+    solution: SolutionOption = None,
+    verbose_help: VerboseHelpOption = False,
+) -> None:
+    """Create or update an alarm rule.
+
+    JSON-only by design: alarm rules carry a complex nested schema (condition,
+    filter predicates, debug settings, alarm details, dashboard binding) where
+    no single shortcut flag yields a useful default. Round-trip
+    ``tb alarm-rule get <id> -f json | tb alarm-rule save --json -`` -- the
+    payload is parsed via ``dict_to_model`` so camelCase keys from the GET
+    response feed straight back into the SDK model.
+    """
+    handle_verbose_help(save, "alarm_rule", verbose_help)
+    data = read_json_input(json_input)
+
+    if not remote and is_local_mode():
+        project_root = find_project_root()
+        solution_dir = resolve_solution_dir(project_root, solution_name=solution)
+        assert project_root is not None
+        # Alarm rules are stored as CalculatedField with type=ALARM
+        data.setdefault("type", "ALARM")
+        if "configuration" in data:
+            data["configuration"].setdefault("type", "ALARM")
+        parent_entity_id = data.get("entityId", {})
+        try:
+            path = embed_in_parent_entity(solution_dir, parent_entity_id, "calculatedFields", data, label="alarm rule")
+        except FileLockTimeout:
+            busy_local_write_error()
+        console.print(f"  Embedded alarm rule in {path.relative_to(project_root)}")
+        return
+
+    client = _get_client(ctx)
+    alarm_rule = dict_to_model("AlarmRuleDefinition", data)
+    result = client.save_alarm_rule(alarm_rule_definition=alarm_rule)
+    name = result.name if hasattr(result, "name") and result.name else ""
+    success(f"Alarm rule '{name}' saved (ID: {result.id.get_id()})")
+
+
+@alarm_rule_app.command()
+@api_docs(method="delete_alarm_rule")
+def delete(
+    ctx: typer.Context,
+    alarm_rule_id: str = typer.Argument(..., help="Alarm rule ID (UUID)"),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation"),
+    verbose_help: VerboseHelpOption = False,
+) -> None:
+    """Delete an alarm rule."""
+    handle_verbose_help(delete, "alarm_rule", verbose_help)
+    if not yes:
+        typer.confirm(f"Delete alarm rule {alarm_rule_id}?", abort=True)
+    client = _get_client(ctx)
+    client.delete_alarm_rule(alarm_rule_id=alarm_rule_id)
+    success(f"Alarm rule {alarm_rule_id} deleted")
+
+
+@alarm_rule_app.command()
+@api_docs(method="get_alarm_rule_names")
+def names(
+    ctx: typer.Context,
+    page: PageOption = 0,
+    page_size: PageSizeOption = 20,
+    text_search: TextSearchOption = None,
+    sort_order: SortOrderOption = None,
+    format: FormatOption = OutputFormat.TABLE,
+    verbose_help: VerboseHelpOption = False,
+) -> None:
+    """List alarm rule names with pagination.
+
+    Note: the underlying ``GET /api/alarmRule/names`` endpoint accepts
+    ``sortOrder`` only -- there is no ``sortProperty`` parameter, so
+    ``--sort-property`` is intentionally omitted from this command.
+    """
+    handle_verbose_help(names, "alarm_rule", verbose_help)
+    client = _get_client(ctx)
+    kwargs: dict = {"page_size": page_size, "page": page}
+    if text_search is not None:
+        kwargs["text_search"] = text_search
+    if sort_order is not None:
+        kwargs["sort_order"] = sort_order
+    result = client.get_alarm_rule_names(**kwargs)
+
+    if format == OutputFormat.JSON:
+        render_json(result)
+        return
+
+    items = result.data or []
+    columns = [("Name", "")]
+    rows = [[name] for name in items]
+    render_table(columns, rows, page, result.total_pages or 0, result.total_elements or 0)
+
+
+@alarm_rule_app.command()
+@api_docs(method="get_latest_alarm_rule_debug_event")
+def debug(
+    ctx: typer.Context,
+    alarm_rule_id: str = typer.Argument(..., help="Alarm rule ID (UUID)"),
+    verbose_help: VerboseHelpOption = False,
+) -> None:
+    """Get latest debug event for an alarm rule.
+
+    The TB endpoint returns an empty body when no debug events have been
+    captured for the rule. We surface that explicitly with a friendly message
+    instead of letting Rich render ``""``; populated payloads are pretty-printed
+    as JSON via :func:`render_json`.
+    """
+    handle_verbose_help(debug, "alarm_rule", verbose_help)
+    client = _get_client(ctx)
+    result = client.get_latest_alarm_rule_debug_event(alarm_rule_id=alarm_rule_id)
+    if result is None or result == "" or result == {} or result == []:
+        console.print("[dim]No debug events available.[/dim]")
+        return
+    render_json(result)
+
+
+@alarm_rule_app.command(name="test-script")
+@api_docs(method="test_alarm_rule_script")
+def test_script(
+    ctx: typer.Context,
+    json_input: str = typer.Option(..., "--json", help="JSON with expression and arguments"),
+    verbose_help: VerboseHelpOption = False,
+) -> None:
+    """Test an alarm rule TBEL expression."""
+    handle_verbose_help(test_script, "alarm_rule", verbose_help)
+    client = _get_client(ctx)
+    data = read_json_input(json_input)
+    result = client.test_alarm_rule_script(body=data)
+    render_json(result)