netdata-cli 0.1.0__py3-none-any.whl

netdata_cli/__init__.py

@@ -0,0 +1,3 @@
+"""netdata-cli — A powerful CLI for the Netdata Agent REST API."""
+
+__version__ = "0.1.0"

netdata_cli/cli.py

@@ -0,0 +1,460 @@
+"""netdata-cli — CLI entry point."""
+
+from __future__ import annotations
+
+import sys
+
+import click
+
+from . import __version__
+from .client import NetdataClient, NetdataError
+from .formatters import (
+    HAS_RICH,
+    console,
+    print_alarm_log,
+    print_alarms,
+    print_chart_detail,
+    print_charts,
+    print_data,
+    print_function,
+    print_info,
+    print_json,
+)
+
+
+def _client(url: str, timeout: int) -> NetdataClient:
+    return NetdataClient(base_url=url, timeout=timeout)
+
+
+def _handle_error(exc: NetdataError) -> None:
+    msg = f"Error: {exc}"
+    if console:
+        console.print(f"[bold red]{msg}[/]")
+    else:
+        print(msg, file=sys.stderr)
+    sys.exit(1)
+
+
+# ------------------------------------------------------------------
+# Root group
+# ------------------------------------------------------------------
+
+
+@click.group()
+@click.version_option(version=__version__, prog_name="netdata-cli")
+@click.option(
+    "--url",
+    "-u",
+    envvar="NETDATA_URL",
+    default="http://localhost:19999",
+    show_default=True,
+    help="Netdata agent URL.",
+)
+@click.option("--timeout", "-t", default=10, show_default=True, help="Request timeout in seconds.")
+@click.option("--json", "-j", "as_json", is_flag=True, help="Output raw JSON.")
+@click.pass_context
+def cli(ctx: click.Context, url: str, timeout: int, as_json: bool) -> None:
+    """netdata-cli — A powerful CLI for the Netdata Agent REST API.
+
+    Query metrics, charts, alarms, functions, and agent info from the
+    command line.  Supports rich tables, JSON output, and time filtering.
+
+    Set NETDATA_URL env var to change the default agent address.
+    """
+    ctx.ensure_object(dict)
+    ctx.obj["client"] = _client(url, timeout)
+    ctx.obj["as_json"] = as_json
+
+
+# ------------------------------------------------------------------
+# info
+# ------------------------------------------------------------------
+
+
+@cli.command()
+@click.pass_context
+def info(ctx: click.Context) -> None:
+    """Show Netdata agent info (version, OS, charts, alarms, collectors)."""
+    try:
+        data = ctx.obj["client"].info()
+        print_info(data, as_json=ctx.obj["as_json"])
+    except NetdataError as exc:
+        _handle_error(exc)
+
+
+# ------------------------------------------------------------------
+# ping
+# ------------------------------------------------------------------
+
+
+@cli.command()
+@click.pass_context
+def ping(ctx: click.Context) -> None:
+    """Check if the Netdata agent is reachable."""
+    try:
+        ok = ctx.obj["client"].ping()
+        if ok:
+            msg = "pong ✓"
+            if console:
+                console.print(f"[bold green]{msg}[/]")
+            else:
+                print(msg)
+        else:
+            msg = "Agent not responding"
+            if console:
+                console.print(f"[bold red]{msg}[/]")
+            else:
+                print(msg)
+            sys.exit(1)
+    except NetdataError as exc:
+        _handle_error(exc)
+
+
+# ------------------------------------------------------------------
+# charts
+# ------------------------------------------------------------------
+
+
+@cli.command()
+@click.argument("query", required=False)
+@click.option("--type", "-T", "chart_type", help="Filter by chart type (e.g. system, disk, cgroup).")
+@click.option("--limit", "-n", default=0, help="Max charts to show (0 = all).")
+@click.pass_context
+def charts(ctx: click.Context, query: str | None, chart_type: str | None, limit: int) -> None:
+    """List or search charts.
+
+    With no arguments, lists all charts.  With QUERY, searches chart
+    id, title, type, family, units, and dimension names.
+    """
+    try:
+        raw = ctx.obj["client"].charts()
+        items = raw.get("charts", {})
+
+        results = []
+        for chart_id, info in items.items():
+            entry = {"id": chart_id, **info}
+
+            # type filter
+            if chart_type and info.get("type", "") != chart_type:
+                continue
+
+            # text search
+            if query:
+                q = query.lower()
+                searchable = " ".join(
+                    [
+                        chart_id,
+                        info.get("name", ""),
+                        info.get("type", ""),
+                        info.get("family", ""),
+                        info.get("title", ""),
+                        info.get("units", ""),
+                        info.get("plugin", ""),
+                        info.get("module", ""),
+                        " ".join(info.get("dimensions", {}).keys()),
+                    ]
+                ).lower()
+                if q not in searchable:
+                    continue
+
+            results.append(entry)
+
+        if limit > 0:
+            results = results[:limit]
+
+        print_charts(results, as_json=ctx.obj["as_json"])
+    except NetdataError as exc:
+        _handle_error(exc)
+
+
+# ------------------------------------------------------------------
+# chart (detail)
+# ------------------------------------------------------------------
+
+
+@cli.command()
+@click.argument("chart_id")
+@click.pass_context
+def chart(ctx: click.Context, chart_id: str) -> None:
+    """Show details for a specific chart (dimensions, metadata)."""
+    try:
+        data = ctx.obj["client"].chart(chart_id)
+        print_chart_detail(data, as_json=ctx.obj["as_json"])
+    except NetdataError as exc:
+        _handle_error(exc)
+
+
+# ------------------------------------------------------------------
+# data
+# ------------------------------------------------------------------
+
+
+@cli.command()
+@click.argument("chart_id")
+@click.option("--after", "-a", default=-60, show_default=True, help="Start time (seconds from now, negative).")
+@click.option("--before", "-b", default=0, show_default=True, help="End time (seconds from now, 0=now).")
+@click.option("--points", "-p", default=60, show_default=True, help="Number of data points.")
+@click.option("--group", "-g", default="average", show_default=True, help="Grouping: average, min, max, sum, incremental.")
+@click.option("--options", "-o", default="", help="Extra options: seconds, jsonwrap, flip, percent.")
+@click.pass_context
+def data(
+    ctx: click.Context,
+    chart_id: str,
+    after: int,
+    before: int,
+    points: int,
+    group: str,
+    options: str,
+) -> None:
+    """Fetch historical data for a chart.
+
+    \b
+    Examples:
+      nd data system.cpu --after -300 --points 10
+      nd data disk.util.sda --after -3600 --group max
+      nd data mem.available --after -86400 --points 1440
+    """
+    try:
+        result = ctx.obj["client"].data(
+            chart_id=chart_id,
+            after=after,
+            before=before,
+            points=points,
+            group=group,
+            options=options,
+        )
+        print_data(result, as_json=ctx.obj["as_json"])
+    except NetdataError as exc:
+        _handle_error(exc)
+
+
+# ------------------------------------------------------------------
+# alarms
+# ------------------------------------------------------------------
+
+
+@cli.command()
+@click.option("--all", "-a", "show_all", is_flag=True, help="Include inactive alarms.")
+@click.option("--active-only", is_flag=True, help="Show only WARNING/CRITICAL alarms.")
+@click.pass_context
+def alarms(ctx: click.Context, show_all: bool, active_only: bool) -> None:
+    """List alarms (health checks).
+
+    \b
+    Examples:
+      nd alarms              # active alarms
+      nd alarms --all        # all including inactive
+      nd alarms --active-only  # only warn/critical
+    """
+    try:
+        data = ctx.obj["client"].alarms(all=show_all)
+        alarm_list = []
+        for alarm_id, info in data.get("alarms", {}).items():
+            alarm_list.append({"id": alarm_id, **info})
+
+        if active_only:
+            alarm_list = [
+                a for a in alarm_list
+                if a.get("status", "").upper() in ("WARNING", "CRITICAL")
+            ]
+
+        # sort by status severity
+        severity_order = {"CRITICAL": 0, "WARNING": 1, "UNDEFINED": 2, "CLEAR": 3, "REMOVED": 4}
+        alarm_list.sort(key=lambda a: severity_order.get(a.get("status", "").upper(), 5))
+
+        print_alarms(alarm_list, as_json=ctx.obj["as_json"])
+    except NetdataError as exc:
+        _handle_error(exc)
+
+
+# ------------------------------------------------------------------
+# alarm-log
+# ------------------------------------------------------------------
+
+
+@cli.command("alarm-log")
+@click.option("--after", "-a", default=0, show_default=True, help="Last N seconds (0 = all).")
+@click.option("--unique", "-u", is_flag=True, help="One entry per alarm (latest status).")
+@click.pass_context
+def alarm_log(ctx: click.Context, after: int, unique: bool) -> None:
+    """Show alarm history log.
+
+    \b
+    Examples:
+      nd alarm-log               # all history
+      nd alarm-log --after 3600  # last hour
+      nd alarm-log --after 86400 --unique  # last 24h, latest per alarm
+    """
+    try:
+        c = ctx.obj["client"]
+        if unique:
+            entries = c.alarm_log_unique(after=after if after else 0)
+        else:
+            entries = c.alarm_log(after=after if after else 0)
+
+        # Normalize — API returns dict with 'alarms' key or a list
+        if isinstance(entries, dict):
+            entries = entries.get("alarms", [])
+        if isinstance(entries, list):
+            entries.sort(key=lambda e: e.get("when", 0), reverse=True)
+
+        print_alarm_log(entries, as_json=ctx.obj["as_json"])
+    except NetdataError as exc:
+        _handle_error(exc)
+
+
+# ------------------------------------------------------------------
+# allmetrics
+# ------------------------------------------------------------------
+
+
+@cli.command()
+@click.option("--format", "-f", "fmt", default="json", type=click.Choice(["json", "shell", "prometheus"]), show_default=True)
+@click.pass_context
+def allmetrics(ctx: click.Context, fmt: str) -> None:
+    """Snapshot of every metric in one call.
+
+    Use --format prometheus for Prometheus-compatible output.
+    """
+    try:
+        data = ctx.obj["client"].allmetrics(format=fmt)
+        if fmt == "json":
+            if isinstance(data, dict):
+                count = len(data)
+                print(f"Metrics families: {count}")
+                if ctx.obj["as_json"]:
+                    print_json(data)
+                else:
+                    # Show summary
+                    for name in sorted(data.keys())[:30]:
+                        entry = data[name]
+                        dims = entry.get("dimensions", {})
+                        print(f"  {name}: {len(dims)} dims = {list(dims.values())[:3]}...")
+                    if count > 30:
+                        print(f"  ... and {count - 30} more")
+            else:
+                print_json(data)
+        else:
+            print(data)
+    except NetdataError as exc:
+        _handle_error(exc)
+
+
+# ------------------------------------------------------------------
+# function
+# ------------------------------------------------------------------
+
+
+@cli.command("function")
+@click.argument("name")
+@click.option("--after", "-a", default=0, help="Start time (seconds from now, negative) or 0.")
+@click.option("--before", "-b", default=0, help="End time or 0 for now.")
+@click.option("--points", "-p", default=0, help="Number of data points (0 = server default).")
+@click.pass_context
+def function_cmd(ctx: click.Context, name: str, after: int, before: int, points: int) -> None:
+    """Call a Netdata function (systemd-journal, docker:container-ls, etc).
+
+    \b
+    Examples:
+      nd function docker:container-ls
+      nd function systemd-journal --after -3600
+      nd function mount-points
+      nd function network-interfaces
+    """
+    try:
+        data = ctx.obj["client"].function(
+            function_name=name,
+            after=after,
+            before=before,
+            points=points,
+        )
+        print_function(data, as_json=ctx.obj["as_json"])
+    except NetdataError as exc:
+        _handle_error(exc)
+
+
+# ------------------------------------------------------------------
+# functions (list available)
+# ------------------------------------------------------------------
+
+
+@cli.command("functions")
+@click.pass_context
+def functions_list(ctx: click.Context) -> None:
+    """List available Netdata functions."""
+    try:
+        data = ctx.obj["client"].info()
+        funcs = data.get("functions", {})
+
+        if ctx.obj["as_json"]:
+            print_json(funcs)
+            return
+
+        if HAS_RICH:
+            from rich.table import Table
+
+            t = Table(title=f"Functions ({len(funcs)})")
+            t.add_column("Name", style="cyan")
+            t.add_column("Help", max_width=60)
+            t.add_column("Tags", style="dim")
+            t.add_column("Timeout", justify="right")
+            for name, info in funcs.items():
+                t.add_row(
+                    name,
+                    info.get("help", "")[:60],
+                    ", ".join(info.get("tags", [])) if isinstance(info.get("tags"), list) else str(info.get("tags", "")),
+                    str(info.get("timeout", "")),
+                )
+            console.print(t)
+        else:
+            for name, info in funcs.items():
+                print(f"  {name}: {info.get('help', '')[:80]}")
+    except NetdataError as exc:
+        _handle_error(exc)
+
+
+# ------------------------------------------------------------------
+# collectors
+# ------------------------------------------------------------------
+
+
+@cli.command()
+@click.pass_context
+def collectors(ctx: click.Context) -> None:
+    """List active data collectors."""
+    try:
+        data = ctx.obj["client"].info()
+        colls = data.get("collectors", [])
+
+        if ctx.obj["as_json"]:
+            print_json(colls)
+            return
+
+        if HAS_RICH:
+            from rich.table import Table
+
+            t = Table(title=f"Collectors ({len(colls)})")
+            t.add_column("Plugin", style="cyan")
+            t.add_column("Module")
+            for c in colls:
+                t.add_row(c.get("plugin", "?"), c.get("module", "—"))
+            console.print(t)
+        else:
+            for c in colls:
+                mod = c.get("module", "")
+                suffix = f" / {mod}" if mod else ""
+                print(f"  {c.get('plugin', '?')}{suffix}")
+    except NetdataError as exc:
+        _handle_error(exc)
+
+
+# ------------------------------------------------------------------
+# Top-level entry
+# ------------------------------------------------------------------
+
+def main() -> None:
+    cli()
+
+
+if __name__ == "__main__":
+    main()

