dataface 0.1.2__py3-none-any.whl

dataface/cli/main.py

@@ -0,0 +1,1501 @@
+"""Main CLI entry point."""
+
+import importlib.util
+import logging
+import os
+import sys
+from pathlib import Path
+from typing import Annotated, Any, Literal
+
+import typer
+from rich import box
+from rich.console import Console
+from rich.panel import Panel
+from typer.core import TyperGroup
+
+from dataface._install_hint import install_hint
+from dataface.cli._console import is_plain_output
+from dataface.cli._parsing import parse_kv_pairs
+from dataface.cli.commands import (
+    chat as chat_cmd,
+    describe as describe_cmd,
+    docs as docs_cmd,
+    extension as extension_cmd,
+    init as init_cmd,
+    inspect as inspect_cmd,
+    query as query_cmd,
+    render as render_cmd,
+    schema as schema_cmd,
+    search as search_cmd,
+    serve as serve_cmd,
+    skills as skills_cmd,
+    validate as validate_cmd,
+)
+from dataface.cli.commands.mcp_init import run_init as _mcp_run_init
+from dataface.cli.commands.skills_init import run_init_skills as _skills_run_init
+from dataface.core.dashboard import RenderFormat
+from dataface.core.project_roots import find_dataface_project
+
+# Evaluated once at process startup — mid-session env changes won't take effect.
+_RICH_MARKUP_MODE: Literal["rich"] | None = None if is_plain_output() else "rich"
+# Probe for private package once at startup; avoids repeated find_spec calls.
+_SUPER_SCHEMA_AVAILABLE: bool = (
+    importlib.util.find_spec("dataface_super_schema") is not None
+)
+
+# MCP subcommand app
+mcp_app = typer.Typer(
+    name="mcp",
+    help="MCP (Model Context Protocol) server commands for AI assistant integration.",
+    no_args_is_help=True,
+    pretty_exceptions_show_locals=False,
+    rich_markup_mode=_RICH_MARKUP_MODE,
+)
+
+# Init subcommand app — `dft init` (project scaffold), `dft init mcp [client]`
+# (AI integration), `dft init code|cursor|vscode` (editor extension install).
+init_app = typer.Typer(
+    name="init",
+    help="Bootstrap a Dataface project, plus its AI / editor integrations.",
+    invoke_without_command=True,
+    pretty_exceptions_show_locals=False,
+    rich_markup_mode=_RICH_MARKUP_MODE,
+)
+
+# Inspect subcommand app
+inspect_app = typer.Typer(
+    name="inspect",
+    help="Inspect database tables and manage inspect templates.",
+    invoke_without_command=True,
+    pretty_exceptions_show_locals=False,
+    rich_markup_mode=_RICH_MARKUP_MODE,
+)
+
+# Shared --project-dir option. Every user-visible command that accepts a
+# project root uses this alias so help text, validation, and DFT_PROJECT_DIR
+# env-var wiring stay in lock-step.
+ProjectDirOption = Annotated[
+    Path | None,
+    typer.Option(
+        "--project-dir",
+        exists=True,
+        file_okay=False,
+        dir_okay=True,
+        resolve_path=True,
+        envvar="DFT_PROJECT_DIR",
+        help="Project root for resolving face paths and finding project config",
+    ),
+]
+
+
+# Configure logging for CLI (only if no handlers configured yet)
+if not logging.getLogger().handlers:
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(name)s - %(levelname)s - %(message)s",
+    )
+
+
+def _has_faces_marker(start: Path) -> bool:
+    """True iff *start* sits inside a Dataface project that has a ``faces/`` directory.
+
+    Anchors on :func:`find_dataface_project` so the walk-up stops at the
+    project root (any of ``dataface.yml``/``dataface.yaml``/``dbt_project.yml``)
+    rather than blindly hunting upward for stray ``faces/`` directories
+    elsewhere on the filesystem. A bare-dbt repo with no scaffolded
+    ``faces/`` returns False — that's the case the banner exists for.
+    """
+    if (start / "faces").is_dir():
+        return True
+    project = find_dataface_project(start)
+    return project is not None and (project / "faces").is_dir()
+
+
+def _render_init_banner() -> None:
+    """Print a nudge to run ``dft init``.
+
+    Only called from :class:`_RootHelpGroup.format_help` when cwd is
+    not inside a scaffolded project. In plain mode (agent context or
+    piped stdout) the banner renders as a single plain line so context
+    captures do not pick up Panel chrome.
+    """
+    if is_plain_output():
+        Console(force_terminal=False, no_color=True).print(
+            "Welcome to Dataface — run `dft init` to start a new project."
+        )
+        return
+    Console().print(
+        Panel(
+            "Run [bold cyan]dft init[/bold cyan] to start a new project!",
+            title="Welcome to Dataface",
+            title_align="left",
+            border_style="yellow",
+            box=box.ROUNDED,
+            padding=(0, 1),
+        )
+    )
+
+
+class _RootHelpGroup(TyperGroup):
+    """Root-only group: alphabetize the Options panel + commands and gate the init banner.
+
+    Click otherwise displays params in declaration order with the
+    auto-added `--help` last; that puts `--version` ahead of `--help`
+    on the root help. TyperGroup also overrides Click's sorted
+    list_commands with registration order, which buckets sub-typer
+    groups after leaf commands within the same rich_help_panel (e.g.
+    `init` after docs/playground/skills under Reference). Sorting here
+    interleaves them so each panel reads A-Z. Also prints the "run
+    `dft init`" banner above the help body when cwd isn't a scaffolded
+    Dataface project. Intentionally attached to the root Typer only —
+    sub-typer and leaf-command orders are left as authored, and
+    sub-typer help never shows the banner.
+    """
+
+    def get_params(self, ctx: Any) -> list[Any]:
+        def key(p: Any) -> str:
+            for opt in getattr(p, "opts", ()) or ():
+                if opt.startswith("--"):
+                    return opt.lstrip("-").lower()
+            return (p.name or "").lower()
+
+        return sorted(super().get_params(ctx), key=key)
+
+    def list_commands(self, ctx: Any) -> list[str]:
+        # typer.rich_utils.rich_format_help iterates this list once and
+        # buckets by rich_help_panel; the per-panel order is the iteration
+        # order, and the panel-section order is determined by which panel
+        # gets its first command first. Sort by (panel-rank, name) so the
+        # documented panel order (Dashboards -> Data & SQL -> AI -> Reference)
+        # survives while sub-typer groups interleave alphabetically with
+        # leaf commands inside each panel.
+        panel_by_name: dict[str, str] = {}
+        for n in super().list_commands(ctx):
+            cmd = self.get_command(ctx, n)
+            panel_by_name[n] = getattr(cmd, "rich_help_panel", None) or ""
+        panel_rank: dict[str, int] = {}
+        for panel in panel_by_name.values():
+            panel_rank.setdefault(panel, len(panel_rank))
+        return sorted(panel_by_name, key=lambda n: (panel_rank[panel_by_name[n]], n))
+
+    def format_help(self, ctx: Any, formatter: Any) -> None:
+        if not _has_faces_marker(Path.cwd()):
+            _render_init_banner()
+        super().format_help(ctx, formatter)
+
+
+# `help_option_names` on the root Click context inherits down to every
+# sub-Typer's group context and every leaf command, so a single setting
+# here gives `-h` to the whole CLI tree.
+app = typer.Typer(
+    name="dft",
+    help="Declarative, dbt-native dashboards in YAML.",
+    no_args_is_help=True,
+    pretty_exceptions_show_locals=False,
+    add_completion=False,
+    context_settings={"help_option_names": ["-h", "--help"]},
+    cls=_RootHelpGroup,
+    rich_markup_mode=_RICH_MARKUP_MODE,
+)
+
+
+# =============================================================================
+# init_app — `dft init …` subcommands (registered as a sub-typer at the bottom)
+# =============================================================================
+
+
+@init_app.callback(invoke_without_command=True)
+def init_default(
+    ctx: typer.Context,
+    project_dir: ProjectDirOption = None,
+    force: Annotated[
+        bool,
+        typer.Option("--force", "-f", help="Overwrite existing scaffold files"),
+    ] = False,
+    yes: Annotated[
+        bool,
+        typer.Option("--yes", "-y", help="Accept all defaults without prompting"),
+    ] = False,
+    agents_md: Annotated[
+        bool | None,
+        typer.Option("--agents-md/--no-agents-md", help="Write/append AGENTS.md"),
+    ] = None,
+    claude_md: Annotated[
+        bool | None,
+        typer.Option("--claude-md/--no-claude-md", help="Create CLAUDE.md pointer"),
+    ] = None,
+    skills: Annotated[
+        bool | None,
+        typer.Option(
+            "--skills/--no-skills",
+            help="Install workflow skills to agent skill directories",
+        ),
+    ] = None,
+    mcp: Annotated[
+        bool | None,
+        typer.Option("--mcp/--no-mcp", help="Set up MCP server for AI assistants"),
+    ] = None,
+    chat_extra: Annotated[
+        bool | None,
+        typer.Option(
+            "--chat-extra/--no-chat-extra",
+            help="Install dataface[chat] extra (enables dft chat)",
+        ),
+    ] = None,
+    with_playground: Annotated[
+        bool | None,
+        typer.Option(
+            "--with-playground/--no-with-playground",
+            help="Install dataface[playground] extra (enables dft playground)",
+        ),
+    ] = None,
+    vscode: Annotated[
+        bool | None,
+        typer.Option(
+            "--vscode/--no-vscode", help="Install Dataface extension into VS Code"
+        ),
+    ] = None,
+    cursor: Annotated[
+        bool | None,
+        typer.Option(
+            "--cursor/--no-cursor", help="Install Dataface extension into Cursor"
+        ),
+    ] = None,
+) -> None:
+    """Bootstrap a Dataface project in an existing repo.
+
+    Detects dbt projects, creates faces/ and faces/partials/, ejects inspect
+    templates, and writes starter dashboards. Optionally wires up MCP for AI
+    assistants and installs the dataface[chat] extra and IDE extensions.
+
+    Safe to re-run — existing files are never overwritten unless --force is used.
+    AGENTS.md: appends a short Dataface blurb when the file exists without markers;
+    refreshes only the ``<!-- dft-dataface:* -->`` section when markers are present.
+
+    Subcommands:
+      dft init skills [target]  # Install workflow skills for AI assistants
+      dft init mcp [client]     # Wire up MCP server
+      dft init code             # Install Dataface extension into VS Code
+      dft init cursor           # …or Cursor
+
+    \b
+    Examples:
+      dft init                        # Init with interactive wizard
+      dft init --yes                  # Accept all defaults non-interactively
+      dft init --project-dir ./myrepo # Init in a specific directory
+      dft init --force                # Re-scaffold, overwriting files
+      dft init --no-mcp --no-vscode   # Skip MCP and IDE extension
+      dft init --with-playground      # Also install dataface[playground]
+    """
+    if ctx.invoked_subcommand is not None:
+        return
+    init_cmd.run_wizard(
+        project_dir=project_dir,
+        force=force,
+        yes=yes,
+        agents_md=agents_md,
+        claude_md=claude_md,
+        skills=skills,
+        mcp=mcp,
+        chat_extra=chat_extra,
+        with_playground=with_playground,
+        vscode=vscode,
+        cursor=cursor,
+    )
+
+
+@init_app.command("code")
+def init_code() -> None:
+    """Install the Dataface extension into VS Code.
+
+    Installs the latest release of the Dataface extension into VS Code.
+    Idempotent — re-runs upgrade to the newest version.
+    """
+    raise typer.Exit(extension_cmd.install_extension("code", emit=typer.echo))
+
+
+@init_app.command("cursor")
+def init_cursor() -> None:
+    """Install the Dataface extension into Cursor.
+
+    Installs the latest release of the Dataface extension into Cursor.
+    Idempotent — re-runs upgrade to the newest version.
+    """
+    raise typer.Exit(extension_cmd.install_extension("cursor", emit=typer.echo))
+
+
+@init_app.command("vscode")
+def init_vscode() -> None:
+    """Alias for `dft init code`."""
+    raise typer.Exit(extension_cmd.install_extension("code", emit=typer.echo))
+
+
+# `dft init skills [target]` — file-based workflow skill install.
+@init_app.command("skills")
+def init_skills(
+    target: Annotated[
+        str | None,
+        typer.Argument(
+            help="Install target: agents (Cursor/Codex/Copilot), codex, or claude"
+        ),
+    ] = None,
+    all_targets: Annotated[
+        bool,
+        typer.Option("--all", help="Install to every detected skill directory"),
+    ] = False,
+    dir_override: Annotated[
+        Path | None,
+        typer.Option(
+            "--dir",
+            help="Explicit skills directory (e.g. .agents/skills)",
+            file_okay=False,
+            dir_okay=True,
+            resolve_path=True,
+        ),
+    ] = None,
+    force: Annotated[
+        bool,
+        typer.Option("--force", "-f", help="Overwrite existing skill files"),
+    ] = False,
+    check: Annotated[
+        bool,
+        typer.Option(
+            "--check",
+            help="Dry run: show what would be installed without writing files",
+        ),
+    ] = False,
+    project_dir: ProjectDirOption = None,
+) -> None:
+    """Install Dataface workflow skills for file-based agent auto-discovery.
+
+    Writes CLI-rendered skill files to ``.agents/skills/`` (Cursor, Codex,
+    Copilot) and/or ``.claude/skills/`` (Claude Code). Does not configure MCP
+    or modify AGENTS.md / CLAUDE.md.
+
+    \b
+    Examples:
+      dft init skills                 # Detect targets and install
+      dft init skills agents          # .agents/skills/ only
+      dft init skills claude          # .claude/skills/ only
+      dft init skills --all           # Every detected target dir
+      dft init skills --dir PATH      # Explicit destination
+      dft init skills --check         # Dry run
+      dft init skills -f              # Overwrite existing files
+    """
+    _skills_run_init(
+        target=target,
+        all_targets=all_targets,
+        dir_override=dir_override,
+        force=force,
+        check=check,
+        project_dir=project_dir,
+    )
+
+
+# `dft init mcp [client]` — MCP config only (skills: `dft init skills`).
+@init_app.command("mcp")
+def init_mcp(
+    client: Annotated[
+        str | None,
+        typer.Argument(
+            help=(
+                "Client to configure: cursor, vscode, claude, claude-code, "
+                "codex, copilot, or print. Omit to auto-detect."
+            )
+        ),
+    ] = None,
+    all_clients: Annotated[
+        bool,
+        typer.Option("--all", help="Write MCP config files for every supported client"),
+    ] = False,
+    force: Annotated[
+        bool,
+        typer.Option("--force", "-f", help="Overwrite existing MCP client config"),
+    ] = False,
+    project_dir: ProjectDirOption = None,
+) -> None:
+    """Add Dataface to your AI client's MCP configuration.
+
+    Writes MCP server entries only. Install workflow skills separately with
+    ``dft init skills``.
+
+    The project root is resolved by walking up from the current directory
+    looking for dataface.yml, dataface.yaml, or dbt_project.yml. Pass
+    --project-dir to override. When the project root differs from your AI
+    client's workspace, the recorded server command points at the project
+    so it starts in the right place.
+
+    \b
+    Examples:
+      dft init mcp                          # Auto-detect clients + project
+      dft init mcp cursor                   # Configure Cursor only
+      dft init mcp claude-code              # Configure Claude Code
+      dft init mcp --all                    # Write every supported config file
+      dft init mcp --project-dir ./analytics  # Target a specific project dir
+      dft init mcp print                    # Print config JSON (for manual setup)
+    """
+    _mcp_run_init(
+        client=client,
+        all_clients=all_clients,
+        force=force,
+        project_dir=project_dir,
+    )
+
+
+# =============================================================================
+# inspect_app — `dft inspect …` subcommands (registered hidden at the bottom)
+# =============================================================================
+
+
+@inspect_app.callback(invoke_without_command=True)
+def inspect_default(
+    ctx: typer.Context,
+    connection: Annotated[
+        str,
+        typer.Option(help="Database connection string", hidden=True),
+    ] = ":memory:",
+    dialect: Annotated[
+        str,
+        typer.Option(
+            help="SQL dialect (duckdb, postgres, bigquery, etc.)", hidden=True
+        ),
+    ] = "duckdb",
+    schema: Annotated[
+        str | None,
+        typer.Option(help="Schema filter", hidden=True),
+    ] = None,
+    output: Annotated[
+        str,
+        typer.Option(help="Path to save inspection JSON", hidden=True),
+    ] = "target/super_schema.json",
+    approximate: Annotated[
+        str,
+        typer.Option(help="Approximate profiling mode: auto, on, off", hidden=True),
+    ] = "auto",
+    include: Annotated[
+        str | None,
+        typer.Option(help="Glob pattern to include tables", hidden=True),
+    ] = None,
+    exclude: Annotated[
+        str | None,
+        typer.Option(help="Glob pattern to exclude tables", hidden=True),
+    ] = None,
+) -> None:
+    """Manage inspect templates and profile database tables (with dataface-super-schema).
+
+    Without subcommand: profiles all tables (requires dataface-super-schema).
+
+    \b
+    Examples:
+      dft inspect eject model          # Copy template to faces/inspect/
+      dft inspect templates            # List built-in templates
+      dft inspect table orders         # Profile a table (needs private pkg)
+    """
+    if ctx.invoked_subcommand is not None:
+        return
+    if not _SUPER_SCHEMA_AVAILABLE:
+        typer.echo(
+            "Batch profiling requires the dataface-super-schema package.\n"
+            "Install it from the monorepo or your private registry.\n\n"
+            "Run 'dft inspect --help' for available template-management commands.",
+            err=True,
+        )
+        raise typer.Exit(1)
+    from dataface_super_schema.cli.commands.inspect import (  # noqa: PLC0415
+        inspect_all_command,
+    )
+
+    inspect_all_command(
+        connection=connection,
+        dialect=dialect,
+        schema=schema,
+        output=output,
+        approximate=approximate,
+        include=include,
+        exclude=exclude,
+    )
+
+
+@inspect_app.command("eject")
+def inspect_eject(
+    templates: Annotated[
+        list[str] | None,
+        typer.Argument(help="Template names to eject (e.g., model quality)"),
+    ] = None,
+    all_templates: Annotated[
+        bool,
+        typer.Option("--all", help="Eject all available templates"),
+    ] = False,
+    force: Annotated[
+        bool,
+        typer.Option("--force", "-f", help="Overwrite existing files"),
+    ] = False,
+    output_dir: Annotated[
+        Path | None,
+        typer.Option(
+            "--output", "-o", help="Output directory (default: faces/inspect/)"
+        ),
+    ] = None,
+) -> None:
+    """Copy inspect templates to faces/inspect/ for customization.
+
+    Ejected templates can be modified to customize the inspect dashboards.
+    The server will use your customized version instead of the built-in template.
+
+    \b
+    Examples:
+      dft inspect eject model            # Eject just the model template
+      dft inspect eject model quality    # Eject specific templates
+      dft inspect eject --all            # Eject all templates
+      dft inspect eject model --force    # Overwrite existing
+      dft inspect eject --all -o custom/ # Custom output directory
+    """
+    inspect_cmd.eject_command(
+        templates=templates or [],
+        all_templates=all_templates,
+        force=force,
+        output_dir=output_dir,
+    )
+
+
+@inspect_app.command("templates")
+def inspect_templates() -> None:
+    """List available inspect templates.
+
+    Shows all built-in inspect templates that can be ejected and customized.
+
+    \b
+    Examples:
+      dft inspect templates
+    """
+    inspect_cmd.templates_command()
+
+
+@inspect_app.command("validate-templates")
+def inspect_validate_templates(
+    output_dir: Annotated[
+        Path | None,
+        typer.Option(
+            "--output",
+            "-o",
+            help="Inspect template directory (default: faces/inspect/)",
+        ),
+    ] = None,
+) -> None:
+    """Validate ejected inspect templates against current built-in template versions.
+
+    Helps teams detect when upstream template changes require rebasing custom templates.
+    """
+    inspect_cmd.validate_ejected_templates_command(output_dir=output_dir)
+
+
+# =============================================================================
+# mcp_app — `dft mcp …` subcommands (registered as a sub-typer at the bottom)
+# =============================================================================
+
+
+@mcp_app.command("serve")
+def mcp_serve(
+    project_dir: ProjectDirOption = None,
+) -> None:
+    """Start the MCP server for AI assistant integration.
+
+    This command starts an MCP (Model Context Protocol) server that enables
+    AI assistants like Claude, Cursor, and ChatGPT to interact with Dataface
+    dashboards.
+
+    The server speaks the MCP protocol over standard input/output — the
+    transport AI clients expect.
+
+    Requires the ``mcp`` extra (run ``dft mcp serve`` with it missing and
+    the printed install command is the canonical one for your environment).
+
+    \b
+    Examples:
+      dft mcp serve
+      dft mcp serve --project-dir ./my-project
+
+    \b
+    Configuration for Claude Desktop (~/.config/claude/config.json):
+      {
+        "mcpServers": {
+          "dataface": {
+            "command": "dft",
+            "args": ["mcp", "serve"]
+          }
+        }
+      }
+    """
+    try:
+        from dataface.ai.mcp import run_server
+    except ImportError as e:
+        typer.echo("MCP server requires additional dependencies.", err=True)
+        typer.echo(f"   Install with: {install_hint('mcp')}", err=True)
+        missing_module = str(e).split("'")[1] if "'" in str(e) else "unknown"
+        typer.echo(f"   Missing: {missing_module}", err=True)
+        raise typer.Exit(1) from None
+
+    import asyncio
+
+    # Change to specified directory if provided
+    if project_dir:
+        os.chdir(project_dir)
+        typer.echo(f"Working directory: {project_dir}", err=True)
+
+    # Run the MCP server (stdio mode)
+    # Note: We don't print anything to stdout as MCP uses it for communication
+    try:
+        asyncio.run(run_server())
+    except KeyboardInterrupt:
+        # Clean exit on Ctrl+C
+        raise typer.Exit(0) from None
+
+
+# =============================================================================
+# Root commands — registered in alphabetical order within each panel so that
+# commands appear A–Z inside Dashboards, Data & SQL, AI, and Reference.
+# Panel order (Dashboards -> Data & SQL -> AI -> Reference) is determined by
+# which panel's first command is registered first — so panel blocks must stay
+# in that order. Sub-typer add_typer() calls are inlined at their correct
+# alphabetical positions within each panel's block.
+# =============================================================================
+
+
+# --- Dashboards -------------------------------------------------------------
+
+
+@app.command("describe", rich_help_panel="Dashboards")
+def describe(
+    paths: Annotated[
+        list[Path],
+        typer.Argument(
+            metavar="[PATH]...",
+            help="Path(s) to face YAML files or directories to describe.",
+        ),
+    ],
+    json_output: Annotated[
+        bool,
+        typer.Option("--json", help="Output as JSON"),
+    ] = False,
+    project_dir: ProjectDirOption = None,
+) -> None:
+    """Describe a dashboard's queries, charts, variables, and layout.
+
+    Compiles the face YAML and returns a structured summary without executing
+    any queries. Use this for orientation when picking up an unfamiliar dashboard.
+    Accepts multiple paths; each may be a file or a directory (walked recursively).
+
+    \b
+    Examples:
+      dft describe faces/sales.yml
+      dft describe faces/sales.yml --json
+      dft describe faces/sales.yml --project-dir ./myrepo
+      dft describe faces/
+      dft describe faces/*.yml --json | jq '.[] | select(.charts | length > 5)'
+    """
+    describe_cmd.describe_command(
+        paths,
+        json_output=json_output,
+        project_dir=project_dir,
+    )
+
+
+@app.command("render", rich_help_panel="Dashboards")
+def render(
+    face: Annotated[
+        Path,
+        typer.Argument(
+            # No exists=/file_okay=: "-" is a valid stdin sentinel and must not fail the check.
+            help='Path to face YAML file, or "-" to read YAML from stdin',
+        ),
+    ],
+    output: Annotated[
+        Path | None,
+        typer.Option(help="Output file path (default: face name with extension)"),
+    ] = None,
+    format: Annotated[
+        RenderFormat,
+        typer.Option(
+            help="Output format: svg, html, png, pdf, terminal, json, text, or yaml"
+        ),
+    ] = "svg",
+    project_dir: ProjectDirOption = None,
+    var: Annotated[
+        list[str] | None,
+        typer.Option(help="Variable value as key=value (repeatable)"),
+    ] = None,
+    no_cache: Annotated[
+        bool,
+        typer.Option(
+            "--no-cache", help="Bypass all query caches and re-run from scratch"
+        ),
+    ] = False,
+    json_errors: Annotated[
+        bool,
+        typer.Option(
+            "--json-errors",
+            help=(
+                "Emit errors as JSON to stdout instead of formatted panels. "
+                "Only affects the error path; the success-path output is "
+                "still controlled by --format."
+            ),
+        ),
+    ] = False,
+    no_warnings: Annotated[
+        bool,
+        typer.Option(
+            "--no-warnings",
+            help=(
+                "Suppress warning output to stderr. Warnings are still included "
+                "in --format json output so agents and consumers always see them."
+            ),
+        ),
+    ] = False,
+    ignore_warning: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--ignore-warning",
+            help=(
+                "Suppress a specific warning code (repeatable). Suppressed warnings "
+                "move to suppressed_warnings in --format json output. "
+                "Unknown codes print a notice but do not exit non-zero."
+            ),
+        ),
+    ] = None,
+) -> None:
+    """Render a dashboard to SVG, HTML, PNG, PDF, or terminal.
+
+    Use "-" as the face argument to read YAML from stdin (useful for agents
+    and shell pipelines).
+
+    \b
+    Examples:
+      dft render faces/sales.yml
+      dft render faces/sales.yml --format html
+      dft render faces/sales.yml --var region=West --var category=Electronics
+      dft render faces/sales.yml --format terminal
+      dft render faces/sales.yml --no-cache
+      dft render faces/sales.yml --json-errors
+      dft render faces/sales.yml --no-warnings
+      dft render faces/sales.yml --ignore-warning BAR_COLOR_1_TO_1_WITH_X
+      echo 'charts: {c: {query: {type: csv, file: data.csv}}}' | dft render - --format terminal
+    """
+    variables = parse_kv_pairs(var or [], "--var")
+
+    use_cache = not no_cache
+    ignore_codes = set(ignore_warning) if ignore_warning else None
+
+    if str(face) == "-":
+        yaml_content = sys.stdin.read()
+        if not yaml_content.strip():
+            print("Error: No YAML input received from stdin", file=sys.stderr)
+            raise typer.Exit(1)
+        render_cmd.render_command_from_yaml(
+            yaml_content=yaml_content,
+            output=str(output) if output else None,
+            format=format,
+            project_dir=project_dir,
+            variables=variables or None,
+            use_cache=use_cache,
+            json_errors=json_errors,
+            no_warnings=no_warnings,
+            ignore_codes=ignore_codes,
+        )
+    else:
+        render_cmd.render_command(
+            face_path=face,
+            output=str(output) if output else None,
+            format=format,
+            project_dir=project_dir,
+            variables=variables or None,
+            use_cache=use_cache,
+            json_errors=json_errors,
+            no_warnings=no_warnings,
+            ignore_codes=ignore_codes,
+        )
+
+
+@app.command("search", rich_help_panel="Dashboards")
+def search(
+    query: Annotated[
+        str,
+        typer.Argument(help="Keywords to match against dashboard metadata"),
+    ],
+    json_output: Annotated[
+        bool,
+        typer.Option("--json", help="Output as JSON"),
+    ] = False,
+    limit: Annotated[
+        int,
+        typer.Option("--limit", help="Maximum results to return (default 10, max 50)"),
+    ] = 10,
+    project_dir: ProjectDirOption = None,
+) -> None:
+    """Search dashboards by keyword with ranked results.
+
+    Returns dashboards ranked by relevance to the query. Each hit includes
+    the title, summary, match score, source path, and matched query/chart names.
+
+    \b
+    Examples:
+      dft search revenue
+      dft search "monthly trends" --limit 5
+      dft search orders --json
+    """
+    search_cmd.search_command(
+        query=query,
+        json_output=json_output,
+        limit=limit,
+        project_dir=project_dir,
+    )
+
+
+@app.command("serve", rich_help_panel="Dashboards")
+def serve(
+    port: Annotated[
+        int | None,
+        typer.Option(help="Port number (auto-resolved if not set)"),
+    ] = None,
+    host: Annotated[
+        str,
+        typer.Option(help="Host address"),
+    ] = "localhost",
+    project_dir: ProjectDirOption = None,
+    connection: Annotated[
+        str | None,
+        typer.Option(help="Database connection string"),
+    ] = None,
+    dialect: Annotated[
+        str | None,
+        typer.Option(help="SQL dialect (auto-detected from dbt, or duckdb)"),
+    ] = None,
+    target: Annotated[
+        str | None,
+        typer.Option(
+            help="dbt target name (default: DBT_TARGET env, then profile default)"
+        ),
+    ] = None,
+) -> None:
+    """Start the dashboard server.
+
+    Renders your dashboards in the browser. Face file paths map
+    to URLs (faces/sales.yml → /sales/). Query params become variables.
+
+    Auto-discovers the project root by walking up from the current directory
+    to find dataface.yml or dbt_project.yml. When a dbt project is found,
+    the SQL dialect is inferred from the profile target.
+
+    Port is auto-resolved: --port flag > DFT_PORT env var > dataface.yml
+    port field > deterministic hash of project directory. If the chosen port
+    is occupied, the next available port is used automatically.
+
+    \b
+    Examples:
+      dft serve
+      dft serve --port 3000
+      dft serve --connection ./data.db --dialect duckdb
+      dft serve --target prod
+    """
+    serve_cmd.serve_command(
+        port=port,
+        host=host,
+        project_dir=project_dir,
+        connection=connection,
+        dialect=dialect,
+        target=target,
+    )
+
+
+@app.command("validate", rich_help_panel="Dashboards")
+def validate(
+    paths: Annotated[
+        list[Path] | None,
+        typer.Argument(
+            metavar="[PATH]...",
+            help="Face YAML files or directories (default: faces/)",
+        ),
+    ] = None,
+    project_dir: ProjectDirOption = None,
+    json_output: Annotated[
+        bool,
+        typer.Option("--json", help="Output as JSON"),
+    ] = False,
+    strict: Annotated[
+        bool,
+        typer.Option(help="Errors always fail; with --strict, warnings also fail."),
+    ] = False,
+) -> None:
+    """Fast YAML schema + cross-reference validation. No DB, no execute.
+
+    \b
+    Examples:
+      dft validate                              # Validate all faces in faces/
+      dft validate faces/                       # Validate all faces in a directory
+      dft validate faces/sales.yml              # Validate one file
+      dft validate faces/*.yml                  # Shell-expanded glob
+      dft validate faces/*.yml --json | jq '.[] | select(.success == false)'
+      dft validate faces/sales.yml faces/orders.yml --strict
+    """
+    validate_cmd.validate_command(
+        paths=paths,
+        project_dir=project_dir,
+        json_output=json_output,
+        strict=strict,
+    )
+
+
+# --- Data & SQL -------------------------------------------------------------
+
+
+@app.command(
+    "query",
+    rich_help_panel="Data & SQL",
+    help="""\b
+SQL and named face queries — common forms:
+  dft query NAME --in FACE.yml
+  dft query 'SQL' --source SRC
+  dft query 'SQL' --validate
+  dft query 'SQL' --describe --source SRC
+
+TARGET is a query name when --in is set; otherwise it's a SQL string.
+--file reads SQL from a file. SQL execute requires --source.
+--validate runs offline.""",
+)
+def query(
+    target: Annotated[
+        str | None,
+        typer.Argument(
+            metavar="TARGET",
+            help="Query name (with --in) or SQL string",
+        ),
+    ] = None,
+    face: Annotated[
+        Path | None,
+        typer.Option(
+            "--in",
+            "-i",
+            metavar="PATH",
+            help="Face YAML path; switches TARGET to named-query mode",
+        ),
+    ] = None,
+    source: Annotated[
+        str | None,
+        typer.Option(
+            "--source",
+            help="Data source (required for raw SQL execute; overrides face source for --describe)",
+        ),
+    ] = None,
+    validate: Annotated[
+        bool,
+        typer.Option(
+            "--validate",
+            help="Static SQL lint only (works for named queries and raw SQL)",
+        ),
+    ] = False,
+    describe: Annotated[
+        bool,
+        typer.Option(
+            "--describe",
+            help="Return column names and types (runs --validate gate first)",
+        ),
+    ] = False,
+    file: Annotated[
+        Path | None,
+        typer.Option("--file", "-f", metavar="PATH", help="Read SQL from file"),
+    ] = None,
+    dialect: Annotated[
+        str | None,
+        typer.Option("--dialect", help="SQL dialect for lint (duckdb, bigquery, …)"),
+    ] = None,
+    var: Annotated[
+        list[str] | None,
+        typer.Option("--var", help="Variable override as key=value (repeatable)"),
+    ] = None,
+    limit: Annotated[
+        int,
+        typer.Option("--limit", help="Max rows, execute path (default 20, max 1000)"),
+    ] = 20,
+    show_suppressed: Annotated[
+        bool,
+        typer.Option("--show-suppressed", help="Include suppressed lint diagnostics"),
+    ] = False,
+    json_output: Annotated[
+        bool,
+        typer.Option("--json", help="JSON output"),
+    ] = False,
+    project_dir: ProjectDirOption = None,
+) -> None:
+    variables = parse_kv_pairs(var or [], "--var")
+
+    query_cmd.query_command(
+        target=target,
+        face=face,
+        source=source,
+        validate=validate,
+        describe=describe,
+        file=file,
+        dialect=dialect,
+        vars=variables or None,
+        limit=limit,
+        show_suppressed=show_suppressed,
+        json_output=json_output,
+        project_dir=project_dir,
+    )
+
+
+_SCHEMA_SEARCH_PANEL = "Search"
+
+
+@app.command("schema", rich_help_panel="Data & SQL")
+def schema(
+    source: Annotated[
+        str | None,
+        typer.Argument(
+            metavar="SOURCE",
+            help="Data source name (omit to list all sources).",
+        ),
+    ] = None,
+    schema_name: Annotated[
+        str | None,
+        typer.Argument(
+            metavar="SCHEMA",
+            help="Schema/namespace name (requires SOURCE).",
+        ),
+    ] = None,
+    table: Annotated[
+        str | None,
+        typer.Argument(
+            metavar="TABLE",
+            help="Table name for deep profiling (requires SOURCE SCHEMA).",
+        ),
+    ] = None,
+    column: Annotated[
+        str | None,
+        typer.Argument(
+            metavar="COLUMN",
+            help="Column name for distribution detail (requires SOURCE SCHEMA TABLE).",
+        ),
+    ] = None,
+    search: Annotated[
+        str | None,
+        typer.Option(
+            "-s",
+            "--search",
+            rich_help_panel=_SCHEMA_SEARCH_PANEL,
+            help=(
+                "Keyword/regexp — filters the table list when given with "
+                "SOURCE + SCHEMA, otherwise searches the schema corpus "
+                "(see Modes above for examples)."
+            ),
+        ),
+    ] = None,
+    scope: Annotated[
+        str | None,
+        typer.Option(
+            "--scope",
+            rich_help_panel=_SCHEMA_SEARCH_PANEL,
+            help=(
+                "Comma-list of fields to search "
+                "(name, description, tag, tests, meta, owner). Default: all."
+            ),
+        ),
+    ] = None,
+    regex: Annotated[
+        bool,
+        typer.Option(
+            "--regex",
+            rich_help_panel=_SCHEMA_SEARCH_PANEL,
+            help="Treat -s keyword as a regular expression.",
+        ),
+    ] = False,
+    role: Annotated[
+        str | None,
+        typer.Option(
+            "--role",
+            rich_help_panel=_SCHEMA_SEARCH_PANEL,
+            help="Filter columns by profiled role (e.g. identifier, measure, time).",
+        ),
+    ] = None,
+    tag: Annotated[
+        str | None,
+        typer.Option(
+            "--tag",
+            rich_help_panel=_SCHEMA_SEARCH_PANEL,
+            help="Filter to rows tagged with this value.",
+        ),
+    ] = None,
+    has_test: Annotated[
+        str | None,
+        typer.Option(
+            "--has-test",
+            rich_help_panel=_SCHEMA_SEARCH_PANEL,
+            help="Filter columns whose dbt tests include this name (e.g. not_null).",
+        ),
+    ] = None,
+    missing: Annotated[
+        str | None,
+        typer.Option(
+            "--missing",
+            rich_help_panel=_SCHEMA_SEARCH_PANEL,
+            help="Include rows that are missing this field (e.g. description).",
+        ),
+    ] = None,
+    column_name: Annotated[
+        str | None,
+        typer.Option(
+            "--column-name",
+            rich_help_panel=_SCHEMA_SEARCH_PANEL,
+            help="Filter to columns matching this glob (e.g. `*_id`).",
+        ),
+    ] = None,
+    table_name: Annotated[
+        str | None,
+        typer.Option(
+            "--table-name",
+            rich_help_panel=_SCHEMA_SEARCH_PANEL,
+            help="Filter to tables matching this glob (e.g. `stg_*`).",
+        ),
+    ] = None,
+    fk_to: Annotated[
+        str | None,
+        typer.Option(
+            "--fk-to",
+            rich_help_panel=_SCHEMA_SEARCH_PANEL,
+            help="Filter to columns with relationships pointing at this table.",
+        ),
+    ] = None,
+    meta: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--meta",
+            rich_help_panel=_SCHEMA_SEARCH_PANEL,
+            help="Filter by exact-match meta key=value (repeatable).",
+        ),
+    ] = None,
+    fields: Annotated[
+        str | None,
+        typer.Option(
+            "--fields",
+            rich_help_panel=_SCHEMA_SEARCH_PANEL,
+            help=(
+                "Show only these fields on each hit "
+                "(comma-list, e.g. `location,matched_field`)."
+            ),
+        ),
+    ] = None,
+    limit: Annotated[
+        int | None,
+        typer.Option(
+            "--limit",
+            rich_help_panel=_SCHEMA_SEARCH_PANEL,
+            help="Truncate to N hits (total/truncated reported).",
+        ),
+    ] = None,
+    json_output: Annotated[
+        bool,
+        typer.Option(
+            "--json",
+            help=(
+                "Output as JSON. "
+                "Envelope: sources.<SRC>.schemas.<SCH>.tables.<TBL>.columns.<COL>."
+            ),
+        ),
+    ] = False,
+    project_dir: ProjectDirOption = None,
+    lineage_depth: Annotated[
+        int,
+        typer.Option(
+            "--lineage-depth",
+            min=1,
+            max=10,
+            help="Hops of upstream/downstream lineage to surface (1–10, default 1)",
+        ),
+    ] = 1,
+) -> None:
+    """Browse the data hierarchy or search the schema corpus.
+
+    Modes
+    -----
+
+    Drill-down (default) — deepest non-None arg determines the return tier:
+
+    \b
+      dft schema                               # list configured data sources
+      dft schema mydb                          # list schemas in that source
+      dft schema mydb main                     # list tables
+      dft schema mydb main orders              # profile table
+      dft schema mydb main orders id           # profile column
+
+    Search mode (-s / --search) — full-text + filter across the schema corpus:
+
+    \b
+      dft schema -s mrr
+      dft schema -s "" --role primary_key      # filter-only (empty keyword)
+      dft schema -s customer --column-name "*_id" --json
+
+    Level-3 regexp filter (-s with SOURCE + SCHEMA) — filter the table list
+    by regexp without leaving drill-down mode:
+
+    \b
+      dft schema wh analytics -s 'revenue|arr'
+      dft schema wh analytics -s 'revenue|arr' --json
+      dft schema -s ".*_at$" --regex --json --fields location,matched_field
+      dft schema -s "" --missing description --table-name "stg_*"
+
+    Use --json for stable JSON output suitable for agent consumption.
+
+    Piping (drill-down) — escape hatch for ad-hoc cross-cutting queries:
+
+    \b
+      # Tables with more than 1000 rows:
+      dft schema wh analytics '*' --json | jq '.sources.wh.schemas.analytics.tables | to_entries[] | select(.value.row_count > 1000) | .key'
+
+    \b
+      # Every column whose name ends in _at:
+      dft schema wh analytics '*' '*' --json | jq '[.sources.wh.schemas.analytics.tables | to_entries[] | {table: .key, cols: [.value.columns | to_entries[] | select(.key | test("_at$")) | .key]}] | map(select(.cols | length > 0))'
+
+    Always quote glob args to prevent shell expansion: TABLE '*', TABLE 'stg_*'.
+    """
+    schema_cmd.schema_command(
+        source=source,
+        schema=schema_name,
+        table=table,
+        column=column,
+        json_output=json_output,
+        project_dir=project_dir,
+        lineage_depth=lineage_depth,
+        search=search,
+        scope=scope,
+        regex=regex,
+        role=role,
+        tag=tag,
+        has_test=has_test,
+        missing=missing,
+        column_name=column_name,
+        table_name=table_name,
+        fk_to=fk_to,
+        meta=meta,
+        fields=fields,
+        limit=limit,
+    )
+
+
+# --- AI ---------------------------------------------------------------------
+
+
+@app.command("chat", rich_help_panel="AI")
+def chat(
+    prompt: Annotated[
+        str | None,
+        typer.Argument(help="Optional one-shot prompt"),
+    ] = None,
+    model: Annotated[
+        str | None,
+        typer.Option("--model", help="Model name, optionally provider-prefixed"),
+    ] = None,
+    continue_session: Annotated[
+        bool,
+        typer.Option(
+            "-c",
+            "--continue",
+            help="Resume the most recent session for the current directory",
+        ),
+    ] = False,
+    resume: Annotated[
+        str | None,
+        typer.Option(
+            "-r",
+            "--resume",
+            help="Resume a specific session by id (see --pick for the interactive list)",
+        ),
+    ] = None,
+    pick: Annotated[
+        bool,
+        typer.Option(
+            "-p",
+            "--pick",
+            help="Open an interactive picker to choose a session to resume",
+        ),
+    ] = False,
+) -> None:
+    """Chat with a terminal AI agent.
+
+    Sessions are auto-saved to ~/.dft/sessions/ and indexed by working directory.
+
+    \b
+    Examples:
+      dft chat                           # Start a fresh session
+      dft chat "What tables do I have?"  # One-shot prompt
+      dft chat -c                        # Resume last session for this directory
+      dft chat -r <session-id>           # Resume a specific session by id
+      dft chat -p                        # Pick from a list of recent sessions
+    """
+    chat_cmd.chat_command(
+        prompt=prompt,
+        model=model,
+        continue_session=continue_session,
+        resume=resume,
+        pick=pick,
+    )
+
+
+app.add_typer(mcp_app, name="mcp", rich_help_panel="AI")
+
+
+# --- Reference --------------------------------------------------------------
+
+
+@app.command("docs", rich_help_panel="Reference")
+def docs(
+    topic: Annotated[
+        str | None,
+        typer.Argument(
+            help="Topic name (run `dft docs` for the index). Use 'all' for the whole reference or 'reference' for the YAML field reference."
+        ),
+    ] = None,
+    search: Annotated[
+        str | None,
+        typer.Option("--search", "-s", help="Full-text query across all topics"),
+    ] = None,
+    json_output: Annotated[
+        bool,
+        typer.Option("--json", help="Output as JSON"),
+    ] = False,
+    limit: Annotated[
+        int,
+        typer.Option(
+            "--limit",
+            min=1,
+            max=50,
+            help="Max search hits to return (default 5, max 50)",
+        ),
+    ] = 5,
+) -> None:
+    """Browse the Dataface YAML reference offline (topics, search).
+
+    \b
+    Modes:
+      dft docs                    # Topic index (one row per H2 section)
+      dft docs cheatsheet         # One-page essentials
+      dft docs <topic>            # Full docs for one section
+      dft docs all                # Whole reference, unsliced
+      dft docs reference          # Generated YAML field reference
+      dft docs --search "grid"    # Substring search across all topics
+
+    Use --json for stable, machine-readable output.
+    """
+    docs_cmd.docs_command(
+        topic=topic,
+        search=search,
+        json_output=json_output,
+        limit=limit,
+    )
+
+
+app.add_typer(init_app, name="init", rich_help_panel="Reference")
+
+
+# Split "extra not installed" (use stub) from "extra installed but broken"
+# (let the ImportError propagate) — a blanket except would swallow real
+# transitive-import failures into the install-hint stub.
+if importlib.util.find_spec("dataface_playground") is None:
+
+    @app.command("playground", rich_help_panel="Reference")
+    def playground_not_installed() -> None:
+        """Start interactive playground with YAML editor and live preview.
+
+        Requires the ``playground`` extra.
+        """
+        from dataface.cli._extras import require_extras
+
+        require_extras("playground")
+
+else:
+    from dataface_playground.cli import main as _playground_main
+
+    app.command("playground", rich_help_panel="Reference")(_playground_main)
+
+
+@app.command("skills", rich_help_panel="Reference")
+def skills(
+    skill_name: Annotated[
+        str | None,
+        typer.Argument(help="Skill name to show (default: list all)"),
+    ] = None,
+    search: Annotated[
+        str | None,
+        typer.Option("--search", "-s", help="Search names, descriptions, and bodies"),
+    ] = None,
+    limit: Annotated[
+        int,
+        typer.Option("--limit", min=1, max=25, help="Max search hits (default 10)"),
+    ] = 10,
+    as_json: Annotated[
+        bool,
+        typer.Option("--json", help="Output as JSON"),
+    ] = False,
+) -> None:
+    """List packaged agent skills, search them, or show one by name.
+
+    \b
+    Modes:
+      dft skills                  # List all skills (grouped: workflows + patterns)
+      dft skills <name>           # Show the named skill body
+      dft skills -s "<query>"     # Search names, descriptions, and bodies
+      dft skills --json           # Stable JSON for any of the above
+
+    Skills are agent workflows and layout patterns. For YAML field reference,
+    use `dft docs` instead.
+    """
+    skills_cmd.skills_command(
+        name=skill_name,
+        search=search,
+        limit=limit,
+        as_json=as_json,
+    )
+
+
+# Hidden — not shown in root help
+app.add_typer(inspect_app, name="inspect", hidden=True)
+
+# Load CLI plugins registered via [project.entry-points."dataface.cli_plugins"].
+# Each plugin's ``register()`` callable mounts its subcommands onto Typer apps
+# (e.g. ``inspect_app``) before the app executes. Runs at import time so that
+# ``dft --help`` shows profiler commands when the private package is installed.
+# importlib.metadata is stdlib since Python 3.8; dataface requires >=3.10, so
+# the outer try is unnecessary. Plugin load errors surface to the user rather
+# than being silently swallowed.
+from importlib.metadata import entry_points as _entry_points
+
+for _ep in _entry_points(group="dataface.cli_plugins"):
+    _plugin = _ep.load()
+    _plugin()
+
+
+def version_callback(value: bool) -> None:
+    """Print version and exit."""
+    if value:
+        from dataface.cli._version_info import collect
+
+        typer.echo(collect().render())
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: Annotated[
+        bool | None,
+        typer.Option(
+            "--version",
+            help="Print version and exit.",
+            callback=version_callback,
+            is_eager=True,
+        ),
+    ] = None,
+) -> None:
+    """dft - Declarative, dbt-native dashboards in YAML."""
+    pass
+
+
+if __name__ == "__main__":
+    app()