lighthouse-cli 0.16.0__py3-none-any.whl

lighthouse/commands/language.py

@@ -0,0 +1,56 @@
+# Copyright 2026 Atlantic Agentic Labs. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+"""`lighthouse language`: the language this CLI, the portal, MCP and the
+assistant speak to you (contract 1.29).
+
+    lighthouse language              your setting, your organisation's, and what is in use
+    lighthouse language --list       only the languages on offer
+
+Read only. A person sets their own language in the portal under Preferences
+(and a client administrator the organisation's under Settings): a delegated
+token reads `/api/v1/me/preferences` but never writes it, as it never writes
+anything but a deploy and a collector request (`oauth.ROUTE_SCOPES`). For one
+run, `--lang` or `LIGHTHOUSE_LANG` wins. The effective language is kept
+beside the profile file so the next run speaks it without a request (i18n.py).
+"""
+from __future__ import annotations
+
+import argparse
+from typing import Any
+
+from lighthouse import i18n
+from lighthouse.main import Command, Context
+from lighthouse.out import Out
+
+
+def _configure(ap: argparse.ArgumentParser) -> None:
+    ap.add_argument("--list", action="store_true", dest="list_all", help="only list the languages on offer")
+
+
+def language(ctx: Context) -> dict[str, Any]:
+    got = ctx.client().get("/api/v1/me/preferences")
+    effective = (got.get("effective") or {}).get("language")
+    i18n.remember(ctx.config.path.parent, ctx.host, effective)
+    return {"ok": True, "language": (got.get("preferences") or {}).get("language"),
+            "tenant_language": (got.get("tenant") or {}).get("language"),
+            "effective": effective, "in_use": i18n.current(),
+            "list_only": bool(ctx.args.list_all),
+            "supported_languages": got.get("supported_languages") or []}
+
+
+def _show(out: Out, body: dict[str, Any]) -> None:
+    names = {x["tag"]: x["name_native"] for x in body["supported_languages"]}
+
+    def named(tag: str | None) -> str | None:
+        return None if tag is None else f"{tag}  {names.get(tag, '')}".rstrip()
+
+    if not body.get("list_only"):
+        out.pairs([("your language", named(body["language"])),
+                   ("your organisation's", named(body["tenant_language"])),
+                   ("in use now", named(body["in_use"]))])
+        out.say("")
+    out.table(["tag", "language"], [[x["tag"], x["name_native"]] for x in body["supported_languages"]])
+
+
+COMMANDS = (Command("language", "your language, and the languages on offer",
+                    _configure, language, _show),)

lighthouse/commands/limits.py

@@ -0,0 +1,61 @@
+# Copyright 2026 Atlantic Agentic Labs. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+"""`lighthouse limits`: the spend limits in force, and whether they reached the engines.
+
+    lighthouse limits
+    lighthouse limits --json
+
+Reads `GET /api/v1/limits`: each limit's scope (`scope_kind` and `scope`),
+its period, its cap (`cap_usd`), what has been spent against it (`spent_usd`,
+`pct`), its alert thresholds, and **whether each deployment has applied it**
+(`deliveries`) — which is the column that matters,
+because a limit the engine has not picked up is not yet a limit.
+
+Limits are **read only** from the command line. Raising a cap is a payment
+decision, and a delegated credential never makes one
+(`docs/adr/0012-delegated-credentials.md`); change them in the portal, where
+the change is audited against a person.
+"""
+from __future__ import annotations
+
+import argparse
+from typing import Any
+
+from lighthouse.main import Command, Context
+from lighthouse.out import Out
+
+
+def _configure(ap: argparse.ArgumentParser) -> None:
+    ap.add_argument("--scope", help="only limits of this scope kind")
+
+
+def limits(ctx: Context) -> dict[str, Any]:
+    body = ctx.client().get("/api/v1/limits")
+    rows = body.get("limits") or []
+    if ctx.args.scope:
+        rows = [r for r in rows if r.get("scope_kind") == ctx.args.scope]
+    return {"ok": True, **body, "limits": rows}
+
+
+def _applied(limit: dict[str, Any]) -> str:
+    """`applied/total` deployments. A limit that is enforced by LightHouse
+    itself is never sent to a gateway, so it has no deliveries to count."""
+    if limit.get("enforced_by") == "platform":
+        return "LightHouse"
+    sent = limit.get("deliveries") or []
+    return f"{sum(1 for d in sent if d.get('status') == 'applied')}/{len(sent)}"
+
+
+def _show(out: Out, body: dict[str, Any]) -> None:
+    out.table(["scope", "what", "period", "cap", "spent", "used %", "state", "alerts at %",
+               "applied by"],
+              [[r.get("scope_kind"), r.get("scope"), r.get("period"), r.get("cap_usd"),
+                r.get("spent_usd"), r.get("pct"), r.get("state"),
+                ", ".join(str(a) for a in r.get("alert_pcts") or []), _applied(r)]
+               for r in body["limits"]])
+    out.note("a limit no deployment has applied is not yet in force; "
+             "change limits in the portal, where the change is audited")
+
+
+COMMANDS = (Command("limits", "the spend limits in force, and whether the engines applied them",
+                    _configure, limits, _show),)

lighthouse/commands/login.py

@@ -0,0 +1,207 @@
+# Copyright 2026 Atlantic Agentic Labs. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+"""`lighthouse login`, `logout` and `tokens`.
+
+    lighthouse login --host t7m2kqx9vbn.atlanticagenticlabs.com
+    lighthouse login --scope "telemetry:read agents:read knowledge:read"
+    lighthouse logout [--all]
+    lighthouse tokens              # every delegated token of mine, and revoke one
+
+`login` runs the device flow (device.py), stores the token in the OS keychain
+(credentials.py), remembers the host in the profile file (config.py), and then
+reads `/api/v1/me` so it can say who you are rather than only that it worked.
+
+Where the tenant sits behind Cloudflare Access, `login` can keep the tenant's
+Access service token in the keychain with the delegated token:
+`--access-client-id ID` and the secret from `--access-client-secret-stdin` (one
+line on standard input) or `LIGHTHOUSE_ACCESS_CLIENT_SECRET`. The secret is never
+a command-line argument, where `ps` and shell history would keep it. The OAuth
+endpoints are not behind Access, so the sign-in itself needs none; the calls
+after it do.
+
+For a pipeline use a machine key instead: `LIGHTHOUSE_TOKEN=aalcp-...` with
+`LIGHTHOUSE_ACCESS_CLIENT_ID` and `LIGHTHOUSE_ACCESS_CLIENT_SECRET`. A delegated
+token lasts eight hours and is not refreshed under `LIGHTHOUSE_TOKEN`.
+
+It never prints the token. Under `--json` the document carries the person, the
+host, the scopes and the expiry — and no credential, which `tests/test_out.py`
+and the golden test both hold it to.
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import Any
+
+from lighthouse import device
+from lighthouse.credentials import ENV_ACCESS_ID, ENV_ACCESS_SECRET, access_from_env
+from lighthouse.exits import FORBIDDEN, USAGE, CliError
+from lighthouse.http import Refused
+from lighthouse.i18n import t
+from lighthouse.main import Command, Context
+from lighthouse.out import Out
+
+
+def _configure_login(ap: argparse.ArgumentParser) -> None:
+    ap.add_argument("--scope", help="the scopes to ask for, space separated "
+                                    "(default: telemetry:read agents:read)")
+    ap.add_argument("--no-browser", action="store_true", dest="no_browser",
+                    help="print the URL instead of opening a browser")
+    ap.add_argument("--name", default="the lighthouse CLI",
+                    help="how this sign-in is described in the portal and the audit log")
+    ap.add_argument("--access-client-id", dest="access_client_id", metavar="ID",
+                    help="the tenant's Cloudflare Access service token id, to keep with "
+                         "the sign-in (the secret: --access-client-secret-stdin)")
+    ap.add_argument("--access-client-secret-stdin", action="store_true",
+                    dest="access_secret_stdin",
+                    help="read the Access service token secret from one line of standard input")
+
+
+def _access(ctx: Context) -> tuple[str, str] | None:
+    """The Access service token for this login: the flag and stdin, else the
+    environment. Never a secret on the command line."""
+    given = (getattr(ctx.args, "access_client_id", None) or "").strip()
+    if getattr(ctx.args, "access_secret_stdin", False):
+        secret = ((ctx.stdin if ctx.stdin is not None else sys.stdin).readline()).strip()
+        if not secret:
+            raise CliError(t("err.access_secret_empty"), code=USAGE, error="usage")
+        if not given:
+            given = (ctx.env.get(ENV_ACCESS_ID) or "").strip()
+        if not given:
+            raise CliError(t("err.access_id_missing"), code=USAGE, error="usage",
+                           hint=t("hint.access_id_missing", id=ENV_ACCESS_ID))
+        return given, secret
+    if given:
+        secret = (ctx.env.get(ENV_ACCESS_SECRET) or "").strip()
+        if not secret:
+            raise CliError(t("err.access_secret_missing"), code=USAGE, error="usage",
+                           hint=t("hint.access_secret_missing", secret=ENV_ACCESS_SECRET))
+        return given, secret
+    return access_from_env(ctx.env)
+
+
+def login(ctx: Context) -> dict[str, Any]:
+    host = ctx.host
+    access = _access(ctx)
+    anonymous = ctx.new_client(host, None, access=access)
+    try:
+        token = device.sign_in(
+            anonymous, out=ctx.out, scope=getattr(ctx.args, "scope", None),
+            client_name=ctx.args.name, no_browser=bool(ctx.args.no_browser),
+            assume_yes=bool(getattr(ctx.args, "yes", False)),
+            no_input=bool(getattr(ctx.args, "no_input", False)),
+            opener=ctx.opener, sleep=ctx.sleep, reader=ctx.reader)
+    finally:
+        anonymous.close()
+    access_id, access_secret = access if access else (None, None)
+    credential = ctx.store.save(host, token, access_client_id=access_id,
+                                access_client_secret=access_secret)
+    ctx.config.remember(host)
+    with ctx.new_client(host, credential) as client:
+        me = client.get("/api/v1/me")
+    viewer = me.get("viewer") or {}
+    credential = ctx.store.save(host, token, email=viewer.get("email"),
+                                access_client_id=access_id, access_client_secret=access_secret)
+    return {"ok": True, "host": host, "access_service_token": access is not None,
+            "client": (me.get("client") or {}).get("name"),
+            "email": viewer.get("email"), "role": viewer.get("role"),
+            "scopes": list(credential.scopes),
+            "expires_at": credential.expires_at.isoformat() if credential.expires_at else None}
+
+
+def _show_login(out: Out, body: dict[str, Any]) -> None:
+    out.done(t("login.signed_in", tenant=body["client"] or body["host"], email=body["email"],
+               role=body["role"]))
+    out.note(t("login.scopes", scopes=" ".join(body["scopes"]) or t("login.no_scopes")))
+    out.note(t("login.in_keychain"))
+    if body.get("access_service_token"):
+        out.note(t("login.access_kept"))
+
+
+def _configure_logout(ap: argparse.ArgumentParser) -> None:
+    ap.add_argument("--all", action="store_true", dest="every",
+                    help="forget every host, not only the current one")
+
+
+def logout(ctx: Context) -> dict[str, Any]:
+    """Revoke at the service *and* forget locally.
+
+    Revoking first matters: a credential only deleted from this machine is
+    still live until it expires, and `logout` is exactly what somebody runs on
+    a laptop they are handing back.
+    """
+    hosts = sorted({p.host for p in ctx.config.profiles.values()}) \
+        if getattr(ctx.args, "every", False) else [ctx.host]
+    out = []
+    for host in hosts:
+        credential = ctx.store.load(host)
+        revoked = False
+        if credential is not None and credential.source == "keychain":
+            with ctx.new_client(host, credential) as client:
+                try:
+                    client.post("/api/v1/oauth/revoke",
+                                {"token": credential.refresh_token or credential.access_token})
+                    revoked = True
+                except CliError as e:
+                    ctx.out.warn(t("logout.could_not_revoke", host=host, error=e.error))
+        ctx.store.forget(host)
+        ctx.config.forget(host)
+        out.append({"host": host, "revoked": revoked,
+                    "had_credential": credential is not None})
+    return {"ok": True, "logged_out": out}
+
+
+def _show_logout(out: Out, body: dict[str, Any]) -> None:
+    for row in body["logged_out"]:
+        if not row["had_credential"]:
+            out.say(t("logout.nothing_stored", host=row["host"]))
+        elif row["revoked"]:
+            out.done(t("logout.revoked", host=row["host"]))
+        else:
+            out.say(t("logout.forgotten", host=row["host"]))
+
+
+def _configure_tokens(ap: argparse.ArgumentParser) -> None:
+    ap.add_argument("--revoke", metavar="TOKEN_ID",
+                    help="revoke one of your own tokens by its id")
+
+
+def tokens(ctx: Context) -> dict[str, Any]:
+    credential = ctx.store.require(ctx.host)
+    if credential.kind == "machine":
+        # A machine key has no person behind it, so no delegated tokens of its
+        # own: the service answers 403 invalid_client. Say so without asking it.
+        raise CliError(t("err.machine_key_no_tokens"), code=FORBIDDEN, error="machine_key",
+                       hint=t("hint.machine_key_no_tokens"))
+    client = ctx.client()
+    if ctx.args.revoke:
+        if not ctx.confirm(t("prompt.revoke_token", token=ctx.args.revoke)):
+            raise CliError(t("err.not_revoked"), error="declined")
+        client.delete(f"/api/v1/oauth/tokens/{ctx.args.revoke}")
+        return {"ok": True, "revoked": ctx.args.revoke}
+    try:
+        return {"ok": True, **client.get("/api/v1/oauth/tokens")}
+    except Refused as e:
+        if e.error == "invalid_client":
+            raise CliError(t("err.no_tokens_to_list"), code=FORBIDDEN,
+                           error="machine_key") from None
+        raise
+
+
+def _show_tokens(out: Out, body: dict[str, Any]) -> None:
+    if "revoked" in body:
+        out.done(t("tokens.revoked", token=body["revoked"]))
+        return
+    out.table(["token", "client", "scopes", "issued", "expires", "last used"],
+              [[t["token_id"], t.get("client_name") or t["client"], " ".join(t["scopes"]), t["issued_at"],
+                t["expires_at"], t["last_used_at"]] for t in body["tokens"]])
+
+
+COMMANDS = (
+    Command("login", "sign in through the browser with a device code",
+            _configure_login, login, _show_login, anonymous=True),
+    Command("logout", "revoke this machine's token and forget it",
+            _configure_logout, logout, _show_logout),
+    Command("tokens", "your delegated tokens, and revoke one",
+            _configure_tokens, tokens, _show_tokens),
+)

lighthouse/commands/models.py

@@ -0,0 +1,61 @@
+# Copyright 2026 Atlantic Agentic Labs. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+"""`lighthouse models`: the model library, with its evidence scores.
+
+    lighthouse models
+    lighthouse models --provider bedrock
+    lighthouse models --json | jq '.items[] | select(.state == "available") | .model'
+
+Reads `GET /api/v1/models`. Price cards are shown to a client administrator and
+to AAL staff only, and the service decides that, not this command: a viewer's
+output simply has no prices in it (`prices_visible` says which).
+"""
+from __future__ import annotations
+
+import argparse
+from typing import Any
+
+from lighthouse.main import Command, Context
+from lighthouse.out import Out
+
+
+def _configure(ap: argparse.ArgumentParser) -> None:
+    ap.add_argument("--task", help="accepted for compatibility; the library is not ranked "
+                                   "per task by the service, so it changes nothing")
+    ap.add_argument("--provider", help="only this provider's models")
+
+
+def models(ctx: Context) -> dict[str, Any]:
+    body = ctx.client().get_all("/api/v1/models", "items")
+    rows = body.get("items") or []
+    # The route takes no filter, so this narrows the answer here.
+    if ctx.args.provider:
+        rows = [m for m in rows if m.get("provider") == ctx.args.provider]
+    if ctx.args.task:
+        ctx.out.warn("--task has no effect: the service does not rank the library per task")
+    return {"ok": True, **body, "items": rows}
+
+
+def _show(out: Out, body: dict[str, Any]) -> None:
+    rows = body.get("items") or []
+    visible = bool(body.get("prices_visible"))
+    headers = ["model", "provider", "family", "state", "evals", "calls (month)"]
+    if visible:
+        headers += ["input /M", "output /M"]
+    table = []
+    for m in rows:
+        evals = m.get("evals") or []
+        row = [m.get("model"), m.get("provider"), m.get("family"), m.get("state"),
+               f"{sum(1 for e in evals if e.get('passed'))}/{len(evals)} passed",
+               m.get("calls_month")]
+        if visible:
+            price = m.get("price") or {}
+            row += [price.get("input_per_m"), price.get("output_per_m")]
+        table.append(row)
+    out.table(headers, table)
+    if visible:
+        out.note("prices are per million tokens, in the provider's own currency")
+
+
+COMMANDS = (Command("models", "the model library and its evidence scores",
+                    _configure, models, _show),)

lighthouse/commands/runs.py

@@ -0,0 +1,157 @@
+# Copyright 2026 Atlantic Agentic Labs. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+"""`lighthouse runs`: what is running now, and what ran.
+
+    lighthouse runs                       # the last runs
+    lighthouse runs tail                  # live, one line per change
+    lighthouse runs tail --once --json    # one snapshot, for a pipeline
+    lighthouse runs show <run_id_hash>
+
+`tail` follows `GET /api/v1/runs/active` (contract 1.12): the live runs, each
+with its current step, its tokens so far and its estimated cost. It polls at
+`--interval` seconds rather than holding a server-sent-events stream, because
+a poll survives a laptop lid, a corporate proxy and a CI runner's idle timeout,
+and the read is cheap — the service answers it from the tenant's data version
+(`store.query_cached`).
+
+Under `--json`, `tail` writes **one JSON object per line** (JSON Lines) rather
+than one document, so `lighthouse runs tail --json | jq -c .` streams. With
+`--once` it writes a single document instead, which is the shape a pipeline
+step wants. Both are covered by the golden test.
+
+`--fail-on-stall` makes it exit 1 if a run has not been seen for
+`stall_after_s`, which is the useful thing to put in a smoke job after a
+deploy.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import time
+from typing import Any
+
+from lighthouse.exits import FAILED, CliError
+from lighthouse.flags import inherited
+from lighthouse.main import Command, Context
+from lighthouse.out import Out
+
+
+def _configure(ap: argparse.ArgumentParser) -> None:
+    sub = ap.add_subparsers(dest="runs_command", metavar="<subcommand>")
+    listing = sub.add_parser("list", parents=[inherited()], help="the last runs (the default)")
+    listing.add_argument("--limit", type=int, default=20)
+    listing.add_argument("--pack")
+    listing.add_argument("--status")
+    show = sub.add_parser("show", parents=[inherited()], help="one run")
+    show.add_argument("run", help="its run_id_hash")
+    show.add_argument("--map", action="store_true", dest="as_map",
+                      help="the run map: every step, model call and retrieval")
+    tail = sub.add_parser("tail", parents=[inherited()], help="follow the live runs")
+    tail.add_argument("--interval", type=float, default=5.0, help="seconds between polls")
+    tail.add_argument("--once", action="store_true", help="one snapshot, then stop")
+    tail.add_argument("--for", type=float, dest="duration", default=None,
+                      help="stop after this many seconds")
+    tail.add_argument("--deployment", help="only this deployment's runs")
+    tail.add_argument("--fail-on-stall", action="store_true", dest="fail_on_stall",
+                      help="exit 1 if a run has stalled")
+
+
+def _line(run: dict[str, Any]) -> list[Any]:
+    step = (run.get("current_step") or {}).get("name")
+    tokens = run.get("tokens") or {}
+    return [run.get("run_id_hash"), run.get("agent"), run.get("state"), step,
+            f"{tokens.get('input', 0)}/{tokens.get('output', 0)}",
+            run.get("cost_usd"), f"{round((run.get('elapsed_ms') or 0) / 1000)}s"]
+
+
+def _row(run: dict[str, Any]) -> list[Any]:
+    """A finished run, as `GET /api/v1/runs` lists it: no tokens or cost, which
+    belong to the live view (`_line`) and to `runs show --map`."""
+    agent = f"{run.get('pack')}:{run.get('card')}" if run.get("card") else run.get("pack")
+    return [run.get("run_id_hash"), agent, run.get("started_at"), run.get("status"),
+            run.get("duration_ms"), run.get("attempts"), run.get("trigger")]
+
+
+def _stalled(body: dict[str, Any]) -> list[str]:
+    return [r["run_id_hash"] for r in (body.get("runs") or [])
+            if r.get("state") == "stalled"]
+
+
+def tail(ctx: Context) -> dict[str, Any]:
+    client = ctx.client()
+    out = ctx.out
+    interval = max(0.5, float(ctx.args.interval))
+    sleep = ctx.sleep or time.sleep
+    clock = time.monotonic
+    # `--for 0` means one poll, so this tests `is not None` rather than truth.
+    duration = getattr(ctx.args, 'duration', None)
+    deadline = None if duration is None else clock() + duration
+    seen: dict[str, str] = {}
+    snapshots = 0
+    last: dict[str, Any] = {}
+    while True:
+        last = client.get("/api/v1/runs/active", deployment=ctx.args.deployment)
+        snapshots += 1
+        rows = last.get("runs") or []
+        if ctx.args.once:
+            break
+        for run in rows:
+            key = str(run.get("run_id_hash"))
+            fingerprint = json.dumps([run.get("state"),
+                                      (run.get("current_step") or {}).get("name"),
+                                      run.get("steps")], sort_keys=True)
+            if seen.get(key) == fingerprint:
+                continue            # nothing changed: a tail should not repeat itself
+            seen[key] = fingerprint
+            if out.as_json:
+                out.json_line({"as_of": last.get("as_of"), **run})
+            else:
+                out.say("  ".join("" if c is None else str(c) for c in _line(run)))
+        if deadline is not None and clock() >= deadline:
+            break
+        sleep(interval)
+    stalled = _stalled(last)
+    if ctx.args.fail_on_stall and stalled:
+        raise CliError(f"{len(stalled)} run(s) have stalled", code=FAILED, error="stalled",
+                       stalled=stalled)
+    return {"ok": True, "streamed": not ctx.args.once, "snapshots": snapshots,
+            "as_of": last.get("as_of"), "stall_after_s": last.get("stall_after_s"),
+            "live": last.get("live"), "runs": last.get("runs") or [], "stalled": stalled}
+
+
+def runs(ctx: Context) -> dict[str, Any]:
+    which = getattr(ctx.args, "runs_command", None) or "list"
+    if which == "tail":
+        return tail(ctx)
+    client = ctx.client()
+    if which == "show":
+        path = f"/api/v1/runs/{ctx.args.run}"
+        if ctx.args.as_map:
+            path += "/map"
+        return {"ok": True, **client.get(path)}
+    rows = list(client.each("/api/v1/runs", "runs", limit=ctx.args.limit,
+                            pack=ctx.args.pack, status=ctx.args.status))
+    return {"ok": True, "runs": rows}
+
+
+def _show(out: Out, body: dict[str, Any]) -> None:
+    if body.get("streamed"):
+        return      # `tail` printed as it went; nothing more to say
+    rows = body.get("runs")
+    if rows is not None and "snapshots" in body:         # `tail`: the live view
+        out.table(["run", "agent", "state", "step", "tokens in/out", "estimated cost", "elapsed"],
+                  [_line(r) for r in rows])
+        if body.get("stalled"):
+            out.warn(f"stalled: {', '.join(body['stalled'])}")
+        out.note("every cost figure is estimated")
+        return
+    if rows is not None:
+        out.table(["run", "agent", "started", "status", "took (ms)", "attempts", "trigger"],
+                  [_row(r) for r in rows])
+        return
+    out.pairs([(k, v) for k, v in body.items()
+               if k != "ok" and not isinstance(v, (list, dict))])
+
+
+COMMANDS = (Command("runs", "what is running now, and what ran",
+                    _configure, runs, _show),)

lighthouse/commands/spend.py

@@ -0,0 +1,84 @@
+# Copyright 2026 Atlantic Agentic Labs. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+"""`lighthouse spend`: what was spent, what it is heading for, what was saved.
+
+    lighthouse spend                      # this month, by day
+    lighthouse spend --by model
+    lighthouse spend --month 2026-10 --json
+    lighthouse spend --forecast
+    lighthouse spend --savings
+
+Reads `GET /api/v1/billing/usage` (contract 1.6) and, with `--forecast`, the
+month-end projection, and with `--savings` the estimated headline. Figures come
+back in the provider's own currency with the caller's display currency beside
+them, as the API returns them; this command converts nothing itself, because a
+CLI quietly applying its own exchange rate is how two reports of the same month
+come to disagree.
+
+**Every saving figure says "estimated"**, here as everywhere.
+"""
+from __future__ import annotations
+
+import argparse
+from typing import Any
+
+from lighthouse.main import Command, Context
+from lighthouse.out import Out
+
+GROUPS = ("day", "model", "pack", "agent", "connection")
+
+
+def _configure(ap: argparse.ArgumentParser) -> None:
+    ap.add_argument("--by", choices=GROUPS, default="day", help="how to group")
+    ap.add_argument("--month", help="YYYY-MM; the current month by default")
+    ap.add_argument("--forecast", action="store_true",
+                    help="the month-end projection against the cap as well")
+    ap.add_argument("--savings", action="store_true",
+                    help="the estimated savings headline as well")
+
+
+def spend(ctx: Context) -> dict[str, Any]:
+    client = ctx.client()
+    out: dict[str, Any] = {"ok": True, "group_by": ctx.args.by,
+                           **client.get("/api/v1/billing/usage",
+                                        month=ctx.args.month, group_by=ctx.args.by)}
+    if ctx.args.forecast:
+        out["forecast"] = client.get("/api/v1/forecast")
+    if ctx.args.savings:
+        out["savings"] = client.get("/api/v1/savings/headline", period=ctx.args.month)
+    return out
+
+
+def _show(out: Out, body: dict[str, Any]) -> None:
+    rows = body.get("rows") or []
+    out.table([body["group_by"], "calls", "input tokens", "output tokens", "cost (USD)",
+               "managed charge"],
+              [[r.get("key"), r.get("calls"), r.get("input_tokens"), r.get("output_tokens"),
+                r.get("cost_usd"), r.get("charge_usd")] for r in rows])
+    total = body.get("total") or {}
+    if total:
+        out.say("")
+        out.pairs([("month", body.get("month")),
+                   ("total cost (USD)", total.get("cost_usd")),
+                   ("managed charge", total.get("charge_usd")),
+                   ("shown in", (body.get("display") or {}).get("currency"))])
+    forecast = body.get("forecast")
+    if forecast:
+        projection = forecast.get("projection") or {}
+        out.say("")
+        out.pairs([("projected month end (estimated)", projection.get("month_end_usd")),
+                   ("likely range (estimated)",
+                    f"{projection['low_usd']} to {projection['high_usd']}" if projection else None),
+                   ("against the cap", forecast.get("cap_usd")),
+                   ("status", forecast.get("status"))])
+    savings = body.get("savings")
+    if savings:
+        headline = savings.get("headline") or {}
+        out.say("")
+        out.pairs([("estimated saving this month", headline.get("usd")),
+                   ("in words", headline.get("sentence"))])
+    out.note("every saving and forecast figure is estimated")
+
+
+COMMANDS = (Command("spend", "what was spent, what it is heading for, what was saved",
+                    _configure, spend, _show),)