slab-cli 0.1.0__py3-none-any.whl

slab_cli/commands/collection.py

@@ -0,0 +1,676 @@
+"""Collection commands — add, remove, cost, search."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from decimal import Decimal
+
+from slab_schemas.cards import CardOut, CardSearchQuery
+from slab_schemas.collection import (
+    CardCopyCostCreate,
+    CardCopyCostUpdate,
+    CardCopyCreate,
+    CardCopyUpdate,
+    CollectionSearchQuery,
+)
+from slab_schemas.enums import AcquisitionType, CopyStatus, CostCategory, grade_delta
+
+from ..client import ApiError, SlabClient
+from ..context import ctx
+from ..flags import COLLECTION_SEARCH_FLAGS, parse_flags
+from ..paging import fetch_all_pages
+from ..picker import pick_card
+from ..display import (
+    console,
+    format_card_summary,
+    format_grade_delta,
+    print_collection,
+    render_dashboard,
+)
+from ..prompts import (
+    ask_date,
+    ask_decimal,
+    ask_decimal_optional,
+    ask_int_optional,
+    ask_text,
+    ask_text_optional,
+    confirm,
+    select_acquisition_type,
+    select_copy,
+    select_cost_action,
+    select_cost_category,
+    select_cost_entry,
+    select_grade,
+    select_grading_company,
+    select_printing_for_slot,
+    walk_prompt,
+)
+from .breaks import pick_or_create_break
+from .lots import pick_or_create_lot
+from ..sources import pick_source
+
+
+# ---------------------------------------------------------------------------
+# cmd_add — decomposed into focused helpers
+# ---------------------------------------------------------------------------
+
+@dataclass
+class AddSession:
+    """Mutable state carried across a batch add session. Acquisition type, the break/purchase-lot,
+    and the box scope are decided once and persist for every card added back-to-back."""
+    client: SlabClient
+    collector: str
+    acq_type: AcquisitionType | None = None
+    break_uuid: str | None = None
+    lot_uuid: str | None = None          # the purchase this batch belongs to; its cost splits across cards
+    release_set_uuid: str | None = None  # the break's product — scopes every card search to that box
+    acquired_source: str | None = None   # where these came from (purchases/trades/gifts), set once
+    cards_added: int = 0
+
+
+def _search_and_select_card(session: AddSession) -> CardOut | None:
+    """Find the exact card the user got, SUBJECT-FIRST: (1) search a player and pick them, (2) pick
+    the set they're in, then (3) pick the exact printing — base, parallel, insert, auto. Step 2 is
+    what stops a player who appears across many products from dumping into one undifferentiated list
+    (the set name also rides each row when the list still spans sets). When a break is in play every
+    search is scoped to that box (its release), so the set step auto-collapses and you only ever see
+    cards that could have come from what you opened. Shares the picker with the rest of the CLI; the
+    only add-specific bits are the next/first prompt and the box-scoped 'not found' message."""
+    prompt = "Search for next card (player):" if session.cards_added > 0 else "Search for a card (player):"
+    not_found = (
+        "No cards found in this box. Try a different player name."
+        if session.release_set_uuid
+        else "No cards found. Try a different player name."
+    )
+    scope = {"release": [session.release_set_uuid]} if session.release_set_uuid else {}
+    # Narrow by set unless already box-scoped (a break's cards are all one set, so it's redundant).
+    narrow_set = session.release_set_uuid is None
+    return pick_card(None, prompt=prompt, not_found=not_found, narrow_set=narrow_set, **scope)
+
+
+def _ensure_acquisition_context(session: AddSession) -> None:
+    """Decide acquisition type once per batch — and for a pack pull the break, or for a purchase an
+    optional lot — BEFORE searching. A pack pull's break also scopes every search to that box.
+    Persists across back-to-back adds."""
+    if session.acq_type is not None:
+        return
+    session.acq_type = AcquisitionType(select_acquisition_type())
+    if session.acq_type == AcquisitionType.pack_pull:
+        brk = pick_or_create_break(session.client, session.collector)
+        if brk is not None:
+            session.break_uuid = brk.uuid
+            session.release_set_uuid = brk.set_uuid  # scope every search to this box
+    elif session.acq_type == AcquisitionType.purchase:
+        # A purchase may be a multi-card buy (an eBay bundle). Offer to attach it to a lot whose
+        # cost splits across the cards — decided once for the batch. If a lot is chosen, its source
+        # and per-card cost come from the split, so we skip those per-card prompts.
+        if confirm("Was this part of a multi-card purchase (an eBay bundle, a show pickup)?", default=False):
+            lot = pick_or_create_lot(session.client, session.collector)
+            if lot is not None:
+                session.lot_uuid = lot.uuid
+                session.acquired_source = lot.source
+        if session.lot_uuid is None:
+            # A one-off buy → ask where it came from, once for the batch.
+            session.acquired_source = pick_source(session.client, session.collector)
+    else:
+        # Trade / gift / other → ask where these came from, once for the batch.
+        session.acquired_source = pick_source(session.client, session.collector)
+
+
+def _per_card_cost(session: AddSession) -> Decimal | None:
+    """The cost that varies per card. Pack pulls derive cost from the break, and a purchase attached
+    to a lot derives cost from the lot's split (so None in both cases); a one-off purchase/trade asks
+    each time."""
+    if session.break_uuid or session.lot_uuid:
+        return None
+    if session.acq_type == AcquisitionType.purchase:
+        return ask_decimal_optional("Purchase price (enter to skip):")
+    if session.acq_type == AcquisitionType.trade:
+        return ask_decimal_optional("Estimated trade value (enter to skip):")
+    return None
+
+
+def _collect_grade_details() -> tuple[str | None, str | None, str | None, str | None]:
+    """Get the collector's self-grade plus any professional grading. Both can coexist — a self-grade
+    is your own rung guess (kept forever), the grading fields are the pro verdict.
+    Returns (self_grade, grading_company, grade, cert_number)."""
+    self_grade = select_grade("Your grade assessment:")
+
+    grading_company = grade = cert_number = None
+    if confirm("Is it professionally graded?", default=False):
+        grading_company = select_grading_company()
+        grade = ask_text_optional("Pro grade (e.g. 10, 9.5, Authentic — enter to skip):")
+        cert_number = ask_text_optional("Cert number (enter to skip):")
+
+    return self_grade, grading_company, grade, cert_number
+
+
+def _show_review(card: CardOut, session: AddSession, acq_cost: Decimal | None,
+                 break_uuid: str | None, self_grade: str | None, grading_company: str | None,
+                 grade: str | None, serial: int | None) -> None:
+    """Print a summary for the user to confirm before submitting."""
+    subjects = ", ".join(s.name for s in card.subjects)
+    console.print("\n  [bold]Review:[/bold]")
+    console.print(f"    Card:        {card.card_number} {subjects}")
+    console.print(f"    Acquired:    {session.acq_type.value}")
+    if break_uuid:
+        console.print(f"    Break:       {break_uuid[:8]}")
+    if session.lot_uuid:
+        console.print(f"    Purchase:    {session.lot_uuid[:8]}  [dim](cost split across the lot)[/dim]")
+    if acq_cost is not None:
+        console.print(f"    Cost:        ${acq_cost:.2f}")
+    if session.acquired_source:
+        console.print(f"    Source:      {session.acquired_source}")
+    if self_grade:
+        console.print(f"    Self grade:  {self_grade}")
+    if grading_company:
+        console.print(f"    Pro grade:   {grading_company} {grade or '—'}")
+    delta = format_grade_delta(grade_delta(self_grade, grade))
+    if delta:
+        console.print(f"    Delta:       {delta}")
+    if serial is not None and card.print_run:
+        console.print(f"    Serial:      {serial}/{card.print_run}")
+
+
+def _prompt_serial(card: CardOut) -> int | None:
+    """Ask for the individual serial number, but only for a numbered printing."""
+    if not card.print_run:
+        return None
+    return ask_int_optional(f"Serial number (of /{card.print_run}, enter to skip):")
+
+
+def _submit_and_report(session: AddSession, card: CardOut, acq_cost: Decimal | None,
+                       break_uuid: str | None, self_grade: str | None,
+                       grading_company: str | None, grade: str | None,
+                       cert_number: str | None, serial: int | None) -> None:
+    """Build the CardCopyCreate, POST it, and print the Added confirmation. Shared by the
+    single-card `add` flow and the break-fill checklist walker, so the submit + report block
+    lives in exactly one place."""
+    payload = CardCopyCreate(
+        card_uuid=card.uuid,
+        break_uuid=break_uuid,
+        lot_uuid=session.lot_uuid,
+        acquisition_type=session.acq_type,
+        acquisition_cost=acq_cost,
+        acquired_source=session.acquired_source,
+        self_grade=self_grade,
+        grading_company=grading_company,
+        grade=grade,
+        cert_number=cert_number,
+        serial_number=serial,
+    )
+
+    copy = session.client.add_copy(session.collector, payload)
+    subjects = ", ".join(s.name for s in card.subjects)
+    console.print(f"\n[green]Added![/green]  {card.card_number} {subjects}  [dim]({copy.uuid[:8]})[/dim]")
+    delta = format_grade_delta(copy.grade_delta)
+    if delta:
+        console.print(f"  Self {copy.self_grade} vs {copy.grading_company} {copy.grade}: [bold]{delta}[/bold]")
+    if copy.acquisition_cost is not None:
+        console.print(f"  Acquisition cost: ${copy.acquisition_cost:.2f}")
+    if copy.cost_basis is not None:
+        console.print(f"  Cost basis:       ${copy.cost_basis:.2f}")
+    if copy.market and copy.market.fair_market_value is not None:
+        fmv = copy.market.fair_market_value
+        conf = " [yellow](low confidence)[/]" if copy.market.low_confidence else ""
+        console.print(f"  Market value:     [bold]${fmv:,.2f}[/]{conf}")
+        if copy.market.unrealized_gain_loss is not None:
+            g = copy.market.unrealized_gain_loss
+            color = "green" if g >= 0 else "red"
+            sign = "+" if g >= 0 else ""
+            console.print(f"  Unrealized:       [{color}]{sign}${g:,.2f}[/]")
+    console.print()
+
+    session.cards_added += 1
+
+
+def _add_single_card(session: AddSession, card: CardOut | None = None) -> bool:
+    """Run one add-card iteration. Returns True if the card was added, False if skipped/cancelled.
+
+    When `card` is given (e.g. from a chase-set missing-card walk) the catalog search is skipped and
+    that exact printing is used — you go straight to the acquisition details."""
+    # Decide how these cards were acquired (and the break/box) up front, so the search is scoped.
+    _ensure_acquisition_context(session)
+
+    if card is None:
+        card = _search_and_select_card(session)
+    if card is None:
+        return False
+
+    console.print(f"\n  [bold]{format_card_summary(card)}[/bold]\n")
+
+    acq_cost = _per_card_cost(session)
+    break_uuid = session.break_uuid
+    self_grade, grading_company, grade, cert_number = _collect_grade_details()
+    serial = _prompt_serial(card)
+
+    _show_review(card, session, acq_cost, break_uuid, self_grade, grading_company, grade, serial)
+
+    if not confirm("Add this card?", default=True):
+        console.print("[dim]Skipped.[/dim]\n")
+        return False
+
+    _submit_and_report(session, card, acq_cost, break_uuid, self_grade,
+                       grading_company, grade, cert_number, serial)
+    return True
+
+
+def cmd_add(args: list[str]) -> None:
+    """Add card(s) to your collection — interactive with batch support."""
+    session = AddSession(client=ctx.client, collector=ctx.collector)
+
+    while True:
+        _add_single_card(session)
+
+        if not confirm("Add another card?", default=True):
+            break
+
+    if session.cards_added > 0:
+        console.print(f"[dim]Done — {session.cards_added} card(s) added.[/dim]")
+
+
+# ---------------------------------------------------------------------------
+# cmd_break_fill — walk a break's checklist, adding the cards you pulled
+# ---------------------------------------------------------------------------
+
+_CHUNK_RE = re.compile(r"\d+|\D+")
+
+
+def _natural_chunks(s: str) -> tuple:
+    """Split a card number into comparable (kind, value) chunks so 'B-2' sorts before 'B-10'.
+    Digit runs compare numerically, letter runs lexically; the leading kind flag (0=text, 1=num)
+    keeps mixed tuples orderable."""
+    return tuple((1, int(t)) if t.isdigit() else (0, t.lower()) for t in _CHUNK_RE.findall(s))
+
+
+def _serial_key(card: CardOut) -> tuple:
+    """Physical-stack order: base cards (purely numeric card numbers) first, ascending numerically
+    (1, 2, ... 600); then alpha-prefixed inserts, alphabetical by their code (AA-SP before PV-ID).
+    The server's card_number sort is lexicographic ('10' < '2'), so we re-sort here."""
+    s = (card.card_number or "").strip()
+    return (0 if s.isdigit() else 1, _natural_chunks(s))
+
+
+def _load_checklist(client: SlabClient, collector: str, set_uuid: str) -> list[CardOut]:
+    """Fetch the checklist spine — one row per slot (base printings of every subset, inserts
+    included), scoped to the opened box — paging past the 200-per-request cap, then sort into
+    physical-stack order. `collector` annotates each slot with owned_quantity for a have/need walk."""
+    slots, _ = fetch_all_pages(
+        lambda limit, offset: client.search_cards(CardSearchQuery(
+            release=[set_uuid],
+            base_only=True,
+            collector=collector,
+            sort="card_number",
+            limit=limit,
+            offset=offset,
+        )),
+    )
+    slots.sort(key=_serial_key)
+    return slots
+
+
+def _add_from_slot(session: AddSession, base_card: CardOut) -> None:
+    """You said yes to a slot: pick the exact printing (base default, parallels on demand), then
+    the same grade/serial steps as `add`. Cost is derived from the break (pack pull), so nothing
+    to type."""
+    printings = session.client.get_parallels(base_card.uuid)
+    printing = select_printing_for_slot(printings)
+    if printing is None:
+        return
+
+    console.print(f"\n  [bold]{format_card_summary(printing)}[/bold]\n")
+    self_grade, grading_company, grade, cert_number = _collect_grade_details()
+    serial = _prompt_serial(printing)
+
+    _show_review(printing, session, None, session.break_uuid,
+                 self_grade, grading_company, grade, serial)
+
+    if confirm("Add this card?", default=True):
+        _submit_and_report(session, printing, None, session.break_uuid,
+                           self_grade, grading_company, grade, cert_number, serial)
+    else:
+        console.print("[dim]Skipped.[/dim]\n")
+
+
+def _walk_checklist(session: AddSession, slots: list[CardOut]) -> None:
+    """Step through the slots in physical-stack order. Enter skips, y adds, a card number jumps
+    to that slot, q quits."""
+    # First occurrence wins if two subsets happen to share a bare number (inserts are prefixed).
+    index_by_number: dict[str, int] = {}
+    for idx, s in enumerate(slots):
+        key = (s.card_number or "").strip().lower()
+        index_by_number.setdefault(key, idx)
+
+    i = 0
+    while 0 <= i < len(slots):
+        action, value = walk_prompt(slots[i], (i + 1, len(slots)))
+        if action == "quit":
+            break
+        if action == "skip":
+            i += 1
+        elif action == "add":
+            _add_from_slot(session, slots[i])
+            i += 1
+        elif action == "jump":
+            target = index_by_number.get((value or "").strip().lower())
+            if target is None:
+                console.print(f"[yellow]#{value} isn't in this checklist.[/yellow]")
+            else:
+                i = target
+
+
+def cmd_break_fill(args: list[str]) -> None:
+    """Walk a break's checklist card by card, adding the ones you pulled — no player names to type,
+    they come from the catalog. Cards are ordered like your physical stack: base serials first,
+    then inserts alphabetical by code."""
+    client, collector = ctx.client, ctx.collector
+
+    brk = pick_or_create_break(client, collector)
+    if brk is None:
+        console.print("[dim]No break selected.[/dim]")
+        return
+
+    console.print(f"\n[bold]Filling {brk.set_name}[/bold] — walking the checklist in serial order.")
+    console.print("[dim]  Enter to skip · y to add · type a card number to jump · q to finish.[/dim]")
+
+    slots = _load_checklist(client, collector, brk.set_uuid)
+    if not slots:
+        console.print("[yellow]No cards found for this set.[/yellow]")
+        return
+
+    session = AddSession(
+        client=client,
+        collector=collector,
+        acq_type=AcquisitionType.pack_pull,
+        break_uuid=brk.uuid,
+        release_set_uuid=brk.set_uuid,
+    )
+    _walk_checklist(session, slots)
+
+    if session.cards_added > 0:
+        console.print(f"[dim]Done — {session.cards_added} card(s) added to {brk.set_name}.[/dim]")
+
+
+# ---------------------------------------------------------------------------
+# cmd_lot_fill — rapid-add the cards in one purchase (person-by-person)
+# ---------------------------------------------------------------------------
+
+def cmd_lot_fill(args: list[str]) -> None:
+    """Add the cards from one purchase back-to-back — you pick the lot ONCE and its cost splits
+    across them, so there's no price to type per card (just grade/serial). Unlike `break fill` there
+    is no checklist to walk: a purchase isn't tied to a set, so you search each card by player
+    (player → set → card). It's `collection add` pre-scoped to this purchase — the repetitive parts
+    (re-choosing the lot, entering a price) removed."""
+    client, collector = ctx.client, ctx.collector
+
+    lot = pick_or_create_lot(client, collector)
+    if lot is None:
+        console.print("[dim]No purchase selected.[/dim]")
+        return
+
+    console.print(f"\n[bold]Filling purchase {lot.uuid[:8]}[/bold] — ${lot.total_cost:.2f}"
+                  + (f" · {lot.source}" if lot.source else "") + ".")
+    console.print("[dim]  Add each card you bought; its cost comes from the split.[/dim]")
+
+    session = AddSession(
+        client=client,
+        collector=collector,
+        acq_type=AcquisitionType.purchase,
+        lot_uuid=lot.uuid,
+        acquired_source=lot.source,
+    )
+
+    while True:
+        _add_single_card(session)
+        if not confirm("Add another card from this purchase?", default=True):
+            break
+
+    if session.cards_added > 0:
+        console.print(f"[dim]Done — {session.cards_added} card(s) added to purchase {lot.uuid[:8]}.[/dim]")
+
+
+# ---------------------------------------------------------------------------
+# cmd_remove
+# ---------------------------------------------------------------------------
+
+def cmd_remove(args: list[str]) -> None:
+    """Find and remove a card from your collection."""
+    q = ask_text("Search your collection:")
+    result = ctx.client.search_collection(ctx.collector, CollectionSearchQuery(q=q, limit=25))
+    if not result.items:
+        console.print("[yellow]No matching cards in your collection.[/yellow]")
+        return
+
+    copy = select_copy(result.items, message=f"Select the copy to remove ({result.total} found):")
+    if copy is None:
+        return
+
+    if confirm(f"Remove this copy? ({copy.uuid[:8]})", default=False):
+        ctx.client.delete_copy(ctx.collector, copy.uuid)
+        console.print("[green]Removed.[/green]")
+    else:
+        console.print("[dim]Cancelled.[/dim]")
+
+
+# ---------------------------------------------------------------------------
+# cmd_cost
+# ---------------------------------------------------------------------------
+
+def _print_cost_ledger(copy) -> None:
+    """Show a copy's existing post-acquisition costs."""
+    console.print("\n  [bold]Existing costs:[/bold]")
+    for c in copy.costs:
+        parts = [f"${c.amount:.2f}"]
+        if c.vendor:
+            parts.append(c.vendor)
+        if c.incurred_date:
+            parts.append(str(c.incurred_date))
+        desc = f" — {c.description}" if c.description else ""
+        console.print(f"    {c.cost_category}: " + " · ".join(parts) + desc)
+
+
+def _show_updated_basis(copy) -> None:
+    """Re-fetch the copy and print its recomputed cost basis after a ledger change."""
+    card_num = copy.card.card_number if copy.card else None
+    if not card_num:
+        return
+    try:
+        updated = ctx.client.search_collection(
+            ctx.collector, CollectionSearchQuery(card_number=card_num, limit=10)
+        )
+        for cp in updated.items:
+            if cp.uuid == copy.uuid and cp.cost_basis is not None:
+                console.print(f"  Updated cost basis: ${cp.cost_basis:.2f}")
+                break
+    except ApiError:
+        pass
+
+
+def _cost_add(copy) -> None:
+    """Log a new post-acquisition cost on a copy."""
+    category = select_cost_category()
+    amount = ask_decimal("Amount:")
+    vendor = ask_text_optional("Vendor (e.g. PSA, USPS — enter to skip):")
+    description = ask_text_optional("Description (enter to skip):")
+
+    ctx.client.add_cost(
+        ctx.collector,
+        copy.uuid,
+        CardCopyCostCreate(
+            cost_category=CostCategory(category),
+            amount=amount,
+            vendor=vendor,
+            description=description,
+        ),
+    )
+    console.print(f"\n[green]Cost added![/green]  {category}: ${amount:.2f}")
+    if vendor:
+        console.print(f"  Vendor: {vendor}")
+    _show_updated_basis(copy)
+
+
+def _cost_edit(copy) -> None:
+    """Edit an existing cost entry — each field is optional (enter to keep the current value)."""
+    cost = select_cost_entry(copy.costs, message="Edit which cost?")
+    if cost is None:
+        return
+
+    console.print(f"\n  Editing [bold]{cost.cost_category}[/bold] ${cost.amount:.2f}"
+                  + (f" · {cost.vendor}" if cost.vendor else ""))
+
+    changes: dict = {}
+    if confirm("Change the category?", default=False):
+        changes["cost_category"] = CostCategory(select_cost_category())
+    new_amount = ask_decimal_optional(f"New amount (enter to keep ${cost.amount:.2f}):")
+    if new_amount is not None:
+        changes["amount"] = new_amount
+    new_vendor = ask_text_optional("New vendor (enter to keep):")
+    if new_vendor is not None:
+        changes["vendor"] = new_vendor
+    new_desc = ask_text_optional("New description (enter to keep):")
+    if new_desc is not None:
+        changes["description"] = new_desc
+
+    if not changes:
+        console.print("[dim]No changes.[/dim]")
+        return
+
+    updated = ctx.client.update_cost(ctx.collector, copy.uuid, cost.uuid, CardCopyCostUpdate(**changes))
+    console.print(f"\n[green]Cost updated![/green]  {updated.cost_category}: ${updated.amount:.2f}")
+    _show_updated_basis(copy)
+
+
+def _cost_delete(copy) -> None:
+    """Delete a cost entry from a copy's ledger."""
+    cost = select_cost_entry(copy.costs, message="Delete which cost?")
+    if cost is None:
+        return
+
+    label = f"{cost.cost_category} ${cost.amount:.2f}" + (f" · {cost.vendor}" if cost.vendor else "")
+    if not confirm(f"Delete this cost? ({label})", default=False):
+        console.print("[dim]Cancelled.[/dim]")
+        return
+
+    ctx.client.delete_cost(ctx.collector, copy.uuid, cost.uuid)
+    console.print("[green]Deleted.[/green]")
+    _show_updated_basis(copy)
+
+
+def cmd_cost(args: list[str]) -> None:
+    """Manage a copy's post-acquisition costs (grading, shipping, …): add a new one, or fix/remove
+    an existing one. A copy with no costs yet goes straight to adding one."""
+    q = ask_text("Search your collection:")
+    result = ctx.client.search_collection(ctx.collector, CollectionSearchQuery(q=q, limit=25))
+    if not result.items:
+        console.print("[yellow]No matching cards in your collection.[/yellow]")
+        return
+
+    copy = select_copy(result.items, message="Select the copy:")
+    if copy is None:
+        return
+
+    # With an existing ledger, offer the full add/edit/delete choice; otherwise just add.
+    if copy.costs:
+        _print_cost_ledger(copy)
+        action = select_cost_action()
+        if action is None:
+            console.print("[dim]Cancelled.[/dim]")
+            return
+    else:
+        action = "add"
+
+    if action == "add":
+        _cost_add(copy)
+    elif action == "edit":
+        _cost_edit(copy)
+    elif action == "delete":
+        _cost_delete(copy)
+
+
+# ---------------------------------------------------------------------------
+# cmd_search
+# ---------------------------------------------------------------------------
+
+def cmd_search(args: list[str]) -> None:
+    """Search your collection with the full card grammar (same flags as `slab card search`)
+    plus collection-only filters (status, grading, acquisition, cost). Not a browser — for the
+    whole thing use `slab collection dashboard` (overview) or `slab collection export` (full list).
+
+    Examples:
+      slab collection search mcdavid
+      slab collection search --team "Minnesota Wild"
+      slab collection search --graded --company PSA
+      slab collection search --acq pack_pull --sort -fmv
+
+    Sort keys: acquired_date, acquisition_cost, numbered, year, card_number, brand, set,
+    fmv, unrealized, roi (prefix - for descending).
+    """
+    if not args:
+        total = ctx.client.search_collection(ctx.collector, CollectionSearchQuery(limit=1)).total
+        console.print(f"[bold]{total}[/bold] cards in your collection.")
+        console.print("  [dim]slab collection search <player>[/dim]   find specific cards")
+        console.print("  [dim]slab collection dashboard[/dim]         overview & stats")
+        console.print("  [dim]slab collection export[/dim]            full printable list")
+        return
+    values, q = parse_flags(args, COLLECTION_SEARCH_FLAGS)
+    values.setdefault("limit", 25)
+    result = ctx.client.search_collection(ctx.collector, CollectionSearchQuery(q=q, **values))
+    print_collection(result)
+
+
+cmd_search.flags = COLLECTION_SEARCH_FLAGS
+
+
+def cmd_sell(args: list[str]) -> None:
+    """Record a sale — mark a copy as sold with the sale price."""
+    q = ask_text("Search your collection:")
+    result = ctx.client.search_collection(ctx.collector, CollectionSearchQuery(q=q, limit=25))
+    if not result.items:
+        console.print("[yellow]No matching cards in your collection.[/yellow]")
+        return
+
+    copy = select_copy(result.items, message=f"Select the copy to sell ({result.total} found):")
+    if copy is None:
+        return
+
+    sale_price = ask_decimal("Sale price:")
+    sold_date = ask_date("Sale date:")
+
+    console.print(f"\n  [bold]Confirm sale:[/bold]")
+    card = copy.card
+    subjects = ", ".join(s.name for s in card.subjects) if card and card.subjects else "—"
+    console.print(f"    Card:       {card.card_number if card else '—'} {subjects}")
+    console.print(f"    Sale price: ${sale_price:.2f}")
+    if copy.cost_basis is not None:
+        realized = sale_price - copy.cost_basis
+        color = "green" if realized >= 0 else "red"
+        sign = "+" if realized >= 0 else ""
+        console.print(f"    Cost basis: ${copy.cost_basis:.2f}")
+        console.print(f"    Realized:   [{color}]{sign}${realized:,.2f}[/]")
+    console.print(f"    Date:       {sold_date}")
+
+    if not confirm("Record this sale?", default=True):
+        console.print("[dim]Cancelled.[/dim]")
+        return
+
+    updated = ctx.client.update_copy(
+        ctx.collector, copy.uuid,
+        CardCopyUpdate(
+            status=CopyStatus.sold,
+            sale_price=sale_price,
+            sold_date=sold_date,
+        ),
+    )
+    console.print(f"\n[green]Sold![/green]  {card.card_number if card else '—'} {subjects}")
+    if updated.realized_gain_loss is not None:
+        g = updated.realized_gain_loss
+        color = "green" if g >= 0 else "red"
+        sign = "+" if g >= 0 else ""
+        console.print(f"  Realized gain/loss: [{color}]{sign}${g:,.2f}[/]")
+    console.print()
+
+
+def cmd_dashboard(args: list[str]) -> None:
+    """A visual overview of your collection — counts, distributions, breaks, and highlights."""
+    render_dashboard(ctx.client.get_dashboard(ctx.collector))