slab-cli 0.1.0__py3-none-any.whl

slab_cli/commands/lots.py

@@ -0,0 +1,114 @@
+"""Lot commands — record and list purchases (a single multi-card buy).
+
+A lot is the sibling of a break: one price paid for one-or-more cards (an eBay bundle, a card-show
+pickup, a COMC order), split evenly across the cards attached to it — but tied to no set, so its
+cards can span any number of products. Also provides helpers used by the collection add flow.
+
+`lot fill` lives in `collection.py` (like `break fill`) because it drives the shared add session."""
+
+from __future__ import annotations
+
+from slab_schemas.collection import CollectionSearchQuery, LotCreate, LotOut, LotSearchQuery
+
+from ..client import SlabClient
+from ..context import ctx
+from ..display import console, print_lots, render_lot_contents
+from ..prompts import ask_date, ask_decimal, confirm, select_lot
+from ..sources import pick_source
+
+
+def pick_or_create_lot(client: SlabClient, collector: str) -> LotOut | None:
+    """Let the user pick an existing purchase or create a new one. Returns the LotOut (whose cost
+    splits across the cards attached to it) or None if skipped."""
+    lots = client.search_lots(collector)
+    if lots.items:
+        choice = select_lot(lots, allow_new=True)
+        if choice == "new":
+            return create_lot_interactive(client, collector)
+        elif isinstance(choice, LotOut):
+            return choice
+        return None  # skipped
+    else:
+        if confirm("No purchases yet. Record one?", default=True):
+            return create_lot_interactive(client, collector)
+        return None
+
+
+def create_lot_interactive(client: SlabClient, collector: str) -> LotOut | None:
+    """Walk the user through recording a purchase. Returns the new LotOut or None."""
+    console.print(
+        "[dim]A purchase is one price paid for one-or-more cards — an eBay bundle, a show pickup. "
+        "Its cost splits across the cards you attach, so each carries what it actually cost you.[/dim]"
+    )
+    total_cost = ask_decimal("Total paid:")
+    lot_date = ask_date("When did you buy it?")
+    # Offer the collector's previously-used sources for arrow-key reuse (falls back to a plain
+    # text prompt on the first purchase, when there's nothing to reuse yet).
+    source = pick_source(client, collector)
+
+    lot = client.create_lot(
+        collector,
+        LotCreate(total_cost=total_cost, lot_date=lot_date, source=source),
+    )
+    console.print(f"[green]Purchase recorded:[/green] {lot.lot_date} — ${lot.total_cost:.2f}"
+                  + (f" · {lot.source}" if lot.source else ""))
+    console.print(
+        "[dim]Why it matters: as you add the cards from this purchase, its cost splits across "
+        "them — so every card carries what it actually cost you (real profit/loss later).[/dim]"
+    )
+    return lot
+
+
+def cmd_lot_list(args: list[str]) -> None:
+    """`slab lot list` — your purchases, then pick one to see value vs cost + its cards."""
+    result = ctx.client.search_lots(ctx.collector, LotSearchQuery(limit=25))
+    print_lots(result)
+    if not result.items:
+        return
+    choice = select_lot(result, allow_new=False)
+    if isinstance(choice, LotOut):
+        _show_lot_contents(choice)
+
+
+def _show_lot_contents(lot: LotOut) -> None:
+    """The purchase's report card: one collection search scoped to the lot — each copy carries its
+    own market data — rendered as value-vs-cost + most valuable + rarest."""
+    cards = ctx.client.search_collection(
+        ctx.collector, CollectionSearchQuery(lot_uuid=lot.uuid, limit=200))
+    render_lot_contents(lot, cards)
+
+
+def cmd_lot_new(args: list[str]) -> None:
+    """`slab lot new` — record a purchase (its cost splits across the cards you add to it, so every
+    card carries what it actually cost you)."""
+    create_lot_interactive(ctx.client, ctx.collector)
+
+
+def cmd_lot_remove(args: list[str]) -> None:
+    """`slab lot remove` — pick a purchase and remove it. The cards stay in your collection but are
+    detached from the purchase (their split-derived cost basis is lost, since that cost was only
+    ever split across them while linked)."""
+    lots = ctx.client.search_lots(ctx.collector, LotSearchQuery(limit=100))
+    if not lots.items:
+        console.print("[slab.dim]No purchases to delete.[/]")
+        return
+
+    choice = select_lot(lots, allow_new=False)
+    if not isinstance(choice, LotOut):
+        return  # skipped / cancelled
+
+    console.print(
+        f"[yellow]Deleting:[/yellow] {choice.lot_date} — ${choice.total_cost:.2f} "
+        f"({choice.copy_count} card(s))"
+    )
+    if choice.copy_count:
+        console.print(
+            f"[dim]Those {choice.copy_count} card(s) stay in your collection but lose the cost "
+            "basis they got from this purchase.[/dim]"
+        )
+    if not confirm("Delete this purchase?", default=False):
+        console.print("[slab.dim]Cancelled.[/]")
+        return
+
+    ctx.client.delete_lot(ctx.collector, choice.uuid)
+    console.print("[green]Purchase deleted.[/green]")

