corethink 1.0.0__py3-none-any.whl

corethink/commands/admin.py

@@ -0,0 +1,703 @@
+"""`corethink admin`: every account and run on this Workbench, credit, limits and super admins (super admins only).
+
+The Workbench checks every request; anyone else is told they cannot use these commands.
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+import uuid
+from pathlib import Path
+from typing import Any
+
+import typer
+from rich.text import Text
+
+from corethink import output as ui
+from corethink.client import ApiError
+from corethink.commands.workspace import entry_amount, entry_type
+from corethink.context import client
+
+app = typer.Typer(help="Every account and run on this Workbench (super admins only).", no_args_is_help=True)
+settings_app = typer.Typer(help="Account limits for everyone: show them, or change them with `set`.")
+superadmins_app = typer.Typer(help="Who can use the admin commands and page.")
+
+YES_OPTION = typer.Option(False, "--yes", "-y", help="Do not ask.")
+JOB_ID = re.compile(r"^[0-9a-f-]{36}$")
+
+LIMIT_LABEL = {
+    "signupCreditUsd": "Welcome credit",
+    "grantsPerDay": "Welcome credits per day",
+    "maxRunningJobs": "Runs at once (personal workspace)",
+    "maxRunningJobsTeam": "Runs at once (team workspace)",
+    "minBudgetUsd": "Smallest run spending limit",
+    "maxBudgetUsd": "Largest run spending limit",
+}
+
+RUN_STATE = {
+    "RUNNING": ("running", "running"),
+    "ADMITTED": ("starting", "running"),
+    "QUEUED": ("queued", "queued"),
+    "PREEMPTED": ("paused", "queued"),
+    "SUCCEEDED": ("succeeded", "succeeded"),
+    "FAILED": ("failed", "failed"),
+    "CANCELLED": ("cancelled", "failed"),
+}
+RUN_FILTERS = ("running", "queued", "succeeded", "failed")
+
+
+# ---- helpers ---------------------------------------------------------------------------------------------------------
+
+
+def _denied(problem: ApiError) -> ApiError:
+    if problem.status == 403 and problem.code == "forbidden":
+        return ApiError(
+            "Only super admins can use `corethink admin`. Ask a super admin to add you.",
+            status=403,
+            code="forbidden",
+            payload=problem.payload,
+        )
+    return problem
+
+
+def _call(method: str, path: str, body: Any = None, **params: Any) -> Any:
+    try:
+        if method == "GET":
+            return client().get(path, **params) or {}
+        return client().request(method, path, json=body, params=params or None) or {}
+    except ApiError as problem:
+        raise _denied(problem) from None
+
+
+def _pick(matches: list[dict[str, Any]], what: str, given: str) -> dict[str, Any]:
+    if len(matches) == 1:
+        return matches[0]
+    if not matches:
+        ui.error(f"No {what} matches {given!r}.")
+        raise typer.Exit(5)
+    ui.error(f"More than one {what} matches {given!r}; be more specific.")
+    raise typer.Exit(2)
+
+
+def _find_account(given: str) -> dict[str, Any]:
+    """An account by ID or email (or the start of either)."""
+    accounts: list[dict[str, Any]] = _call("GET", "/api/v1/admin/accounts").get("accounts") or []
+    folded = given.strip().casefold()
+    for test in (
+        lambda a: a.get("uid") == given,
+        lambda a: str(a.get("email", "")).casefold() == folded,
+        lambda a: str(a.get("uid", "")).startswith(given),
+        lambda a: str(a.get("email", "")).casefold().startswith(folded),
+    ):
+        matches = [a for a in accounts if test(a)]
+        if matches:
+            return _pick(matches, "account", given)
+    return _pick([], "account", given)
+
+
+def _count(value: Any) -> str:
+    try:
+        return f"{int(value):,}"
+    except (TypeError, ValueError):
+        return "—"
+
+
+def _limit_text(unit: Any, value: Any) -> str:
+    if value is None:
+        return "—"
+    if unit == "usd":
+        return ui.usd(value, 0 if float(value).is_integer() else 2)
+    return _count(value)
+
+
+def _run_state(run: dict[str, Any]) -> Text:
+    label = RUN_STATE.get(str(run.get("state", "")).upper(), (str(run.get("state") or "—").lower(), ""))[0]
+    styled = ui.state_text(run.get("state"))
+    return Text(label, style=styled.style)
+
+
+def _limit_keys(known: list[str], pairs: list[str]) -> dict[str, float | int | None]:
+    """KEY=VALUE pairs as limit values; a key may be written in any case or kebab-case; `default` clears it."""
+    lookup = {re.sub(r"[-_]", "", key).lower(): key for key in known}
+    values: dict[str, float | int | None] = {}
+    for pair in pairs:
+        name, sep, raw = pair.partition("=")
+        key = lookup.get(re.sub(r"[-_]", "", name.strip()).lower())
+        if not sep or not key:
+            ui.error(f"{pair}: use KEY=VALUE with one of {', '.join(known)} (VALUE `default` clears it).")
+            raise typer.Exit(2)
+        text = raw.strip().lstrip("$").replace(",", "")
+        if text.lower() in ("", "default", "none", "null"):
+            values[key] = None
+            continue
+        try:
+            number = float(text)
+        except ValueError:
+            ui.error(f"{pair}: give a number, or `default`.")
+            raise typer.Exit(2) from None
+        values[key] = int(number) if number.is_integer() else number
+    if not values:
+        ui.error(f"Give at least one KEY=VALUE: {', '.join(known)}.")
+        raise typer.Exit(2)
+    return values
+
+
+def _change_text(values: dict[str, Any], units: dict[str, Any]) -> str:
+    return ", ".join(
+        f"{LIMIT_LABEL.get(k, k)} → {'default' if v is None else _limit_text(units.get(k), v)}"
+        for k, v in values.items()
+    )
+
+
+# ---- overview and accounts -------------------------------------------------------------------------------------------
+
+
+@app.command("overview")
+def overview() -> None:
+    """Accounts, runs, spend and credit across the Workbench."""
+    data = _call("GET", "/api/v1/admin/overview")
+    accounts, runs = data.get("accounts") or {}, data.get("runs") or {}
+    spend, credit = data.get("spend") or {}, data.get("credit") or {}
+
+    def human() -> None:
+        ui.fields(
+            [
+                ("Total", _count(accounts.get("total"))),
+                ("Confirmed", _count(accounts.get("verified"))),
+                ("New in the last 7 days", _count(accounts.get("newLast7"))),
+                (
+                    "Test accounts not counted",
+                    _count(accounts["hiddenTests"]) if accounts.get("hiddenTests") else None,
+                ),
+                (
+                    "Sign-ups per day",
+                    "  ".join(f"{d.get('date', '')[5:]}: {d.get('count')}" for d in accounts.get("daily") or [])
+                    or None,
+                ),
+            ],
+            title="Accounts",
+        )
+        ui.out.print()
+        ui.fields(
+            [
+                ("Running", _count(runs.get("running"))),
+                ("Queued", _count(runs.get("queued"))),
+                (
+                    "Finished in the last 7 days",
+                    f"{_count(runs.get('finishedLast7'))} ({_count(runs.get('succeededLast7'))} succeeded, "
+                    f"{_count(runs.get('failedLast7'))} failed)",
+                ),
+                (
+                    "Total",
+                    _count(runs.get("total")) + (" (newest only)" if runs.get("capped") else ""),
+                ),
+                (
+                    "Test-account runs not counted",
+                    _count(runs["hiddenTests"]) if runs.get("hiddenTests") else None,
+                ),
+            ],
+            title="Runs",
+        )
+        ui.out.print()
+        ui.fields(
+            [
+                ("Spent on runs", ui.usd(spend.get("totalUsd"))),
+                ("In the last 7 days", ui.usd(spend.get("last7Usd"))),
+                (
+                    "Credit given or bought",
+                    ui.usd(float(credit.get("grantedUsd") or 0) + float(credit.get("boughtUsd") or 0)),
+                ),
+                ("Welcome credit", ui.usd(credit.get("welcomeUsd"))),
+                ("Added by admins", ui.usd(credit.get("addedUsd"))),
+                ("Bought", ui.usd(credit.get("boughtUsd"))),
+                ("Used", ui.usd(credit.get("usedUsd"))),
+                ("Left", ui.usd(credit.get("leftUsd"))),
+                ("Held by running jobs", ui.usd(credit.get("heldUsd"))),
+            ],
+            title="Spend and credit",
+        )
+        if runs.get("problem"):
+            ui.warn(f"Runs could not all be read: {runs['problem']}")
+
+    ui.emit(data, human)
+
+
+@app.command("accounts")
+def accounts(
+    search: str = typer.Option(None, "--search", "-s", help="Only accounts whose email contains this."),
+    limit: int = typer.Option(100, "--limit", "-n", min=1, help="Show at most this many."),
+) -> None:
+    """Every account, newest first.
+
+    Example: corethink admin accounts --search acme.com
+    """
+    data = _call("GET", "/api/v1/admin/accounts")
+    every = data.get("accounts") or []
+    matched = [a for a in every if not search or search.casefold() in str(a.get("email", "")).casefold()]
+    shown = matched[:limit]
+
+    def human() -> None:
+        ui.table(
+            shown,
+            [
+                ("Email", "email"),
+                ("Created", lambda a: ui.when(a.get("createdAt"))),
+                ("Confirmed", lambda a: "yes" if a.get("verified") else Text("no", style="yellow")),
+                ("Workspaces", lambda a: _count(a.get("workspaces"))),
+                ("Balance", lambda a: ui.usd(a.get("balanceUsd"))),
+                ("Spent", lambda a: ui.usd(a.get("spentUsd"))),
+                ("Runs", lambda a: _count(a.get("runs"))),
+                ("ID", lambda a: ui.short_id(a.get("uid"), 12)),
+            ],
+            empty="No accounts match.",
+        )
+        hidden = data.get("hiddenTestAccounts")
+        ui.info(
+            f"{len(shown)} of {len(every)} accounts"
+            + (f" ({len(matched)} match)" if search else "")
+            + (f" · {hidden} test accounts hidden" if hidden else "")
+        )
+
+    ui.emit(
+        {
+            "accounts": shown,
+            "total": len(every),
+            "hiddenTestAccounts": data.get("hiddenTestAccounts"),
+        },
+        human,
+    )
+
+
+@app.command("account")
+def account(
+    who: str = typer.Argument(..., metavar="ACCOUNT", help="The account's email or ID (or the start of either)."),
+) -> None:
+    """One account: its workspaces, credit, limits and runs."""
+    found = _find_account(who)
+    detail = _call("GET", f"/api/v1/admin/accounts/{found['uid']}")
+    shown = detail.get("account") or found
+
+    def human() -> None:
+        held = float(shown.get("heldUsd") or 0)
+        ui.fields(
+            [
+                ("Email", shown.get("email")),
+                ("ID", shown.get("uid")),
+                ("Created", ui.when(shown.get("createdAt"))),
+                ("Confirmed", "yes" if shown.get("verified") else "no"),
+                (
+                    "Balance",
+                    ui.usd(shown.get("balanceUsd")) + (f" ({ui.usd(held)} held)" if held > 0 else ""),
+                ),
+                (
+                    "Spent on runs",
+                    f"{ui.usd(shown.get('spentUsd'))} · {_count(shown.get('runs'))} runs",
+                ),
+            ]
+        )
+        ui.out.print()
+        ui.table(
+            detail.get("workspaces") or [],
+            [("Workspace", "name"), ("Kind", "kind"), ("Role", "role"), ("ID", "id")],
+            title="Workspaces",
+            empty="No workspaces.",
+        )
+        limits = (detail.get("limits") or {}).get("limits") or []
+        if limits:
+            ui.out.print()
+            _account_limits_table(limits)
+        ui.out.print()
+        ui.table(
+            (detail.get("ledger") or [])[:20],
+            [
+                ("When", lambda e: ui.when(e.get("at"))),
+                ("Type", entry_type),
+                ("Note", lambda e: e.get("note") or e.get("kind")),
+                ("Amount", entry_amount),
+            ],
+            title="Credit",
+            empty="No credit yet.",
+        )
+        ui.out.print()
+        ui.table(
+            (detail.get("runs") or [])[:20],
+            [
+                ("Job", lambda r: ui.short_id(r.get("jobId"))),
+                ("Environment", "environment"),
+                ("Status", _run_state),
+                ("Spent", lambda r: ui.usd(r.get("spentUsd"))),
+                ("Updated", lambda r: ui.ago(r.get("updatedAt"))),
+            ],
+            title="Runs",
+            empty="No runs.",
+        )
+
+    ui.emit(detail, human)
+
+
+def _account_limits_table(limits: list[dict[str, Any]]) -> None:
+    ui.table(
+        limits,
+        [
+            ("Limit", lambda x: LIMIT_LABEL.get(x.get("key", ""), x.get("key"))),
+            ("Key", "key"),
+            ("In use", lambda x: _limit_text(x.get("unit"), x.get("value"))),
+            (
+                "Its own",
+                lambda x: _limit_text(x.get("unit"), x.get("own")) if x.get("own") is not None else "—",
+            ),
+            ("For everyone", lambda x: _limit_text(x.get("unit"), x.get("global"))),
+        ],
+        title="Limits for this account",
+    )
+
+
+@app.command("add-credit")
+def add_credit(
+    who: str = typer.Argument(..., metavar="ACCOUNT", help="The account's email or ID."),
+    usd: float = typer.Argument(..., metavar="USD", help="US dollars to add (up to 1,000)."),
+    note: str = typer.Option(..., "--note", help="Why, in a few words (the account's ledger shows it)."),
+    key: str = typer.Option(
+        None,
+        "--key",
+        help="A unique key for this credit (8-64 letters, digits, dashes); repeating a request with the same key adds "
+        "nothing. Default: a new one.",
+    ),
+    yes: bool = YES_OPTION,
+) -> None:
+    """Add promotional credit to an account.
+
+    Example: corethink admin add-credit ana@acme.com 50 --note "Pilot credit"
+    """
+    if not 0 < usd <= 1000:
+        ui.error("Give an amount from $0.01 to $1,000.")
+        raise typer.Exit(2)
+    if not note.strip():
+        ui.error("Add a short note.")
+        raise typer.Exit(2)
+    if key is not None and not re.fullmatch(r"[A-Za-z0-9-]{8,64}", key):
+        ui.error("--key: use 8 to 64 letters, digits or dashes.")
+        raise typer.Exit(2)
+    found = _find_account(who)
+    ui.confirm(f"Add {ui.usd(usd)} to {found.get('email')} ({note.strip()})?", yes=yes)
+    body = {"usd": round(usd, 2), "note": note.strip(), "key": key or str(uuid.uuid4())}
+    done = _call("POST", f"/api/v1/admin/accounts/{found['uid']}/credit", body)
+
+    def human() -> None:
+        if done.get("repeated"):
+            ui.warn(
+                f"That credit was already added (same key): nothing more was added. Balance {ui.usd(done.get('balanceUsd'))}."
+            )
+        else:
+            ui.success(f"Added {ui.usd(usd)} to {found.get('email')}. Balance {ui.usd(done.get('balanceUsd'))}.")
+
+    ui.emit({"uid": found["uid"], "email": found.get("email"), "key": body["key"], **done}, human)
+
+
+@app.command("limits")
+def limits(
+    who: str = typer.Argument(..., metavar="ACCOUNT", help="The account's email or ID."),
+    pairs: list[str] = typer.Argument(  # noqa: B008
+        None,
+        metavar="[KEY=VALUE]...",
+        help="Limits to set; VALUE `default` uses the value for everyone.",
+    ),
+    yes: bool = YES_OPTION,
+) -> None:
+    """Show an account's own limits, or set them.
+
+    Example: corethink admin limits ana@acme.com maxRunningJobs=5 maxBudgetUsd=default
+    """
+    found = _find_account(who)
+    current = _call("GET", f"/api/v1/admin/accounts/{found['uid']}").get("limits") or {}
+    if not pairs:
+        ui.emit(current, lambda: _account_limits_table(current.get("limits") or []))
+        return
+    rows = current.get("limits") or []
+    known = [row["key"] for row in rows] or list(LIMIT_LABEL)
+    values = _limit_keys(known, pairs)
+    ui.confirm(
+        f"Set for {found.get('email')}: {_change_text(values, {row['key']: row.get('unit') for row in rows})}?",
+        yes=yes,
+    )
+    saved = _call("POST", f"/api/v1/admin/accounts/{found['uid']}/limits", {"values": values})
+
+    def human() -> None:
+        ui.success(f"Saved {found.get('email')}'s limits.")
+        _account_limits_table(saved.get("limits") or [])
+
+    ui.emit(saved, human)
+
+
+# ---- settings ----------------------------------------------------------------------------------------------------------
+
+
+def _settings_table(data: dict[str, Any]) -> None:
+    ui.table(
+        data.get("limits") or [],
+        [
+            ("Limit", lambda x: LIMIT_LABEL.get(x.get("key", ""), x.get("key"))),
+            ("Key", "key"),
+            (
+                "Value",
+                lambda x: _limit_text(x.get("unit"), x.get("value")) + ("" if x.get("saved") else " (default)"),
+            ),
+            ("Default", lambda x: _limit_text(x.get("unit"), x.get("default"))),
+            (
+                "Allowed",
+                lambda x: f"{_limit_text(x.get('unit'), x.get('min'))} to {_limit_text(x.get('unit'), x.get('max'))}",
+            ),
+            ("Per account", lambda x: "yes" if x.get("perAccount") else "no"),
+        ],
+        empty="No limits.",
+    )
+    if data.get("updatedBy"):
+        ui.info(f"Last changed by {data['updatedBy']} {ui.ago(data.get('updatedAt'))}.")
+
+
+@settings_app.callback(invoke_without_command=True)
+def settings_show(ctx: typer.Context) -> None:
+    """Account limits for everyone: welcome credit, runs at once, run spending limits.
+
+    Change them with `corethink admin settings set KEY=VALUE…`.
+    """
+    if ctx.invoked_subcommand is not None:
+        return
+    data = _call("GET", "/api/v1/admin/settings")
+    ui.emit(data, lambda: _settings_table(data))
+
+
+@settings_app.command("set")
+def settings_set(
+    pairs: list[str] = typer.Argument(  # noqa: B008
+        ..., metavar="KEY=VALUE...", help="VALUE `default` goes back to the default."
+    ),
+    yes: bool = YES_OPTION,
+) -> None:
+    """Change limits for every account; limits left out stay as they are.
+
+    Example: corethink admin settings set signupCreditUsd=10 maxRunningJobs=3
+    """
+    current = _call("GET", "/api/v1/admin/settings")
+    rows = current.get("limits") or []
+    known = [row["key"] for row in rows] or list(LIMIT_LABEL)
+    values = _limit_keys(known, pairs)
+    ui.confirm(
+        f"Change for every account: {_change_text(values, {row['key']: row.get('unit') for row in rows})}?",
+        yes=yes,
+    )
+    saved = _call("POST", "/api/v1/admin/settings", {"values": values})
+
+    def human() -> None:
+        ui.success("Saved.")
+        _settings_table(saved)
+
+    ui.emit(saved, human)
+
+
+# ---- runs ----------------------------------------------------------------------------------------------------------------
+
+
+@app.command("runs")
+def runs(
+    qa: bool = typer.Option(False, "--qa", help="Include test accounts' runs (marked QA)."),
+    status: str = typer.Option(None, "--status", help="Only running, queued, succeeded or failed runs."),
+    search: str = typer.Option(
+        None,
+        "--search",
+        "-s",
+        help="Only runs whose person, workspace or environment contains this.",
+    ),
+    limit: int = typer.Option(50, "--limit", "-n", min=1, help="Show at most this many."),
+) -> None:
+    """Every workspace's runs, newest first.
+
+    Example: corethink admin runs --status failed
+    """
+    if status is not None and status.lower() not in RUN_FILTERS:
+        ui.error(f"--status: use one of {', '.join(RUN_FILTERS)}.")
+        raise typer.Exit(2)
+    data = _call("GET", "/api/v1/admin/runs", qa=1 if qa else None)
+    every = data.get("runs") or []
+    needle = (search or "").casefold()
+
+    def keep(run: dict[str, Any]) -> bool:
+        if status and RUN_STATE.get(str(run.get("state", "")).upper(), ("", ""))[1] != status.lower():
+            return False
+        return not needle or any(
+            needle in str(run.get(k) or "").casefold()
+            for k in ("by", "workspaceName", "workspace", "environment", "jobId")
+        )
+
+    matched = [r for r in every if keep(r)]
+    shown = matched[:limit]
+
+    def human() -> None:
+        ui.table(
+            shown,
+            [
+                ("Job", lambda r: ui.short_id(r.get("jobId"))),
+                ("Who", lambda r: ("QA · " if r.get("qa") else "") + str(r.get("by") or "—")),
+                ("Workspace", lambda r: r.get("workspaceName") or r.get("workspace")),
+                ("Environment", "environment"),
+                ("Kind", "kind"),
+                ("Status", _run_state),
+                ("Stage", "stage"),
+                (
+                    "Spent",
+                    lambda r: f"{ui.usd(r.get('spentUsd'))} / {ui.usd(r.get('budgetUsd'), 0)}",
+                ),
+                ("Started", lambda r: ui.when(r.get("startedAt") or r.get("submittedAt"))),
+            ],
+            empty="No runs match.",
+        )
+        notes = [f"{len(shown)} of {len(matched)} runs"]
+        if data.get("hiddenTestRuns") and not qa:
+            notes.append(f"{data['hiddenTestRuns']} test-account runs hidden (--qa shows them)")
+        if data.get("capped"):
+            notes.append("only the newest runs were read")
+        ui.info(" · ".join(notes))
+        if data.get("problem"):
+            ui.warn(f"Runs could not all be read: {data['problem']}")
+
+    ui.emit({**data, "runs": shown}, human)
+
+
+@app.command("logs")
+def logs(
+    job_id: str = typer.Argument(..., help="The run's job ID (or its start)."),
+    output: Path = typer.Option(  # noqa: B008
+        None,
+        "--output",
+        "-o",
+        help="Where to save the .tar.gz (default run-<job>-logs.tar.gz here); - for stdout.",
+    ),
+) -> None:
+    """Download a run's logs (its record, hold and log files) as one .tar.gz, from any workspace."""
+    job = job_id.strip().lower()
+    if not JOB_ID.fullmatch(job):
+        every = _call("GET", "/api/v1/admin/runs", qa=1).get("runs") or []
+        job = _pick([r for r in every if str(r.get("jobId", "")).startswith(job)], "run", job_id)["jobId"]
+    path = f"/api/v1/admin/runs/{job}/logs"
+    try:
+        if output is not None and str(output) == "-":
+            with client().stream("GET", path) as response:
+                for chunk in response.iter_bytes():
+                    sys.stdout.buffer.write(chunk)
+            sys.stdout.buffer.flush()
+            return
+        target = output or Path(f"run-{job}-logs.tar.gz")
+        saved = client().download(path, target)
+    except ApiError as problem:
+        raise _denied(problem) from None
+    size = saved.stat().st_size
+    ui.emit(
+        {"jobId": job, "path": str(saved), "bytes": size},
+        lambda: ui.success(f"Saved the logs of {ui.short_id(job)} to {saved} ({size:,} bytes)."),
+    )
+
+
+# ---- super admins ---------------------------------------------------------------------------------------------------------
+
+
+@superadmins_app.callback(invoke_without_command=True)
+def superadmins_default(ctx: typer.Context) -> None:
+    """Who can use the admin commands and page (team owners always can)."""
+    if ctx.invoked_subcommand is None:
+        superadmins_list()
+
+
+@superadmins_app.command("list")
+def superadmins_list() -> None:
+    """The super admins."""
+    data = _call("GET", "/api/v1/admin/superadmins")
+    you = data.get("you")
+
+    def human() -> None:
+        ui.table(
+            data.get("admins") or [],
+            [
+                (
+                    "Email",
+                    lambda a: str(a.get("email")) + (" (you)" if a.get("email") == you else ""),
+                ),
+                (
+                    "Status",
+                    lambda a: "team owner" if a.get("owner") else "joined" if a.get("joined") else "not signed up yet",
+                ),
+                ("Added by", "addedBy"),
+                ("Added", lambda a: ui.when(a.get("addedAt"))),
+            ],
+            empty="No super admins.",
+        )
+
+    ui.emit(data, human)
+
+
+@superadmins_app.command("add")
+def superadmins_add(
+    email: str = typer.Argument(..., help="Their email address."),
+    notify: bool = typer.Option(False, "--notify", help="Also email them that they were added (off by default)."),
+) -> None:
+    """Make someone a super admin. They get access once they sign up with this email."""
+    done = _call("POST", "/api/v1/admin/superadmins", {"email": email.strip(), "notify": notify})
+    ui.emit(
+        done,
+        lambda: ui.success(
+            f"{email.strip()} is a super admin. {'Email sent.' if done.get('emailed') else 'No email sent.'}"
+        ),
+    )
+
+
+@superadmins_app.command("remove")
+def superadmins_remove(
+    email: str = typer.Argument(..., help="Their email address."),
+    yes: bool = YES_OPTION,
+) -> None:
+    """Take away someone's super admin access."""
+    ui.confirm(f"Remove {email.strip()} as a super admin?", yes=yes)
+    done = _call("DELETE", "/api/v1/admin/superadmins", {"email": email.strip()})
+    ui.emit(
+        {"email": email.strip(), **done},
+        lambda: ui.success(f"{email.strip()} is no longer a super admin."),
+    )
+
+
+# ---- waitlist (read only) ---------------------------------------------------------------------------------------------------
+
+
+@app.command("waitlist")
+def waitlist(
+    pending: bool = typer.Option(False, "--pending", help="Only people not sent the beta email yet."),
+) -> None:
+    """The waitlist: who asked to join and who was sent the beta email (read only)."""
+    data = _call("GET", "/api/v1/waitlist")
+    entries = [e for e in data.get("entries") or [] if not pending or not e.get("invitedAt")]
+
+    def human() -> None:
+        ui.fields([("Sign-up", "open to everyone" if data.get("open") else "invite only")])
+        ui.out.print()
+        ui.table(
+            entries,
+            [
+                ("Email", lambda e: str(e.get("email")) + (" (test)" if e.get("test") else "")),
+                ("From", "source"),
+                ("Joined", lambda e: ui.when(e.get("at"))),
+                (
+                    "Sent the beta email",
+                    lambda e: ui.when(e.get("invitedAt")) if e.get("invitedAt") else "not yet",
+                ),
+            ],
+            empty="No one is waiting." if pending else "The waitlist is empty.",
+        )
+
+    ui.emit({**data, "entries": entries}, human)
+
+
+app.add_typer(settings_app, name="settings")
+app.add_typer(superadmins_app, name="superadmins")
+
+
+def register(root: typer.Typer) -> None:
+    root.add_typer(app, name="admin", rich_help_panel="Admin")