ripple-sql 0.1.0__py3-none-any.whl

ripple/cli.py

@@ -0,0 +1,733 @@
+"""Ripple CLI.
+
+    ripple                        summary of the current project
+    ripple breaks model.column    what a change to this column affects
+    ripple trace model.column     where this column's value comes from
+    ripple graph [-o FILE]        full lineage graph as JSON
+    ripple unresolved             external tables blocking coverage
+    ripple ingest-schema FILE     add warehouse column lists (JSON/CSV, - for stdin)
+    ripple ingest-usage FILE      add a query-history export (what actually ran)
+    ripple collect-usage [PLAT]   run your own warehouse CLI and ingest what ran
+    ripple usage                  what ran and what didn't, from that history
+    ripple mcp                    run as an MCP server (stdio)
+    ripple doctor                 check that this install can serve MCP clients
+    ripple serve [model.column]   the answer page, live: ask in a browser, see coverage
+
+Output stays quiet: counts and names first, detail on request (--json).
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from ripple.answer import (
+    PREVIEW_COLUMNS,
+    attach,
+    breaks_lines,
+    noun_for,
+    plain_text,
+    trace_lines,
+)
+
+DIM = "\033[2m"
+BOLD = "\033[1m"
+AMBER = "\033[33m"
+RESET = "\033[0m"
+
+
+def _style(text: str, *codes: str) -> str:
+    if not sys.stdout.isatty():
+        return text
+    return "".join(codes) + text + RESET
+
+
+SHARED_NAME_EXAMPLES = 3
+
+
+def _fold_shared_names(pairs: list[tuple[str, int]]) -> list[tuple[str, int]]:
+    """Three shared-name examples and a count, never the whole list.
+
+    HTTP Archive's almanac keeps one query per chapter per year, so 841 names
+    are shared across year folders; each printed its own line, 841 lines
+    between the answer and the next step. The full list stays in --json."""
+    shared = [pair for pair in pairs if "share the name" in pair[0]]
+    if len(shared) <= SHARED_NAME_EXAMPLES:
+        return pairs
+    others = [pair for pair in pairs if "share the name" not in pair[0]]
+    hidden = len(shared) - SHARED_NAME_EXAMPLES
+    note = (
+        f"...and {hidden} more names shared by several files, each qualified by "
+        "path (full list: ripple --json)"
+    )
+    return others + shared[:SHARED_NAME_EXAMPLES] + [(note, 1)]
+
+
+def _collapse(messages) -> list[tuple[str, int]]:
+    """Distinct messages in first-seen order, with how many times each ran."""
+    counts: dict[str, int] = {}
+    for message in messages:
+        counts[message] = counts.get(message, 0) + 1
+    return list(counts.items())
+
+
+def _configure_logging(verbose: bool) -> None:
+    """Per-file parse failures are counted in the summary and detailed in
+    --json, so without --verbose they must not reach stderr. Unconfigured,
+    Python's last-resort handler prints every warning, which on a large repo
+    buries the answer under hundreds of lines and reads as a crash.
+
+    Set on the root logger, not on "ripple": most of the volume comes from
+    sqlglot, and quieting only our own loggers left 298 of 301 lines on a
+    7,439-model repo. Any library we add later is covered by the same line.
+    """
+    import logging
+
+    level = logging.DEBUG if verbose else logging.ERROR
+    logging.basicConfig(level=level, stream=sys.stderr, format="%(message)s")
+    logging.getLogger().setLevel(level)
+
+
+def _note(message: str) -> None:
+    """Progress goes to stderr so piping stdout stays clean."""
+    print(_style(message, DIM), file=sys.stderr)
+
+
+def _load_graph(args):
+    import time
+
+    from ripple.graph import LineageGraph
+    from ripple.project import find_project_root, load_project
+
+    root = find_project_root(Path(args.path))
+    use_cache = not getattr(args, "no_cache", False)
+    if use_cache:
+        from ripple import cache
+
+        cached = cache.load(root, args.dialect)
+        if cached is not None:
+            return cached.project, cached
+    quiet = getattr(args, "json", False)
+    if not quiet:
+        # a large repo takes minutes here with nothing to show for it; saying
+        # so is the difference between "working" and "hung"
+        _note(f"Reading SQL in {root} (first run; later questions use the cache)...")
+    started = time.monotonic()
+    project = load_project(args.path, dialect=args.dialect)
+    graph = LineageGraph.build(project)
+    if use_cache:
+        from ripple import cache
+
+        cache.store(graph, root, args.dialect)
+    if not quiet:
+        elapsed = time.monotonic() - started
+        cached_note = "cached, so the next question is instant" if use_cache else "not cached"
+        _note(f"Indexed {len(project.models)} models in {elapsed:.0f}s ({cached_note}).\n")
+    return project, graph
+
+
+def _parse_target(target: str) -> tuple[str, str]:
+    if "." not in target:
+        sys.exit(f"Expected model.column, got '{target}'")
+    model, _, column = target.rpartition(".")
+    return model, column
+
+
+MODE_WORDS = {
+    "dbt-manifest": "compiled dbt manifest",
+    "dbt-raw": "reading raw model SQL",
+    "dbt-monorepo": "several dbt projects",
+    "sql-dir": "plain SQL files",
+}
+
+
+def _dominant_cause(project, graph, stats) -> str:
+    """Why the review count is what it is, and the command that shrinks it.
+
+    "426 links need review" told filecoin-data-portal's reader nothing
+    actionable. But blame must be counted, not guessed: on jaffle-shop this
+    line blamed 6 external tables, the user closed all six, and the count
+    moved from 18 to 18. A cause is only named with the number of review
+    links it actually accounts for.
+    """
+    guessed = any("Assuming" in w and "dialect" in w for w in project.warnings)
+    if guessed and stats["failed"]:
+        return (
+            f"the dialect was guessed as {stats['dialect']} and "
+            f"{stats['failed']} models would not parse: try --dialect"
+        )
+    review = [e for e in graph.edges if e.trust == "review_required"]
+    external = sum(1 for e in review if "not found in this project" in e.reason)
+    if external:
+        share = f"all {external}" if external == len(review) else f"{external} of the {len(review)}"
+        return f"{share} trace to tables defined outside the project: ripple unresolved"
+    if stats["failed"] or stats["star_only"]:
+        return "some models could not be fully parsed: ripple --json for which"
+    return ""
+
+
+def cmd_summary(args) -> None:
+    project, graph = _load_graph(args)
+    stats = graph.stats()
+    if args.json:
+        print(json.dumps({**stats, "warnings": list(project.warnings)}, indent=2))
+        return
+    mode = MODE_WORDS.get(stats["mode"], stats["mode"])
+    noun = noun_for(stats["mode"])
+    print(
+        f"{_style(str(stats['models']), BOLD)} {noun}s, {stats['sources']} sources "
+        f"{_style('(' + mode + ' · ' + stats['dialect'] + ')', DIM)}"
+    )
+    print(f"{stats['ok']} analyzed in full, {stats['edges']} column links")
+    partial = stats["star_only"] + stats["fallback"] + stats["failed"] + stats["timed_out"]
+    if partial:
+        print(
+            _style(f"{partial} {noun}s partially covered or skipped (details: ripple --json)", DIM)
+        )
+    if stats["review_required_edges"]:
+        print(_style(f"{stats['review_required_edges']} links need review", AMBER))
+        cause = _dominant_cause(project, graph, stats)
+        if cause:
+            print(_style(f"  {cause}", DIM))
+    for warning, count in _fold_shared_names(_collapse(project.warnings)):
+        # one line per distinct warning: a 16-project monorepo used to print
+        # the same "no compiled manifest" sentence 16 times
+        suffix = f" (x{count})" if count > 1 else ""
+        print(_style(warning + suffix, DIM))
+    print(_style("\n" + _next_step(project, graph), DIM))
+
+
+def _next_step(project, graph) -> str:
+    """One runnable command, always.
+
+    A project where nothing has downstream fanout used to end on collision
+    warnings with no next move, which is where a new reader stops. sqlmesh-examples
+    and dagster-open-platform both landed there.
+    """
+    suggestion = graph.suggest_target()
+    if suggestion:
+        return (
+            f"try: ripple breaks {suggestion['model']}.{suggestion['column']}"
+            f"  (feeds {suggestion['fanout']} downstream)"
+        )
+    if not project.models:
+        return f"No SQL found in {project.root}. Run inside a dbt project or SQL directory."
+    widest = max(
+        project.models,
+        key=lambda m: len(getattr(graph.reports.get(m.name), "columns", []) or []),
+    )
+    return f"try: ripple columns {widest.name}  (nothing here has downstream reach yet)"
+
+
+def _run_target_query(graph, method: str, model: str, column: str, max_depth: int = 25) -> dict:
+    from ripple.graph import UnknownTarget
+
+    try:
+        return getattr(graph, method)(model, column, max_depth=max(1, max_depth))
+    except UnknownTarget as e:
+        hint = f" Did you mean: {', '.join(e.suggestions)}?" if e.suggestions else ""
+        print(f"{e}.{hint}", file=sys.stderr)
+        sys.exit(2)
+
+
+LINE_STYLES = {"plain": None, "bold": BOLD, "dim": DIM, "warn": AMBER}
+
+
+def _print_lines(lines: list[list[tuple[str, str]]]) -> None:
+    for segments in lines:
+        print(
+            "".join(
+                _style(text, LINE_STYLES[role]) if LINE_STYLES[role] else text
+                for text, role in segments
+            )
+        )
+
+
+def cmd_breaks(args) -> None:
+    project, graph = _load_graph(args)
+    model, column = _parse_target(args.target)
+    result = _run_target_query(graph, "breaks", model, column, max_depth=args.depth)
+    result = attach(result, "breaks", noun_for(project.mode))
+    if args.json:
+        print(json.dumps(result, indent=2))
+        return
+    answer = result["answer"]
+    _print_lines(breaks_lines(answer, full=args.full))
+    _page_door(args, project, graph, answer, plain_text(breaks_lines(answer, full=True)))
+
+
+def cmd_trace(args) -> None:
+    project, graph = _load_graph(args)
+    model, column = _parse_target(args.target)
+    result = _run_target_query(graph, "trace", model, column, max_depth=args.depth)
+    result = attach(result, "trace", noun_for(project.mode))
+    if args.json:
+        print(json.dumps(result, indent=2))
+        return
+    answer = result["answer"]
+    _print_lines(trace_lines(answer))
+    _page_door(args, project, graph, answer, result["text"])
+
+
+def _page_door(args, project, graph, answer: dict, text: str) -> None:
+    """--html writes the answer page where asked; --open writes it under
+    .ripple/answers and hands it to a browser, or prints the path when no
+    browser will take it (a sandbox, an SSH session)."""
+    if not (getattr(args, "html", None) or getattr(args, "open", False)):
+        return
+    from ripple import answer_page
+
+    path = answer_page.write_for(
+        graph, Path(project.root), answer, text, Path(args.html) if args.html else None
+    )
+    if args.open and answer_page.open_in_browser(path):
+        print(_style(f"opened {path}", DIM))
+    else:
+        print(_style(f"answer page: {path}", DIM))
+
+
+def cmd_models(args) -> None:
+    _, graph = _load_graph(args)
+    rows = []
+    for name, report in sorted(graph.reports.items()):
+        rows.append(
+            {
+                "name": name,
+                "columns": len([c for c in report.columns if c != "*"]),
+                "status": report.status,
+            }
+        )
+    if args.json:
+        print(json.dumps(rows, indent=2))
+        return
+    for row in rows:
+        note = (
+            "" if row["status"] == "ok" else _style(f"  ({row['status'].replace('_', ' ')})", DIM)
+        )
+        print(f"{row['name']} {_style('· ' + str(row['columns']) + ' columns', DIM)}{note}")
+
+
+def cmd_columns(args) -> None:
+    from ripple.graph import UnknownTarget
+
+    _, graph = _load_graph(args)
+    try:
+        name, _ = graph._require_target(args.model, "")
+    except UnknownTarget as e:
+        if "no column" not in str(e):
+            hint = f" Did you mean: {', '.join(e.suggestions)}?" if e.suggestions else ""
+            print(f"{e}.{hint}", file=sys.stderr)
+            sys.exit(2)
+        name = graph._candidates[args.model.lower()][0]
+    report = graph.reports[name]
+    columns = [c for c in report.columns if c != "*"]
+    if args.json:
+        print(json.dumps({"model": name, "columns": columns, "status": report.status}, indent=2))
+        return
+    print(f"{name} {_style('· ' + report.status.replace('_', ' '), DIM)}")
+    for column in columns:
+        fanout = sum(1 for e in graph._down.get((name, column), []) if e.kind == "value")
+        mark = _style(f"  → feeds {fanout}", DIM) if fanout else ""
+        print(f"  {column}{mark}")
+
+
+def cmd_graph(args) -> None:
+    _, graph = _load_graph(args)
+    payload = json.dumps(graph.to_dict(), indent=2)
+    if args.output:
+        Path(args.output).write_text(payload, encoding="utf-8")
+        print(f"wrote {args.output}")
+    else:
+        print(payload)
+
+
+def cmd_unresolved(args) -> None:
+    _, graph = _load_graph(args)
+    unresolved = graph.unresolved_tables()
+    if args.json:
+        print(json.dumps({"unresolved": unresolved, "total": len(unresolved)}, indent=2))
+        return
+    if not unresolved:
+        print("Every referenced table resolves; nothing to ingest.")
+        return
+    print(f"{_style(str(len(unresolved)), BOLD)} external tables with unknown columns:")
+    for row in unresolved:
+        blocked = (
+            _style(f"  blocks {row['blocked_models']}", AMBER) if row["blocked_models"] else ""
+        )
+        print(
+            f"  {row['table']} "
+            f"{_style('· referenced by ' + str(row['referencing_models']), DIM)}{blocked}"
+        )
+    print(
+        _style(
+            "\nfetch their columns from your warehouse, then: ripple ingest-schema cols.csv",
+            DIM,
+        )
+    )
+
+
+def cmd_ingest_schema(args) -> None:
+    from ripple.project import find_project_root
+    from ripple.schemas import merge_schemas, normalize_tables, parse_csv
+
+    text = (
+        sys.stdin.read()
+        if args.file == "-"
+        else Path(args.file).read_text(errors="replace", encoding="utf-8")
+    )
+    stripped = text.lstrip()
+    try:
+        if stripped.startswith(("{", "[")):
+            payload = json.loads(text)
+            tables = normalize_tables({"rows": payload} if isinstance(payload, list) else payload)
+        else:
+            tables = parse_csv(text)
+    except (json.JSONDecodeError, ValueError) as e:
+        sys.exit(f"Could not read {args.file}: {e}")
+    root = find_project_root(Path(args.path))
+    from ripple import cache
+
+    before = None if getattr(args, "no_cache", False) else cache.load(root, args.dialect)
+    before_review = before.stats()["review_required_edges"] if before else None
+    delta = merge_schemas(root, tables)
+    if args.json:
+        print(json.dumps(delta, indent=2))
+        return
+    changed = [*delta["tables_added"], *delta["tables_updated"]]
+    if not changed:
+        print("Nothing new; schemas already known.")
+        return
+    print(
+        f"{_style(str(delta['columns_added']), BOLD)} columns across "
+        f"{len(changed)} tables written to {delta['path']}"
+    )
+    for name in changed:
+        print(f"  {name}")
+    # the promise of doing this work is a smaller review count; show whether
+    # it moved, including an honest "still N" (jaffle went 18 to 18 because
+    # its review links had a different cause)
+    _, graph = _load_graph(args)
+    after_review = graph.stats()["review_required_edges"]
+    if before_review is None or before_review != after_review:
+        origin = f"{before_review} → " if before_review is not None else ""
+        print(_style(f"links needing review: {origin}{after_review}", DIM))
+    else:
+        print(
+            _style(
+                f"links needing review: still {before_review}; these have another "
+                "cause (ripple --json shows each edge's reason)",
+                DIM,
+            )
+        )
+
+
+def cmd_ci(args) -> None:
+    from ripple.ci import run
+
+    sys.exit(
+        run(args.base, args.path, args.dialect, args.json, args.fail_on, args.select, args.html)
+    )
+
+
+def cmd_ingest_usage(args) -> None:
+    from ripple.project import find_project_root
+    from ripple.usage import ingest_file
+    from ripple.usage.ingest import write_store
+
+    project, _ = _load_graph(args)
+    try:
+        store = ingest_file(
+            args.file,
+            [m.name for m in project.models],
+            project.dialect,
+            model_aliases={m.name: set(m.aliases) for m in project.models},
+        )
+    except (OSError, ValueError) as e:
+        sys.exit(str(e))
+    write_store(find_project_root(Path(args.path)), store)
+    if args.json:
+        print(json.dumps(store, indent=2))
+        return
+    stats = store["statements"]
+    touched = stats["touched_tables"]
+    rate = f", {100.0 * stats['matched'] / touched:.0f}% matched this project" if touched else ""
+    print(f"Ingested {stats['total']:,} statements{rate}.")
+    print(_style("\ntry: ripple usage", DIM))
+
+
+def cmd_collect_usage(args) -> None:
+    from ripple.usage.cli import run_collect
+
+    run_collect(args, _load_graph)
+
+
+def cmd_usage(args) -> None:
+    from ripple.project import find_project_root
+    from ripple.usage import render, render_empty
+    from ripple.usage.ingest import models_fingerprint, read_store
+
+    store = read_store(find_project_root(Path(args.path)))
+    if store is None:
+        print(render_empty())
+        return
+    warning = None
+    recorded = store.get("models_fingerprint")
+    if recorded:
+        current = _current_model_names(args)
+        if current is not None and models_fingerprint(current) != recorded:
+            warning = (
+                "the project's models changed since this usage was ingested; "
+                "per-model counts reflect the old set. Re-run: ripple collect-usage "
+                "(or ingest-usage)."
+            )
+    if args.json:
+        print(json.dumps({**store, "warning": warning} if warning else store, indent=2))
+        return
+    if warning:
+        print(_style(warning, AMBER) + "\n")
+    print(render(store))
+
+
+def _current_model_names(args) -> list[str] | None:
+    """Today's model names, as cheaply as truth allows: the cached graph
+    when one exists, a project load (no graph build) otherwise."""
+    from ripple import cache
+    from ripple.project import find_project_root, load_project
+
+    root = find_project_root(Path(args.path))
+    cached = None if getattr(args, "no_cache", False) else cache.load(root, args.dialect)
+    if cached is not None:
+        return [m.name for m in cached.project.models]
+    try:
+        return [m.name for m in load_project(args.path, dialect=args.dialect).models]
+    except Exception:
+        return None
+
+
+def cmd_mcp(args) -> None:
+    from ripple.mcp_server import run_stdio
+
+    run_stdio(path=args.path, dialect=args.dialect)
+
+
+def cmd_doctor(args) -> None:
+    from ripple.doctor import run
+
+    sys.exit(run(as_json=args.json))
+
+
+def cmd_serve(args) -> None:
+    from ripple.server import serve
+
+    serve(path=args.path, dialect=args.dialect, port=args.port, target=args.target)
+
+
+def add_common(parser: argparse.ArgumentParser, suppress: bool = False) -> None:
+    # SUPPRESS keeps subparser defaults from clobbering flags given before the subcommand.
+    def dflt(value):
+        return argparse.SUPPRESS if suppress else value
+
+    parser.add_argument("--path", default=dflt("."), help="project directory (default: current)")
+    parser.add_argument(
+        "--dialect", default=dflt(None), help="SQL dialect override (snowflake, bigquery, ...)"
+    )
+    parser.add_argument(
+        "--json", action="store_true", default=dflt(False), help="machine-readable output"
+    )
+    parser.add_argument(
+        "--no-cache",
+        action="store_true",
+        default=dflt(False),
+        help="rebuild instead of using the graph cache",
+    )
+    parser.add_argument(
+        "--verbose",
+        action="store_true",
+        default=dflt(False),
+        help="show per-file parse failures instead of counting them",
+    )
+
+
+def _page_flags(parser) -> None:
+    parser.add_argument(
+        "--html", metavar="PATH", help="also write the answer as a self-contained page"
+    )
+    parser.add_argument(
+        "--open",
+        action="store_true",
+        help="write the answer page under .ripple/answers and open it in your browser",
+    )
+
+
+def utf8_streams() -> None:
+    """A pipe out of ripple carries UTF-8 on every OS. Windows defaults a
+    pipe to the ANSI code page, which cannot encode the arrows in the text
+    and is not what the program on the other end expects. A console keeps
+    its own encoding and shows a placeholder for what it cannot draw."""
+    for stream in (sys.stdin, sys.stdout, sys.stderr):
+        if stream is None or not hasattr(stream, "reconfigure"):
+            continue
+        if stream.isatty():
+            stream.reconfigure(errors="replace")
+        else:
+            stream.reconfigure(encoding="utf-8", errors="replace")
+
+
+def main(argv: list[str] | None = None) -> None:
+    utf8_streams()
+    common = argparse.ArgumentParser(add_help=False)
+    add_common(common, suppress=True)
+
+    parser = argparse.ArgumentParser(
+        prog="ripple",
+        description="See what a SQL change breaks before you merge.",
+    )
+    add_common(parser)
+    try:
+        from importlib.metadata import version
+
+        parser.add_argument(
+            "--version", action="version", version=f"ripple {version('ripple-sql')}"
+        )
+    except Exception:
+        pass
+    sub = parser.add_subparsers(dest="command")
+
+    sub.add_parser("models", help="list models with column counts", parents=[common])
+    p_columns = sub.add_parser(
+        "columns", help="list a model's columns and their fanout", parents=[common]
+    )
+    p_columns.add_argument("model")
+
+    p_breaks = sub.add_parser("breaks", help="what breaks if this column changes", parents=[common])
+    p_breaks.add_argument("target", help="model.column")
+    p_breaks.add_argument(
+        "--full",
+        action="store_true",
+        help=f"list every affected column, not the first {PREVIEW_COLUMNS} per model",
+    )
+    p_breaks.add_argument(
+        "--depth", type=int, default=25, help="follow lineage this many hops (default 25)"
+    )
+    _page_flags(p_breaks)
+
+    p_trace = sub.add_parser("trace", help="where this column comes from", parents=[common])
+    p_trace.add_argument("target", help="model.column")
+    p_trace.add_argument(
+        "--depth", type=int, default=25, help="follow lineage this many hops (default 25)"
+    )
+    _page_flags(p_trace)
+
+    p_graph = sub.add_parser("graph", help="export the lineage graph as JSON", parents=[common])
+    p_graph.add_argument("-o", "--output", default=None)
+
+    p_ci = sub.add_parser(
+        "ci", help="blast radius of the models changed since a git ref", parents=[common]
+    )
+    p_ci.add_argument("--base", default="origin/main", help="git ref to compare against")
+    p_ci.add_argument(
+        "--fail-on",
+        choices=["none", "breaks", "review"],
+        default="none",
+        help="exit nonzero if the change breaks things (breaks) or has unverified edges (review)",
+    )
+    p_ci.add_argument(
+        "--html",
+        metavar="PATH",
+        help="also write the change as a self-contained answer page, one view per changed column",
+    )
+    p_ci.add_argument(
+        "--select",
+        choices=["dbt"],
+        default=None,
+        help="print only the models to rebuild, as a dbt --select string: "
+        'dbt build --select "$(ripple ci --select dbt)". Exits 0; anything '
+        "uncertain widens to model+ rather than being skipped",
+    )
+
+    sub.add_parser(
+        "unresolved", help="external tables blocking coverage (unknown columns)", parents=[common]
+    )
+    p_ingest = sub.add_parser(
+        "ingest-schema",
+        help="add warehouse column lists for external tables (JSON or CSV)",
+        parents=[common],
+    )
+    p_ingest.add_argument("file", help="JSON/CSV file with table columns, or - for stdin")
+
+    p_ingest_usage = sub.add_parser(
+        "ingest-usage",
+        help="add a query-history export: what actually ran (JSONL or JSON array)",
+        parents=[common],
+    )
+    p_ingest_usage.add_argument("file", help="query-history export with a query_text field")
+
+    p_collect = sub.add_parser(
+        "collect-usage",
+        help="run your own warehouse CLI (snow, bq, databricks) and ingest what ran",
+        parents=[common],
+    )
+    p_collect.add_argument(
+        "platform",
+        nargs="?",
+        choices=["snowflake", "bigquery", "databricks"],
+        help="omit to see what's installed and configured",
+    )
+    p_collect.add_argument(
+        "--connection",
+        default=None,
+        help="connection or profile name (for bigquery: the project id)",
+    )
+    p_collect.add_argument("--days", type=int, default=7, help="window size (default 7)")
+    p_collect.add_argument(
+        "--scope",
+        choices=["mine", "account"],
+        default="mine",
+        help="mine = your queries, no permission; account = everyone's, may need a grant",
+    )
+    p_collect.add_argument("--region", default="us", help="BigQuery INFORMATION_SCHEMA region")
+    p_collect.add_argument(
+        "--timeout", type=float, default=60.0, help="seconds before the CLI call is abandoned"
+    )
+
+    sub.add_parser(
+        "usage", help="what ran and what didn't, from the ingested history", parents=[common]
+    )
+
+    sub.add_parser("mcp", help="run as an MCP server over stdio", parents=[common])
+
+    sub.add_parser("doctor", help="check that this install can serve MCP clients", parents=[common])
+
+    p_serve = sub.add_parser(
+        "serve", help="the answer page, live: ask in a browser, see coverage", parents=[common]
+    )
+    p_serve.add_argument("target", nargs="?", help="open on this question (model.column)")
+    p_serve.add_argument("--port", type=int, default=8722)
+
+    args = parser.parse_args(argv)
+    _configure_logging(getattr(args, "verbose", False))
+    handlers = {
+        None: cmd_summary,
+        "models": cmd_models,
+        "columns": cmd_columns,
+        "breaks": cmd_breaks,
+        "trace": cmd_trace,
+        "graph": cmd_graph,
+        "ci": cmd_ci,
+        "unresolved": cmd_unresolved,
+        "ingest-schema": cmd_ingest_schema,
+        "ingest-usage": cmd_ingest_usage,
+        "collect-usage": cmd_collect_usage,
+        "usage": cmd_usage,
+        "mcp": cmd_mcp,
+        "doctor": cmd_doctor,
+        "serve": cmd_serve,
+    }
+    handlers[args.command](args)
+
+
+if __name__ == "__main__":
+    main()