netdata_cli/client.py

@@ -0,0 +1,223 @@
+"""Netdata REST API client."""
+
+from __future__ import annotations
+
+import time
+from typing import Any
+
+import requests
+
+
+class NetdataError(Exception):
+    """Error communicating with Netdata."""
+
+
+class NetdataClient:
+    """Thin wrapper around the Netdata REST API (v1)."""
+
+    def __init__(self, base_url: str = "http://localhost:19999", timeout: int = 10):
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self._session = requests.Session()
+        self._session.headers.update({"Accept": "application/json"})
+
+    # ------------------------------------------------------------------
+    # Low-level
+    # ------------------------------------------------------------------
+
+    def _get(self, path: str, params: dict | None = None, raw: bool = False) -> Any:
+        url = f"{self.base_url}{path}"
+        try:
+            resp = self._session.get(url, params=params, timeout=self.timeout)
+            resp.raise_for_status()
+            if raw:
+                return resp.text
+            if not resp.content:
+                return [] if "alarm_log" in path else {}
+            return resp.json()
+        except requests.ConnectionError:
+            raise NetdataError(
+                f"Cannot connect to Netdata at {self.base_url}. "
+                "Is the agent running?"
+            )
+        except requests.Timeout:
+            raise NetdataError(f"Request to {url} timed out after {self.timeout}s")
+        except (requests.HTTPError, requests.exceptions.ChunkedEncodingError) as exc:
+            raise NetdataError(f"HTTP error from {url}: {exc}")
+        except ValueError:
+            raise NetdataError(f"Invalid JSON response from {url}")
+
+    # ------------------------------------------------------------------
+    # Agent info
+    # ------------------------------------------------------------------
+
+    def info(self) -> dict:
+        """Return /api/v1/info — agent version, OS, collectors, etc."""
+        return self._get("/api/v1/info")
+
+    # ------------------------------------------------------------------
+    # Charts
+    # ------------------------------------------------------------------
+
+    def charts(self) -> dict:
+        """Return all charts.  Response['charts'] is a dict keyed by chart id."""
+        return self._get("/api/v1/charts")
+
+    def chart(self, chart_id: str) -> dict:
+        """Return details for a single chart."""
+        return self._get("/api/v1/chart", params={"chart": chart_id})
+
+    # ------------------------------------------------------------------
+    # Data (historical)
+    # ------------------------------------------------------------------
+
+    def data(
+        self,
+        chart_id: str,
+        after: int = -60,
+        before: int = 0,
+        points: int = 60,
+        group: str = "average",
+        format: str = "json",
+        options: str = "",
+    ) -> dict:
+        """
+        Fetch data points for *chart_id*.
+
+        Parameters
+        ----------
+        after : int
+            Seconds relative to now (negative) or unix timestamp.
+        before : int
+            Seconds relative to now (negative) or unix timestamp. 0 = now.
+        points : int
+            Number of data points to return.
+        group : str
+            Grouping method: average, min, max, sum, incremental, etc.
+        format : str
+            json | csv | tsv | ssv |Cumhurbaşkan
+        options : str
+            Comma-separated: seconds, jsonwrap, flip, min2max, percent, etc.
+        """
+        params: dict[str, Any] = {
+            "chart": chart_id,
+            "after": after,
+            "before": before,
+            "points": points,
+            "group": group,
+            "format": format,
+        }
+        if options:
+            params["options"] = options
+        return self._get("/api/v1/data", params=params)
+
+    # ------------------------------------------------------------------
+    # All metrics (snapshot)
+    # ------------------------------------------------------------------
+
+    def allmetrics(self, format: str = "json") -> dict | str:
+        """Return a snapshot of every metric. format: json | shell | prometheus."""
+        if format == "json":
+            return self._get("/api/v1/allmetrics")
+        # shell/prometheus return plain text
+        return self._get(
+            "/api/v1/allmetrics",
+            params={"format": format, "help": "yes"},
+            raw=True,
+        )
+
+    # ------------------------------------------------------------------
+    # Alarms
+    # ------------------------------------------------------------------
+
+    def alarms(self, all: bool = False) -> dict:
+        """Active alarms, or all (including inactive) if *all* is True."""
+        path = "/api/v1/alarms"
+        params = {"all": "yes"} if all else None
+        return self._get(path, params=params)
+
+    def alarm_log(self, after: int = 0) -> list:
+        """Alarm log entries.  *after*: 0 = all, negative = last N seconds."""
+        params = {}
+        if after:
+            params["after"] = after
+        try:
+            return self._get("/api/v1/alarm_log", params=params)
+        except NetdataError:
+            # Netdata returns empty chunked response when alarm log is empty
+            return []
+
+    def alarm_log_unique(self, after: int = 0) -> list:
+        """Alarm log, one entry per unique alarm (latest status)."""
+        params = {"all": "yes"}
+        if after:
+            params["after"] = after
+        try:
+            return self._get("/api/v1/alarm_log", params=params)
+        except NetdataError:
+            return []
+
+    # ------------------------------------------------------------------
+    # Functions (systemd-journal, docker:container-ls, etc.)
+    # ------------------------------------------------------------------
+
+    def function(
+        self,
+        function_name: str,
+        context: str = "",
+        after: int = 0,
+        before: int = 0,
+        points: int = 0,
+        format: str = "json",
+        options: str = "",
+    ) -> Any:
+        """Call a Netdata function (e.g. systemd-journal, docker:container-ls)."""
+        params: dict[str, Any] = {"function": function_name}
+        if context:
+            params["context"] = context
+        if after:
+            params["after"] = after
+        if before:
+            params["before"] = before
+        if points:
+            params["points"] = points
+        if format:
+            params["format"] = format
+        if options:
+            params["options"] = options
+        return self._get("/api/v1/function", params=params)
+
+    # ------------------------------------------------------------------
+    # Helpers
+    # ------------------------------------------------------------------
+
+    def search_charts(self, query: str) -> list[dict]:
+        """Search charts by id, name, type, family, title, or units."""
+        q = query.lower()
+        raw = self.charts()
+        results = []
+        for chart_id, info in raw.get("charts", {}).items():
+            searchable = " ".join(
+                [
+                    chart_id,
+                    info.get("name", ""),
+                    info.get("type", ""),
+                    info.get("family", ""),
+                    info.get("title", ""),
+                    info.get("units", ""),
+                    info.get("plugin", ""),
+                    info.get("module", ""),
+                    " ".join(info.get("dimensions", {}).keys()),
+                ]
+            ).lower()
+            if q in searchable:
+                results.append({"id": chart_id, **info})
+        return results
+
+    def ping(self) -> bool:
+        """Return True if the agent is reachable and ready."""
+        try:
+            data = self._get("/api/v1/info")
+            return bool(data.get("version"))
+        except NetdataError:
+            return False

