sovaria-cli 0.2.9__tar.gz → 0.3.0__tar.gz

{sovaria_cli-0.2.9 → sovaria_cli-0.3.0}/.gitignore

@@ -8,3 +8,5 @@ dist/
 .env.*
 !.env.example
 !.env.*.example
+
+.venv/

{sovaria_cli-0.2.9 → sovaria_cli-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sovaria-cli
-Version: 0.2.9
+Version: 0.3.0
 Summary: Sovaria BaaS command-line interface (sov)
 Project-URL: Homepage, https://sovaria.in
 Project-URL: Documentation, https://docs.sovaria.in/cli
@@ -12,7 +12,7 @@ Requires-Dist: httpx>=0.28.1
 Requires-Dist: keyring>=25.0
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: rich>=13.7.0
-Requires-Dist: sovaria-sdk==0.4.1
+Requires-Dist: sovaria-sdk==0.5.0
 Requires-Dist: tomli-w>=1.2.0
 Requires-Dist: typer>=0.17.4
 Provides-Extra: dev
@@ -22,13 +22,22 @@ Requires-Dist: pytest>=8.0; extra == 'dev'
 Requires-Dist: ruff>=0.9; extra == 'dev'
 Requires-Dist: twine>=6.0; extra == 'dev'
 Provides-Extra: mcp
-Requires-Dist: sovaria-sdk[mcp]==0.4.1; extra == 'mcp'
+Requires-Dist: sovaria-sdk[mcp]==0.5.0; extra == 'mcp'
 Description-Content-Type: text/markdown
 
 # Sovaria CLI
 
 Operator CLI for gateway-backed Sovaria project and platform workflows.
 
+## Install
+
+```bash
+npm install -g @sovaria/cli   # or: npx @sovaria/cli --help
+pip install sovaria-cli       # same CLI from PyPI
+```
+
+Both need Python 3.11+. The npm package sets up a private environment in `~/.sovaria/npm-cli` on first run.
+
 ## Run
 
 Examples below use `sov ...` command syntax.
@@ -113,6 +122,12 @@ sov realtime ws-url my-channel --org <org_id> --project <project_id>
 - `sov fn ...` Forge function deploy/status/invoke
 - `sov project ...` project config template + scaffold creation
 - `sov api call ...` raw gateway API request
+- `sov branches list|create|get|update|use|delete` environments as branches (`create x --from staging`, `use x`)
+- `sov gen types typescript|python|dart|swift|kotlin -o <file>` row models from the live schema
+- `sov storage cp [-r] <src> <dst>` copy between local paths and `ss://bucket/path` (or between buckets)
+- `sov collections delete <path> [-r]` delete a collection or document (and its subcollections with `-r`)
+- `sov auth-product export users.json|users.csv` every app user (profile fields only)
+- `sov functions new <name> --runtime python|node|typescript|go` a function folder with a starter handler
 
 ## Project Bootstrap (Config JSON)
 

{sovaria_cli-0.2.9 → sovaria_cli-0.3.0}/apps/cli/README.md

@@ -2,6 +2,15 @@
 
 Operator CLI for gateway-backed Sovaria project and platform workflows.
 
+## Install
+
+```bash
+npm install -g @sovaria/cli   # or: npx @sovaria/cli --help
+pip install sovaria-cli       # same CLI from PyPI
+```
+
+Both need Python 3.11+. The npm package sets up a private environment in `~/.sovaria/npm-cli` on first run.
+
 ## Run
 
 Examples below use `sov ...` command syntax.
@@ -86,6 +95,12 @@ sov realtime ws-url my-channel --org <org_id> --project <project_id>
 - `sov fn ...` Forge function deploy/status/invoke
 - `sov project ...` project config template + scaffold creation
 - `sov api call ...` raw gateway API request
+- `sov branches list|create|get|update|use|delete` environments as branches (`create x --from staging`, `use x`)
+- `sov gen types typescript|python|dart|swift|kotlin -o <file>` row models from the live schema
+- `sov storage cp [-r] <src> <dst>` copy between local paths and `ss://bucket/path` (or between buckets)
+- `sov collections delete <path> [-r]` delete a collection or document (and its subcollections with `-r`)
+- `sov auth-product export users.json|users.csv` every app user (profile fields only)
+- `sov functions new <name> --runtime python|node|typescript|go` a function folder with a starter handler
 
 ## Project Bootstrap (Config JSON)
 

{sovaria_cli-0.2.9 → sovaria_cli-0.3.0}/apps/cli/src/__init__.py

@@ -1,3 +1,3 @@
 """Sovaria CLI — sov command."""
 
-__version__ = "0.2.9"
+__version__ = "0.3.0"

sovaria_cli-0.3.0/apps/cli/src/commands/ai_data.py

@@ -0,0 +1,341 @@
+"""AI & data commands (W9), attached to existing groups without editing them:
+
+* ``sov db advisor`` — index advisor (hypothetical indexes), ``apply`` / ``status``;
+* ``sov db insights`` — query insights (pg_stat_statements) and ``reset``;
+* ``sov collections pipeline`` — document pipelines (where / aggregate / sort / limit / select …);
+* ``sov agents versions | publish | rollback | compare`` — agent versions;
+* ``sov gateway`` — the project's model gateway: routes, completions, usage, cache.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from urllib.parse import quote
+
+import typer
+
+from apps.cli.src.utils.api_client import CLIRequestError, call_api
+from apps.cli.src.utils.display import handle_cli_error, print_json
+
+_ORG = typer.Option(None, "--org")
+_PROJECT = typer.Option(None, "--project")
+_ENV = typer.Option(None, "--env")
+_PROFILE = typer.Option(None, "--profile")
+
+
+def _seg(value: str) -> str:
+    return quote(str(value), safe="")
+
+
+def _call(method: str, path: str, *, profile, org_id, project_id, env_id=None, body=None, params=None,
+          timeout: float = 60.0):
+    try:
+        return call_api(method=method, path=path, profile=profile, org_id=org_id, project_id=project_id,
+                        env_id=env_id, require_scope=True, body=body, params=params, timeout=timeout)
+    except CLIRequestError as exc:
+        handle_cli_error(exc)
+        raise typer.Exit(1) from exc
+
+
+def _db_path(profile, org_id, project_id, suffix: str) -> str:
+    from apps.cli.src.utils.project_context import resolve_scope
+
+    org, project, _env = resolve_scope(profile=profile, org_id=org_id, project_id=project_id, env_id=None, require=True)
+    return f"/api/v1/governance/tenants/{_seg(org)}/databases/{_seg(project)}/{suffix}"
+
+
+# ── sov db advisor / insights ──────────────────────────────────────────────────────────────────
+
+advisor_app = typer.Typer(help="Index advisor: indexes that would speed up the slowest queries, tested as "
+                               "hypothetical indexes first", invoke_without_command=True)
+insights_app = typer.Typer(help="Query insights: the project's statements by total time, average, calls…",
+                           invoke_without_command=True)
+
+
+@advisor_app.callback()
+def advisor(
+    ctx: typer.Context,
+    queryid: str | None = typer.Option(None, "--queryid", help="Only this statement (from sov db insights)"),
+    as_json: bool = typer.Option(False, "--json"),
+    profile: str | None = _PROFILE, org_id: str | None = _ORG, project_id: str | None = _PROJECT,
+) -> None:
+    """Recommend indexes for the project's most expensive statements."""
+    if ctx.invoked_subcommand:
+        return
+    out = _call("GET", _db_path(profile, org_id, project_id, "index-advisor"), profile=profile, org_id=org_id,
+                project_id=project_id, params={"queryid": queryid} if queryid else None, timeout=120)
+    if as_json:
+        print_json(out)
+        return
+    _print_recommendations(out)
+
+
+def _print_recommendations(out: dict) -> None:
+    mode = "tested with hypothetical indexes" if out.get("mode") == "hypopg" else "unverified (no hypopg here)"
+    recs = out.get("recommendations") or []
+    typer.echo(f"{len(recs)} recommendation(s), {mode}, {len(out.get('statements') or [])} statement(s) examined.")
+    for w in out.get("warnings") or []:
+        typer.echo(f"! {w}", err=True)
+    for r in recs:
+        best = max((s.get("gain_pct") or 0 for s in r.get("statements") or []), default=0)
+        typer.echo(f"\n  {r['schema']}.{r['table']} ({', '.join(r['columns'])})"
+                   + (f" — plan cost −{best}%" if best else "") + f", {r.get('table_rows', 0):,} rows")
+        typer.echo(f"    {r['sql']}")
+        for s in (r.get("statements") or [])[:3]:
+            typer.echo(f"    · {s['query'][:110]}")
+    if recs and (out.get("limits") or {}).get("apply"):
+        r = recs[0]
+        typer.echo(f"\nApply: sov db advisor apply --table {r['schema']}.{r['table']} --columns {','.join(r['columns'])}")
+
+
+@advisor_app.command("query")
+def advisor_query(
+    sql: str = typer.Argument(..., help="One SELECT / WITH / UPDATE / DELETE (only EXPLAINed, never run)"),
+    as_json: bool = typer.Option(False, "--json"),
+    profile: str | None = _PROFILE, org_id: str | None = _ORG, project_id: str | None = _PROJECT,
+) -> None:
+    """Recommend indexes for one statement."""
+    out = _call("POST", _db_path(profile, org_id, project_id, "index-advisor/query"), profile=profile, org_id=org_id,
+                project_id=project_id, body={"query": sql})
+    print_json(out) if as_json else _print_recommendations(out)
+
+
+@advisor_app.command("apply")
+def advisor_apply(
+    table: str = typer.Option(..., "--table", help="schema.table (public. may be left out)"),
+    columns: str = typer.Option(..., "--columns", help="Comma list, in index order (1-3)"),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Don't ask for confirmation"),
+    profile: str | None = _PROFILE, org_id: str | None = _ORG, project_id: str | None = _PROJECT,
+) -> None:
+    """Build a recommended index with CREATE INDEX CONCURRENTLY (no write lock); follow it with `status`."""
+    schema, _, name = table.rpartition(".")
+    cols = [c.strip() for c in columns.split(",") if c.strip()]
+    if not yes and not typer.confirm(f"Create an index on {schema or 'public'}.{name} ({', '.join(cols)})?"):
+        raise typer.Exit(1)
+    out = _call("POST", _db_path(profile, org_id, project_id, "index-advisor/apply"), profile=profile, org_id=org_id,
+                project_id=project_id, body={"schema": schema or "public", "table": name, "columns": cols})
+    typer.echo(f"{out['index_name']}: {out['status']}  (sov db advisor status {out['index_name']})")
+
+
+@advisor_app.command("status")
+def advisor_status(
+    index_name: str = typer.Argument(...),
+    profile: str | None = _PROFILE, org_id: str | None = _ORG, project_id: str | None = _PROJECT,
+) -> None:
+    """Whether an index the advisor started is building, ready, failed or invalid."""
+    print_json(_call("GET", _db_path(profile, org_id, project_id, f"index-advisor/indexes/{_seg(index_name)}"),
+                     profile=profile, org_id=org_id, project_id=project_id))
+
+
+@insights_app.callback()
+def insights(
+    ctx: typer.Context,
+    sort: str = typer.Option("total", "--sort", help="total, mean, calls, max or rows"),
+    limit: int = typer.Option(20, "--limit", min=1, max=1000),
+    as_json: bool = typer.Option(False, "--json"),
+    profile: str | None = _PROFILE, org_id: str | None = _ORG, project_id: str | None = _PROJECT,
+) -> None:
+    """The project's statements from pg_stat_statements (plan caps the rows: db.query_insights_rows)."""
+    if ctx.invoked_subcommand:
+        return
+    out = _call("GET", _db_path(profile, org_id, project_id, "query-insights"), profile=profile, org_id=org_id,
+                project_id=project_id, params={"sort": sort, "limit": str(limit)})
+    if as_json or not out.get("enabled"):
+        print_json(out)
+        return
+    typer.echo(f"{'calls':>9} {'total ms':>11} {'mean ms':>9} {'max ms':>9} {'hit %':>6}  query")
+    for s in out.get("statements") or []:
+        hit = "" if s.get("cache_hit_pct") is None else f"{s['cache_hit_pct']:.0f}"
+        flag = "*" if s.get("slow") else " "
+        typer.echo(f"{s['calls']:>9,} {s['total_ms']:>11,.1f} {s['mean_ms']:>9.1f} {s['max_ms']:>9.1f} {hit:>6} {flag}"
+                   f"{' '.join(s['query'].split())[:90]}  [{s['queryid']}]")
+    typer.echo(f"* slower than {out.get('slow_ms')} ms on average · since {out.get('since') or 'the last reset'}")
+
+
+@insights_app.command("reset")
+def insights_reset(
+    yes: bool = typer.Option(False, "--yes", "-y"),
+    profile: str | None = _PROFILE, org_id: str | None = _ORG, project_id: str | None = _PROJECT,
+) -> None:
+    """Clear this database's query statistics."""
+    if not yes and not typer.confirm("Clear the query statistics of this project's database?"):
+        raise typer.Exit(1)
+    print_json(_call("POST", _db_path(profile, org_id, project_id, "query-insights/reset"), profile=profile,
+                     org_id=org_id, project_id=project_id, body={}))
+
+
+# ── sov collections pipeline ───────────────────────────────────────────────────────────────────
+
+
+def pipeline(
+    collection: str = typer.Argument(..., help="Collection path, or the group id with --group"),
+    stages_file: Path | None = typer.Option(None, "--file", "-f", help="JSON file: a list of stages or {\"stages\": [...]}"),
+    stages: str | None = typer.Option(None, "--stages", help="Stages as inline JSON"),
+    group: bool = typer.Option(False, "--group", help="Run over the collection group (every collection with this id)"),
+    profile: str | None = _PROFILE, org_id: str | None = _ORG, project_id: str | None = _PROJECT,
+    env_id: str | None = _ENV,
+) -> None:
+    """Run a document pipeline: where, aggregate, distinct, sort, offset, limit, select, remove_fields, sample.
+
+    Example: sov collections pipeline orders --stages '[{"where": ["status","==","paid"]},
+    {"aggregate": {"accumulators": [{"op": "sum", "field": "amount", "alias": "total"}], "groups": ["country"]}},
+    {"sort": [["total","desc"]]}, {"limit": 5}]'"""
+    raw = stages_file.read_text(encoding="utf-8") if stages_file else stages
+    if not raw:
+        raise typer.BadParameter("Give the stages with --file or --stages")
+    try:
+        parsed = json.loads(raw)
+    except ValueError as exc:
+        raise typer.BadParameter(f"Stages aren't valid JSON: {exc}") from exc
+    body = parsed if isinstance(parsed, dict) else {"stages": parsed}
+    if group:
+        body["collection_group"] = True
+    print_json(_call("POST", f"/api/v1/data/doc/_pipeline/{quote(collection, safe='/')}", profile=profile,
+                     org_id=org_id, project_id=project_id, env_id=env_id, body=body))
+
+
+# ── sov agents versions / publish / rollback / compare ─────────────────────────────────────────
+
+
+def agent_versions(agent_id: str = typer.Argument(...), profile: str | None = _PROFILE, org_id: str | None = _ORG,
+                   project_id: str | None = _PROJECT) -> None:
+    """An agent's published version and its kept versions."""
+    print_json(_call("GET", f"/api/v1/sovariq/agents/{_seg(agent_id)}/versions", profile=profile, org_id=org_id,
+                     project_id=project_id))
+
+
+def agent_publish(agent_id: str = typer.Argument(...), note: str = typer.Option("", "--note", "-m"),
+                  profile: str | None = _PROFILE, org_id: str | None = _ORG, project_id: str | None = _PROJECT) -> None:
+    """Publish the agent's current definition; app users run it from now on."""
+    out = _call("POST", f"/api/v1/sovariq/agents/{_seg(agent_id)}/versions", profile=profile, org_id=org_id,
+                project_id=project_id, body={"note": note})
+    typer.echo(f"Published version {out['version']}")
+
+
+def agent_rollback(agent_id: str = typer.Argument(...), version: int = typer.Argument(...),
+                   note: str = typer.Option("", "--note", "-m"), yes: bool = typer.Option(False, "--yes", "-y"),
+                   profile: str | None = _PROFILE, org_id: str | None = _ORG, project_id: str | None = _PROJECT) -> None:
+    """Make an older version current again (it is published as a new version)."""
+    if not yes and not typer.confirm(f"Roll agent {agent_id} back to version {version}? It replaces the draft too."):
+        raise typer.Exit(1)
+    out = _call("POST", f"/api/v1/sovariq/agents/{_seg(agent_id)}/versions/{version}/rollback", profile=profile,
+                org_id=org_id, project_id=project_id, body={"note": note})
+    typer.echo(f"Rolled back to version {out['rolled_back_to']} (published as version {out['version']})")
+
+
+def agent_compare(agent_id: str = typer.Argument(...), a: str = typer.Argument(..., help="Version number"),
+                  b: str = typer.Argument("draft", help="Version number or 'draft'"),
+                  profile: str | None = _PROFILE, org_id: str | None = _ORG, project_id: str | None = _PROJECT) -> None:
+    """What changed between two versions (or a version and the draft)."""
+    out = _call("GET", f"/api/v1/sovariq/agents/{_seg(agent_id)}/versions/compare", profile=profile, org_id=org_id,
+                project_id=project_id, params={"a": a, "b": b})
+    typer.echo(f"Changed: {', '.join(out.get('changed_fields') or []) or 'nothing'}")
+    for key in ("custom_tools", "tools", "knowledge_bases", "playbooks", "mcp_servers"):
+        if key in out:
+            typer.echo(f"  {key}: +{out[key]['added']} −{out[key]['removed']}")
+    if out.get("model"):
+        typer.echo(f"  model: {out['model']['before']} → {out['model']['after']}")
+    for line in out.get("instructions_diff") or []:
+        typer.echo(f"  {line}")
+
+
+# ── sov gateway ────────────────────────────────────────────────────────────────────────────────
+
+gateway_app = typer.Typer(help="Model gateway: routes over your own model keys, with fallbacks, a cache and usage per model")
+
+
+@gateway_app.command("routes")
+def gateway_routes(profile: str | None = _PROFILE, org_id: str | None = _ORG, project_id: str | None = _PROJECT) -> None:
+    """Routes, the models they may use and the plan's limits."""
+    print_json(_call("GET", "/api/v1/sovariq/gateway", profile=profile, org_id=org_id, project_id=project_id))
+
+
+@gateway_app.command("set")
+def gateway_set(
+    name: str = typer.Argument(...),
+    models: str = typer.Option(..., "--models", help="provider/model, first one answers, the rest are fallbacks"),
+    cache_ttl: int = typer.Option(0, "--cache-ttl", help="Cache identical requests this many seconds (0 = off)"),
+    retry_on: str | None = typer.Option(None, "--retry-on", help="Comma list: rate_limit, server_error, timeout, auth"),
+    app_users: bool = typer.Option(False, "--app-users", help="Let the app's signed-in users call this route"),
+    daily_per_user: int = typer.Option(200, "--daily-per-user", help="Requests one app user may make a day"),
+    max_output_tokens: int | None = typer.Option(None, "--max-output-tokens"),
+    profile: str | None = _PROFILE, org_id: str | None = _ORG, project_id: str | None = _PROJECT,
+) -> None:
+    """Create or change a route."""
+    body: dict = {"models": [m.strip() for m in models.split(",") if m.strip()],
+                  "cache": {"enabled": cache_ttl > 0, "ttl_s": cache_ttl},
+                  "access": "app_users" if app_users else "members", "daily_requests_per_user": daily_per_user,
+                  "max_output_tokens": max_output_tokens}
+    if retry_on:
+        body["retry_on"] = [r.strip() for r in retry_on.split(",") if r.strip()]
+    print_json(_call("PUT", f"/api/v1/sovariq/gateway/routes/{_seg(name)}", profile=profile, org_id=org_id,
+                     project_id=project_id, body=body))
+
+
+@gateway_app.command("delete")
+def gateway_delete(name: str = typer.Argument(...), yes: bool = typer.Option(False, "--yes", "-y"),
+                   profile: str | None = _PROFILE, org_id: str | None = _ORG, project_id: str | None = _PROJECT) -> None:
+    if not yes and not typer.confirm(f"Delete route {name}?"):
+        raise typer.Exit(1)
+    print_json(_call("DELETE", f"/api/v1/sovariq/gateway/routes/{_seg(name)}", profile=profile, org_id=org_id,
+                     project_id=project_id))
+
+
+@gateway_app.command("complete")
+def gateway_complete(
+    route: str = typer.Argument(...),
+    prompt: str = typer.Argument(..., help="The user message"),
+    system: str = typer.Option("", "--system"),
+    max_tokens: int = typer.Option(1024, "--max-tokens"),
+    no_cache: bool = typer.Option(False, "--no-cache"),
+    as_json: bool = typer.Option(False, "--json"),
+    profile: str | None = _PROFILE, org_id: str | None = _ORG, project_id: str | None = _PROJECT,
+) -> None:
+    """One completion on a route (shows which model answered and whether it came from the cache)."""
+    out = _call("POST", f"/api/v1/sovariq/gateway/{_seg(route)}/complete", profile=profile, org_id=org_id,
+                project_id=project_id, timeout=180,
+                body={"system": system, "messages": [{"role": "user", "content": prompt}], "max_tokens": max_tokens,
+                      "cache": not no_cache})
+    if as_json:
+        print_json(out)
+        return
+    typer.echo(out.get("text") or "")
+    tried = " → ".join(f"{a['model']}{'' if a['ok'] else ' (' + str(a.get('error')) + ')'}" for a in out.get("attempts") or [])
+    typer.echo(f"\n[{out.get('model')}{', cached' if out.get('cached') else ''}{'; ' + tried if tried else ''}]", err=True)
+
+
+@gateway_app.command("usage")
+def gateway_usage(days: int = typer.Option(7, "--days", min=1, max=90), as_json: bool = typer.Option(False, "--json"),
+                  profile: str | None = _PROFILE, org_id: str | None = _ORG, project_id: str | None = _PROJECT) -> None:
+    """Requests, errors, fallbacks, cache hits, tokens and latency per model."""
+    out = _call("GET", "/api/v1/sovariq/gateway/usage", profile=profile, org_id=org_id, project_id=project_id,
+                params={"days": str(days)})
+    if as_json:
+        print_json(out)
+        return
+    typer.echo(f"{'model':<40} {'requests':>9} {'errors':>7} {'fallbacks':>9} {'cached':>7} {'tokens in/out':>16} {'avg ms':>7}")
+    for model, m in sorted((out.get("models") or {}).items()):
+        typer.echo(f"{model:<40} {m['requests']:>9,} {m['errors']:>7,} {m['fallbacks']:>9,} {m['cache_hits']:>7,} "
+                   f"{m['input_tokens']:>8,}/{m['output_tokens']:<7,} {m['avg_latency_ms']:>7,}")
+
+
+@gateway_app.command("cache-clear")
+def gateway_cache_clear(profile: str | None = _PROFILE, org_id: str | None = _ORG, project_id: str | None = _PROJECT) -> None:
+    print_json(_call("POST", "/api/v1/sovariq/gateway/cache/clear", profile=profile, org_id=org_id, project_id=project_id))
+
+
+def register(main_app: typer.Typer) -> None:
+    """Attach the commands to their groups (called once from main)."""
+    from apps.cli.src.commands import collections as collections_mod
+    from apps.cli.src.commands import db as db_mod
+    from apps.cli.src.commands import knowledge as knowledge_mod
+
+    db_mod.app.add_typer(advisor_app, name="advisor")
+    db_mod.app.add_typer(insights_app, name="insights")
+    collections_mod.app.command("pipeline")(pipeline)
+    knowledge_mod.agents_app.command("versions")(agent_versions)
+    knowledge_mod.agents_app.command("publish")(agent_publish)
+    knowledge_mod.agents_app.command("rollback")(agent_rollback)
+    knowledge_mod.agents_app.command("compare")(agent_compare)
+    main_app.add_typer(gateway_app, name="gateway", help="Model gateway: routes, fallbacks, cache, usage per model")

sovaria_cli-0.3.0/apps/cli/src/commands/alerts.py

@@ -0,0 +1,142 @@
+"""`sov alerts`: SLO alerts — email the team or a signed webhook when latency, 5xx rate, function failures or
+database connections cross a threshold (Observability › Alerts).
+
+    sov alerts list
+    sov alerts create --metric latency_p95_ms --threshold 800 [--window 15] [--target "GET /rest/v1/orders"]
+                      [--no-email] [--webhook https://hooks.example.com/sovaria]
+    sov alerts pause|resume <rule-id>
+    sov alerts test <rule-id>
+    sov alerts delete <rule-id>
+    sov alerts events [--limit 50]
+"""
+
+from __future__ import annotations
+
+from urllib.parse import quote
+
+import typer
+
+from apps.cli.src.utils.api_client import CLIRequestError, call_api
+from apps.cli.src.utils.display import handle_cli_error, print_json, print_success
+from apps.cli.src.utils.output_mode import wants_json
+
+app = typer.Typer(help="SLO alerts: latency, 5xx rate, function failures, DB connections → email / signed webhook")
+
+METRICS = ("latency_p95_ms", "latency_p99_ms", "error_rate", "function_failures", "db_connections")
+BASE = "/api/v1/observability/alerts"
+
+
+def _opts(profile, org_id, project_id, env_id) -> dict:
+    return {"profile": profile, "org_id": org_id, "project_id": project_id, "env_id": env_id, "require_scope": True}
+
+
+def _call(method: str, path: str, opts: dict, **kw) -> dict:
+    try:
+        out = call_api(method=method, path=path, **opts, **kw)
+    except CLIRequestError as exc:
+        handle_cli_error(exc)
+        raise typer.Exit(1) from exc
+    return out if isinstance(out, dict) else {}
+
+
+def _rid(rule_id: str) -> str:
+    return f"{BASE}/{quote(rule_id.strip(), safe='')}"
+
+
+Profile = typer.Option(None, "--profile")
+Org = typer.Option(None, "--org")
+Project = typer.Option(None, "--project")
+Env = typer.Option(None, "--env")
+
+
+@app.command("list")
+def alerts_list(profile: str | None = Profile, org_id: str | None = Org, project_id: str | None = Project, env_id: str | None = Env) -> None:
+    """Alert rules with their state (ok, firing, no_data, paused) and the plan limit."""
+    data = _call("GET", BASE, _opts(profile, org_id, project_id, env_id))
+    if wants_json():
+        print_json(data)
+        return
+    rows = [{"id": r.get("id"), "name": r.get("name"), "metric": r.get("metric"),
+             "over": f"{r.get('threshold')} {r.get('unit') or ''}".strip(), "window": f"{r.get('window_minutes')} min",
+             "target": r.get("target") or "project", "state": r.get("state") if r.get("enabled") else "paused",
+             "value": r.get("value"), "to": "+".join(x for x in ("email" if r.get("email") else "", "webhook" if r.get("webhook_url") else "") if x)}
+            for r in data.get("rules", [])]
+    print_json(rows, title=f"Alert rules ({data.get('used', 0)} of {data.get('limit', 0)})")
+
+
+@app.command("create")
+def alerts_create(
+    metric: str = typer.Option(..., "--metric", help=", ".join(METRICS)),
+    threshold: float = typer.Option(..., "--threshold", help="ms for latency, percent for error_rate, a count otherwise"),
+    window: int = typer.Option(15, "--window", help="Minutes: 5, 10, 15, 30 or 60 (route alerts: 15+)"),
+    target: str | None = typer.Option(None, "--target", help="Route ('GET /rest/v1/orders') or function name; default: whole project"),
+    envs: str | None = typer.Option(None, "--envs", help="Route alerts: environment ids, comma-separated (default: all)"),
+    name: str | None = typer.Option(None, "--name"),
+    email: bool = typer.Option(True, "--email/--no-email", help="Email the project team"),
+    webhook: str | None = typer.Option(None, "--webhook", help="HTTPS URL that receives a signed POST"),
+    min_requests: int = typer.Option(20, "--min-requests", min=1, help="Request alerts: ignore windows with fewer requests"),
+    profile: str | None = Profile, org_id: str | None = Org, project_id: str | None = Project, env_id: str | None = Env,
+) -> None:
+    """Create an alert rule. A webhook's signing secret is printed once: store it to verify X-Sovaria-Signature."""
+    if metric not in METRICS:
+        raise typer.BadParameter(f"--metric must be one of {', '.join(METRICS)}")
+    body: dict = {"metric": metric, "threshold": threshold, "window_minutes": window, "email": email, "min_requests": min_requests}
+    for key, value in (("target", target), ("env", envs), ("name", name), ("webhook_url", webhook)):
+        if value:
+            body[key] = value
+    data = _call("POST", BASE, _opts(profile, org_id, project_id, env_id), body=body)
+    if data.get("signing_secret"):
+        typer.echo(f"Signing secret (shown once): {data['signing_secret']}")
+    print_json({k: v for k, v in data.items() if k != "signing_secret"}, title="Alert rule created")
+
+
+def _toggle(rule_id: str, enabled: bool, opts: dict) -> None:
+    data = _call("PATCH", _rid(rule_id), opts, body={"enabled": enabled})
+    print_success(f"{data.get('name') or rule_id}: {'resumed' if enabled else 'paused'}")
+
+
+@app.command("pause")
+def alerts_pause(rule_id: str, profile: str | None = Profile, org_id: str | None = Org, project_id: str | None = Project, env_id: str | None = Env) -> None:
+    """Stop checking and notifying for a rule."""
+    _toggle(rule_id, False, _opts(profile, org_id, project_id, env_id))
+
+
+@app.command("resume")
+def alerts_resume(rule_id: str, profile: str | None = Profile, org_id: str | None = Org, project_id: str | None = Project, env_id: str | None = Env) -> None:
+    """Check and notify again."""
+    _toggle(rule_id, True, _opts(profile, org_id, project_id, env_id))
+
+
+@app.command("test")
+def alerts_test(rule_id: str, profile: str | None = Profile, org_id: str | None = Org, project_id: str | None = Project, env_id: str | None = Env) -> None:
+    """Measure the rule now and send a test to its webhook (no email)."""
+    data = _call("POST", f"{_rid(rule_id)}/test", _opts(profile, org_id, project_id, env_id))
+    value = data.get("value")
+    typer.echo(f"Now: {'no data' if value is None else value} — {'would fire' if data.get('would_fire') else 'would not fire'}"
+               + (f" ({data['note']})" if data.get("note") else ""))
+    hook = data.get("webhook")
+    if hook:
+        typer.echo("Webhook: delivered" if hook.get("ok") else f"Webhook failed: {hook.get('error')}")
+
+
+@app.command("delete")
+def alerts_delete(
+    rule_id: str,
+    yes: bool = typer.Option(False, "--yes", "-y", help="Don't ask"),
+    profile: str | None = Profile, org_id: str | None = Org, project_id: str | None = Project, env_id: str | None = Env,
+) -> None:
+    """Delete an alert rule."""
+    if not yes and not typer.confirm(f"Delete alert rule {rule_id}?"):
+        raise typer.Exit(1)
+    _call("DELETE", _rid(rule_id), _opts(profile, org_id, project_id, env_id))
+    print_success(f"Deleted {rule_id}")
+
+
+@app.command("events")
+def alerts_events(
+    limit: int = typer.Option(50, "--limit", min=1, max=200),
+    profile: str | None = Profile, org_id: str | None = Org, project_id: str | None = Project, env_id: str | None = Env,
+) -> None:
+    """Fired and resolved alerts, newest first."""
+    data = _call("GET", f"{BASE}/events", _opts(profile, org_id, project_id, env_id), params={"limit": str(limit)})
+    print_json(data.get("events", []), title="Alert events")

{sovaria_cli-0.2.9 → sovaria_cli-0.3.0}/apps/cli/src/commands/api.py

@@ -13,7 +13,7 @@ app = typer.Typer(help="Raw gateway API calls")
 @app.command("call")
 def call_command(
     method: str = typer.Argument(..., help="HTTP method, e.g. GET/POST"),
-    path: str = typer.Argument(..., help="Gateway path, e.g. /api/v1/system/engines/health"),
+    path: str = typer.Argument(..., help="Gateway path, e.g. /api/v1/auth/me"),
     body: str | None = typer.Option(None, "--body", help="JSON request body"),
     query: str | None = typer.Option(None, "--query", help="JSON object query params"),
     profile: str | None = typer.Option(None, "--profile"),
@@ -30,12 +30,19 @@ def call_command(
         if parsed_query is not None and not isinstance(parsed_query, dict):
             raise CLIRequestError("--query must be a JSON object")
 
+        # A query string written in the path (`/x?limit=4`) is kept: the HTTP client would
+        # otherwise replace it with --query's params.
+        from urllib.parse import parse_qsl
+
+        bare_path, _, inline = path.partition("?")
+        params = dict(parse_qsl(inline, keep_blank_values=True))
+        params.update({str(k): str(v) for k, v in (parsed_query or {}).items()})
         result = call_api(
             method=method,
-            path=path,
+            path=bare_path,
             profile=profile,
             body=parsed_body,
-            params={str(k): str(v) for k, v in (parsed_query or {}).items()},
+            params=params,
             require_auth=not no_auth,
             require_scope=require_scope,
             org_id=org_id,

{sovaria_cli-0.2.9 → sovaria_cli-0.3.0}/apps/cli/src/commands/audit.py

@@ -122,20 +122,16 @@ def sim_run(
     if parsed_context is not None and not isinstance(parsed_context, dict):
         raise CLIRequestError("--context must be a JSON object")
 
-    premium_api(
-        f"Running simulation '{simulation_name}'…",
-        success="Completed",
+    # The name/operations are accepted for older scripts; the run covers the whole project
+    # (started in the background and polled — a full run outlasts one request).
+    from apps.cli.src.commands.sim import run_simulation_api
+    from apps.cli.src.utils.display import print_json
+    from apps.cli.src.utils.premium_display import run_with_spinner
+
+    print_json(
+        run_with_spinner(f"Running simulation '{simulation_name}'…", lambda: run_simulation_api(profile=profile),
+                         success="Completed"),
         title="Simulation",
-        method="POST",
-        path="/api/v1/sim/run",
-        profile=profile,
-        body={
-            "simulation_name": simulation_name,
-            "operations": parsed_ops,
-            "echo_flag": True,
-            "include_execution_tree": include_execution_tree,
-            "context": parsed_context or {},
-        },
     )