leancpms-cli 0.1.0__py3-none-any.whl

cpms/cli/main.py

@@ -0,0 +1,982 @@
+"""`cpms`: the operator's command line, a thin client of the JSON API (architecture §3, appendix).
+
+Rules: `--json` on every command, tables by default; exit 0 (ok), 1 (the
+action failed), 2 (usage); never a prompt without a TTY. `cpms` alone prints
+the live state.
+"""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import json
+import os
+import sys
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Callable
+from zoneinfo import ZoneInfo
+
+from cpms.manifest.documents import ManifestError, diff, json_schema, parse_yaml, to_data, to_yaml
+
+from . import login
+from .client import Api, ApiError, UsageError, config_path, load_config
+
+Out = Callable[[str], None]
+
+
+def _print(s: str = "") -> None:
+    sys.stdout.write(s + "\n")
+
+
+def _err(s: str) -> None:
+    sys.stderr.write(s + "\n")
+
+
+def _dump(data: Any) -> None:
+    _print(json.dumps(data, indent=2, ensure_ascii=False))
+
+
+def table(rows: list[list[Any]], header: list[str], right: int | None = None) -> None:
+    """A plain text table. Columns from index `right` on are right-aligned (numbers)."""
+    cells = [[("" if v is None else str(v)) for v in r] for r in rows]
+    widths = [max(len(h), *(len(r[i]) for r in cells)) if cells else len(h) for i, h in enumerate(header)]
+
+    def line(vs: list[str]) -> str:
+        return "  ".join(v.rjust(w) if right is not None and i >= right else v.ljust(w)
+                         for i, (v, w) in enumerate(zip(vs, widths))).rstrip()
+
+    _print(line(header))
+    for r in cells:
+        _print(line(r))
+
+
+def _hm(ts: str | None) -> str:
+    """An ISO time as 'YYYY-MM-DD HH:MM:SS' (UTC, as stored)."""
+    return ts[:19].replace("T", " ") if ts else ""
+
+
+def _amps(c: dict[str, Any]) -> str:
+    return " ".join(f"{p} {float(c.get(p) or 0):.1f}" for p in ("L1", "L2", "L3"))
+
+
+def _money(amount: str | None, currency: str) -> str:
+    return f"{amount} {currency}" if amount is not None else ""
+
+
+# --- live state ---------------------------------------------------------------------
+
+
+def cmd_status(api: Api, a: argparse.Namespace) -> int:
+    body = api.get("/status", organization=getattr(a, "org", None), site=getattr(a, "site", None))
+    if a.json:
+        _dump(body)
+        return 0
+    if not body["sites"]:
+        _print("no sites")
+    for site in body["sites"]:
+        _print(f"{site['organization']}/{site['key']}  {site['name']}  station A: {_amps(site['station_current'])}")
+        for fg in site["fuse_groups"]:
+            _print(f"  fuse group {fg['key']}: budget {fg['budget_amps']} A of {fg['physical_fuse_amps']} A, "
+                   f"{fg['active_sessions']} active, station A: {_amps(fg['station_current'])}")
+            rows = []
+            for cp in fg["charge_points"]:
+                for o in cp["outlets"]:
+                    s = o["session"]
+                    rows.append([
+                        cp["key"], cp["ocpp_id"], "up" if cp["connected"] else "down", o["key"],
+                        o["status"] or "-", s["transaction_id"] if s else "", s["wh"] if s else "",
+                        _money(s["amount_incl_vat"], s["currency"]) if s else "",
+                        _amps(o["station_current"]), (o["issued_limit"] or {}).get("amps", ""), o["verdict"],
+                        _hm(cp["last_event_at"]),
+                    ])
+            if rows:
+                _print()
+                table(rows, ["CP", "OCPP ID", "LINK", "OUTLET", "STATUS", "TX", "WH", "INCL VAT", "STATION A",
+                             "LIMIT", "VERDICT", "LAST EVENT"])
+                _print()
+    if body.get("unclaimed"):
+        _print(f"{body['unclaimed']} unclaimed charge point(s): cpms chargepoints --unclaimed")
+    return 0
+
+
+def _key_column(r: dict[str, Any]) -> str:
+    """The box's key as an operator needs it: blank for `auth: none`, otherwise its state, and a refusal."""
+    live = r["live"] or {}
+    if r["auth"] != "basic" and not live.get("auth_key"):
+        return ""
+    state = live.get("auth_key") or "none"
+    return f"{state} (refused: {live['refused']})" if live.get("refused") else state
+
+
+def cmd_chargepoints(api: Api, a: argparse.Namespace) -> int:
+    if a.verb == "rekey":
+        if not a.key:
+            raise UsageError("rekey needs a charge point key: cpms chargepoints rekey <key>")
+        r = api.call("POST", f"/chargepoints/{a.key}/rekey", params={"organization": a.org}, json={})
+        if a.json:
+            _dump(r)
+        elif r["rotated"]:
+            _print(f"{a.key}: the box answered {r['gateway']['box_status']}; it reconnects with the new key")
+        else:
+            _print(f"{a.key} is not connected: key requirement cleared; it gets a new key when it is back")
+        return 0
+    body = api.get("/chargepoints", organization=a.org, unclaimed="true" if a.unclaimed else None)
+    if a.json:
+        _dump(body)
+        return 0
+    rows = body["chargepoints"]
+    if a.unclaimed:
+        table([[r["ocpp_id"], "up" if r["connected"] else "down", r["remote_address"], _hm(r["first_seen_at"]),
+                _hm(r["last_event_at"]), r["boot"].get("vendor"), r["boot"].get("model"), r["sessions"],
+                r["refused"]] for r in rows],
+              ["OCPP ID", "LINK", "ADDRESS", "FIRST SEEN", "LAST EVENT", "VENDOR", "MODEL", "SESSIONS", "REFUSED"])
+        return 0
+    table([[r["organization"], r["site"], r["fuse_group"], r["key"], r["ocpp_id"],
+            ("up" if r["live"]["connected"] else "down") if r["live"] else "never seen",
+            r["live"]["status"] if r["live"] else "", _hm(r["live"]["last_event_at"]) if r["live"] else "",
+            (r["live"]["boot"].get("model") or "") if r["live"] else "",
+            r["push"]["status"] if r["push"] else "", ",".join(r["phase_rotation"]),
+            _key_column(r)] for r in rows],
+          ["ORG", "SITE", "FUSE", "CP", "OCPP ID", "LINK", "STATUS", "LAST EVENT", "MODEL", "PUSH", "ROTATION", "KEY"])
+    return 0
+
+
+# --- sessions ------------------------------------------------------------------------
+
+
+SESSION_CSV = ["ocpp_id", "transaction_id", "organization", "site", "charge_point", "outlet", "connector", "status",
+               "started_at", "ended_at", "end_reason", "end_inferred", "learned", "wh", "plan", "tariff",
+               "price_per_kwh", "price_amounts", "vat_rate", "amount_incl_vat", "amount_excl_vat", "currency"]
+
+
+def cmd_sessions(api: Api, a: argparse.Namespace) -> int:
+    body = api.get("/sessions", organization=a.org, site=a.site, since=a.since, status=a.status, limit=a.limit)
+    if a.json:
+        _dump(body)
+        return 0
+    rows = body["sessions"]
+    if a.csv:
+        w = csv.DictWriter(sys.stdout, fieldnames=SESSION_CSV, extrasaction="ignore", lineterminator="\n")
+        w.writeheader()
+        w.writerows(rows)
+        return 0
+    table([[f"{s['ocpp_id']}/{s['transaction_id']}", s["organization"] or "(unclaimed)", s["site"], s["outlet"],
+            s["status"], _hm(s["started_at"]), _hm(s["ended_at"]), s["wh"],
+            _money(s["amount_incl_vat"], s["currency"]), s["end_reason"]] for s in rows],
+          ["SESSION", "ORG", "SITE", "OUTLET", "STATUS", "STARTED (UTC)", "ENDED (UTC)", "WH", "INCL VAT", "END"])
+    return 0
+
+
+def _ref(ref: str) -> tuple[str, int]:
+    ocpp_id, _, tx = ref.rpartition("/")
+    if not ocpp_id or not tx.isdigit():
+        raise UsageError(f"a session is <ocpp_id>/<transaction_id>, not {ref!r}")
+    return ocpp_id, int(tx)
+
+
+def _event_rows(events: list[dict[str, Any]]) -> None:
+    def summary(e: dict[str, Any]) -> str:
+        d = {k: v for k, v in (e.get("data") or {}).items() if k not in ("raw", "capabilities", "voltage") and v is not None}
+        return json.dumps(d, ensure_ascii=False)[:100]
+
+    table([[e["seq"], _hm(e["ts"]), e["chargepoint_id"], e["connector_id"], e["transaction_id"], e["event"],
+            summary(e)] for e in events], ["SEQ", "TS (UTC)", "CHARGE POINT", "C", "TX", "EVENT", "DATA"])
+
+
+def cmd_session(api: Api, a: argparse.Namespace) -> int:
+    ocpp_id, tx = _ref(a.ref)
+    base = f"/sessions/{ocpp_id}/{tx}"
+    if a.verb == "stop":
+        result = api.post(f"{base}/stop")
+        _dump(result) if a.json else _print(f"stop requested for {ocpp_id}/{tx}; it ends when the box reports it")
+        return 0
+    if a.verb == "close":
+        if not a.message:
+            raise UsageError("close needs a reason: -m \"…\"")
+        result = api.post(f"{base}/close", {"reason": a.message})
+        _dump(result) if a.json else _print(f"closed {ocpp_id}/{tx}" if result["closed"] else "not closed")
+        return 0
+    s = api.get(base)
+    events = api.get(f"{base}/events")["events"] if a.events else None
+    if a.json:
+        _dump({**s, "events": events} if events is not None else s)
+        return 0
+    side = {"incl_vat": "incl. VAT", "excl_vat": "excl. VAT"}.get(s["price_amounts"], "")
+    lines = [
+        ("session", f"{s['ocpp_id']}/{s['transaction_id']}"),
+        ("organization", s["organization"] or "(unclaimed)"),
+        ("site / cp / outlet", f"{s['site'] or '-'} / {s['charge_point'] or '-'} / {s['outlet'] or '-'} "
+                               f"(connector {s['connector']})"),
+        ("status", s["status"] + (" (learned from meter values)" if s["learned"] else "")),
+        ("started (UTC)", _hm(s["started_at"])),
+        ("ended (UTC)", f"{_hm(s['ended_at'])}  {s['end_reason']}" + (
+            "  (not the box's own stop)" if s["end_inferred"] else "") if s["ended_at"] else "-"),
+        ("energy", f"{s['wh']} Wh (register {s['meter_start_wh']} → {s['meter_last_wh']})"),
+        ("price", f"{s['price_per_kwh']} {s['currency']}/kWh {side}, plan {s['plan']}" if s["price_per_kwh"] else "-"),
+        ("amount", f"{s['amount_incl_vat']} incl. VAT, {s['amount_excl_vat']} excl. VAT {s['currency']}"
+         if s["amount_incl_vat"] is not None else "-"),
+        ("samples", str(len(s["samples"]))),
+    ]
+    if s.get("close"):
+        lines.append(("closed by", f"{s['close']['actor']}: {s['close']['reason']}"))
+    for k, v in lines:
+        _print(f"{k:<20}{v}")
+    if events is not None:
+        _print()
+        _event_rows(events)
+    return 0
+
+
+def cmd_events(api: Api, a: argparse.Namespace) -> int:
+    body = api.get("/events", since=a.since, limit=a.limit, chargepoint=a.chargepoint, event=a.event)
+    if a.json:
+        _dump(body)
+        return 0
+    _event_rows(body["events"])
+    _err(f"next: cpms events --since {body['next_since']}  (latest {body['latest_seq']})")
+    return 0
+
+
+# --- reports -------------------------------------------------------------------------------
+
+
+_RECEIPT_FIGURES = ["SESSIONS", "KWH (RECEIPTS)", "INCL VAT", "EXCL VAT", "VAT"]
+_SESSION_FIGURES = ["SESSIONS", "KWH (SESSIONS)"]
+
+
+def _figures(f: dict[str, Any], receipts: bool) -> list[Any]:
+    if not receipts:
+        return [f["sessions"], f["kwh"]]
+    return [f["sessions"], f["kwh_on_receipts"], f["amount_incl_vat"], f["amount_excl_vat"], f["vat_amount"]]
+
+
+def _local(ts: str, tz: str) -> str:
+    """An ISO time with offset as local wall time, for people only."""
+    return datetime.fromisoformat(ts).astimezone(ZoneInfo(tz)).strftime("%Y-%m-%d %H:%M")
+
+
+def _statement_part(part: dict[str, Any], receipts: bool) -> None:
+    label = "collected_by" if receipts else "reason"
+    figs = _RECEIPT_FIGURES if receipts else _SESSION_FIGURES
+    lines, cps, sites = [], [], []
+    for site in part["sites"]:
+        sites.append([site["key"], site["name"], *_figures(site, receipts)])
+        for cp in site["charge_points"]:
+            cps.append([site["key"], cp["key"], cp["ocpp_id"], *_figures(cp, receipts)])
+            for o in cp["outlets"]:
+                for x in o["by_channel"]:
+                    lines.append([site["key"], cp["key"], o["key"], x["channel"], x[label],
+                                  *_figures(x, receipts)])
+    table(lines, ["SITE", "CP", "OUTLET", "CHANNEL", label.replace("_", " ").upper(), *figs], right=5)
+    if receipts:
+        _print()
+        table(cps, ["SITE", "CP", "OCPP ID", *figs], right=3)
+        _print()
+        table(sites, ["SITE", "NAME", *figs], right=2)
+    _print()
+    table([[x["channel"], x[label], *_figures(x, receipts)] for x in part["by_channel"]]
+          + [["total", "", *_figures(part, receipts)]], ["CHANNEL", label.replace("_", " ").upper(), *figs], right=2)
+
+
+def cmd_statement(api: Api, a: argparse.Namespace) -> int:
+    body = api.get("/reports/statement", month=a.month, organization=a.org)
+    if a.json:
+        _dump(body)
+        return 0
+    p, tz = body["period"], body["period"]["timezone"]
+    _print(f"Statement {p['month']}  {body['organization']} ({body['organization_name']})")
+    _print(f"{_local(p['from'], tz)} to {_local(p['to'], tz)} {tz}; amounts in {body['currency']}")
+    _print()
+    receipts, none = body["receipts"], body["no_receipt"]
+    _print("Receipts issued in the month (money by document date; kWh is the energy on the receipts, "
+           "not energy delivered in the month)")
+    if receipts["sessions"]:
+        _statement_part(receipts, True)
+    else:
+        _print("no receipts")
+    _print()
+    _print("No receipt: sessions that ended in the month without one (cancelled, unpaid, or pending capture); "
+           "no money")
+    if none["sessions"]:
+        _statement_part(none, False)
+    else:
+        _print("none")
+    if body["active_sessions"]:
+        _print()
+        _print(f"{body['active_sessions']} session(s) still active")
+    for w in body["warnings"]:
+        _err(f"warning: {w}")
+    return 0
+
+
+# --- manifest ------------------------------------------------------------------------------
+
+
+def _read_docs(path: str) -> list[dict[str, Any]]:
+    try:
+        text = sys.stdin.read() if path == "-" else Path(path).read_text()
+    except OSError as e:
+        raise UsageError(str(e)) from None
+    try:
+        docs = parse_yaml(text)
+    except ManifestError as e:
+        raise ApiError("document does not validate", detail=e.errors) from None
+    if not docs:
+        raise UsageError(f"{path}: no documents")
+    order = {"organization": 0, "pricelist": 1, "site": 2}
+    return [to_data(d) for d in sorted(docs, key=lambda d: order[d.kind])]
+
+
+def _show_plan(p: dict[str, Any]) -> None:
+    cur = f"version {p['current_version']}" if p["current_version"] else "new"
+    _print(f"{p['organization']} {p['kind']} {p['key']}: {cur}")
+    for c in p["changes"] or ["(no changes)"]:
+        _print(f"  {c}")
+    for w in p["warnings"]:
+        _print(f"  ! {w}")
+    for i in p["info"]:
+        _print(f"  {i}")
+    for e in p["errors"]:
+        _print(f"  error: {e}")
+
+
+def _deferrable(e: ApiError, doc: dict[str, Any], docs: list[dict[str, Any]]) -> bool:
+    """A document for an organization that this file creates can only be planned after it exists."""
+    org = doc.get("organization")
+    return e.status == 404 and any(d["kind"] == "organization" and d["organization"]["key"] == org for d in docs)
+
+
+def _plans(api: Api, docs: list[dict[str, Any]], prune: bool) -> list[dict[str, Any] | None]:
+    out: list[dict[str, Any] | None] = []
+    for d in docs:
+        try:
+            out.append(api.post("/manifest/plan", {"document": d, "prune": prune}))
+        except ApiError as e:
+            if not _deferrable(e, d, docs):
+                raise
+            out.append(None)
+    return out
+
+
+def _show_plans(docs: list[dict[str, Any]], plans: list[dict[str, Any] | None]) -> None:
+    for d, p in zip(docs, plans):
+        if p is None:
+            _print(f"{d['organization']} {d['kind']}: planned after its organization is applied")
+        else:
+            _show_plan(p)
+
+
+def cmd_plan(api: Api, a: argparse.Namespace) -> int:
+    docs = _read_docs(a.file)
+    plans = _plans(api, docs, a.prune)
+    if a.json:
+        _dump({"plans": plans})
+    else:
+        _show_plans(docs, plans)
+    return 1 if any(p and p["errors"] for p in plans) else 0
+
+
+def cmd_apply(api: Api, a: argparse.Namespace) -> int:
+    if not a.message or not a.message.strip():
+        raise UsageError("apply needs a message: -m \"why\"")
+    docs = _read_docs(a.file)
+    plans = _plans(api, docs, a.prune)
+    if not a.json:
+        _show_plans(docs, plans)
+    if any(p and p["errors"] for p in plans):
+        if a.json:
+            _dump({"plans": plans, "applied": []})
+        _err("not applied: the plan has errors")
+        return 1
+    if all(p is not None and not p["changes"] for p in plans):
+        _dump({"plans": plans, "applied": []}) if a.json else _print("nothing to apply")
+        return 0
+    if not a.yes:
+        # Never a prompt without a TTY, and never an unconfirmed apply either:
+        # scripts and agents opt in with --yes (Terraform's -auto-approve).
+        if not sys.stdin.isatty():
+            if a.json:
+                _dump({"plans": plans, "applied": []})
+            _err("cpms: not a TTY: re-run with --yes to apply")
+            return 2
+        if input("apply? [y/N] ").strip().lower() not in ("y", "yes"):
+            _err("not applied")
+            return 1
+    results = []
+    for d, p in zip(docs, plans):
+        if p is None:
+            p = api.post("/manifest/plan", {"document": d, "prune": a.prune})
+            if not a.json:
+                _show_plan(p)
+            if p["errors"]:
+                _err("stopped: the plan has errors")
+                return 1
+        if not p["changes"]:
+            continue
+        r = api.post("/manifest/apply", {"document": d, "base_digest": p["base_digest"], "message": a.message,
+                                          "prune": a.prune})
+        results.append(r)
+        if not a.json:
+            _print(f"applied {r['organization']} {r['kind']} {r['key']} version {r['version']}")
+    if a.json:
+        _dump({"plans": plans, "applied": results})
+    return 0
+
+
+def _selector(a: argparse.Namespace) -> tuple[str, str] | None:
+    if a.site:
+        return "site", a.site
+    if a.pricelist:
+        return "pricelist", "pricelist"
+    if a.organization:
+        return "organization", a.org
+    return None
+
+
+def cmd_export(api: Api, a: argparse.Namespace) -> int:
+    sel = _selector(a)
+    if sel:
+        docs = [api.get(f"/manifest/{a.org}/{sel[0]}/{sel[1]}", version=a.version)]
+    else:
+        if a.version:
+            raise UsageError("--version needs --site, --pricelist or --organization")
+        docs = api.get(f"/manifest/{a.org}")["documents"]
+    if a.json:
+        _dump({"documents": docs})
+        return 0
+    order = {"organization": 0, "pricelist": 1, "site": 2}
+    docs.sort(key=lambda d: (order.get(d["kind"], 9), d["key"]))
+    sys.stdout.write(to_yaml([d["document"] for d in docs]))
+    return 0
+
+
+def _need_selector(a: argparse.Namespace) -> tuple[str, str]:
+    sel = _selector(a)
+    if sel is None:
+        raise UsageError("which document? --site KEY, --pricelist or --organization")
+    return sel
+
+
+def cmd_history(api: Api, a: argparse.Namespace) -> int:
+    kind, key = _need_selector(a)
+    body = api.get(f"/manifest/{a.org}/{kind}/{key}/history")
+    if a.json:
+        _dump(body)
+        return 0
+    table([[f"v{v['version']}", _hm(v["applied_at"]), v["author"], v["message"]] for v in body["versions"]],
+          ["VERSION", "APPLIED (UTC)", "AUTHOR", "MESSAGE"])
+    return 0
+
+
+def _version(v: str) -> int:
+    try:
+        return int(v.lstrip("v"))
+    except ValueError:
+        raise UsageError(f"not a version: {v!r}") from None
+
+
+def cmd_diff(api: Api, a: argparse.Namespace) -> int:
+    kind, key = _need_selector(a)
+    new = _version(a.new) if a.new else None
+    old = _version(a.old)
+    path = f"/manifest/{a.org}/{kind}/{key}"
+    before = api.get(path, version=old)
+    after = api.get(path, version=new)
+    changes = [str(c) for c in diff(before["document"], after["document"])]
+    if a.json:
+        _dump({"from": before["version"], "to": after["version"], "changes": changes})
+        return 0
+    _print(f"{a.org} {kind} {key}: v{before['version']} → v{after['version']}")
+    for c in changes or ["(no changes)"]:
+        _print(f"  {c}")
+    return 0
+
+
+def cmd_validate(api: Api | None, a: argparse.Namespace) -> int:
+    """Offline: the schema and what one document can check on its own. `plan` checks the rest."""
+    try:
+        text = sys.stdin.read() if a.file == "-" else Path(a.file).read_text()
+    except OSError as e:
+        raise UsageError(str(e)) from None
+    try:
+        docs = parse_yaml(text)
+    except ManifestError as e:
+        if a.json:
+            _dump({"valid": False, "errors": e.errors})
+        else:
+            for line in e.errors:
+                _print(f"error: {line}")
+        return 1
+    if a.json:
+        _dump({"valid": True, "documents": [{"kind": d.kind, "organization": d.org_key, "key": d.doc_key}
+                                            for d in docs]})
+    else:
+        for d in docs:
+            _print(f"ok  {d.org_key} {d.kind} {d.doc_key}")
+    return 0
+
+
+def cmd_schema(api: Api | None, a: argparse.Namespace) -> int:
+    """Offline: the documents' JSON Schema, for an editor (schema/manifest.cpms-v1.schema.json)."""
+    _dump(json_schema())
+    return 0
+
+
+# --- keys ------------------------------------------------------------------------------------
+
+
+def cmd_keys_issue(api: Api, a: argparse.Namespace) -> int:
+    r = api.post("/keys", {"name": a.name, "organization": a.org, "scope": a.scope})
+    if a.json:
+        _dump(r)
+    else:
+        whose = f"organization {r['organization']}" if r["organization"] else "operator"
+        _err(f"issued {whose} {r['scope']} key {r['prefix']} ({r['name']}); it is shown once:")
+        _print(r["secret"])
+    return 0
+
+
+def cmd_keys_list(api: Api, a: argparse.Namespace) -> int:
+    r = api.get("/keys", organization=a.org)
+    if a.json:
+        _dump(r)
+    else:
+        table([[k["prefix"], k["organization"] or "(operator)", k["scope"], k["name"], k["owner"] or "",
+                k["issued_by"] or "", _hm(k["created_at"]), _hm(k["revoked_at"])] for k in r["keys"]],
+              ["prefix", "organization", "scope", "name", "personal (owner)", "issued by", "created", "revoked"])
+    return 0
+
+
+def cmd_keys_revoke(api: Api, a: argparse.Namespace) -> int:
+    r = api.post(f"/keys/{a.prefix}/revoke")
+    _dump(r) if a.json else _print(f"revoked {r['prefix']} at {_hm(r['revoked_at'])}")
+    return 0
+
+
+# --- login ---------------------------------------------------------------------------------
+
+
+def cmd_login(api: None, a: argparse.Namespace) -> int:
+    """The device flow: approve in the portal, get a personal key, save it as a profile."""
+    path = config_path()
+    name = login.profile_name(getattr(a, "profile", None) or os.environ.get("CPMS_PROFILE") or "default")
+    text = login.read(path)
+    url = (a.url or login.profile_value(path, text, name, "url") or os.environ.get("CPMS_URL", "")).rstrip("/")
+    if not url.startswith(("https://", "http://")):
+        raise UsageError(f"not an http(s) address: {url!r}" if url else "give the instance: cpms login --url https://…")
+    login.set_profile(path, text, name, url, "lcp_check")  # refuse now rather than after a key is issued
+    http, started = login.start(url, a.scope)
+    try:
+        page = login.verification_url(url, str(started.get("user_code", "")))
+        _err(f"To log in, open this page and approve, logged in to the portal as yourself:\n\n"
+             f"  {page}\n\n"
+             f"Check that the page shows the code {started['user_code']}. It is valid for "
+             f"{int(started['expires_in']) // 60} minutes.")
+        if not a.no_browser and login.can_open_browser() and login.open_browser(page):
+            _err("(opened in your browser)")
+        _err("Waiting for approval… (Ctrl-C to stop)")
+        key = login.poll(http, started)
+    finally:
+        http.close()
+    try:
+        login.write(path, login.set_profile(path, login.read(path), name, url, key["api_key"]))
+    except (OSError, UsageError) as e:  # never leave a key nobody can find: revoke it
+        login.revoke(url, key["api_key"])
+        raise ApiError(f"could not save the key ({e}); it was revoked") from None
+    result = {"profile": name, "url": url, "config": str(path), **{k: key[k] for k in ("prefix", "name",
+                                                                                      "organization", "scope")}}
+    if a.json:
+        _dump(result)
+    else:
+        whose = f"organization {key['organization']}" if key["organization"] else "the operator"
+        _print(f"logged in: a personal {key['scope']} key {key['prefix']} for {whose}, saved as profile [{name}] "
+               f"in {path}")
+    return 0
+
+
+def cmd_logout(api: Api, a: argparse.Namespace) -> int:
+    """Revoke the key in use, then forget the profile, if the key came from it: a key from the environment
+    is only revoked, and a profile holding another key is left alone."""
+    name = getattr(a, "profile", None) or os.environ.get("CPMS_PROFILE") or "default"
+    path = config_path()
+    text = login.read(path)
+    from_profile = login.profile_value(path, text, name, "api_key") == api.config.api_key
+    try:
+        r: dict[str, Any] = api.post("/auth/logout")
+    except ApiError as e:
+        if e.status != 401:  # 401: the key no longer works anyway; forget it
+            raise
+        r = {"prefix": None, "revoked_at": None}
+    removed = False
+    if from_profile:
+        rest = login.drop_profile(path, login.read(path), name)
+        if rest is not None:
+            login.write(path, rest)
+            removed = True
+    if a.json:
+        _dump({**r, "profile": name if from_profile else None, "removed": removed})
+    else:
+        _print(f"revoked key {r['prefix']}" if r["prefix"] else "the key no longer worked")
+        if removed:
+            _print(f"removed profile [{name}] from {path}")
+        else:
+            _print("the key came from CPMS_API_KEY; unset it")
+    return 0
+
+
+def cmd_whoami(api: Api, a: argparse.Namespace) -> int:
+    r = api.get("/auth/me")
+    if a.json:
+        _dump(r)
+        return 0
+    who = r["email"] if r["personal"] else "a machine key"
+    whose = f"organization {r['organization']}" if r["organization"] else "the operator (every organization)"
+    _print(f"{who}: {r['scope']} key {r['prefix']} ({r['name']}) for {whose}")
+    return 0
+
+
+# --- admission ------------------------------------------------------------------------------
+
+
+def _duration(text: str) -> int:
+    """Seconds from '900', '90s', '15m' or '1h'."""
+    t = text.strip().lower()
+    unit = {"s": 1, "m": 60, "h": 3600}.get(t[-1:], 0)
+    number = t[:-1] if unit else t
+    if not number.isdecimal() or int(number) <= 0:
+        raise UsageError(f"not a duration: {text!r} (e.g. 900, 90s, 15m, 1h)")
+    return int(number) * (unit or 1)
+
+
+def _show_admission(r: dict[str, Any]) -> None:
+    w = r["window"]
+    if r["default"] == "open":
+        _print("admission: open (OCPP_ADMISSION=open): every unknown box is admitted unclaimed")
+    elif w is None:
+        _print("admission: closed; unknown boxes are refused. cpms admission open --for 15m to admit them for a while")
+    else:
+        _print(f"admission: OPEN until {_hm(w['until'])} UTC ({int(w['remaining_s'])} s left); then closed")
+        _print("what it lets in: cpms events --event unknown_chargepoint (reason \"window\")")
+    _print(f"longest window: {int(r['window_max_s'])} s; a restart of the gateway closes it")
+
+
+def cmd_admission(api: Api, a: argparse.Namespace) -> int:
+    verb = getattr(a, "admission_command", None) or "status"
+    if verb == "open":
+        r = api.post("/admission/open", {"for_s": _duration(a.duration)})
+    elif verb == "close":
+        r = api.post("/admission/close")
+        if not a.json:
+            _print("closed the window" if r.get("closed") else "no window was open")
+    else:
+        r = api.get("/admission")
+    _dump(r) if a.json else _show_admission(r)
+    return 0
+
+
+# --- members ---------------------------------------------------------------------------------
+
+
+def cmd_members(api: Api, a: argparse.Namespace) -> int:
+    r = api.get("/members")
+    if a.json:
+        _dump(r)
+    else:
+        table([[m["organization"] or "(operator)", m["email"], m["role"], "yes" if m["active"] else "no",
+                _hm(m["added_at"]), m["added_by"] or ""] for m in r["members"]],
+              ["organization", "email", "role", "active", "added", "added by"])
+    return 0
+
+
+def _member_body(a: argparse.Namespace) -> dict[str, Any]:
+    if bool(a.org) == bool(a.operator):
+        raise UsageError("give --org KEY or --operator")
+    return {"email": a.email, "organization": a.org}
+
+
+def cmd_members_add(api: Api, a: argparse.Namespace) -> int:
+    r = api.post("/members", {**_member_body(a), "role": a.role})
+    scope = f"organization {r['organization']}" if r["organization"] else "the operator (every organization)"
+    _dump(r) if a.json else _print(f"{a.email} may log in to the portal for {scope}, role {r['role']}"
+                                   f"{'' if r['added'] else ' (already could)'}")
+    return 0
+
+
+def cmd_members_set_role(api: Api, a: argparse.Namespace) -> int:
+    r = api.post("/members/role", {**_member_body(a), "role": a.role})
+    if a.json:
+        _dump(r)
+    else:
+        _print(f"{a.email} has role {r['role']} in {r['organization'] or 'the operator'}"
+               f"{'' if r['changed'] else ' (already had)'}")
+        if r["revoked_keys"]:
+            _print(f"revoked keys it no longer allows: {', '.join(r['revoked_keys'])}")
+    return 0
+
+
+def cmd_members_remove(api: Api, a: argparse.Namespace) -> int:
+    r = api.post("/members/remove", _member_body(a))
+    if a.json:
+        _dump(r)
+    else:
+        _print(f"removed {a.email} from {r['organization'] or 'the operator'}" if r["removed"]
+               else f"{a.email} was not a member of {r['organization'] or 'the operator'}")
+        if r.get("active") is False:  # only the operator is told
+            _print(f"{a.email} has no membership left and can no longer log in")
+        if r.get("revoked_keys"):
+            _print(f"revoked their keys, and keys issued from them: {', '.join(r['revoked_keys'])}")
+    return 0
+
+
+# --- OCPI ------------------------------------------------------------------------------------
+
+
+def cmd_ocpi_connect(api: Api, a: argparse.Namespace) -> int:
+    r = api.post("/ocpi/connections", {"organization": a.org, "name": a.name})
+    if a.json:
+        _dump(r)
+        return 0
+    _err(f"connection {r['organization']}/{r['name']} is {r['state']}. Send the partner both lines below; "
+         "Token A is shown once and works until they register:")
+    _print(f"versions URL: {r['versions_url']}")
+    _print(f"Token A:      {r['token_a']}")
+    return 0
+
+
+def cmd_ocpi_connections(api: Api, a: argparse.Namespace) -> int:
+    body = api.get("/ocpi/connections", organization=a.org)
+    if a.json:
+        _dump(body)
+        return 0
+    table([[c["organization"], c["name"], c["state"], ", ".join(c["their_roles"]), c["locations_receiver"] or "-",
+            _hm(c["registered_at"])] for c in body["connections"]],
+          ["ORG", "NAME", "STATE", "THEIR ROLES", "LOCATIONS RECEIVER", "REGISTERED (UTC)"])
+    return 0
+
+
+def cmd_ocpi_disconnect(api: Api, a: argparse.Namespace) -> int:
+    r = api.post(f"/ocpi/connections/{a.org}/{a.name}/disconnect")
+    _dump(r) if a.json else _print(f"{r['organization']}/{r['name']} is {r['state']}; its tokens no longer work")
+    return 0
+
+
+def cmd_ocpi_preview(api: Api, a: argparse.Namespace) -> int:
+    r = api.get(f"/ocpi/{a.org}/locations/{a.site}")
+    if not a.json and not r["published"]:
+        _err("not published: partners do not get this Location (publish: true in the site document)")
+    _dump(r["location"] if not a.json else r)
+    return 0
+
+
+# --- the parser ------------------------------------------------------------------------------
+
+
+class _Parser(argparse.ArgumentParser):
+    def error(self, message: str) -> Any:  # exit 2, as argparse does, but through our handler
+        raise UsageError(f"{self.prog}: {message}")
+
+
+def parser() -> argparse.ArgumentParser:
+    common = _Parser(add_help=False)
+    common.add_argument("--json", action="store_true", default=argparse.SUPPRESS, help="machine-readable output")
+    common.add_argument("--profile", default=argparse.SUPPRESS, help="profile in ~/.config/cpms/config.toml")
+    p = _Parser(prog="cpms", parents=[common], description="LeanCPMS from the command line. "
+                "Alone, prints the live state.")
+    sub = p.add_subparsers(dest="command", parser_class=_Parser)
+
+    def cmd(name: str, fn: Callable[..., int], help: str, **kw: Any) -> argparse.ArgumentParser:
+        sp = sub.add_parser(name, parents=[common], help=help, description=help, **kw)
+        sp.set_defaults(fn=fn)
+        return sp
+
+    s = cmd("status", cmd_status, "live state per site, fuse group, charge point and outlet")
+    s.add_argument("--site")
+    s.add_argument("--org", help="operator: one organization")
+
+    s = cmd("chargepoints", cmd_chargepoints, "declared charge points with live state [rekey KEY]")
+    s.add_argument("verb", nargs="?", choices=["rekey"], help="rekey: a new key for a box declared auth: basic")
+    s.add_argument("key", nargs="?")
+    s.add_argument("--unclaimed", action="store_true", help="operator: boxes nobody has declared")
+    s.add_argument("--org")
+
+    s = cmd("sessions", cmd_sessions, "sessions, newest first")
+    s.add_argument("--site")
+    s.add_argument("--since", help="ISO date (UTC) or time")
+    s.add_argument("--status", choices=["active", "ended"])
+    s.add_argument("--org")
+    s.add_argument("--limit", type=int, default=100)
+    s.add_argument("--csv", action="store_true")
+
+    s = cmd("session", cmd_session, "one session: <ocpp_id>/<transaction_id> [stop|close -m REASON]")
+    s.add_argument("ref")
+    s.add_argument("verb", nargs="?", choices=["stop", "close"])
+    s.add_argument("--events", action="store_true", help="the box's events for this session")
+    s.add_argument("-m", "--message", help="the reason for close")
+
+    s = cmd("events", cmd_events, "the gateway's event log (pass-through)")
+    s.add_argument("--since", type=int, default=0)
+    s.add_argument("--chargepoint")
+    s.add_argument("--event")
+    s.add_argument("--limit", type=int, default=100)
+
+    r = sub.add_parser("report", parents=[common], help="reports: the monthly statement")
+    rsub = r.add_subparsers(dest="report_command", parser_class=_Parser, required=True)
+    s = rsub.add_parser("statement", parents=[common], help="a month's receipts (incl./excl. VAT) and sessions without one, per site, "
+                        "charge point and outlet",
+                        description="The monthly statement (PRD §6.1), from this system's sessions and ledger.")
+    s.set_defaults(fn=cmd_statement)
+    s.add_argument("--month", help="YYYY-MM in the organization's time zone (default: this month so far)")
+    s.add_argument("--org", help="operator: which organization (an organization key knows its own)")
+
+    m = sub.add_parser("manifest", parents=[common], help="declared state: export, plan, apply, history, diff, validate, schema")
+    msub = m.add_subparsers(dest="manifest_command", parser_class=_Parser, required=True)
+
+    def mcmd(name: str, fn: Callable[..., int], help: str) -> argparse.ArgumentParser:
+        sp = msub.add_parser(name, parents=[common], help=help, description=help)
+        sp.set_defaults(fn=fn)
+        return sp
+
+    def selector(sp: argparse.ArgumentParser) -> None:
+        sp.add_argument("org")
+        g = sp.add_mutually_exclusive_group()
+        g.add_argument("--site", metavar="KEY")
+        g.add_argument("--pricelist", action="store_true")
+        g.add_argument("--organization", action="store_true")
+
+    s = mcmd("export", cmd_export, "the current documents as YAML (all, or one)")
+    selector(s)
+    s.add_argument("--version", type=int)
+    for name, fn, help in (("plan", cmd_plan, "what applying FILE would change"),
+                           ("apply", cmd_apply, "plan FILE, show it, confirm on a TTY (or --yes), apply")):
+        s = mcmd(name, fn, help)
+        s.add_argument("file", help="YAML, one or more documents separated by ---; - for stdin")
+        s.add_argument("--prune", action="store_true", help="allow removals")
+        if name == "apply":
+            s.add_argument("-m", "--message", help="why (stored with the version)")
+            s.add_argument("--yes", "-y", action="store_true", help="apply without asking; required without a TTY")
+    s = mcmd("history", cmd_history, "the versions of one document")
+    selector(s)
+    s = mcmd("diff", cmd_diff, "the changes between two versions of one document (NEW defaults to current)")
+    selector(s)
+    s.add_argument("old", help="e.g. v3")
+    s.add_argument("new", nargs="?")
+    s = mcmd("validate", cmd_validate, "check FILE against the schema, offline")
+    s.add_argument("file")
+    mcmd("schema", cmd_schema, "the documents' JSON Schema, for an editor, offline")
+
+    oc = sub.add_parser("ocpi", parents=[common], help="OCPI partners (Nobil, roaming) and what they see")
+    osub = oc.add_subparsers(dest="ocpi_command", parser_class=_Parser, required=True)
+    s = osub.add_parser("connect", parents=[common], help="a connection for a partner: prints Token A once and "
+                        "the versions URL to send them")
+    s.set_defaults(fn=cmd_ocpi_connect)
+    s.add_argument("org")
+    s.add_argument("--name", required=True, help="the partner, e.g. nobil-test")
+    s = osub.add_parser("connections", parents=[common], help="connections and their state")
+    s.set_defaults(fn=cmd_ocpi_connections)
+    s.add_argument("--org")
+    s = osub.add_parser("disconnect", parents=[common], help="close a connection: its tokens stop working")
+    s.set_defaults(fn=cmd_ocpi_disconnect)
+    s.add_argument("org")
+    s.add_argument("name")
+    s = osub.add_parser("preview", parents=[common], help="the Location JSON for a site, as OCPI would send it now")
+    s.set_defaults(fn=cmd_ocpi_preview)
+    s.add_argument("org")
+    s.add_argument("site")
+
+    s = cmd("login", cmd_login, "log in with your portal login: approve in the browser, get a personal key, "
+            "saved as a profile (--profile, default [default])")
+    s.add_argument("--url", help="the instance, e.g. https://cpms.example.com (default: the profile's)")
+    s.add_argument("--scope", choices=["read", "write"], default="write",
+                   help="what to ask for; you decide when approving (default write)")
+    s.add_argument("--no-browser", action="store_true", help="only print the address to open")
+    cmd("logout", cmd_logout, "revoke this profile's key and remove the profile")
+    cmd("whoami", cmd_whoami, "the key in use: whose, which organization, read or write")
+
+    k = sub.add_parser("keys", parents=[common], help="API keys (an organization's write key: its own) "
+                       "[list|issue|revoke]")
+    ksub = k.add_subparsers(dest="keys_command", parser_class=_Parser, required=True)
+    s = ksub.add_parser("list", parents=[common], help="the keys you may manage, revoked ones too")
+    s.set_defaults(fn=cmd_keys_list)
+    s.add_argument("--org", help="operator: one organization")
+    s = ksub.add_parser("issue", parents=[common], help="issue a key; printed once")
+    s.set_defaults(fn=cmd_keys_issue)
+    s.add_argument("--name", required=True)
+    s.add_argument("--org", help="an organization; without it an operator key (operator) or your own organization's")
+    s.add_argument("--scope", choices=["read", "write"], default="write",
+                   help="read: may only look (GET); write (default): may also act")
+    s = ksub.add_parser("revoke", parents=[common], help="revoke a key by its prefix")
+    s.set_defaults(fn=cmd_keys_revoke)
+    s.add_argument("prefix")
+
+    ad = sub.add_parser("admission", parents=[common], help="the gateway's admission window for unknown boxes "
+                        "(operator) [status|open --for 15m|close]")
+    ad.set_defaults(fn=cmd_admission)
+    asub = ad.add_subparsers(dest="admission_command", parser_class=_Parser)
+    s = asub.add_parser("status", parents=[common], help="closed, open, or a window and what it let in")
+    s.set_defaults(fn=cmd_admission)
+    s = asub.add_parser("open", parents=[common], help="admit unknown boxes for a while (the gateway caps it)")
+    s.set_defaults(fn=cmd_admission)
+    s.add_argument("--for", dest="duration", required=True, metavar="DURATION", help="e.g. 900, 15m, 1h")
+    s = asub.add_parser("close", parents=[common], help="close the window now")
+    s.set_defaults(fn=cmd_admission)
+
+    m = sub.add_parser("members", parents=[common], help="who may log in to the portal (an organization's "
+                       "write key: its own) [list|add|remove|set-role]")
+    m.set_defaults(fn=cmd_members)
+    msub = m.add_subparsers(dest="members_command", parser_class=_Parser)
+    s = msub.add_parser("list", parents=[common], help="the members you may manage")
+    s.set_defaults(fn=cmd_members)
+    for name, fn, help in (("add", cmd_members_add, "let EMAIL log in with a one-time code by e-mail"),
+                           ("remove", cmd_members_remove, "take away one membership, and revoke the keys the "
+                            "member got with cpms login and every key issued from them"),
+                           ("set-role", cmd_members_set_role, "change the widest key EMAIL may get with cpms "
+                            "login; lowered, their write keys and keys issued from them are revoked")):
+        s = msub.add_parser(name, parents=[common], help=help, description=help)
+        s.set_defaults(fn=fn)
+        s.add_argument("email")
+        g = s.add_mutually_exclusive_group()
+        g.add_argument("--org", help="the organization the member sees")
+        g.add_argument("--operator", action="store_true", help="operator key: every organization (us, on the "
+                       "hosted instance)")
+        if name != "remove":
+            s.add_argument("--role", choices=["read", "write"], default="read" if name == "add" else None,
+                           required=name == "set-role",
+                           help="read (default for add): cpms login gives read keys only; write: may act too. "
+                           "The portal only reads, whatever the role")
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    try:
+        a = parser().parse_args(argv)
+        a.json = getattr(a, "json", False)
+        fn = getattr(a, "fn", None)
+        if fn is None:  # `cpms` alone: the live state
+            a.site = a.org = None
+            fn = cmd_status
+        if fn in (cmd_validate, cmd_schema, cmd_login):  # offline, or a login: no key yet
+            return int(fn(None, a))
+        api = Api(load_config(getattr(a, "profile", None)))
+        try:
+            return int(fn(api, a))
+        finally:
+            api.close()
+    except UsageError as e:
+        _err(str(e) if str(e).startswith("cpms") else f"cpms: {e}")
+        return 2
+    except ApiError as e:
+        if getattr(e, "detail", None):
+            details = e.detail if isinstance(e.detail, list) else [e.detail]
+            _err(f"cpms: {e}")
+            for d in details:
+                _err(f"  {d if isinstance(d, str) else json.dumps(d, ensure_ascii=False)}")
+        else:
+            _err(f"cpms: {e}")
+        return 1
+    except KeyboardInterrupt:
+        return 130
+
+
+if __name__ == "__main__":
+    sys.exit(main())