netdata_cli/formatters.py

@@ -0,0 +1,331 @@
+"""Output formatters for netdata-cli."""
+
+from __future__ import annotations
+
+import json
+import sys
+from datetime import datetime, timezone
+from typing import Any
+
+try:
+    from rich.console import Console
+    from rich.table import Table
+    from rich.text import Text
+
+    HAS_RICH = True
+except ImportError:
+    HAS_RICH = False
+
+console = Console() if HAS_RICH else None
+
+
+# ------------------------------------------------------------------
+# Generic helpers
+# ------------------------------------------------------------------
+
+
+def print_json(data: Any, pretty: bool = True) -> None:
+    """Print data as JSON."""
+    kwargs = {"indent": 2, "default": str} if pretty else {"default": str}
+    print(json.dumps(data, **kwargs))
+
+
+def _human_bytes(n: float | int | None) -> str:
+    if n is None:
+        return "—"
+    for unit in ("B", "KiB", "MiB", "GiB", "TiB"):
+        if abs(n) < 1024:
+            return f"{n:.1f} {unit}"
+        n /= 1024
+    return f"{n:.1f} PiB"
+
+
+def _human_duration(seconds: float | int | None) -> str:
+    if seconds is None:
+        return "—"
+    if seconds < 60:
+        return f"{seconds:.0f}s"
+    if seconds < 3600:
+        return f"{seconds / 60:.0f}m"
+    if seconds < 86400:
+        return f"{seconds / 3600:.1f}h"
+    return f"{seconds / 86400:.1f}d"
+
+
+def _ts_to_str(ts: int | float | None) -> str:
+    if ts is None:
+        return "—"
+    return datetime.fromtimestamp(ts, tz=timezone.utc).strftime("%Y-%m-%d %H:%M:%S UTC")
+
+
+def _colorize_severity(severity: str) -> str:
+    if not HAS_RICH:
+        return severity
+    mapping = {
+        "CRITICAL": "[bold red]CRITICAL[/]",
+        "WARNING": "[bold yellow]WARNING[/]",
+        "CLEAR": "[bold green]CLEAR[/]",
+        "UNDEFINED": "[dim]UNDEFINED[/]",
+        "REMOVED": "[dim]REMOVED[/]",
+    }
+    return mapping.get(severity.upper(), severity)
+
+
+# ------------------------------------------------------------------
+# Info
+# ------------------------------------------------------------------
+
+
+def print_info(data: dict, as_json: bool = False) -> None:
+    if as_json:
+        print_json(data)
+        return
+
+    alarms = data.get("alarms", {})
+    rows = [
+        ("Version", data.get("version", "?")),
+        ("OS", data.get("container_os_name", data.get("os_name", "?"))),
+        ("Kernel", f"{data.get('kernel_name', '?')} {data.get('kernel_version', '?')}"),
+        ("Architecture", data.get("architecture", "?")),
+        ("CPU Cores", data.get("cores_total", "?")),
+        ("CPU Freq", f"{int(data.get('cpu_freq', 0)) / 1e6:.0f} MHz"),
+        ("RAM", _human_bytes(int(data.get("ram_total", 0)))),
+        ("Disk", _human_bytes(int(data.get("total_disk_space", 0)))),
+        ("Container", data.get("container", "none")),
+        ("Charts", data.get("charts-count", "?")),
+        ("Metrics", data.get("metrics-count", "?")),
+        ("Memory Mode", data.get("memory-mode", "?")),
+        ("Alarms OK", alarms.get("normal", "?")),
+        ("Alarms Warn", alarms.get("warning", "?")),
+        ("Alarms Crit", alarms.get("critical", "?")),
+        ("Cloud", "claimed" if data.get("agent-claimed") else "not claimed"),
+        ("HTTPS", "yes" if data.get("https-enabled") else "no"),
+        ("Collectors", len(data.get("collectors", []))),
+    ]
+
+    if HAS_RICH:
+        t = Table(title="Netdata Agent", show_header=False, box=None, padding=(0, 2))
+        t.add_column(style="bold cyan", min_width=14)
+        t.add_column()
+        for label, value in rows:
+            t.add_row(label, str(value))
+        console.print(t)
+    else:
+        for label, value in rows:
+            print(f"  {label:14s}  {value}")
+
+
+# ------------------------------------------------------------------
+# Charts
+# ------------------------------------------------------------------
+
+
+def print_charts(charts: list[dict], as_json: bool = False) -> None:
+    if as_json:
+        print_json(charts)
+        return
+
+    if HAS_RICH:
+        t = Table(title=f"Charts ({len(charts)})")
+        t.add_column("Chart ID", style="cyan", max_width=45)
+        t.add_column("Title", max_width=40)
+        t.add_column("Type", style="dim")
+        t.add_column("Units", style="green")
+        t.add_column("Dims", justify="right")
+        t.add_column("Family", style="dim")
+        for c in charts:
+            t.add_row(
+                c.get("id", "?"),
+                c.get("title", "")[:40],
+                c.get("type", ""),
+                c.get("units", ""),
+                str(len(c.get("dimensions", {}))),
+                c.get("family", ""),
+            )
+        console.print(t)
+    else:
+        print(f"  {'Chart ID':45s} {'Title':40s} {'Type':15s} {'Units':10s} Dims")
+        print(f"  {'─' * 45} {'─' * 40} {'─' * 15} {'─' * 10} ────")
+        for c in charts:
+            dims = len(c.get("dimensions", {}))
+            print(
+                f"  {c.get('id',''):45s} {c.get('title','')[:40]:40s} "
+                f"{c.get('type',''):15s} {c.get('units',''):10s} {dims:>4}"
+            )
+    print(f"\n  Total: {len(charts)} charts")
+
+
+def print_chart_detail(data: dict, as_json: bool = False) -> None:
+    if as_json:
+        print_json(data)
+        return
+
+    if HAS_RICH:
+        t = Table(title=data.get("id", "Chart"), show_header=False, box=None)
+        t.add_column(style="bold cyan", min_width=14)
+        t.add_column()
+        for key in ("id", "name", "type", "family", "title", "units", "plugin", "module"):
+            t.add_row(key, str(data.get(key, "—")))
+        t.add_row("dimensions", str(len(data.get("dimensions", {}))))
+        t.add_row("update_every", str(data.get("update_every", "—")))
+        t.add_row("history", str(data.get("history", "—")))
+        console.print(t)
+
+        if data.get("dimensions"):
+            dt = Table(title="Dimensions")
+            dt.add_column("ID", style="cyan")
+            dt.add_column("Name")
+            dt.add_column("Algorithm")
+            dt.add_column("Multiplier")
+            dt.add_column("Divisor")
+            for dim_id, dim_info in data["dimensions"].items():
+                dt.add_row(
+                    dim_id,
+                    dim_info.get("name", ""),
+                    dim_info.get("algorithm", ""),
+                    str(dim_info.get("multiplier", "")),
+                    str(dim_info.get("divisor", "")),
+                )
+            console.print(dt)
+    else:
+        for key in ("id", "name", "type", "family", "title", "units", "plugin", "module"):
+            print(f"  {key:14s}  {data.get(key, '—')}")
+        print(f"\n  Dimensions:")
+        for dim_id, dim_info in data.get("dimensions", {}).items():
+            print(f"    {dim_id}: {dim_info.get('name','')} ({dim_info.get('algorithm','')})")
+
+
+# ------------------------------------------------------------------
+# Data
+# ------------------------------------------------------------------
+
+
+def print_data(data: dict, as_json: bool = False) -> None:
+    """Print /api/v1/data response."""
+    if as_json:
+        print_json(data)
+        return
+
+    labels = data.get("labels", [])
+    rows = data.get("data", [])
+
+    if HAS_RICH:
+        t = Table(title=data.get("chart", "Data"))
+        for label in labels:
+            style = "cyan" if label == "time" else None
+            t.add_column(label, style=style, justify="right")
+        for row in rows[-20:]:  # last 20 rows
+            formatted = []
+            for i, val in enumerate(row):
+                if labels[i] == "time":
+                    formatted.append(_ts_to_str(val))
+                elif isinstance(val, float):
+                    formatted.append(f"{val:.2f}")
+                else:
+                    formatted.append(str(val) if val is not None else "—")
+            t.add_row(*formatted)
+        console.print(t)
+        if len(rows) > 20:
+            console.print(f"[dim]  ... showing last 20 of {len(rows)} points[/]")
+    else:
+        header = "  ".join(f"{l:>12s}" for l in labels)
+        print(f"  {header}")
+        for row in rows[-20:]:
+            vals = []
+            for i, val in enumerate(row):
+                if labels[i] == "time":
+                    vals.append(f"{_ts_to_str(val):>12s}")
+                elif isinstance(val, float):
+                    vals.append(f"{val:>12.2f}")
+                else:
+                    vals.append(f"{str(val) if val is not None else '—':>12s}")
+            print(f"  {'  '.join(vals)}")
+        if len(rows) > 20:
+            print(f"  ... showing last 20 of {len(rows)} points")
+
+
+# ------------------------------------------------------------------
+# Alarms
+# ------------------------------------------------------------------
+
+
+def print_alarms(alarms: list[dict], as_json: bool = False) -> None:
+    if as_json:
+        print_json(alarms)
+        return
+
+    if HAS_RICH:
+        t = Table(title=f"Alarms ({len(alarms)})")
+        t.add_column("Chart", style="cyan", max_width=30)
+        t.add_column("Name", max_width=30)
+        t.add_column("Status", justify="center")
+        t.add_column("Value", justify="right")
+        t.add_column("Warning", justify="right", style="yellow")
+        t.add_column("Critical", justify="right", style="red")
+        t.add_column("Last Updated")
+        for a in alarms:
+            t.add_row(
+                a.get("chart", "?"),
+                a.get("name", "?"),
+                _colorize_severity(a.get("status", "?")),
+                str(a.get("value", "—")),
+                str(a.get("warn", "—")),
+                str(a.get("crit", "—")),
+                _ts_to_str(a.get("last_updated")),
+            )
+        console.print(t)
+    else:
+        print(f"  {'Chart':30s} {'Name':30s} {'Status':10s} {'Value':>10s} {'Warn':>10s} {'Crit':>10s}")
+        for a in alarms:
+            print(
+                f"  {a.get('chart',''):30s} {a.get('name',''):30s} "
+                f"{a.get('status',''):10s} {str(a.get('value','—')):>10s} "
+                f"{str(a.get('warn','—')):>10s} {str(a.get('crit','—')):>10s}"
+            )
+    print(f"\n  Total: {len(alarms)} alarms")
+
+
+def print_alarm_log(entries: list[dict], as_json: bool = False) -> None:
+    if as_json:
+        print_json(entries)
+        return
+
+    if HAS_RICH:
+        t = Table(title=f"Alarm Log ({len(entries)} entries)")
+        t.add_column("Time", style="dim")
+        t.add_column("Chart", style="cyan", max_width=30)
+        t.add_column("Name", max_width=25)
+        t.add_column("Status", justify="center")
+        t.add_column("Old", justify="center")
+        t.add_column("Value", justify="right")
+        for e in entries[-50:]:
+            t.add_row(
+                _ts_to_str(e.get("when")),
+                e.get("chart", "?"),
+                e.get("name", "?"),
+                _colorize_severity(e.get("status_new", e.get("status", "?"))),
+                e.get("status_old", "—"),
+                str(e.get("value", "—")),
+            )
+        console.print(t)
+        if len(entries) > 50:
+            console.print(f"[dim]  ... showing last 50 of {len(entries)} entries[/]")
+    else:
+        for e in entries[-30:]:
+            print(
+                f"  {_ts_to_str(e.get('when'))}  {e.get('chart',''):25s}  "
+                f"{e.get('name',''):20s}  {e.get('status_new', e.get('status',''))}"
+            )
+
+
+# ------------------------------------------------------------------
+# Functions
+# ------------------------------------------------------------------
+
+
+def print_function(data: Any, as_json: bool = False) -> None:
+    """Generic function output."""
+    if as_json:
+        print_json(data)
+        return
+    print_json(data)

