plyrana-cli 0.1.0__tar.gz

plyrana_cli-0.1.0/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: plyrana-cli
+Version: 0.1.0
+Summary: Plyrana CLI — manage any self-hosted Plyrana instance from your terminal. Auth, devices, variables, automations, system.
+Author-email: Plyrana <dev@plyrana.com>
+License: AGPL-3.0
+Project-URL: Homepage, https://github.com/plyrana/core
+Project-URL: Documentation, https://github.com/plyrana/core/tree/main/cli
+Project-URL: Repository, https://github.com/plyrana/core
+Project-URL: Issues, https://github.com/plyrana/core/issues
+Keywords: plyrana,iot,cli,devops,automation
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: GNU Affero General Public License v3
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx<0.29.0,>=0.23.0
+Requires-Dist: typer>=0.9.0
+Requires-Dist: rich>=13.0.0
+
+# plyrana-cli — Terminal client for Plyrana
+
+Thin command-line client for the Plyrana IoT Device Hub REST API. Great for CI/CD, scripting, batch operations.
+
+## Install
+
+```bash
+pip install plyrana-cli
+# dev install from source:
+pip install -e ./cli
+```
+
+## First run
+
+```bash
+# Point to your hub
+plyrana config set-url https://hub.example.com
+
+# Login (password prompt if omitted)
+plyrana auth login --email admin@example.com
+
+# Verify
+plyrana auth status
+```
+
+## Commands
+
+### Auth
+```bash
+plyrana auth login --email <EMAIL>
+plyrana auth logout
+plyrana auth status
+```
+
+### Devices
+```bash
+plyrana devices list [--limit 50] [--type hardware]
+plyrana devices get <UID>
+plyrana devices claim <UID>
+plyrana devices unclaim <UID>
+```
+
+### Variables
+```bash
+plyrana variables list [--device <UID>]
+plyrana variables get <UID> <KEY>
+plyrana variables set <UID> <KEY> <VALUE>        # auto-cast: 22.5 / true / '{"x":1}'
+plyrana variables history <UID> <KEY> [--limit 20]
+```
+
+### Automations
+```bash
+plyrana automations list
+plyrana automations run <ID>
+plyrana automations toggle <ID> --on | --off
+```
+
+### System
+```bash
+plyrana system health         # public, no auth
+plyrana system license        # CE / Pro / Enterprise + limits
+plyrana system integrations   # MQTT / HA / Prometheus / Grafana status
+plyrana system metrics        # Prometheus text-format
+```
+
+### Config
+```bash
+plyrana config show
+plyrana config set-url <URL>
+plyrana config clear
+```
+
+## Auth storage
+
+Tokens are stored in `~/.plyrana/config.json` with `0600` perms (best-effort on Windows).
+
+Override via env:
+- `PLYRANA_URL=https://hub.example.com`
+- `PLYRANA_TOKEN=eyJ...`
+
+Env beats file — great for CI.
+
+## Example: CI smoke-test
+
+```bash
+export PLYRANA_URL=https://hub.example.com
+export PLYRANA_TOKEN=$PLYRANA_CI_TOKEN
+plyrana system health || exit 1
+plyrana devices list --limit 1 || exit 1
+```
+
+## License
+
+AGPL-3.0 — see [LICENSE](../LICENSE) in the main repo.

plyrana_cli-0.1.0/README.md

