lighthouse-cli 0.16.0__py3-none-any.whl

lighthouse/__init__.py

@@ -0,0 +1,6 @@
+# Copyright 2026 Atlantic Agentic Labs. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+"""The `lighthouse` command line for LightHouse."""
+from __future__ import annotations
+
+__version__ = "0.16.0"

lighthouse/__main__.py

@@ -0,0 +1,9 @@
+# Copyright 2026 Atlantic Agentic Labs. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+"""`python -m lighthouse`, the same as the `lighthouse` script."""
+from __future__ import annotations
+
+from lighthouse.main import run
+
+if __name__ == "__main__":
+    run()

lighthouse/commands/agents.py

@@ -0,0 +1,310 @@
+# Copyright 2026 Atlantic Agentic Labs. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+"""`lighthouse agents`: list, inspect, scaffold, deploy, read logs, roll back.
+
+    lighthouse agents                              # every agent, with its state
+    lighthouse agents show research:summary
+    lighthouse agents init my-agent                # scaffold agent.toml here
+    lighthouse agents logs research:summary --limit 20
+    lighthouse agents deploy research:summary --version 1.4.0 --wait
+    lighthouse agents rollback research:summary --to 1.3.0
+
+**`init` is local and complete.** It writes an `agent.toml` next to you, with
+every field the pipeline will ask for and a comment on each: instructions, the
+knowledge bases, the tools, the model policy, the guardrails, the approvals and
+the evaluation set. Nothing is sent anywhere, so it works before you have
+signed in, and the file is what `deploy` will read.
+
+**`logs` is complete**: it reads the agent's runs (`GET /api/v1/runs`) and,
+with `--trace`, one run's spans, which is what anybody actually wants when an
+agent misbehaves.
+
+**`deploy` and `rollback` make a released version current** (the `deploy`
+scope: sign in with `lighthouse login --scope "telemetry:read agents:read
+deploy"`). Each sends `release.add` for the agent and version; rolling back is
+the same with an earlier version (`--to`, or the last version that passed its
+gate before the current one). The service decides what happens:
+
+- the version has passed its evaluation gate and your policy allows it: it
+  goes live, as you, and `--wait` follows the command until your deployment
+  says `applied` (or refused, or failed: exit 1);
+- otherwise nothing is sent: a **pending request** waits for a person to
+  approve it in LightHouse with their second factor (sign-off happens in
+  LightHouse and nowhere else, `docs/adr/0002-approvals-only-in-the-platform.md`).
+  The command prints where. `--wait` waits for that decision and then for
+  the command; rejected or expired is exit 1, still waiting at
+  `--wait-timeout` is exit 5.
+"""
+from __future__ import annotations
+
+import argparse
+import time
+from pathlib import Path
+from typing import Any
+
+from lighthouse.exits import FAILED, RETRY, USAGE, CliError
+from lighthouse.flags import inherited
+from lighthouse.main import Command, Context
+from lighthouse.out import Out
+
+SCAFFOLD = '''# An agent for LightHouse. `lighthouse agents deploy` reads this file.
+#
+# Everything here is checked before an agent runs: the model policy against the
+# model library's evidence scores, the knowledge bases against what this tenant
+# has indexed, the tools against the Cedar gate, and the evaluation set against
+# its own thresholds. A field left out takes the tenant's default, which the
+# portal's Deployments page shows.
+name = "{name}"
+description = "One sentence: what this agent is for."
+
+# Plain words. Retrieved text is evidence, never instruction: an agent is told
+# here what to do, and the gateway enforces what it may touch regardless.
+instructions = """
+You are …
+"""
+
+# Knowledge bases this agent may read, by index name (`lighthouse kb`).
+knowledge_bases = []
+
+# Tools, by name. Write access is a separate, named tool and sits behind an
+# approval; an agent never gains one by asking.
+tools = []
+
+[model]
+# A task class, so the router picks the cheapest model that meets the bar
+# (see https://docs.atlanticagenticlabs.com/). Pin one with `id` instead if you
+# must, and the run map will say you did.
+task = "summarise"
+# id = "…"
+max_output_tokens = 2048
+
+[guardrails]
+# A daily cap in the tenant's billing currency. The gateway enforces it in
+# code the model cannot reach.
+daily_spend_cap = 5.0
+refuse_outside_knowledge_bases = true
+
+[approvals]
+# Anything that acts outside LightHouse waits for a person. Sign-off is in
+# LightHouse and nowhere else.
+required_for = ["write", "send", "pay"]
+
+[evals]
+# The set this agent must pass before a version can be deployed. Paths are
+# relative to this file.
+set = "evals/"
+threshold = 0.8
+'''
+
+
+def _configure(ap: argparse.ArgumentParser) -> None:
+    sub = ap.add_subparsers(dest="agents_command", metavar="<subcommand>")
+    sub.add_parser("list", parents=[inherited()], help="every agent (the default)")
+    show = sub.add_parser("show", parents=[inherited()], help="one agent's configuration and last runs")
+    show.add_argument("agent", help="pack:card, e.g. research:summary")
+    init = sub.add_parser("init", parents=[inherited()], help="scaffold agent.toml in this directory")
+    init.add_argument("name", help="the agent's name")
+    init.add_argument("--file", default="agent.toml", help="where to write it")
+    init.add_argument("--force", action="store_true", help="overwrite an existing file")
+    logs = sub.add_parser("logs", parents=[inherited()], help="an agent's runs, and one run's steps")
+    logs.add_argument("agent")
+    logs.add_argument("--limit", type=int, default=20)
+    logs.add_argument("--status", help="only runs with this status")
+    logs.add_argument("--trace", metavar="RUN_ID_HASH", help="one run's spans instead")
+    deploy = sub.add_parser("deploy", parents=[inherited()],
+                            help="make a released version of an agent current (deploy scope)")
+    deploy.add_argument("agent", help="pack:card, e.g. research:summary")
+    deploy.add_argument("--version", required=True, help="the released version to make current")
+    _release_args(deploy)
+    rollback = sub.add_parser("rollback", parents=[inherited()],
+                              help="go back to an earlier released version (deploy scope)")
+    rollback.add_argument("agent", help="pack:card")
+    rollback.add_argument("--to", default=None,
+                          help="the version to go back to (default: the last one that passed "
+                               "its gate before the current one)")
+    _release_args(rollback)
+
+
+def _release_args(ap: argparse.ArgumentParser) -> None:
+    ap.add_argument("--deployment", help="the deployment, where the tenant has more than one")
+    ap.add_argument("--reason", default=None, help="why, for the audit log")
+    ap.add_argument("--wait", action="store_true",
+                    help="wait until the deployment answers (and, if it waits for approval, "
+                         "for the decision)")
+    ap.add_argument("--wait-timeout", type=float, default=900.0, dest="wait_timeout",
+                    help="seconds to wait at most (default 900); then exit 5")
+
+
+def _init(ctx: Context) -> dict[str, Any]:
+    target = Path(ctx.args.file)
+    if target.exists() and not ctx.args.force:
+        raise CliError(f"{target} already exists", error="exists",
+                       hint="pass --force to overwrite it")
+    target.write_text(SCAFFOLD.format(name=ctx.args.name))
+    return {"ok": True, "wrote": str(target), "agent": ctx.args.name,
+            "next": ["edit it", "lighthouse evals run <pack:card> --cap 5 --wait",
+                     "lighthouse agents deploy <pack:card> --version <version> --wait"]}
+
+
+def _logs(ctx: Context) -> dict[str, Any]:
+    client = ctx.client()
+    if ctx.args.trace:
+        return {"ok": True, "agent": ctx.args.agent,
+                **client.get(f"/api/v1/runs/{ctx.args.trace}/trace")}
+    pack, _, card = str(ctx.args.agent).partition(":")
+    rows = list(client.each("/api/v1/runs", "runs", limit=ctx.args.limit,
+                            pack=pack, card=card or None, status=ctx.args.status))
+    return {"ok": True, "agent": ctx.args.agent, "runs": rows}
+
+
+def agents(ctx: Context) -> dict[str, Any]:
+    which = getattr(ctx.args, "agents_command", None) or "list"
+    if which == "init":
+        return _init(ctx)
+    if which == "logs":
+        return _logs(ctx)
+    if which == "deploy":
+        return _release(ctx, str(ctx.args.version), "deploy",
+                        ctx.args.reason or "deployed from the lighthouse CLI")
+    if which == "rollback":
+        return _release(ctx, ctx.args.to or _previous(ctx), "rollback",
+                        ctx.args.reason or "rolled back from the lighthouse CLI")
+    if which == "show":
+        agent = ctx.args.agent
+        if not agent:
+            raise CliError("which agent?", code=USAGE, error="usage")
+        return {"ok": True, **ctx.client().get(f"/api/v1/agents/{agent}")}
+    return {"ok": True, **ctx.client().get_all("/api/v1/agents", "items")}
+
+
+FINAL = ("applied", "refused", "failed", "expired")
+POLL_S = 3.0
+
+
+def _previous(ctx: Context) -> str:
+    """The version to roll back to: the newest release that passed its gate
+    and is not the one running now."""
+    a = ctx.client().get(f"/api/v1/agents/{ctx.args.agent}")
+    current = a.get("version")
+    for r in a.get("releases") or []:
+        if r.get("gate_passed") and r.get("version") and r.get("version") != current:
+            return str(r["version"])
+    raise CliError(f"{ctx.args.agent} has no earlier version that passed its gate to go back to",
+                   code=USAGE, error="no_earlier_version", hint="name one with --to")
+
+
+def wait_for(ctx: Context, read: Any, done: Any, what: str) -> dict[str, Any]:
+    """Poll `read()` until `done(doc)`, every POLL_S, for at most
+    --wait-timeout seconds (exit 5 after that)."""
+    deadline = time.monotonic() + float(getattr(ctx.args, "wait_timeout", 900.0) or 900.0)
+    tries = max(1, int(float(getattr(ctx.args, "wait_timeout", 900.0) or 900.0) / POLL_S) + 1)
+    sleep = ctx.sleep or time.sleep
+    doc: dict[str, Any] = read()
+    for _ in range(tries):
+        if done(doc):
+            return doc
+        if time.monotonic() > deadline:
+            break
+        sleep(POLL_S)
+        doc = read()
+    if done(doc):
+        return doc
+    raise CliError(f"still waiting for {what}", code=RETRY, error="still_waiting",
+                   hint="run it again with --wait later, or look in the portal")
+
+
+def _follow(ctx: Context, agent: str, command: dict[str, Any]) -> dict[str, Any]:
+    cid = command["command_id"]
+    client = ctx.client()
+    got = wait_for(ctx, lambda: client.get(f"/api/v1/agents/{agent}/commands/{cid}"),
+                   lambda d: d.get("status") in FINAL, "your deployment to answer")
+    if got.get("status") != "applied":
+        raise CliError(f"your deployment did not make it current: {got.get('status')}"
+                       + (f" ({got.get('reason')})" if got.get("reason") else ""),
+                       code=FAILED, error=f"command_{got.get('status')}",
+                       command=cid, reason=got.get("reason"))
+    return got
+
+
+def _release(ctx: Context, version: str, action: str, reason: str) -> dict[str, Any]:
+    agent = str(ctx.args.agent)
+    body: dict[str, Any] = {"type": "release.add",
+                            "params": {"version": version, "reason": reason}}
+    if ctx.args.deployment:
+        body["deployment"] = ctx.args.deployment
+    got = ctx.client().post(f"/api/v1/agents/{agent}/commands", body)
+    mode = (got.get("deploy") or {}).get("mode", "live")
+    out: dict[str, Any] = {"ok": True, "action": action, "agent": agent, "version": version,
+                           "mode": mode}
+    if mode == "pending":
+        out.update({"status": "pending_approval", "request_id": got.get("request_id"),
+                    "why": got.get("why"), "why_words": got.get("why_words"),
+                    "approve_url": got.get("approve_url")})
+        if not ctx.args.wait:
+            return out
+        rid = got["request_id"]
+        client = ctx.client()
+        decided = wait_for(ctx, lambda: client.get(f"/api/v1/deploy-requests/{rid}"),
+                           lambda d: d.get("status") != "pending", "a person to approve it")
+        if decided.get("status") != "approved":
+            raise CliError(f"the deploy request was {decided.get('status')}"
+                           + (f": {decided.get('decision_reason')}"
+                              if decided.get("decision_reason") else ""),
+                           code=FAILED, error=f"request_{decided.get('status')}",
+                           request_id=rid)
+        command = decided.get("command") or {"command_id": decided.get("command_id")}
+        out["approved_by"] = decided.get("decided_by")
+    else:
+        command = got
+    out.update({"command": command.get("command_id"), "status": command.get("status")})
+    if ctx.args.wait and command.get("command_id"):
+        final = _follow(ctx, agent, command)
+        out.update({"status": final["status"], "detail": final.get("detail")})
+    return out
+
+
+def _show(out: Out, body: dict[str, Any]) -> None:
+    if body.get("action") in ("deploy", "rollback"):
+        out.pairs([("agent", body["agent"]), ("version", body["version"]),
+                   ("status", body.get("status") or ""),
+                   ("command", body.get("command") or "")])
+        if body["mode"] == "pending":
+            out.note(f"waiting for approval in LightHouse: "
+                     f"{body.get('why_words') or body.get('why')}")
+            if body.get("approve_url"):
+                out.note(f"a person approves it at {body['approve_url']}")
+        elif body.get("status") == "applied":
+            out.done(f"version {body['version']} is current")
+        else:
+            out.note("sent to your deployment; `--wait` follows it until it answers")
+        return
+    if "wrote" in body:
+        out.done(f"wrote {body['wrote']}")
+        for step in body["next"]:
+            out.note(f"  then: {step}")
+        return
+    if "spans" in body:
+        out.table(["span", "kind", "starts at (ms)", "took (ms)", "status"],
+                  [[s.get("name"), s.get("kind"), s.get("start_ms"),
+                    s.get("duration_ms"), s.get("status")] for s in body["spans"]])
+        return
+    if "runs" in body:
+        out.table(["run", "started", "status", "took (ms)", "attempts", "trigger"],
+                  [[r.get("run_id_hash"), r.get("started_at"), r.get("status"),
+                    r.get("duration_ms"), r.get("attempts"), r.get("trigger")]
+                   for r in body["runs"]])
+        return
+    rows = body.get("items")
+    if rows is None:
+        out.pairs([(k, v) for k, v in body.items()
+                   if k != "ok" and not isinstance(v, (list, dict))])
+        return
+    out.table(["agent", "pack", "state", "models", "runs (month)", "estimated cost"],
+              [[a.get("id"), a.get("pack"), a.get("state"), ", ".join(a.get("models") or []),
+                (a.get("month") or {}).get("runs"), (a.get("month") or {}).get("cost_usd")]
+               for a in rows])
+    out.note("every cost figure is estimated")
+
+
+COMMANDS = (Command("agents", "list, inspect, scaffold, deploy and roll back agents",
+                    _configure, agents, _show),)

lighthouse/commands/builds.py

@@ -0,0 +1,85 @@
+# Copyright 2026 Atlantic Agentic Labs. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+"""`lighthouse builds`: agents built with the agent builder, and where each is.
+
+    lighthouse builds
+    lighthouse builds --status publish_requested
+    lighthouse builds show 5f0c...e1            # one, with its scores and estimated cost
+    lighthouse builds --json | jq '.proposals[] | select(.status == "evaluated")'
+
+Reads `GET /api/v1/builder/proposals` (contract 1.24). Read only, on purpose:
+an agent is drafted, sent to your deployment, evaluated and approved in the
+portal (Agents, then Build an agent), because approval needs a person with a
+second factor and a delegated token is never that.
+
+Every cost shown is **estimated**, from your deployment's own price card.
+"""
+from __future__ import annotations
+
+import argparse
+from typing import Any
+
+from lighthouse.exits import USAGE, CliError
+from lighthouse.flags import inherited
+from lighthouse.main import Command, Context
+from lighthouse.out import Out
+
+
+def _configure(ap: argparse.ArgumentParser) -> None:
+    ap.add_argument("--status", help="only proposals at this step, e.g. publish_requested")
+    sub = ap.add_subparsers(dest="builds_command", metavar="<subcommand>")
+    show = sub.add_parser("show", parents=[inherited()],
+                          help="one proposal, with its scores and estimated cost")
+    show.add_argument("proposal", help="the proposal's id (32 hex characters)")
+
+
+def builds(ctx: Context) -> dict[str, Any]:
+    client = ctx.client()
+    if getattr(ctx.args, "builds_command", None) == "show":
+        pid = str(ctx.args.proposal)
+        if len(pid) != 32 or any(c not in "0123456789abcdef" for c in pid):
+            raise CliError("a proposal id is 32 hex characters", code=USAGE, error="usage")
+        return {"ok": True, "proposal": client.get(f"/api/v1/builder/proposals/{pid}")}
+    params = {"status": ctx.args.status} if getattr(ctx.args, "status", None) else {}
+    return {"ok": True, **client.get("/api/v1/builder/proposals", **params)}
+
+
+def _money(v: Any) -> str:
+    return "-" if v is None else f"${float(v):,.2f}"
+
+
+def _scores(p: dict[str, Any]) -> str:
+    ev = p.get("evaluation") or {}
+    if ev.get("passed") is None:
+        return "not yet"
+    held = sum(1 for c in (ev.get("redteam") or {}).values() if c.get("passed"))
+    return ("passed" if ev["passed"] else "failed") + \
+        f" (red team {held}/{len(ev.get('redteam') or {})})"
+
+
+def _show(out: Out, body: dict[str, Any]) -> None:
+    one = body.get("proposal")
+    if one is not None:
+        est = one.get("estimate") or {}
+        ev = one.get("evaluation") or {}
+        out.pairs([("agent", one.get("agent")), ("status", one.get("status")),
+                   ("deployment", one.get("deployment")), ("version", one.get("version")),
+                   ("template", one.get("template")),
+                   ("problems", ", ".join(one.get("problems") or []) or "-"),
+                   ("retrieval", (ev.get("retrieval") or {}).get("metrics") or "not yet"),
+                   ("evaluation", _scores(one)),
+                   ("estimated per run", _money(est.get("per_run_usd"))),
+                   ("estimated per month", _money(est.get("per_month_usd")))])
+        out.note("costs are estimated, from your deployment's own price card")
+        return
+    rows = body.get("proposals") or []
+    out.table(["proposal", "agent", "status", "evaluation", "estimated / month"],
+              [[p.get("proposal_id", "")[:12], p.get("agent"), p.get("status"), _scores(p),
+                _money((p.get("estimate") or {}).get("per_month_usd"))] for p in rows])
+    if body.get("waiting"):
+        out.note(f"{body['waiting']} waiting for approval in the portal (Agents, then Build "
+                 "an agent)")
+
+
+COMMANDS = (Command("builds", "agents built with the agent builder, and where each is",
+                    _configure, builds, _show),)

lighthouse/commands/collectors.py

@@ -0,0 +1,147 @@
+# Copyright 2026 Atlantic Agentic Labs. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+"""`lighthouse collectors`: ask Atlantic for a collector, and follow the request.
+
+    lighthouse collectors requests                  # your tenant's requests and their stage
+    lighthouse collectors request --vendor "Invented CRM" --product "Sales Suite" \\
+        --reads "Accounts and opportunities" --cloud aws [--kind crm] [--access read] \\
+        [--urgency normal] [--docs-url https://...]
+
+**A request becomes a public issue** in Atlantic's collectors backlog. The
+issue carries the fields below and "Requested by N LightHouse clients", never
+your organisation's name, a person or a domain; the service refuses text that
+names your organisation (`names_your_organisation`, exit 2). If another
+client already asked for the same vendor and product, your request joins
+that issue instead of opening another.
+
+**Asking needs the handler or client_admin role**; reading needs viewer. Both
+use the CLI's own sign-in (`lighthouse login`). At a terminal, a field left
+off the command line is asked for; under `--no-input`, or with standard input
+not a terminal, a missing required field is exit 7.
+
+**The stage** is the backlog's: requested, triage, needs-onboarding,
+approved, building, certifying, certified or declined. Approved, certified
+and declined also arrive in Notices.
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import Any
+
+from lighthouse.exits import USAGE, CliError, NeedsAPerson
+from lighthouse.flags import inherited
+from lighthouse.http import Refused
+from lighthouse.main import Command, Context
+from lighthouse.out import Out
+
+PATH = "/api/v1/collector-requests"
+ACCESS = ("read", "read_write")
+CLOUDS = ("aws", "azure", "gcp", "on-premises", "atlantic-hosted")
+URGENCY = ("low", "normal", "high")
+# (flag, body field, question, required)
+FIELDS = (("vendor", "vendor", "Vendor (who makes the system)", True),
+          ("product", "product", "Product", True),
+          ("reads", "reads", "What should it read?", True),
+          ("cloud", "deployment_cloud", f"Deployment cloud ({', '.join(CLOUDS)})", True),
+          ("kind", "kind", "Kind, e.g. crm or tickets (Enter to skip)", False),
+          ("docs_url", "docs_url", "Public API documentation link (Enter to skip)", False))
+
+
+def _configure(ap: argparse.ArgumentParser) -> None:
+    sub = ap.add_subparsers(dest="collectors_command", metavar="<subcommand>")
+    sub.add_parser("requests", parents=[inherited()],
+                   help="your tenant's collector requests and their stage (the default)")
+    req = sub.add_parser("request", parents=[inherited()],
+                         help="ask Atlantic for a collector (handler or client_admin)")
+    req.add_argument("--vendor", help="who makes the system, e.g. 'Invented CRM'")
+    req.add_argument("--product", help="the product, e.g. 'Sales Suite'")
+    req.add_argument("--reads", help="what it should read")
+    req.add_argument("--cloud", choices=CLOUDS, help="where your deployment runs")
+    req.add_argument("--kind", help="what it reads, as a slug: crm, tickets, wiki, ...")
+    req.add_argument("--access", choices=ACCESS, default="read",
+                     help="read (the default) or read_write")
+    req.add_argument("--urgency", choices=URGENCY, default="normal",
+                     help="low, normal (the default) or high")
+    req.add_argument("--docs-url", dest="docs_url",
+                     help="the vendor's public API documentation, https://")
+
+
+def _row(r: dict[str, Any]) -> dict[str, Any]:
+    return {"id": r.get("id"), "vendor": r.get("vendor"), "product": r.get("product"),
+            "kind": r.get("kind"), "stage": r.get("stage"), "issue_iid": r.get("issue_iid"),
+            "issue_url": r.get("issue_url"), "request_count": r.get("request_count"),
+            "created_at": r.get("created_at"), "updated_at": r.get("updated_at")}
+
+
+def _list(ctx: Context) -> dict[str, Any]:
+    body = ctx.client().get(PATH) or {}
+    return {"ok": True, "requests": [_row(r) for r in body.get("requests") or []]}
+
+
+def _interactive(ctx: Context) -> bool:
+    if getattr(ctx.args, "no_input", False):
+        return False
+    return bool((ctx.stdin or sys.stdin).isatty())
+
+
+def _ask(ctx: Context) -> dict[str, Any]:
+    a = ctx.args
+    body: dict[str, Any] = {"access": a.access, "urgency": a.urgency}
+    for flag, field, question, required in FIELDS:
+        value = getattr(a, flag, None)
+        if value is None:
+            if not _interactive(ctx):
+                if required:
+                    raise NeedsAPerson(f"--{flag.replace('_', '-')}")
+                continue
+            if flag == "vendor":
+                ctx.out.note("The request becomes a public issue: do not name your "
+                             "organisation, its clients or any person.")
+            value = (ctx.reader or input)(f"{question}: ").strip() or None
+            if value is None and required:
+                raise CliError(f"{question} is required", code=USAGE, error="invalid")
+        if value is not None:
+            body[field] = value
+    try:
+        got = ctx.client().request("POST", PATH, json_body=body) or {}
+    except Refused as e:
+        if e.error in ("invalid", "bad_query", "names_your_organisation"):
+            raise CliError(e.message, code=USAGE, error=e.error,
+                           hint="see `lighthouse collectors request --help`") from None
+        if e.error == "conflict":
+            raise CliError(e.message, code=e.code, error=e.error,
+                           hint="`lighthouse collectors requests` shows it") from None
+        raise
+    return {"ok": True, "action": "request", **_row(got), "access": got.get("access"),
+            "deployment_cloud": got.get("deployment_cloud"), "urgency": got.get("urgency")}
+
+
+def collectors(ctx: Context) -> dict[str, Any]:
+    if getattr(ctx.args, "collectors_command", None) == "request":
+        return _ask(ctx)
+    return _list(ctx)
+
+
+def _issue(r: dict[str, Any]) -> str:
+    return f"#{r['issue_iid']}" if r.get("issue_iid") else "not sent yet"
+
+
+def _show(out: Out, body: dict[str, Any]) -> None:
+    if body.get("action") == "request":
+        out.pairs([("request", body["id"]), ("collector", f"{body['vendor']} {body['product']}"),
+                   ("stage", body["stage"]), ("issue", _issue(body)),
+                   ("clients asking", body["request_count"] if body["request_count"] else "-")])
+        out.note("Atlantic triages it in the collectors backlog; approved, certified and "
+                 "declined arrive in Notices" if body.get("issue_iid") else
+                 "recorded; it is sent to the collectors backlog shortly")
+        return
+    out.table(["request", "collector", "stage", "issue", "clients asking", "asked"],
+              [[r["id"], f"{r['vendor']} {r['product']}", r["stage"], _issue(r),
+                r["request_count"] if r["request_count"] else "-", r["created_at"] or "-"]
+               for r in body["requests"]])
+    out.note("`lighthouse collectors request --vendor ... --product ...` asks for another")
+
+
+COMMANDS = (Command("collectors", "ask Atlantic for a collector, and follow your requests",
+                    _configure, collectors, _show),)