slab_cli/commands/pricing.py

@@ -0,0 +1,386 @@
+"""Pricing commands — market price lookups and portfolio valuation."""
+
+from __future__ import annotations
+
+from slab_schemas.cards import SetSearchQuery
+from slab_schemas.collection import CollectionSearchQuery, PortfolioSummary
+
+from slab_schemas.cards import CardOut, SetOut
+
+from ..context import MissingCollector, ctx
+from ..display import (
+    console,
+    render_card_market,
+    render_comps,
+    render_portfolio,
+    render_price_history,
+    render_sealed_price_history,
+    render_set_market,
+)
+from ..paging import fetch_all_pages
+from ..picker import pick_card, search_and_pick_subject
+from ..prompts import (
+    select_priced_card,
+    select_set,
+    select_set_filter,
+)
+
+
+def _optional_collector() -> str | None:
+    """The active collector if one is resolvable, else None — pricing is catalog-level and works
+    without ownership, but if we have a collector we annotate each row with owned quantity."""
+    try:
+        return ctx.collector
+    except MissingCollector:
+        return None
+
+
+def _pick_card(args: list[str]) -> CardOut | None:
+    """Price/comps selection: player → set (or all) → a card from the FMV-tagged list. Shares the
+    subject-first core (`search_and_pick_subject`) with every other picker, then adds the two
+    pricing-specific steps: the enriched search (each row carries its headline FMV + owned tag) and
+    a set-narrowing step before the FMV list. Returns the chosen card, or None if the user backed
+    out or nothing matched."""
+    picked = search_and_pick_subject(
+        " ".join(args) if args else None,
+        collector=_optional_collector(),
+        include_market=True,
+    )
+    if picked is None:
+        return None
+    cards, subject = picked
+
+    # Narrow to a set (auto-skips when the player only appears in one set).
+    slug = select_set_filter(cards)
+    if slug:
+        cards = [c for c in cards if c.set_slug == slug]
+
+    return select_priced_card(cards, subject, show_set=not slug)
+
+
+def cmd_price(args: list[str]) -> None:
+    """Price a player's cards: pick the player, narrow to a set (or all), see every printing with
+    its FMV (● = you own it), then drill into one for the full market view. Catalog-level — no
+    ownership required, but owned copies are tagged when a collector is configured."""
+    card = _pick_card(args)
+    if card is None:
+        return
+    render_card_market(ctx.client.get_card_market(card.uuid))
+
+
+def cmd_comps(args: list[str]) -> None:
+    """See the recent comps (raw observed sales) behind a card's price. Same player → set → card
+    flow as `price`, then lists the individual sales that FMV is built from."""
+    card = _pick_card(args)
+    if card is None:
+        return
+    render_comps(ctx.client.get_card_comps(card.uuid))
+
+
+def _fetch_all_copies(page: int = 200, cap: int = 5000) -> tuple[list, PortfolioSummary | None]:
+    """Page through the whole collection for the per-set/mover/break breakdowns, and grab the
+    server's summary block (full-result aggregates, identical on every page) from the first page —
+    that's the source of truth for grand totals. `cap` is a safety bound so a runaway collection
+    can't spin forever."""
+    copies, first = fetch_all_pages(
+        lambda limit, offset: ctx.client.search_collection(
+            ctx.collector, CollectionSearchQuery(sort="-unrealized", limit=limit, offset=offset)
+        ),
+        page=page,
+        cap=cap,
+    )
+    return copies, (first.summary if first else None)
+
+
+def _aggregate_by_set(copies: list) -> list[dict]:
+    """Roll copies up per set, mirroring the server's headline math so the parts reconcile with the
+    whole: cost basis is summed per-copy, FMV is quantity-weighted, comp coverage is copy-weighted."""
+    sets: dict[str, dict] = {}
+    for cp in copies:
+        card = cp.card
+        name = (card.set_name if card else None) or "— Unknown set —"
+        s = sets.setdefault(name, {
+            "name": name, "copies": 0, "total_qty": 0, "priced_qty": 0,
+            "cost_basis": 0.0, "fmv": 0.0, "has_fmv": False,
+        })
+        qty = cp.quantity or 1
+        s["copies"] += 1
+        s["total_qty"] += qty
+        if cp.cost_basis is not None:
+            s["cost_basis"] += float(cp.cost_basis)
+        if cp.market and cp.market.fair_market_value is not None:
+            s["fmv"] += float(cp.market.fair_market_value) * qty
+            s["priced_qty"] += qty
+            s["has_fmv"] = True
+
+    for s in sets.values():
+        s["unrealized"] = (s["fmv"] - s["cost_basis"]) if s["has_fmv"] else None
+        s["comp_pct"] = (s["priced_qty"] / s["total_qty"] * 100) if s["total_qty"] else 0.0
+
+    # Most valuable first; sets with no market data sink to the bottom (sorted by cost basis).
+    return sorted(
+        sets.values(),
+        key=lambda s: (s["has_fmv"], s["fmv"] if s["has_fmv"] else s["cost_basis"]),
+        reverse=True,
+    )
+
+
+def _portfolio_totals(summary: PortfolioSummary) -> dict:
+    """Grand totals for the valuation panel, straight from the server's summary block — the same
+    math the dashboard shows, so the two never diverge."""
+    fmv = summary.portfolio_value
+    return {
+        "cost_basis": float(summary.total_cost_basis or 0),
+        "fmv": float(fmv) if fmv is not None else None,
+        "unrealized": (
+            float(summary.total_unrealized_gain_loss)
+            if summary.total_unrealized_gain_loss is not None else None
+        ),
+        "roi": float(summary.portfolio_roi) if summary.portfolio_roi is not None else None,
+        "priced_qty": summary.priced_copies,
+        "total_qty": summary.priced_copies + summary.unpriced_copies,
+    }
+
+
+def _most_valuable_break(copies: list, breaks: list) -> dict | None:
+    """The break whose pulled copies carry the most market value — did opening that box pay off?
+    FMV is summed from the copies we already priced; cost/metadata comes from the breaks list."""
+    fmv_by_break: dict[str, float] = {}
+    priced_by_break: dict[str, int] = {}
+    for cp in copies:
+        if cp.break_uuid and cp.market and cp.market.fair_market_value is not None:
+            qty = cp.quantity or 1
+            fmv_by_break[cp.break_uuid] = (
+                fmv_by_break.get(cp.break_uuid, 0.0) + float(cp.market.fair_market_value) * qty
+            )
+            priced_by_break[cp.break_uuid] = priced_by_break.get(cp.break_uuid, 0) + qty
+
+    if not fmv_by_break:
+        return None
+
+    top_uuid = max(fmv_by_break, key=fmv_by_break.get)
+    brk = next((b for b in breaks if b.uuid == top_uuid), None)
+    if brk is None:
+        return None
+
+    cost = float(brk.total_cost)
+    fmv = fmv_by_break[top_uuid]
+    return {
+        "set_name": brk.set_name or "— Unknown set —",
+        "break_type": brk.break_type,
+        "break_date": brk.break_date,
+        "cost": cost,
+        "fmv": fmv,
+        "gain": fmv - cost,
+        "copy_count": brk.copy_count,
+        "priced": priced_by_break.get(top_uuid, 0),
+    }
+
+
+def cmd_portfolio(args: list[str]) -> None:
+    """Portfolio-level financial summary — cost basis vs market value, per-set stats, top movers."""
+    copies, summary = _fetch_all_copies()
+    if not copies:
+        console.print("[dim]No cards in your collection yet.[/dim]")
+        return
+    if summary is None:
+        # The API always includes the summary block; its absence is a server bug — say so
+        # rather than invent numbers client-side.
+        console.print("[red]Server response had no portfolio summary — can't value the collection.[/red]")
+        return
+
+    by_set = _aggregate_by_set(copies)
+    totals = _portfolio_totals(summary)
+
+    # Top movers: copies with real unrealized P&L, biggest gain first (already sorted by the fetch).
+    movers = [
+        cp for cp in copies
+        if cp.market and cp.market.unrealized_gain_loss is not None
+    ][:10] or None
+
+    breaks = ctx.client.search_breaks(ctx.collector).items
+    mvb = _most_valuable_break(copies, breaks)
+
+    render_portfolio(
+        len(copies), totals, movers=movers, by_set=by_set, most_valuable_break=mvb
+    )
+
+
+def _fetch_all_sets(page: int = 200, cap: int = 1000) -> list[SetOut]:
+    """The whole set catalog for client-side fuzzy picking. Sets number in the dozens today, so
+    this is one request; `cap` bounds the paging if the catalog grows past reason."""
+    sets, _ = fetch_all_pages(
+        lambda limit, offset: ctx.client.search_sets(SetSearchQuery(limit=limit, offset=offset)),
+        page=page,
+        cap=cap,
+    )
+    return sets
+
+
+def cmd_set_market(args: list[str]) -> None:
+    """The set-level money view: type a set name, fuzzy-pick the match, then see every sealed
+    SKU's FMV (case/box/blaster) next to the most expensive cards inside it — what the wax costs
+    vs what you're chasing. Catalog-level, no ownership required."""
+    query = " ".join(args) if args else None
+
+    sets = _fetch_all_sets()
+    if not sets:
+        console.print("[yellow]No sets in the catalog yet.[/yellow]")
+        return
+
+    chosen = select_set(sets, initial=query)
+    if chosen is None:
+        return
+
+    sealed = ctx.client.get_set_sealed(chosen.uuid)
+    top = ctx.client.get_set_top_cards(chosen.uuid, limit=10)
+    render_set_market(chosen, sealed, top)
+
+
+# Above this many daily points, an unflagged history is re-fetched weekly — a two-year series
+# should read as a trend, not a 400-row dump. --daily always forces every point.
+_AUTO_WEEKLY_OVER = 90
+
+
+def _history_options(args: list[str]) -> tuple[list[str], str | None, int | None]:
+    """(query_args, interval|None, days|None) from --daily/--weekly/--monthly/--days N.
+    interval None = auto (daily, bucketed to weekly when the series is long)."""
+    query: list[str] = []
+    interval: str | None = None
+    days: int | None = None
+    i = 0
+    while i < len(args):
+        a = args[i]
+        if a in ("--daily", "--weekly", "--monthly"):
+            interval = a.lstrip("-")
+        elif a == "--days":
+            if i + 1 < len(args):
+                i += 1
+                try:
+                    days = max(1, int(args[i]))
+                except ValueError:
+                    console.print(f"[yellow]--days expects a number, got {args[i]!r} — ignored.[/yellow]")
+            else:
+                console.print("[yellow]--days expects a number — ignored.[/yellow]")
+        else:
+            query.append(a)
+        i += 1
+    return query, interval, days
+
+
+def _start_from_days(days: int | None) -> str | None:
+    if days is None:
+        return None
+    from datetime import date, timedelta
+
+    return (date.today() - timedelta(days=days)).isoformat()
+
+
+def _fetch_history(fetch, interval: str | None, days: int | None):
+    """Fetch with the resolved interval: an explicit flag is obeyed; otherwise daily, re-fetched
+    weekly when the series is long (with a note so the densest view is one flag away)."""
+    start = _start_from_days(days)
+    h = fetch(start=start, interval=interval or "daily")
+    if interval is None and len(h.points) > _AUTO_WEEKLY_OVER:
+        h = fetch(start=start, interval="weekly")
+        console.print(
+            f"[slab.dim]Long series — showing weekly buckets ({len(h.points)} points). "
+            f"Use --daily for every point.[/]"
+        )
+    return h
+
+
+def cmd_history(args: list[str]) -> None:
+    """Price history for a card — how its value has changed over time.
+
+    Flags:
+      --daily / --weekly / --monthly   bucket size (default: daily, auto-weekly for long series)
+      --days N                         only the last N days
+
+    Examples:
+      slab card history bedard
+      slab card history bedard --days 90 --daily
+      slab card history mcdavid --monthly"""
+    from InquirerPy import inquirer
+    from InquirerPy.base.control import Choice
+
+    query, interval, days = _history_options(args)
+    card = pick_card(" ".join(query) if query else None)
+    if card is None:
+        return
+
+    # Get available grade buckets from the card's market data
+    market = ctx.client.get_card_market(card.uuid)
+    if not market.price_points:
+        console.print("[yellow]No pricing data available for this card.[/yellow]")
+        return
+
+    grade_keys = sorted({pp.grade_key for pp in market.price_points})
+    if len(grade_keys) == 1:
+        gk = grade_keys[0]
+    else:
+        gk = inquirer.select(
+            message="Grade bucket:",
+            choices=[Choice(gk, name=gk) for gk in grade_keys],
+        ).execute()
+
+    history = _fetch_history(
+        lambda start, interval: ctx.client.get_card_price_history(
+            card.uuid, grade_key=gk, start=start, interval=interval),
+        interval, days,
+    )
+    render_price_history(history)
+
+
+def cmd_set_history(args: list[str]) -> None:
+    """Price history for a sealed product — how a box/case/blaster's value has changed over time.
+
+    Flags:
+      --daily / --weekly / --monthly   bucket size (default: daily, auto-weekly for long series)
+      --days N                         only the last N days
+
+    Examples:
+      slab set history allure
+      slab set history "series 1" --days 180 --weekly"""
+    from InquirerPy import inquirer
+    from InquirerPy.base.control import Choice
+
+    query, interval, days = _history_options(args)
+
+    sets = _fetch_all_sets()
+    if not sets:
+        console.print("[yellow]No sets in the catalog yet.[/yellow]")
+        return
+
+    chosen = select_set(sets, initial=" ".join(query) if query else None)
+    if chosen is None:
+        return
+
+    sealed = ctx.client.get_set_sealed(chosen.uuid)
+    if not sealed:
+        console.print("[yellow]No sealed products catalogued for this set.[/yellow]")
+        return
+
+    priced = [p for p in sealed if p.price_median is not None]
+    if not priced:
+        console.print("[yellow]No sealed pricing for this set yet.[/yellow]")
+        return
+    if len(priced) == 1:
+        product = priced[0]
+    else:
+        labels = {
+            p.uuid: f"{p.format.value.replace('_', ' ').title()}  ·  FMV ${p.price_median:,.2f}"
+            for p in priced
+        }
+        uuid = inquirer.select(
+            message="Sealed product:",
+            choices=[Choice(p.uuid, name=labels[p.uuid]) for p in priced],
+        ).execute()
+        product = next(p for p in priced if p.uuid == uuid)
+
+    history = _fetch_history(
+        lambda start, interval: ctx.client.get_sealed_price_history(
+            product.uuid, start=start, interval=interval),
+        interval, days,
+    )
+    render_sealed_price_history(history)