@@ -0,0 +1,94 @@
+# plyrana-cli — Terminal client for Plyrana
+
+Thin command-line client for the Plyrana IoT Device Hub REST API. Great for CI/CD, scripting, batch operations.
+
+## Install
+
+```bash
+pip install plyrana-cli
+# dev install from source:
+pip install -e ./cli
+```
+
+## First run
+
+```bash
+# Point to your hub
+plyrana config set-url https://hub.example.com
+
+# Login (password prompt if omitted)
+plyrana auth login --email admin@example.com
+
+# Verify
+plyrana auth status
+```
+
+## Commands
+
+### Auth
+```bash
+plyrana auth login --email <EMAIL>
+plyrana auth logout
+plyrana auth status
+```
+
+### Devices
+```bash
+plyrana devices list [--limit 50] [--type hardware]
+plyrana devices get <UID>
+plyrana devices claim <UID>
+plyrana devices unclaim <UID>
+```
+
+### Variables
+```bash
+plyrana variables list [--device <UID>]
+plyrana variables get <UID> <KEY>
+plyrana variables set <UID> <KEY> <VALUE>        # auto-cast: 22.5 / true / '{"x":1}'
+plyrana variables history <UID> <KEY> [--limit 20]
+```
+
+### Automations
+```bash
+plyrana automations list
+plyrana automations run <ID>
+plyrana automations toggle <ID> --on | --off
+```
+
+### System
+```bash
+plyrana system health         # public, no auth
+plyrana system license        # CE / Pro / Enterprise + limits
+plyrana system integrations   # MQTT / HA / Prometheus / Grafana status
+plyrana system metrics        # Prometheus text-format
+```
+
+### Config
+```bash
+plyrana config show
+plyrana config set-url <URL>
+plyrana config clear
+```
+
+## Auth storage
+
+Tokens are stored in `~/.plyrana/config.json` with `0600` perms (best-effort on Windows).
+
+Override via env:
+- `PLYRANA_URL=https://hub.example.com`
+- `PLYRANA_TOKEN=eyJ...`
+
+Env beats file — great for CI.
+
+## Example: CI smoke-test
+
+```bash
+export PLYRANA_URL=https://hub.example.com
+export PLYRANA_TOKEN=$PLYRANA_CI_TOKEN
+plyrana system health || exit 1
+plyrana devices list --limit 1 || exit 1
+```
+
+## License
+
+AGPL-3.0 — see [LICENSE](../LICENSE) in the main repo.

plyrana_cli-0.1.0/plyrana_cli/__init__.py

@@ -0,0 +1,3 @@
+"""plyrana-cli — Terminal client for the Plyrana IoT Device Hub."""
+
+__version__ = "0.1.0"

plyrana_cli-0.1.0/plyrana_cli/client.py