netdata_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,223 @@
+Metadata-Version: 2.4
+Name: netdata-cli
+Version: 0.1.0
+Summary: A powerful CLI for the Netdata Agent REST API — query metrics, charts, alarms, and functions from the terminal.
+Author-email: Sosi <sosi@example.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/sosiman/netdata-cli
+Project-URL: Repository, https://github.com/sosiman/netdata-cli
+Project-URL: Issues, https://github.com/sosiman/netdata-cli/issues
+Keywords: netdata,cli,monitoring,metrics,devops,observability
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: System Administrators
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Monitoring
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.0
+Requires-Dist: requests>=2.28
+Requires-Dist: rich>=13.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Dynamic: license-file
+
+# netdata-cli
+
+A powerful CLI for the [Netdata](https://www.netdata.cloud/) Agent REST API.
+
+Query metrics, charts, alarms, functions, and agent info — all from the terminal.
+Rich table output, JSON mode, time filtering, and search built-in.
+
+```
+┌─────────────────────────────────────────────┐
+│            Netdata Agent                     │
+│  Version   v2.10.4                          │
+│  OS        Debian GNU/Linux 13 (trixie)     │
+│  Kernel    Linux 6.8.0-136-generic          │
+│  CPU Cores 4                                │
+│  RAM       15.4 GiB                         │
+│  Charts    1669                             │
+│  Metrics   4124                             │
+│  Alarms OK 603                              │
+└─────────────────────────────────────────────┘
+```
+
+## Installation
+
+```bash
+pip install netdata-cli
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/sosiman/netdata-cli
+cd netdata-cli
+pip install -e .
+```
+
+## Quick Start
+
+```bash
+# Agent info
+nd info
+
+# Check connectivity
+nd ping
+
+# Search charts
+nd charts cpu
+nd charts --type disk
+
+# Get historical data
+nd data system.cpu --after -300 --points 10
+nd data mem.available --after -3600
+
+# Alarms
+nd alarms
+nd alarms --active-only
+nd alarm-log --after 86400
+
+# Functions
+nd functions
+nd function docker:container-ls
+nd function mount-points
+nd function network-interfaces
+
+# Collectors
+nd collectors
+
+# Raw JSON output
+nd --json info
+nd --json charts
+```
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `nd info` | Agent version, OS, CPU, RAM, chart/alarm counts, collectors |
+| `nd ping` | Check if the agent is reachable |
+| `nd charts [QUERY]` | List or search charts by id, title, type, units, dimensions |
+| `nd chart CHART_ID` | Show chart details (dimensions, metadata, history) |
+| `nd data CHART_ID` | Fetch historical data points with time range and grouping |
+| `nd alarms` | List health alarms (active or all) |
+| `nd alarm-log` | Alarm history with time filtering |
+| `nd allmetrics` | Snapshot of every metric (JSON, shell, or Prometheus format) |
+| `nd function NAME` | Call Netdata functions (docker, systemd, network, etc.) |
+| `nd functions` | List available functions |
+| `nd collectors` | List active data collectors |
+
+## Configuration
+
+Set the `NETDATA_URL` environment variable to point to a remote agent:
+
+```bash
+export NETDATA_URL=http://my-server:19999
+nd info
+```
+
+Or pass `--url` on every call:
+
+```bash
+nd --url http://my-server:19999 charts
+```
+
+## Output Formats
+
+Every command supports `--json` (`-j`) for raw JSON output, useful for piping to `jq`:
+
+```bash
+nd --json charts | jq '.[] | select(.units == "percentage")'
+nd --json alarms | jq '.[] | select(.status == "WARNING")'
+nd --json data system.cpu | jq '.data[-1]'
+```
+
+## Time Filtering
+
+The `--after` flag accepts negative seconds (relative to now):
+
+| Value | Meaning |
+|---|---|
+| `-60` | Last minute |
+| `-300` | Last 5 minutes |
+| `-3600` | Last hour |
+| `-86400` | Last 24 hours |
+| `-604800` | Last 7 days |
+
+Data granularity depends on the chart's `update_every` setting and the Netdata database retention.
+
+## Examples
+
+### Monitor CPU in real-time
+
+```bash
+watch -n 2 'nd data system.cpu --after -10 --points 10'
+```
+
+### Find all disk charts
+
+```bash
+nd charts disk
+```
+
+### Export all metrics as Prometheus
+
+```bash
+nd allmetrics --format prometheus
+```
+
+### Check only critical alarms
+
+```bash
+nd alarms --active-only
+```
+
+### List Docker containers via Netdata
+
+```bash
+nd function docker:container-ls
+```
+
+### Show network interfaces
+
+```bash
+nd function network-interfaces
+```
+
+## Requirements
+
+- Python 3.10+
+- A running Netdata agent (v1.x or v2.x)
+
+## Dependencies
+
+- [click](https://click.palletsprojects.com/) — CLI framework
+- [requests](https://requests.readthedocs.io/) — HTTP client
+- [rich](https://rich.readthedocs.io/) — Terminal formatting
+
+## Development
+
+```bash
+git clone https://github.com/sosiman/netdata-cli
+cd netdata-cli
+pip install -e ".[dev]"
+pytest
+ruff check .
+```
+
+## License
+
+[MIT](LICENSE)

netdata_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+netdata_cli/__init__.py,sha256=rIbZbYbNCaZoSgcA-IOtDHW52a1eZSUD-2ONKIaMVsM,92
+netdata_cli/cli.py,sha256=ZCfaEzf119wYfzv5ZM2kM4hjrZMC6BvpMInU8PBpszQ,14570
+netdata_cli/client.py,sha256=T4DuVOP_CKvzpF1FiXbG1OvYvqhgO29tOqHykFCp48A,7862
+netdata_cli/formatters.py,sha256=rokGtvuwK1MsR2cMOEjza2ggL4YvqSOLnvCgCwiPm_w,11644
+netdata_cli-0.1.0.dist-info/licenses/LICENSE,sha256=Tq3uYZqMEv-MzVnsiXx-L99tt5Css4jGrocf6KpFdfM,1061
+netdata_cli-0.1.0.dist-info/METADATA,sha256=QoL8zXtGoXNJFhlbCjhuhNmazh3m_u_fQ8dD9S4Fs7A,5686
+netdata_cli-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+netdata_cli-0.1.0.dist-info/entry_points.txt,sha256=15fw-SmjPRO9-1z1h0g8I2pWuyNXZDm_MmHkiDklELw,44
+netdata_cli-0.1.0.dist-info/top_level.txt,sha256=TC9SwX7mrl2Q1QDRKMs045wkb5Bg3MH1y_iAiL1jhDc,12
+netdata_cli-0.1.0.dist-info/RECORD,,

netdata_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

netdata_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+nd = netdata_cli.cli:main

netdata_cli-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sosi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

netdata_cli-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+netdata_cli