slab_cli/commands/registry.py

@@ -0,0 +1,140 @@
+"""The command registry — the ONE source of truth for the slab CLI's command surface.
+
+Every command is declared here exactly once as a `Command` under a `Group`. This single list drives
+BOTH dispatch (main.py routes `slab <group> <verb>` through it) AND the help screens (`slab`,
+`slab <group>`), so the help you read and the commands that run can never disagree. Adding a command
+= adding one line here; the help updates itself. This is deliberately the canonical reference for
+what the CLI can do — external docs should point here rather than restate it.
+
+Structure is pure noun-verb (like `git`, `docker`, `gh`): a `<group>` noun, then a `<verb>`. Learn a
+noun and you can guess its verbs; verbs stay consistent across nouns (`search`, `add`, `remove`,
+`dashboard`, `price`…). Everything searchable uses the verb `search` with the SHARED flag grammar
+(`slab_cli.flags`) — the same `--team`/`--year`/… work on `card`, `set`, and `collection` search."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from difflib import get_close_matches
+from typing import Callable
+
+from . import breaks, catalog, collection, custom_sets, export, lots, pricing, setup
+
+Handler = Callable[[list[str]], None]
+
+
+@dataclass(frozen=True)
+class Command:
+    """One `slab <group> <verb>` command: the verb, a one-line summary, its args hint, and the
+    function that runs it. Summary + args render straight into the help — keep them tight."""
+
+    verb: str
+    summary: str
+    handler: Handler
+    args: str = ""
+
+    def usage(self, group: str) -> str:
+        """`slab card search <query>` — the full invocation, args included."""
+        base = f"slab {group} {self.verb}"
+        return f"{base} {self.args}" if self.args else base
+
+
+@dataclass(frozen=True)
+class Group:
+    """A noun (`card`, `collection`, …) and the verbs under it, plus a one-line blurb for the header.
+
+    `default` names a verb to run when the group is invoked bare (`slab community` → its board);
+    groups without one show their help instead — the right behavior for multi-verb nouns."""
+
+    name: str
+    blurb: str
+    commands: list[Command] = field(default_factory=list)
+    default: str | None = None
+
+
+# --- The command surface -----------------------------------------------------------------------
+# Each group is a noun; each Command a verb. This list IS the CLI. Edit here, help follows.
+
+GROUPS: list[Group] = [
+    Group("card", "look up a card in the catalog", [
+        Command("search", "Search the catalog (player, set, team…)", catalog.cmd_search, "[query] [flags]"),
+        Command("parallels", "Every parallel (the rainbow) of a card", catalog.cmd_rainbow, "<query>"),
+        Command("price", "Market price + 7d/30d trend", pricing.cmd_price, "<query>"),
+        Command("comps", "Recent raw sales behind the price", pricing.cmd_comps, "<query>"),
+        Command("history", "Price history over time", pricing.cmd_history, "<query>"),
+    ]),
+    Group("set", "browse and price sealed products", [
+        Command("search", "Browse sets / products", catalog.cmd_sets, "[query] [flags]"),
+        Command("price", "Set market: sealed FMV (case/box/blaster) + top cards", pricing.cmd_set_market, "[query]"),
+        Command("history", "Sealed price history over time (box/case/blaster)", pricing.cmd_set_history, "[query]"),
+    ]),
+    Group("community", "everyone's catalog activity", [
+        Command("board", "Community board: catalog stats, activity, leaderboards", catalog.cmd_community),
+    ], default="board"),
+    Group("collection", "your inventory", [
+        Command("add", "Add card(s) you own", collection.cmd_add),
+        Command("search", "Search your collection (same flags as card search)", collection.cmd_search, "[query] [flags]"),
+        Command("sell", "Record a sale (mark sold with price)", collection.cmd_sell),
+        Command("remove", "Remove a copy", collection.cmd_remove),
+        Command("cost", "Log a cost (grading, shipping) on a copy", collection.cmd_cost),
+        Command("export", "Export a set to a printable checklist", export.cmd_export),
+        Command("dashboard", "Overview: counts, value, composition", collection.cmd_dashboard),
+        Command("portfolio", "Portfolio: cost basis vs FMV + top movers", pricing.cmd_portfolio),
+    ]),
+    Group("break", "case / box breaks", [
+        Command("list", "Your breaks — pick one to see value vs cost + top pulls", breaks.cmd_break_list),
+        Command("new", "Record a break", breaks.cmd_break_new),
+        Command("fill", "Walk a break's checklist, adding what you pulled", collection.cmd_break_fill),
+        Command("remove", "Delete a break (pulled cards stay in your collection)", breaks.cmd_break_remove),
+    ]),
+    Group("lot", "multi-card purchases (eBay bundles)", [
+        Command("list", "Your purchases — pick one to see value vs cost + its cards", lots.cmd_lot_list),
+        Command("new", "Record a purchase (cost splits across its cards)", lots.cmd_lot_new),
+        Command("fill", "Add the cards from one purchase back-to-back", collection.cmd_lot_fill),
+        Command("remove", "Delete a purchase (its cards stay in your collection)", lots.cmd_lot_remove),
+    ]),
+    Group("chase", "custom sets & set-completion", [
+        Command("create", "Create a custom set (curated or dynamic)", custom_sets.cmd_chase_create),
+        Command("add", "Add cards to a curated set", custom_sets.cmd_chase_add),
+        Command("view", "View a set with completion + add missing", custom_sets.cmd_chase_view, "[uuid]"),
+        Command("edit", "Edit name, description, or visibility", custom_sets.cmd_chase_edit),
+        Command("list", "Your sets (created + subscribed)", custom_sets.cmd_chase_list),
+        Command("find", "Discover public sets by name", custom_sets.cmd_chase_find, "[query]"),
+        Command("subscribe", "Subscribe to / unsubscribe from a public set", custom_sets.cmd_chase_subscribe, "[query]"),
+        Command("remove", "Remove a card from a set", custom_sets.cmd_chase_remove),
+        Command("delete", "Delete a set you created", custom_sets.cmd_chase_delete),
+    ]),
+    Group("collector", "your identity", [
+        Command("create", "Create a collector", setup.cmd_register, "<name>"),
+        Command("current", "Show the active collector", setup.cmd_whoami),
+    ]),
+]
+
+# --- Lookup + suggestion (used by dispatch) ----------------------------------------------------
+
+_GROUPS_BY_NAME: dict[str, Group] = {g.name: g for g in GROUPS}
+_COMMANDS: dict[tuple[str, str], Command] = {
+    (g.name, c.verb): c for g in GROUPS for c in g.commands
+}
+
+
+def get_group(name: str) -> Group | None:
+    return _GROUPS_BY_NAME.get(name)
+
+
+def get_command(group: str, verb: str) -> Command | None:
+    return _COMMANDS.get((group, verb))
+
+
+def suggest_group(name: str) -> str | None:
+    """Closest group name to a typo, or None — powers 'did you mean …?'."""
+    m = get_close_matches(name, list(_GROUPS_BY_NAME), n=1, cutoff=0.6)
+    return m[0] if m else None
+
+
+def suggest_verb(group: str, verb: str) -> str | None:
+    """Closest verb within a group to a typo, or None."""
+    g = get_group(group)
+    if not g:
+        return None
+    m = get_close_matches(verb, [c.verb for c in g.commands], n=1, cutoff=0.6)
+    return m[0] if m else None

slab_cli/commands/setup.py

@@ -0,0 +1,24 @@
+"""Setup commands — register a collector, check identity."""
+
+from __future__ import annotations
+
+from ..config import get_collector_uuid
+from ..context import ctx
+from ..display import console
+from ..prompts import ask_text
+
+
+def cmd_register(args: list[str]) -> None:
+    name = " ".join(args) if args else ask_text("Collector name:")
+    collector = ctx.client.create_collector(name)
+    console.print(f"\n[green]Collector created:[/green] {collector.name}")
+    console.print(f"  UUID: {collector.uuid}")
+    console.print(f"\n  Now run: [bold]export SLAB_COLLECTOR={collector.uuid}[/bold]")
+
+
+def cmd_whoami(args: list[str]) -> None:
+    uuid = get_collector_uuid()
+    if uuid:
+        console.print(f"Active collector: [bold]{uuid}[/bold]")
+    else:
+        console.print("[dim]No collector set. Run: slab collector create <name>[/dim]")

slab_cli/config.py

@@ -0,0 +1,21 @@
+"""CLI configuration — resolved from env vars or defaults."""
+
+from __future__ import annotations
+
+import os
+
+
+def get_base_url() -> str:
+    url = os.environ.get("SLAB_API_URL", "").strip()
+    return url or "https://api.slab.dev-jeb.com"
+
+
+def get_api_key() -> str | None:
+    key = os.environ.get("SLAB_API_KEY", "").strip()
+    return key or None
+
+
+def get_collector_uuid() -> str | None:
+    """The active collector UUID. Set once, reused across commands."""
+    uuid = os.environ.get("SLAB_COLLECTOR", "").strip()
+    return uuid or None