@@ -0,0 +1,64 @@
+"""Thin httpx wrapper used by all CLI commands."""
+
+from __future__ import annotations
+
+import httpx
+import typer
+
+from .config import Config
+
+
+class PlyranaAPIError(Exception):
+    def __init__(self, status: int, detail: str) -> None:
+        super().__init__(f"HTTP {status}: {detail}")
+        self.status = status
+        self.detail = detail
+
+
+def require_auth(cfg: Config) -> None:
+    if not cfg.is_authenticated:
+        typer.secho(
+            "Not authenticated. Run: plyrana auth login --email <you> --password <pw>",
+            fg=typer.colors.RED,
+            err=True,
+        )
+        raise typer.Exit(code=2)
+
+
+def http(cfg: Config, method: str, path: str, **kwargs) -> httpx.Response:
+    """Perform an API call. Path is relative (e.g. '/api/v1/devices')."""
+    url = cfg.base_url + path
+    headers = kwargs.pop("headers", {}) or {}
+    if cfg.token:
+        headers["Authorization"] = f"Bearer {cfg.token}"
+    timeout = kwargs.pop("timeout", 30.0)
+    try:
+        response = httpx.request(method, url, headers=headers, timeout=timeout, **kwargs)
+    except httpx.RequestError as exc:
+        typer.secho(f"Network error: {exc}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=3) from exc
+
+    if response.status_code >= 400:
+        try:
+            detail = response.json()
+        except ValueError:
+            detail = response.text
+        raise PlyranaAPIError(response.status_code, str(detail))
+
+    return response
+
+
+def get(cfg: Config, path: str, **kwargs) -> httpx.Response:
+    return http(cfg, "GET", path, **kwargs)
+
+
+def post(cfg: Config, path: str, json: dict | None = None, **kwargs) -> httpx.Response:
+    return http(cfg, "POST", path, json=json, **kwargs)
+
+
+def put(cfg: Config, path: str, json: dict | None = None, **kwargs) -> httpx.Response:
+    return http(cfg, "PUT", path, json=json, **kwargs)
+
+
+def delete(cfg: Config, path: str, **kwargs) -> httpx.Response:
+    return http(cfg, "DELETE", path, **kwargs)

plyrana_cli-0.1.0/plyrana_cli/commands/__init__.py

@@ -0,0 +1 @@
+

plyrana_cli-0.1.0/plyrana_cli/commands/auth.py

@@ -0,0 +1,84 @@
+"""Auth subcommand: login, logout, status."""
+
+from __future__ import annotations
+
+import getpass
+
+import typer
+from rich.console import Console
+
+from ..client import PlyranaAPIError, get, post
+from ..config import Config
+
+
+app = typer.Typer()
+console = Console()
+
+
+@app.command("login")
+def login(
+    email: str = typer.Option(..., "--email", "-e", prompt=True, help="Your email address."),
+    password: str | None = typer.Option(
+        None,
+        "--password",
+        "-p",
+        help="Your password (will be prompted if omitted).",
+    ),
+    url: str | None = typer.Option(
+        None, "--url", help="Plyrana base URL (override ~/.plyrana/config.json)."
+    ),
+) -> None:
+    """Authenticate and save a JWT token to ~/.plyrana/config.json."""
+    cfg = Config.load()
+    if url:
+        cfg.base_url = url.rstrip("/")
+    if not password:
+        password = getpass.getpass("Password: ")
+
+    try:
+        response = post(
+            cfg,
+            "/api/v1/auth/login",
+            json={"email": email, "password": password},
+        )
+    except PlyranaAPIError as exc:
+        typer.secho(f"Login failed: {exc.detail}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=1)
+
+    data = response.json()
+    cfg.token = data.get("access_token")
+    if not cfg.token:
+        typer.secho("Login response missing 'access_token'", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=1)
+    cfg.save()
+    console.print(f"[green]Logged in[/] as [bold]{email}[/] at [dim]{cfg.base_url}[/]")
+
+
+@app.command("logout")
+def logout() -> None:
+    """Remove the saved token."""
+    cfg = Config.load()
+    cfg.clear()
+    console.print("[green]Logged out[/] — ~/.plyrana/config.json removed.")
+
+
+@app.command("status")
+def status() -> None:
+    """Show current login status and identity."""
+    cfg = Config.load()
+    console.print(f"[bold]Base URL:[/] {cfg.base_url}")
+    if not cfg.is_authenticated:
+        console.print("[yellow]Not authenticated.[/]")
+        console.print("Run: [cyan]plyrana auth login --email <you>[/]")
+        raise typer.Exit(code=0)
+
+    try:
+        response = get(cfg, "/api/v1/users/me")
+    except PlyranaAPIError as exc:
+        typer.secho(f"Auth check failed: {exc.detail}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=1)
+
+    me = response.json()
+    console.print(
+        f"[green]Authenticated[/] as [bold]{me.get('email')}[/] (role: {me.get('role')})"
+    )

plyrana_cli-0.1.0/plyrana_cli/commands/automations.py

@@ -0,0 +1,88 @@
+"""Automations subcommand: list / run / toggle."""
+
+from __future__ import annotations
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from ..client import PlyranaAPIError, get, post, put, require_auth
+from ..config import Config
+
+
+app = typer.Typer()
+console = Console()
+
+
+@app.command("list")
+def list_automations() -> None:
+    """List all automations in your org."""
+    cfg = Config.load()
+    require_auth(cfg)
+    try:
+        response = get(cfg, "/api/v1/automations")
+    except PlyranaAPIError as exc:
+        typer.secho(f"Error: {exc.detail}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=1)
+
+    data = response.json()
+    automations = data if isinstance(data, list) else data.get("items", [])
+
+    if not automations:
+        console.print("[dim]No automations found.[/]")
+        return
+
+    table = Table(title=f"Automations ({len(automations)})")
+    table.add_column("ID", style="cyan")
+    table.add_column("Name")
+    table.add_column("Trigger", style="magenta")
+    table.add_column("Enabled")
+    table.add_column("Last run", style="dim")
+    for auto in automations:
+        table.add_row(
+            str(auto.get("id", "-")),
+            auto.get("name") or "-",
+            auto.get("trigger_type", "-"),
+            "[green]yes[/]" if auto.get("enabled") else "[red]no[/]",
+            auto.get("last_triggered_at") or "-",
+        )
+    console.print(table)
+
+
+@app.command("run")
+def run_automation(
+    automation_id: int = typer.Argument(..., help="Automation ID."),
+) -> None:
+    """Manually trigger an automation (runs actions once, bypassing trigger)."""
+    cfg = Config.load()
+    require_auth(cfg)
+    try:
+        response = post(cfg, f"/api/v1/automations/{automation_id}/run")
+    except PlyranaAPIError as exc:
+        typer.secho(f"Error: {exc.detail}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=1)
+    console.print(f"[green]Triggered[/] automation #{automation_id}")
+    console.print_json(data=response.json())
+
+
+@app.command("toggle")
+def toggle_automation(
+    automation_id: int = typer.Argument(..., help="Automation ID."),
+    enabled: bool = typer.Option(True, "--on/--off", help="Turn automation on or off."),
+) -> None:
+    """Enable or disable an automation."""
+    cfg = Config.load()
+    require_auth(cfg)
+    try:
+        response = put(
+            cfg,
+            f"/api/v1/automations/{automation_id}",
+            json={"enabled": enabled},
+        )
+    except PlyranaAPIError as exc:
+        typer.secho(f"Error: {exc.detail}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=1)
+
+    state = "on" if enabled else "off"
+    console.print(f"[green]Automation #{automation_id} is now {state}[/]")
+    console.print_json(data=response.json())

plyrana_cli-0.1.0/plyrana_cli/commands/config_cmd.py

@@ -0,0 +1,40 @@
+"""Config subcommand: show / set-url / clear."""
+
+from __future__ import annotations
+
+import typer
+from rich.console import Console
+
+from ..config import Config
+
+
+app = typer.Typer()
+console = Console()
+
+
+@app.command("show")
+def show() -> None:
+    """Show current CLI configuration."""
+    cfg = Config.load()
+    console.print(f"[bold]Base URL:[/] {cfg.base_url}")
+    if cfg.token:
+        console.print(f"[bold]Token:[/] {cfg.token[:20]}... [dim](stored)[/]")
+    else:
+        console.print("[yellow]No token[/] — run 'plyrana auth login'.")
+
+
+@app.command("set-url")
+def set_url(url: str = typer.Argument(..., help="New base URL.")) -> None:
+    """Change the Plyrana base URL."""
+    cfg = Config.load()
+    cfg.base_url = url.rstrip("/")
+    cfg.save()
+    console.print(f"[green]Base URL set to[/] {cfg.base_url}")
+
+
+@app.command("clear")
+def clear() -> None:
+    """Delete the config file (token + URL)."""
+    cfg = Config.load()
+    cfg.clear()
+    console.print("[green]Config cleared[/] — ~/.plyrana/config.json removed.")

plyrana_cli-0.1.0/plyrana_cli/commands/devices.py

@@ -0,0 +1,101 @@
+"""Devices subcommand: list / get / claim / unclaim."""
+
+from __future__ import annotations
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from ..client import PlyranaAPIError, delete, get, post, require_auth
+from ..config import Config
+
+
+app = typer.Typer()
+console = Console()
+
+
+@app.command("list")
+def list_devices(
+    limit: int = typer.Option(50, "--limit", "-n", help="Max rows to show."),
+    device_type: str | None = typer.Option(None, "--type", help="Filter by device type."),
+) -> None:
+    """List all devices in your org."""
+    cfg = Config.load()
+    require_auth(cfg)
+
+    params = {"limit": limit}
+    if device_type:
+        params["device_type"] = device_type
+
+    try:
+        response = get(cfg, "/api/v1/devices", params=params)
+    except PlyranaAPIError as exc:
+        typer.secho(f"Error: {exc.detail}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=1)
+
+    data = response.json()
+    devices = data if isinstance(data, list) else data.get("items", [])
+
+    if not devices:
+        console.print("[dim]No devices found.[/]")
+        return
+
+    table = Table(title=f"Devices ({len(devices)})")
+    table.add_column("UID", style="cyan", no_wrap=True)
+    table.add_column("Name")
+    table.add_column("Type", style="magenta")
+    table.add_column("Status")
+    table.add_column("Last seen", style="dim")
+
+    for dev in devices[:limit]:
+        table.add_row(
+            dev.get("uid", "-"),
+            dev.get("name") or "-",
+            dev.get("device_type", "-"),
+            "[green]online[/]" if dev.get("online") else "[red]offline[/]",
+            dev.get("last_seen_at") or "-",
+        )
+    console.print(table)
+
+
+@app.command("get")
+def get_device(uid: str = typer.Argument(..., help="Device UID.")) -> None:
+    """Show full details for a device."""
+    cfg = Config.load()
+    require_auth(cfg)
+    try:
+        response = get(cfg, f"/api/v1/devices/{uid}")
+    except PlyranaAPIError as exc:
+        typer.secho(f"Error: {exc.detail}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=1)
+
+    console.print_json(data=response.json())
+
+
+@app.command("claim")
+def claim_device(uid: str = typer.Argument(..., help="Device UID to claim.")) -> None:
+    """Claim an unclaimed device for your organization."""
+    cfg = Config.load()
+    require_auth(cfg)
+    try:
+        response = post(cfg, f"/api/v1/devices/{uid}/claim")
+    except PlyranaAPIError as exc:
+        typer.secho(f"Error: {exc.detail}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=1)
+    console.print(f"[green]Claimed[/] device [bold]{uid}[/]")
+    console.print_json(data=response.json())
+
+
+@app.command("unclaim")
+def unclaim_device(uid: str = typer.Argument(..., help="Device UID to unclaim.")) -> None:
+    """Release a device back to the pool."""
+    cfg = Config.load()
+    require_auth(cfg)
+    if not typer.confirm(f"Really unclaim device {uid}?"):
+        raise typer.Exit(code=0)
+    try:
+        post(cfg, f"/api/v1/devices/{uid}/unclaim")
+    except PlyranaAPIError as exc:
+        typer.secho(f"Error: {exc.detail}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=1)
+    console.print(f"[green]Unclaimed[/] device [bold]{uid}[/]")

plyrana_cli-0.1.0/plyrana_cli/commands/system.py

@@ -0,0 +1,82 @@
+"""System subcommand: health / license / integrations / metrics."""
+
+from __future__ import annotations
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from ..client import PlyranaAPIError, get, require_auth
+from ..config import Config
+
+
+app = typer.Typer()
+console = Console()
+
+
+@app.command("health")
+def health() -> None:
+    """Public backend health check (no auth)."""
+    cfg = Config.load()
+    try:
+        response = get(cfg, "/health")
+    except PlyranaAPIError as exc:
+        typer.secho(f"Error: {exc.detail}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=1)
+    data = response.json()
+    status = data.get("status", "unknown")
+    version = data.get("version", "?")
+    color = "green" if status == "ok" else "red"
+    console.print(f"[{color}]{status.upper()}[/] (version {version}) @ {cfg.base_url}")
+
+
+@app.command("license")
+def license_info() -> None:
+    """Show current license (CE / Pro / Enterprise)."""
+    cfg = Config.load()
+    require_auth(cfg)
+    try:
+        response = get(cfg, "/api/v1/license")
+    except PlyranaAPIError as exc:
+        typer.secho(f"Error: {exc.detail}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=1)
+
+    lic = response.json()
+    table = Table(title="License")
+    table.add_column("Field", style="cyan")
+    table.add_column("Value")
+
+    for key in ("license_id", "issued_to", "edition", "expires_at", "signed", "valid"):
+        table.add_row(key, str(lic.get(key, "-")))
+
+    limits = lic.get("limits", {})
+    for key, value in limits.items():
+        display = "∞" if value == -1 else str(value)
+        table.add_row(f"limits.{key}", display)
+
+    console.print(table)
+
+
+@app.command("integrations")
+def integrations_status() -> None:
+    """Aggregated status of MQTT / HA / Prometheus / Grafana integrations."""
+    cfg = Config.load()
+    require_auth(cfg)
+    try:
+        response = get(cfg, "/api/v1/integrations/status")
+    except PlyranaAPIError as exc:
+        typer.secho(f"Error: {exc.detail}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=1)
+    console.print_json(data=response.json())
+
+
+@app.command("metrics")
+def metrics() -> None:
+    """Fetch raw Prometheus metrics output (text/plain)."""
+    cfg = Config.load()
+    try:
+        response = get(cfg, "/metrics")
+    except PlyranaAPIError as exc:
+        typer.secho(f"Error: {exc.detail}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=1)
+    console.print(response.text)

plyrana_cli-0.1.0/plyrana_cli/commands/variables.py

@@ -0,0 +1,147 @@
+"""Variables subcommand: list / get / set / history."""
+
+from __future__ import annotations
+
+import json as json_lib
+from typing import Any
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from ..client import PlyranaAPIError, get, post, put, require_auth
+from ..config import Config
+
+
+app = typer.Typer()
+console = Console()
+
+
+def _coerce_value(raw: str) -> Any:
+    """Coerce a CLI string to int/float/bool/json/string."""
+    lower = raw.lower()
+    if lower in {"true", "false"}:
+        return lower == "true"
+    try:
+        return int(raw)
+    except ValueError:
+        pass
+    try:
+        return float(raw)
+    except ValueError:
+        pass
+    if raw.startswith(("{", "[")):
+        try:
+            return json_lib.loads(raw)
+        except json_lib.JSONDecodeError:
+            pass
+    return raw
+
+
+@app.command("list")
+def list_variables(
+    device_uid: str | None = typer.Option(None, "--device", "-d", help="Filter by device UID."),
+) -> None:
+    """List variable definitions (optionally per device)."""
+    cfg = Config.load()
+    require_auth(cfg)
+    if device_uid:
+        path = f"/api/v1/variables/device/{device_uid}"
+    else:
+        path = "/api/v1/variables/defs"
+    try:
+        response = get(cfg, path)
+    except PlyranaAPIError as exc:
+        typer.secho(f"Error: {exc.detail}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=1)
+
+    data = response.json()
+    variables = data if isinstance(data, list) else data.get("items", [])
+
+    if not variables:
+        console.print("[dim]No variables found.[/]")
+        return
+
+    table = Table(title=f"Variables ({len(variables)})")
+    table.add_column("Key", style="cyan")
+    table.add_column("Name")
+    table.add_column("Type", style="magenta")
+    table.add_column("Unit", style="dim")
+    for var in variables:
+        table.add_row(
+            str(var.get("key", "-")),
+            var.get("name") or "-",
+            var.get("var_type", "-"),
+            var.get("unit") or "-",
+        )
+    console.print(table)
+
+
+@app.command("get")
+def get_variable(
+    device_uid: str = typer.Argument(..., help="Device UID."),
+    key: str = typer.Argument(..., help="Variable key."),
+) -> None:
+    """Read the current value of a variable."""
+    cfg = Config.load()
+    require_auth(cfg)
+    try:
+        response = get(cfg, f"/api/v1/devices/{device_uid}/variables/{key}")
+    except PlyranaAPIError as exc:
+        typer.secho(f"Error: {exc.detail}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=1)
+    console.print_json(data=response.json())
+
+
+@app.command("set")
+def set_variable(
+    device_uid: str = typer.Argument(..., help="Device UID."),
+    key: str = typer.Argument(..., help="Variable key."),
+    value: str = typer.Argument(..., help="Value (auto-cast bool/int/float/JSON)."),
+) -> None:
+    """Write a new value to a variable."""
+    cfg = Config.load()
+    require_auth(cfg)
+    payload = {"value": _coerce_value(value)}
+    try:
+        response = put(cfg, f"/api/v1/devices/{device_uid}/variables/{key}", json=payload)
+    except PlyranaAPIError as exc:
+        typer.secho(f"Error: {exc.detail}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=1)
+    console.print(f"[green]Set[/] {device_uid}.{key} = [bold]{payload['value']!r}[/]")
+    console.print_json(data=response.json())
+
+
+@app.command("history")
+def history(
+    device_uid: str = typer.Argument(..., help="Device UID."),
+    key: str = typer.Argument(..., help="Variable key."),
+    limit: int = typer.Option(20, "--limit", "-n", help="Max samples."),
+) -> None:
+    """Show recent history for a variable."""
+    cfg = Config.load()
+    require_auth(cfg)
+    try:
+        response = get(
+            cfg,
+            f"/api/v1/devices/{device_uid}/variables/{key}/history",
+            params={"limit": limit},
+        )
+    except PlyranaAPIError as exc:
+        typer.secho(f"Error: {exc.detail}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=1)
+
+    samples = response.json()
+    if not samples:
+        console.print("[dim]No history samples.[/]")
+        return
+
+    table = Table(title=f"{device_uid}.{key} history")
+    table.add_column("Timestamp", style="dim")
+    table.add_column("Value", style="cyan")
+    for sample in samples[:limit]:
+        table.add_row(
+            str(sample.get("timestamp", "-")),
+            str(sample.get("value", "-")),
+        )
+    console.print(table)

plyrana_cli-0.1.0/plyrana_cli/config.py

@@ -0,0 +1,52 @@
+"""Plyrana CLI config: load/save token + base URL from ~/.plyrana/config.json."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+
+DEFAULT_BASE_URL = "http://localhost:8000"
+CONFIG_DIR = Path(os.path.expanduser("~")) / ".plyrana"
+CONFIG_PATH = CONFIG_DIR / "config.json"
+
+
+class Config:
+    def __init__(self, base_url: str = DEFAULT_BASE_URL, token: str | None = None) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.token = token
+
+    @classmethod
+    def load(cls) -> "Config":
+        """Load from file + env-var overrides. Env beats file."""
+        data: dict = {}
+        if CONFIG_PATH.exists():
+            try:
+                data = json.loads(CONFIG_PATH.read_text(encoding="utf-8"))
+            except (OSError, json.JSONDecodeError):
+                data = {}
+
+        base_url = os.environ.get("PLYRANA_URL") or data.get("base_url") or DEFAULT_BASE_URL
+        token = os.environ.get("PLYRANA_TOKEN") or data.get("token")
+        return cls(base_url=base_url, token=token)
+
+    def save(self) -> None:
+        CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+        CONFIG_PATH.write_text(
+            json.dumps({"base_url": self.base_url, "token": self.token}, indent=2),
+            encoding="utf-8",
+        )
+        # Best-effort: restrict to user only (0600). No-op on Windows without admin.
+        try:
+            os.chmod(CONFIG_PATH, 0o600)
+        except OSError:
+            pass
+
+    def clear(self) -> None:
+        if CONFIG_PATH.exists():
+            CONFIG_PATH.unlink()
+
+    @property
+    def is_authenticated(self) -> bool:
+        return bool(self.token)

plyrana_cli-0.1.0/plyrana_cli/main.py

@@ -0,0 +1,48 @@
+"""plyrana CLI entry point — `plyrana <subcommand>`.
+
+Subcommands:
+  auth          login / logout / status
+  devices       list / get / claim / unclaim
+  variables     list / get / set / history
+  automations   list / run / toggle
+  system        health / license / integrations / metrics
+  config        show / set-url / clear
+"""
+
+from __future__ import annotations
+
+import typer
+
+from . import __version__
+from .commands import automations, auth, config_cmd, devices, system, variables
+
+
+app = typer.Typer(
+    name="plyrana",
+    help="Plyrana CLI — manage a Plyrana IoT Device Hub from your terminal.",
+    no_args_is_help=True,
+    add_completion=True,
+)
+
+app.add_typer(auth.app, name="auth", help="Authentication: login / logout / status.")
+app.add_typer(devices.app, name="devices", help="List, inspect, claim and unclaim devices.")
+app.add_typer(variables.app, name="variables", help="Read and write device variables.")
+app.add_typer(automations.app, name="automations", help="List, run, toggle automations.")
+app.add_typer(system.app, name="system", help="Health, license and integration status.")
+app.add_typer(config_cmd.app, name="config", help="CLI configuration (base URL, token).")
+
+
+@app.callback(invoke_without_command=True)
+def root(
+    ctx: typer.Context,
+    version: bool = typer.Option(False, "--version", "-V", help="Print version and exit."),
+) -> None:
+    if version:
+        typer.echo(f"plyrana {__version__}")
+        raise typer.Exit(code=0)
+    if ctx.invoked_subcommand is None:
+        typer.echo(ctx.get_help())
+
+
+if __name__ == "__main__":
+    app()

plyrana_cli-0.1.0/plyrana_cli.egg-info/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: plyrana-cli
+Version: 0.1.0
+Summary: Plyrana CLI — manage any self-hosted Plyrana instance from your terminal. Auth, devices, variables, automations, system.
+Author-email: Plyrana <dev@plyrana.com>
+License: AGPL-3.0
+Project-URL: Homepage, https://github.com/plyrana/core
+Project-URL: Documentation, https://github.com/plyrana/core/tree/main/cli
+Project-URL: Repository, https://github.com/plyrana/core
+Project-URL: Issues, https://github.com/plyrana/core/issues
+Keywords: plyrana,iot,cli,devops,automation
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: GNU Affero General Public License v3
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx<0.29.0,>=0.23.0
+Requires-Dist: typer>=0.9.0
+Requires-Dist: rich>=13.0.0
+
+# plyrana-cli — Terminal client for Plyrana
+
+Thin command-line client for the Plyrana IoT Device Hub REST API. Great for CI/CD, scripting, batch operations.
+
+## Install
+
+```bash
+pip install plyrana-cli
+# dev install from source:
+pip install -e ./cli
+```
+
+## First run
+
+```bash
+# Point to your hub
+plyrana config set-url https://hub.example.com
+
+# Login (password prompt if omitted)
+plyrana auth login --email admin@example.com
+
+# Verify
+plyrana auth status
+```
+
+## Commands
+
+### Auth
+```bash
+plyrana auth login --email <EMAIL>
+plyrana auth logout
+plyrana auth status
+```
+
+### Devices
+```bash
+plyrana devices list [--limit 50] [--type hardware]
+plyrana devices get <UID>
+plyrana devices claim <UID>
+plyrana devices unclaim <UID>
+```
+
+### Variables
+```bash
+plyrana variables list [--device <UID>]
+plyrana variables get <UID> <KEY>
+plyrana variables set <UID> <KEY> <VALUE>        # auto-cast: 22.5 / true / '{"x":1}'
+plyrana variables history <UID> <KEY> [--limit 20]
+```
+
+### Automations
+```bash
+plyrana automations list
+plyrana automations run <ID>
+plyrana automations toggle <ID> --on | --off
+```
+
+### System
+```bash
+plyrana system health         # public, no auth
+plyrana system license        # CE / Pro / Enterprise + limits
+plyrana system integrations   # MQTT / HA / Prometheus / Grafana status
+plyrana system metrics        # Prometheus text-format
+```
+
+### Config
+```bash
+plyrana config show
+plyrana config set-url <URL>
+plyrana config clear
+```
+
+## Auth storage
+
+Tokens are stored in `~/.plyrana/config.json` with `0600` perms (best-effort on Windows).
+
+Override via env:
+- `PLYRANA_URL=https://hub.example.com`
+- `PLYRANA_TOKEN=eyJ...`
+
+Env beats file — great for CI.
+
+## Example: CI smoke-test
+
+```bash
+export PLYRANA_URL=https://hub.example.com
+export PLYRANA_TOKEN=$PLYRANA_CI_TOKEN
+plyrana system health || exit 1
+plyrana devices list --limit 1 || exit 1
+```
+
+## License
+
+AGPL-3.0 — see [LICENSE](../LICENSE) in the main repo.

plyrana_cli-0.1.0/plyrana_cli.egg-info/SOURCES.txt

@@ -0,0 +1,19 @@
+README.md
+pyproject.toml
+plyrana_cli/__init__.py
+plyrana_cli/client.py
+plyrana_cli/config.py
+plyrana_cli/main.py
+plyrana_cli.egg-info/PKG-INFO
+plyrana_cli.egg-info/SOURCES.txt
+plyrana_cli.egg-info/dependency_links.txt
+plyrana_cli.egg-info/entry_points.txt
+plyrana_cli.egg-info/requires.txt
+plyrana_cli.egg-info/top_level.txt
+plyrana_cli/commands/__init__.py
+plyrana_cli/commands/auth.py
+plyrana_cli/commands/automations.py
+plyrana_cli/commands/config_cmd.py
+plyrana_cli/commands/devices.py
+plyrana_cli/commands/system.py
+plyrana_cli/commands/variables.py

plyrana_cli-0.1.0/plyrana_cli.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

plyrana_cli-0.1.0/plyrana_cli.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+plyrana = plyrana_cli.main:app

plyrana_cli-0.1.0/plyrana_cli.egg-info/requires.txt

@@ -0,0 +1,3 @@
+httpx<0.29.0,>=0.23.0
+typer>=0.9.0
+rich>=13.0.0

plyrana_cli-0.1.0/plyrana_cli.egg-info/top_level.txt

@@ -0,0 +1 @@
+plyrana_cli

plyrana_cli-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[project]
+name = "plyrana-cli"
+version = "0.1.0"
+description = "Plyrana CLI — manage any self-hosted Plyrana instance from your terminal. Auth, devices, variables, automations, system."
+readme = "README.md"
+license = { text = "AGPL-3.0" }
+authors = [
+    { name = "Plyrana", email = "dev@plyrana.com" }
+]
+keywords = ["plyrana", "iot", "cli", "devops", "automation"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Intended Audience :: System Administrators",
+    "License :: OSI Approved :: GNU Affero General Public License v3",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: System :: Systems Administration",
+]
+requires-python = ">=3.10"
+dependencies = [
+    "httpx>=0.23.0,<0.29.0",
+    "typer>=0.9.0",
+    "rich>=13.0.0",
+]
+
+[project.scripts]
+plyrana = "plyrana_cli.main:app"
+
+[project.urls]
+Homepage = "https://github.com/plyrana/core"
+Documentation = "https://github.com/plyrana/core/tree/main/cli"
+Repository = "https://github.com/plyrana/core"
+Issues = "https://github.com/plyrana/core/issues"
+
+[tool.setuptools.packages.find]
+include = ["plyrana_cli*"]
+
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"

plyrana_cli-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+