dataspring-cli 0.3.0__py3-none-any.whl

cli/main.py

@@ -0,0 +1,3232 @@
+"""DataSpring CLI - Main entry point.
+
+Two layers, one wire. ``cli/generated.py`` is the dispatch registry as
+commands, generated from the models in ``cli/contract.py`` (decision D19,
+step 4): ``dataspring <key> --<field>`` for a flat tool, ``dataspring <key>
+<verb> --<field>`` for an edit family, every flag a model field, so the
+tree can never lack a field the server has. This module mounts that tree
+and adds the human layer on top: the session commands (login, whoami,
+version, upgrade, skills), the reads over the REST routes (``metrics
+list``, ``dashboards show``, ...), and a few short-named conveniences
+(``query``, ``switch``, ``sql``, ``export``, ``secret set --stdin``,
+``datacore pull|push|check|deploy|run|reset``) that are each a few lines
+over the same ``cli.runtime.call_tool`` the generated commands use, with a
+prompt, a file, stdin or a table where a person wants one. Nothing here
+builds a dispatch body by hand.
+"""
+
+import asyncio
+import json
+import sys
+from pathlib import Path
+from typing import Annotated, Literal, NoReturn, Optional
+
+import typer
+import yaml
+
+from cli.auth import CLIAuthManager, AuthenticationError
+from cli.generated import mount as mount_generated
+from cli.output import (
+    console,
+    format_output,
+    print_error,
+    print_info,
+    print_report_hint,
+    print_success,
+    print_warning,
+    print_yaml,
+    print_user_context,
+    print_visualization_suggestion,
+    OutputFormat,
+)
+from cli.runtime import call_tool
+
+
+# Initialize auth manager
+auth = CLIAuthManager()
+
+# Initialize main app
+app = typer.Typer(
+    name="dataspring",
+    help="DataSpring CLI - Query metrics and manage dashboards from the terminal.",
+    no_args_is_help=True,
+)
+
+# Sub-command groups: the reads and the human conveniences. Writes are the
+# generated tree (`dataspring dashboard_edit create ...`, mounted at the end
+# of this module); a group here that once held create/update/delete keeps
+# only what the generated twin cannot be: a read, a prompt, a file, stdin.
+metrics_app = typer.Typer(help="Metrics: list and show (writes: dataspring metric_edit)")
+dimensions_app = typer.Typer(help="Dimension operations")
+org_app = typer.Typer(help="Organization operations")
+dashboards_app = typer.Typer(help="Dashboards: list, show, update from a file, widgets by id (writes: dashboard_edit, widget_edit)")
+manifest_app = typer.Typer(help="Manifest: status and export (upload: dataspring import_manifest)")
+models_app = typer.Typer(help="Semantic models: list and show (writes: dataspring semantic_model_edit)")
+schedules_app = typer.Typer(help="Scheduled reports: list and show (writes: dataspring report_edit)")
+quick_metrics_app = typer.Typer(help="Quick metrics: list and show (writes: dataspring quick_metric_edit)")
+context_app = typer.Typer(help="Your preferences (update: dataspring update_context)")
+
+# Register sub-command groups
+app.add_typer(metrics_app, name="metrics")
+app.add_typer(dimensions_app, name="dimensions")
+app.add_typer(org_app, name="org")
+app.add_typer(dashboards_app, name="dashboards")
+app.add_typer(manifest_app, name="manifest")
+app.add_typer(models_app, name="models")
+app.add_typer(schedules_app, name="schedules")
+app.add_typer(quick_metrics_app, name="quick-metrics")
+app.add_typer(context_app, name="context")
+business_context_app = typer.Typer(help="Org business_context document operations")
+app.add_typer(business_context_app, name="business-context")
+learned_app = typer.Typer(help="The learned trail: what DataSpring learned for this org")
+app.add_typer(learned_app, name="learned")
+warehouses_app = typer.Typer(help="The org's warehouses: external and managed, and which is active")
+app.add_typer(warehouses_app, name="warehouses")
+datacore_app = typer.Typer(help="The datacore workspace: pull, edit locally, push, check, deploy, run")
+app.add_typer(datacore_app, name="datacore")
+from cli.skills_commands import skills_app  # noqa: E402
+app.add_typer(skills_app, name="skills")
+
+
+# ============================================================================
+# Helpers
+# ============================================================================
+#
+# Every command talks to the DataSpring API over HTTPS with the user's OAuth
+# access token. Reads use the REST routes; every write, and every operation
+# the server owns end to end (query, explain, export, render, org switch), goes
+# through ``POST /api/dispatch/{tool_key}`` - the same handlers MCP and the
+# inline agent call, so role checks, validation and the learned trail happen
+# once, on the server. The CLI never opens Firestore or a warehouse itself:
+# nothing under backend/cli/ imports `services`, `storage`, `warehouse`,
+# `mf_engine` or google-cloud-firestore (tests/test_cli_thin_client.py pins
+# that). Before this, thirty-eight commands imported the service layer and hit
+# Firestore with the operator's local Google credentials, keyed by an e-mail
+# in a user-editable config file - which bypassed every server role check.
+
+
+def run_async(coro):
+    """Run an async function synchronously."""
+    return asyncio.run(coro)
+
+
+def split_commas(values: Optional[list[str]]) -> Optional[list[str]]:
+    """Allow ``-m a,b,c`` as a shorthand for ``-m a -m b -m c``.
+
+    Typer's ``list[str]`` only splits on repeated flags; bare commas pass
+    through as one string and MetricFlow then 500s on the unknown name.
+    """
+    if not values:
+        return values
+    return [item.strip() for entry in values for item in entry.split(",") if item.strip()]
+
+
+def require_auth():
+    """Get authenticated user or exit with error.
+
+    Returns:
+        UserContext for authenticated user
+
+    Raises:
+        typer.Exit: If not authenticated
+    """
+    try:
+        return run_async(auth.get_user())
+    except AuthenticationError as e:
+        print_error(str(e), hint="Run 'dataspring login' to authenticate")
+        raise typer.Exit(1)
+
+
+def get_api_base() -> str:
+    """Get the backend API base URL."""
+    from settings import get_settings
+    # mcp_server_base_url is https://dataspring.app/api
+    # /query endpoint is at root, not under /api
+    base = get_settings().mcp_server_base_url
+    # Strip /api suffix to get the host root
+    return base.removesuffix("/api")
+
+
+def api_get(path: str, token: str, timeout: float = 60.0) -> dict:
+    """Make an authenticated GET request to the backend API."""
+    import httpx
+
+    url = f"{get_api_base()}{path}"
+    with httpx.Client(timeout=timeout) as client:
+        response = client.get(
+            url,
+            headers={"Authorization": f"Bearer {token}"},
+        )
+        response.raise_for_status()
+        return response.json()
+
+
+def api_delete(path: str, token: str, timeout: float = 60.0) -> dict:
+    """Make an authenticated DELETE request to the backend API."""
+    import httpx
+
+    url = f"{get_api_base()}{path}"
+    with httpx.Client(timeout=timeout) as client:
+        response = client.delete(
+            url,
+            headers={"Authorization": f"Bearer {token}"},
+        )
+        response.raise_for_status()
+        return response.json()
+
+
+def api_put(path: str, body: dict, token: str, timeout: float = 60.0) -> dict:
+    """Make an authenticated PUT request to the backend API."""
+    import httpx
+
+    url = f"{get_api_base()}{path}"
+    with httpx.Client(timeout=timeout) as client:
+        response = client.put(
+            url,
+            headers={"Authorization": f"Bearer {token}"},
+            json=body,
+        )
+        response.raise_for_status()
+        return response.json()
+
+
+def api_post(path: str, body: dict, token: str, timeout: float = 60.0) -> dict:
+    """Make an authenticated POST request to the backend API.
+
+    Args:
+        path: URL path (e.g. "/api/dispatch/query_metrics")
+        body: JSON request body
+        token: OAuth access token
+
+    Returns:
+        Parsed JSON response
+
+    Raises:
+        Exception: On HTTP or connection errors
+    """
+    import httpx
+
+    url = f"{get_api_base()}{path}"
+    with httpx.Client(timeout=timeout) as client:
+        response = client.post(
+            url,
+            headers={"Authorization": f"Bearer {token}"},
+            json=body,
+        )
+        response.raise_for_status()
+        return response.json()
+
+
+class DispatchToolError(Exception):
+    """A dispatch handler answered ``{"error": ...}`` (with HTTP 200).
+
+    The handlers report domain failures - "Metric 'x' not found", a role the
+    user lacks, an expression that does not parse - in the body rather than as
+    a status code, so the wire shape is the same on MCP and here. Raised by
+    `api_dispatch` so a command handles it on the same path as an HTTP error.
+    """
+
+    def __init__(self, payload: dict):
+        self.payload = payload
+        self.code = payload.get("code")
+        self.hint = payload.get("suggestion") or payload.get("hint")
+        super().__init__(str(payload.get("error")))
+
+
+def api_dispatch(tool_key: str, body: dict, token: str, timeout: float = 60.0) -> dict:
+    """``POST /api/dispatch/{tool_key}`` and unwrap the handler's answer.
+
+    Action families take ``{"action": {"action": "<verb>", ...}}``; flat tools
+    take their keyword arguments as the body. A ``{"error": ...}`` answer
+    becomes `DispatchToolError`; HTTP 400/403/404 arrive as
+    ``httpx.HTTPStatusError`` from `api_post`. `format_api_error` turns either
+    into a message the user can act on.
+    """
+    result = api_post(f"/api/dispatch/{tool_key}", body, token, timeout=timeout)
+    if isinstance(result, dict) and result.get("error"):
+        raise DispatchToolError(result)
+    return result
+
+
+def _response_detail(response) -> str | None:
+    """The server's ``detail`` as one line, whatever shape it came in.
+
+    FastAPI's own errors carry a string; the dispatch route answers a
+    malformed action with pydantic's list of ``{loc, msg}``; ``/query`` used
+    to answer ``{"message": ..., "suggestions": [...]}``.
+    """
+    try:
+        body = response.json()
+    except Exception:
+        return None
+    detail = body.get("detail") if isinstance(body, dict) else None
+    if detail is None:
+        return None
+    if isinstance(detail, dict):
+        return str(detail.get("message") or detail)
+    if isinstance(detail, list):
+        parts = []
+        for err in detail:
+            if isinstance(err, dict):
+                loc = ".".join(str(p) for p in err.get("loc", []) if p != "body")
+                parts.append(f"{loc}: {err.get('msg')}" if loc else str(err.get("msg")))
+            else:
+                parts.append(str(err))
+        return "; ".join(parts)
+    return str(detail)
+
+
+def format_api_error(exc: Exception, role_action: str | None = None) -> tuple[str, str | None]:
+    """Turn an exception from an api_* call into (message, hint).
+
+    Pulls the server's ``detail`` field out of an HTTPStatusError when present so
+    the user sees the actual error rather than a generic httpx repr. The
+    ``role_action`` hint (e.g. ``"delete metrics"``) is only attached to 403
+    responses; on other failures the hint is omitted so we don't gaslight the
+    user into thinking it's a permission problem. A `DispatchToolError` carries
+    the handler's own message and, when it offered one, its suggestion.
+    """
+    import httpx
+
+    if isinstance(exc, DispatchToolError):
+        return str(exc), exc.hint
+
+    if isinstance(exc, httpx.HTTPStatusError):
+        status = exc.response.status_code
+        detail = _response_detail(exc.response)
+        message = detail if detail else str(exc)
+        if status == 401:
+            hint = "Your login was rejected - run 'dataspring login' again."
+        elif status == 403:
+            hint = (
+                f"You need a higher role to {role_action}." if role_action
+                else "You don't have permission for this action."
+            )
+        elif status == 404:
+            hint = None  # message already says "not found"
+        elif status >= 500:
+            hint = "Server error — check backend logs or try again."
+        else:
+            hint = None
+        return message, hint
+
+    if isinstance(exc, httpx.ConnectError):
+        return (
+            f"Could not connect to {get_api_base()}",
+            "Check MCP_SERVER_BASE_URL or your network.",
+        )
+    if isinstance(exc, httpx.TimeoutException):
+        return "Request timed out", "Try again, or narrow the request."
+
+    return str(exc), None
+
+
+def fail(
+    exc: BaseException, role_action: str | None = None, *, prefix: str | None = None
+) -> NoReturn:
+    """Report a failed API call and exit 1.
+
+    `typer.Exit` / `typer.Abort` pass through untouched, so a command can keep
+    "Cancelled" (exit 0) inside the same ``try`` as its API calls.
+    """
+    if isinstance(exc, (typer.Exit, typer.Abort)):
+        raise exc
+    msg, hint = format_api_error(exc, role_action)  # type: ignore[arg-type]
+    print_error(f"{prefix}: {msg}" if prefix else msg, hint=hint)
+    raise typer.Exit(1)
+
+
+def load_definition_file(file: Path) -> dict:
+    """Load a metric/model definition from a YAML or JSON file.
+
+    Args:
+        file: Path to the definition file
+
+    Returns:
+        Parsed definition dictionary
+
+    Raises:
+        typer.Exit: If file not found or parsing fails
+    """
+    if not file.exists():
+        print_error(f"File not found: {file}")
+        raise typer.Exit(1)
+
+    try:
+        content = file.read_text()
+        if file.suffix in (".yaml", ".yml"):
+            return yaml.safe_load(content)
+        return json.loads(content)
+    except yaml.YAMLError as e:
+        print_error(f"Invalid YAML: {e}")
+        raise typer.Exit(1)
+    except json.JSONDecodeError as e:
+        print_error(f"Invalid JSON: {e}")
+        raise typer.Exit(1)
+
+
+# ============================================================================
+# Top-level commands
+# ============================================================================
+
+
+def _print_version_report() -> None:
+    """The version, and the manifest skew against the server when logged in."""
+    from cli.version import version_report
+
+    token = auth.get_access_token() if auth.is_logged_in() else None
+    try:
+        lines = version_report(base=get_api_base(), token=token)
+    except AuthenticationError:
+        lines = version_report(base=get_api_base(), token=None)
+    console.print(f"[bold]DataSpring CLI[/] v{lines[0].split(' ', 1)[1]}")
+    for line in lines[1:]:
+        console.print(line)
+
+
+def _version_option(value: bool) -> None:
+    if value:
+        _print_version_report()
+        raise typer.Exit()
+
+
+@app.callback()
+def _root(
+    version: Annotated[
+        Optional[bool],
+        typer.Option("--version", callback=_version_option, is_eager=True, help="Print the version and exit"),
+    ] = None,
+):
+    """DataSpring CLI - Query metrics and manage dashboards from the terminal."""
+
+
+@app.command()
+def version():
+    """Show the CLI version and, when logged in, its skew against the server."""
+    _print_version_report()
+
+
+@app.command()
+def upgrade(
+    check: Annotated[bool, typer.Option("--check", help="Only compare with PyPI's latest; change nothing")] = False,
+):
+    """Upgrade the CLI in place (uv tool, pipx or pip, whichever installed it)."""
+    import subprocess
+
+    from cli import upgrade as up
+
+    current = up.cli_version()
+    console.print(f"installed: {up.DIST} {current}")
+    try:
+        latest = up.latest_pypi_version()
+    except Exception as e:
+        print_error(f"Could not read PyPI: {e}")
+        raise typer.Exit(1)
+    console.print(f"latest on PyPI: {latest}")
+    if not up.is_newer(latest, current):
+        print_success("Already at the latest version")
+        return
+    if check:
+        console.print("an upgrade is available; run `dataspring upgrade`")
+        return
+    method = up.detect_install_method()
+    command = up.upgrade_command(method)
+    console.print(f"upgrading via {method}: {' '.join(command)}")
+    result = subprocess.run(command, check=False)
+    if result.returncode != 0:
+        print_error(f"upgrade command exited {result.returncode}")
+        raise typer.Exit(1)
+    after = up.installed_version_after_upgrade()
+    print_success(f"{up.DIST} {current} -> {after}")
+    if after == current:
+        print_warning("the version did not change; the installer may have used another environment")
+    console.print("run `dataspring skills install --all` to bring the installed skills up to date")
+
+
+@app.command()
+def login():
+    """Login via Google OAuth.
+
+    Opens a browser window to authenticate with Google.
+    Your credentials are stored locally in ~/.dataspring/credentials.json.
+    """
+    if auth.is_logged_in():
+        email = auth.get_stored_email()
+        print_info(f"Already logged in as {email}")
+        print_info("Run 'dataspring logout' first to switch accounts")
+        return
+
+    try:
+        user = run_async(auth.login())
+        print_success(f"Logged in as {user.email}")
+        print_info(f"Organization: {user.org_id} ({user.role})")
+    except AuthenticationError as e:
+        print_error(str(e))
+        raise typer.Exit(1)
+    except Exception as e:
+        print_error(f"Login failed: {e}")
+        raise typer.Exit(1)
+
+
+@app.command()
+def logout():
+    """Logout and clear stored credentials."""
+    if not auth.is_logged_in():
+        print_info("Not logged in")
+        return
+
+    email = auth.get_stored_email()
+    run_async(auth.logout())
+    print_success(f"Logged out {email}")
+
+
+@app.command()
+def whoami():
+    """Show current user and organization."""
+    user = require_auth()
+    print_user_context(
+        email=user.email,
+        org_id=user.org_id,
+        role=user.role,
+        org_name=user.org_name,
+    )
+
+
+@app.command()
+def report(
+    command: Annotated[
+        str,
+        typer.Argument(help="The CLI command that failed (e.g. 'query', 'dashboards list')"),
+    ],
+    error_message: Annotated[
+        str,
+        typer.Argument(help="The exact error message you received"),
+    ],
+    expected: Annotated[
+        Optional[str],
+        typer.Option("--expected", "-e", help="What you expected to happen"),
+    ] = None,
+    context: Annotated[
+        Optional[str],
+        typer.Option("--context", "-c", help="What you were trying to achieve"),
+    ] = None,
+):
+    """Submit an error report to help improve DataSpring.
+
+    Examples:
+        dataspring report "query" "Permission denied" --expected "Query should succeed" --context "Querying revenue metric"
+        dataspring report "dashboards list" "Connection timeout"
+    """
+    token = auth.get_access_token()
+
+    from importlib.metadata import version as get_version
+
+    try:
+        cli_version = get_version("dataspring-cli")
+    except Exception:
+        cli_version = "unknown"
+
+    # The handler has no cli_version field; keep the version in the context
+    # line so triage still sees which build produced the report.
+    context_info = f"{context} (cli {cli_version})" if context else f"cli {cli_version}"
+
+    try:
+        result = call_tool(
+            "submit_error_report",
+            None,
+            {
+                "command": command,
+                "error_message": error_message,
+                "expected": expected,
+                "context_info": context_info,
+                "source": "cli",
+            },
+            token=token,
+            timeout=15.0,
+        )
+        print_success(f"Error report submitted (ID: {result['id']})")
+        print_info("Thank you for the feedback.")
+    except Exception as e:
+        fail(e, prefix="Failed to submit report")
+
+
+@app.command()
+def docs(
+    full: Annotated[
+        bool,
+        typer.Option("--full", help="Show full documentation (llms-full.txt)"),
+    ] = False,
+    raw: Annotated[
+        bool,
+        typer.Option("--raw", help="Output raw markdown without formatting"),
+    ] = False,
+):
+    """Show DataSpring documentation for LLMs.
+
+    Fetches documentation from dataspring.app designed for LLM consumption.
+    Use this to understand DataSpring's capabilities, API, and CLI commands.
+
+    Examples:
+        dataspring docs              # Show navigation/summary
+        dataspring docs --full       # Show complete documentation
+        dataspring docs --full --raw # Raw markdown for piping
+    """
+    import httpx
+    from rich.markdown import Markdown
+
+    url = "https://dataspring.app/llms-full.txt" if full else "https://dataspring.app/llms.txt"
+
+    try:
+        with httpx.Client(timeout=30.0) as client:
+            response = client.get(url)
+            response.raise_for_status()
+            content = response.text
+
+        if raw:
+            print(content)
+        else:
+            console.print(Markdown(content))
+
+    except httpx.HTTPStatusError as e:
+        print_error(f"Failed to fetch documentation: HTTP {e.response.status_code}")
+        raise typer.Exit(1)
+    except httpx.RequestError as e:
+        print_error(f"Failed to fetch documentation: {e}")
+        print_info("Check your internet connection or try again later")
+        raise typer.Exit(1)
+
+
+def _query_body(
+    metrics: list[str],
+    dimensions: Optional[list[str]] = None,
+    grain: Optional[str] = None,
+    start_date: Optional[str] = None,
+    end_date: Optional[str] = None,
+    limit: Optional[int] = None,
+    order_by: Optional[str] = None,
+    warehouse: Optional[str] = None,
+) -> dict:
+    """The keyword arguments of the ``query_metrics`` / ``export_data`` tools.
+
+    Only what the user asked for goes on the wire, so the server's defaults
+    (and the user's stored query preferences) apply to the rest.
+    """
+    body: dict = {"metrics": metrics}
+    if dimensions:
+        body["dimensions"] = dimensions
+    if grain:
+        body["grain"] = grain
+    if start_date:
+        body["start_date"] = start_date
+    if end_date:
+        body["end_date"] = end_date
+    if limit:
+        body["limit"] = limit
+    if order_by:
+        body["order_by"] = order_by
+    if warehouse:
+        body["warehouse"] = warehouse
+    return body
+
+
+def _print_query_notes(result: dict) -> None:
+    """What the server folded into the query, so a number is never shown bare."""
+    for applied in result.get("applied_defaults") or []:
+        text = applied.get("echo_text") if isinstance(applied, dict) else None
+        print_info(text or f"Applied a saved preference: {applied}")
+    for note in result.get("notes") or []:
+        console.print(f"[dim]{note}[/]")
+    if result.get("hint"):
+        print_info(result["hint"])
+
+
+@app.command()
+def query(
+    metrics: Annotated[
+        list[str],
+        typer.Option("-m", "--metrics", help="Metric names to query"),
+    ],
+    dimensions: Annotated[
+        Optional[list[str]],
+        typer.Option("-d", "--dimensions", help="Dimensions to group by (use qualified names, e.g. customer__region)"),
+    ] = None,
+    grain: Annotated[
+        Optional[str],
+        typer.Option("-g", "--grain", help="Time grain: day, week, month, quarter, year"),
+    ] = None,
+    start_date: Annotated[
+        Optional[str],
+        typer.Option("--start", help="Start date (YYYY-MM-DD)"),
+    ] = None,
+    end_date: Annotated[
+        Optional[str],
+        typer.Option("--end", help="End date (YYYY-MM-DD)"),
+    ] = None,
+    limit: Annotated[
+        Optional[int],
+        typer.Option("--limit", help="Maximum rows to return"),
+    ] = None,
+    order_by: Annotated[
+        Optional[str],
+        typer.Option("--order-by", help="Column to sort by (append ' desc' for descending)"),
+    ] = None,
+    suggest_viz: Annotated[
+        bool,
+        typer.Option("--suggest-viz", help="Suggest a visualization type"),
+    ] = False,
+    warehouse: Annotated[
+        Optional[str],
+        typer.Option("--warehouse", help="Which of the org's warehouses to query (see `warehouses list`); default: the active one"),
+    ] = None,
+    format: Annotated[
+        OutputFormat,
+        typer.Option("--format", "-f", help="Output format"),
+    ] = "table",
+):
+    """Query metrics from your data warehouse.
+
+    Examples:
+        dataspring query -m total_revenue -g month
+        dataspring query -m revenue -d region --limit 10
+        dataspring query -m revenue -m orders --start 2024-01-01 --end 2024-12-31
+        dataspring query -m total_revenue -g month --warehouse managed
+    """
+    require_auth()
+    token = auth.get_access_token()
+
+    body = _query_body(
+        split_commas(metrics) or [],
+        split_commas(dimensions),
+        grain,
+        start_date,
+        end_date,
+        limit,
+        order_by,
+        warehouse,
+    )
+    if suggest_viz:
+        body["suggest_visualization"] = True
+
+    try:
+        result = call_tool("query_metrics", None, body, token=token, timeout=120.0)
+    except Exception as e:
+        if isinstance(e, (typer.Exit, typer.Abort)):
+            raise
+        msg, hint = format_api_error(e)
+        print_error(f"Query failed: {msg}", hint=hint)
+        print_report_hint("query", msg)
+        raise typer.Exit(1)
+
+    data = result.get("data", [])
+    columns = result.get("columns", [])
+
+    format_output(
+        data,
+        format=format,
+        columns=columns,
+        title=f"Query Results ({len(data)} rows)",
+    )
+    if format == "table":
+        _print_query_notes(result)
+        viz = result.get("visualization")
+        if suggest_viz and isinstance(viz, dict):
+            print_visualization_suggestion(
+                viz.get("widget_type", "?"), viz.get("rationale", "")
+            )
+
+
+@app.command()
+def export(
+    output: Annotated[
+        Path,
+        typer.Option("--output", "-o", help="Output file path (required)"),
+    ],
+    metrics: Annotated[
+        Optional[list[str]],
+        typer.Option("-m", "--metrics", help="Metric names to export"),
+    ] = None,
+    dimensions: Annotated[
+        Optional[list[str]],
+        typer.Option("-d", "--dimensions", help="Dimensions to group by"),
+    ] = None,
+    grain: Annotated[
+        Optional[str],
+        typer.Option("-g", "--grain", help="Time grain: day, week, month, quarter, year"),
+    ] = None,
+    start_date: Annotated[
+        Optional[str],
+        typer.Option("--start", help="Start date (YYYY-MM-DD)"),
+    ] = None,
+    end_date: Annotated[
+        Optional[str],
+        typer.Option("--end", help="End date (YYYY-MM-DD)"),
+    ] = None,
+    dashboard: Annotated[
+        Optional[str],
+        typer.Option("--dashboard", help="Dashboard ID to export (exports all widget data)"),
+    ] = None,
+    warehouse: Annotated[
+        Optional[str],
+        typer.Option("--warehouse", help="Which of the org's warehouses to query (metrics export); default: the active one"),
+    ] = None,
+    format: Annotated[
+        str,
+        typer.Option("--format", "-f", help="Output format: csv or json"),
+    ] = "csv",
+):
+    """Export query results or dashboard data to CSV or JSON.
+
+    You can either:
+    - Export query results by specifying metrics
+    - Export all data from a dashboard by specifying --dashboard
+
+    Examples:
+        dataspring export -o revenue.csv -m total_revenue -g month
+        dataspring export -o sales.json -m revenue -m orders -f json
+        dataspring export -o dashboard.csv --dashboard abc123
+        dataspring export -o report.csv -m revenue -d region --start 2024-01-01
+    """
+    require_auth()
+
+    metrics = split_commas(metrics)
+    dimensions = split_commas(dimensions)
+
+    # Validate format
+    format_lower = format.lower()
+    if format_lower not in ("csv", "json"):
+        print_error(
+            f"Invalid format: {format}",
+            hint="Use 'csv' or 'json'",
+        )
+        raise typer.Exit(1)
+
+    # Ensure output has correct extension
+    output_path = output
+    expected_ext = f".{format_lower}"
+    if output_path.suffix.lower() != expected_ext:
+        output_path = output_path.with_suffix(expected_ext)
+        print_warning(f"Output file extension adjusted to {output_path.name}")
+
+    # Must have either metrics or dashboard
+    if not metrics and not dashboard:
+        print_error(
+            "Either --metrics or --dashboard must be provided",
+            hint="Use -m metric_name or --dashboard dashboard_id",
+        )
+        raise typer.Exit(1)
+
+    token = auth.get_access_token()
+
+    if dashboard:
+        body: dict = {"format": format_lower, "dashboard_id": dashboard}
+        print_info(f"Exporting data from dashboard {dashboard}...")
+    else:
+        body = {
+            "format": format_lower,
+            **_query_body(metrics or [], dimensions, grain, start_date, end_date, warehouse=warehouse),
+        }
+        print_info(f"Exporting metrics: {', '.join(metrics or [])}...")
+
+    try:
+        result = call_tool("export_data", None, body, token=token, timeout=120.0)
+    except Exception as e:
+        if isinstance(e, (typer.Exit, typer.Abort)):
+            raise
+        msg, hint = format_api_error(e)
+        print_error(f"Export failed: {msg}", hint=hint)
+        print_report_hint("export", msg)
+        raise typer.Exit(1)
+
+    # The server renders the CSV/JSON; the CLI only writes the bytes it got.
+    output_path.write_text(result.get("content") or "", encoding="utf-8")
+
+    row_count = result.get("row_count", 0)
+    columns = result.get("columns") or []
+    print_success(f"Exported {row_count} rows to {output_path}")
+    if columns:
+        print_info(f"Columns: {', '.join(columns)}")
+
+
+# ============================================================================
+# Metrics sub-commands
+# ============================================================================
+#
+# ``list`` and ``show`` read ``GET /api/semantic-layer/metrics[/{name}]``.
+# Writes are the generated ``dataspring metric_edit create|update|delete|
+# preview|impact`` (``--metric-data-json @metric.yaml``), so the ownership
+# rules (dbt owns computation, DataSpring owns text), the confirmation gate
+# for redefining a native metric and the learned-trail entry all happen on
+# the server and the flags can never lag the model.
+
+
+@metrics_app.command("list")
+def metrics_list(
+    format: Annotated[
+        OutputFormat,
+        typer.Option("--format", "-f", help="Output format"),
+    ] = "table",
+):
+    """List available metrics."""
+    require_auth()
+    token = auth.get_access_token()
+
+    try:
+        result = api_get("/api/semantic-layer/metrics", token)
+    except Exception as e:
+        fail(e, role_action="list metrics")
+
+    format_output(
+        result.get("metrics", []),
+        format=format,
+        columns=["name", "type", "description"],
+        title="Available Metrics",
+    )
+
+
+@metrics_app.command("show")
+def metrics_show(
+    name: Annotated[str, typer.Argument(help="Metric name")],
+    format: Annotated[
+        OutputFormat,
+        typer.Option("--format", "-f", help="Output format"),
+    ] = "table",
+):
+    """Show details for a specific metric."""
+    require_auth()
+    token = auth.get_access_token()
+
+    try:
+        metric = api_get(f"/api/semantic-layer/metrics/{name}", token)
+    except Exception as e:
+        fail(e, role_action="view metrics")
+
+    format_output(metric, format=format, title=f"Metric: {name}")
+
+
+# ============================================================================
+# Dimensions sub-commands
+# ============================================================================
+
+
+@dimensions_app.command("list")
+def dimensions_list(
+    format: Annotated[
+        OutputFormat,
+        typer.Option("--format", "-f", help="Output format"),
+    ] = "table",
+):
+    """List available dimensions."""
+    user = require_auth()
+    token = auth.get_access_token()
+
+    try:
+        result = api_get("/api/semantic-layer/dimensions", token)
+        dimensions = result.get("dimensions", [])
+        format_output(
+            dimensions,
+            format=format,
+            columns=["name"],
+            title="Available Dimensions",
+        )
+    except Exception as e:
+        print_error(str(e))
+        raise typer.Exit(1)
+
+
+# ============================================================================
+# Org sub-commands
+# ============================================================================
+#
+# ``switch`` is the ``switch_organization`` dispatch tool: the server resolves
+# the caller from the bearer token and writes only that user's document.
+# Before this, the CLI called `services.auth.switch_org(email, org_id)` with
+# the e-mail from a user-editable config file, over the operator's own
+# Firestore credentials - anyone with ADC could switch another user's org.
+# ``list`` reads ``GET /api/me/organizations``, the REST twin of the
+# ``dataspring://organizations`` resource; ``/api/me`` carries only the
+# current org.
+
+#: The read route for the caller's organizations.
+ORGANIZATIONS_PATH = "/api/me/organizations"
+
+
+def _orgs_from(result) -> list[dict]:
+    """A bare list or an ``{"organizations": [...]}`` envelope, either way."""
+    if isinstance(result, dict):
+        return result.get("organizations") or []
+    return list(result or [])
+
+
+@org_app.command("list")
+def org_list(
+    format: Annotated[
+        OutputFormat,
+        typer.Option("--format", "-f", help="Output format"),
+    ] = "table",
+):
+    """List organizations you belong to."""
+    if not auth.is_logged_in():
+        print_error("Not logged in", hint="Run 'dataspring login' first")
+        raise typer.Exit(1)
+
+    token = auth.get_access_token()
+
+    try:
+        orgs = _orgs_from(api_get(ORGANIZATIONS_PATH, token))
+    except Exception as e:
+        fail(e, role_action="list your organizations")
+
+    format_output(
+        orgs,
+        format=format,
+        columns=["id", "name", "role", "current"],
+        title="Your Organizations",
+    )
+
+
+@org_app.command("switch")
+def org_switch(
+    org_id: Annotated[str, typer.Argument(help="Organization ID to switch to")],
+):
+    """Switch to a different organization."""
+    if not auth.is_logged_in():
+        print_error("Not logged in", hint="Run 'dataspring login' first")
+        raise typer.Exit(1)
+
+    token = auth.get_access_token()
+
+    try:
+        result = call_tool("switch_organization", None, {"org_id": org_id}, token=token)
+    except Exception as e:
+        fail(e, role_action="switch to this organization")
+
+    print_success(f"Switched to organization: {result.get('org_id', org_id)}")
+    print_info(f"Role: {result.get('role')}")
+
+
+# `dataspring switch <org>` is the same command at the root (the D19 note's
+# name for it); `org switch` stays for the hands that know it.
+app.command("switch")(org_switch)
+
+
+# ============================================================================
+# Dashboards sub-commands
+# ============================================================================
+#
+# Reads: ``GET /api/dashboards`` and ``GET /api/dashboards/{id}``, which answer
+# with the stored document as-is. Writes are the generated ``dashboard_edit``,
+# ``widget_edit``, ``page_edit`` and ``section_edit`` groups and the
+# ``render_dashboard`` / ``render_widget`` commands (``-o file.pdf`` saves
+# the render). What stays here is what a person wants and the generated
+# twin cannot be: ``update`` from a file (its whole-definition path is the
+# one REST write, ``PUT /api/dashboards/{id}``, which no dispatch action
+# covers), ``add-widget`` building the widget from flags, and the
+# ``*-widget`` commands that take a widget id where the action wants
+# page/section/widget indices.
+
+
+def _get_dashboard(dashboard_id: str, token: str) -> dict:
+    """``GET /api/dashboards/{id}`` - 404 when missing or not visible to the user."""
+    return api_get(f"/api/dashboards/{dashboard_id}", token)
+
+
+def _owner_label(owner_uid: str | None, user) -> str:
+    """"you" for the caller; otherwise the uid, shortened.
+
+    Display names lived in Firestore and were read with the operator's own
+    credentials; no read-only route exposes them, so the uid stands in.
+    """
+    if not owner_uid:
+        return "-"
+    if owner_uid == user.uid:
+        return "you"
+    return owner_uid[:8] + "..."
+
+
+def _page_widgets(page: dict) -> int:
+    return sum(len(section.get("widgets") or []) for section in page.get("sections") or [])
+
+
+def _page_index(dashboard: dict, page_id: str) -> int | None:
+    for i, page in enumerate(dashboard.get("pages") or []):
+        if page.get("id") == page_id:
+            return i
+    return None
+
+
+def _find_widget_location(dashboard: dict, widget_id: str) -> tuple[int, int, int] | None:
+    """(page_index, section_index, widget_index) of a widget, by id."""
+    for p, page in enumerate(dashboard.get("pages") or []):
+        for s, section in enumerate(page.get("sections") or []):
+            for w, widget in enumerate(section.get("widgets") or []):
+                if widget.get("id") == widget_id:
+                    return p, s, w
+    return None
+
+
+def _dashboard_summary(dashboard: dict) -> dict:
+    return {
+        "id": dashboard.get("id"),
+        "title": dashboard.get("title"),
+        "description": dashboard.get("description") or "-",
+        "visibility": dashboard.get("visibility"),
+    }
+
+
+def _print_dashboard_result(result: dict, format: OutputFormat, summary: dict, title: str) -> None:
+    """The `_ok(dashboard)` shape: full document as JSON, a summary otherwise."""
+    if format == "json":
+        format_output(result.get("dashboard", result), format=format)
+    else:
+        format_output(summary, format=format, title=title)
+
+
+@dashboards_app.command("list")
+def dashboards_list(
+    format: Annotated[
+        OutputFormat,
+        typer.Option("--format", "-f", help="Output format"),
+    ] = "table",
+):
+    """List your dashboards (personal and team).
+
+    Shows dashboards you own (personal) and dashboards shared with
+    your organization (team).
+    """
+    user = require_auth()
+    token = auth.get_access_token()
+
+    try:
+        result = api_get("/api/dashboards", token)
+    except Exception as e:
+        fail(e, role_action="list dashboards")
+
+    all_dashboards = []
+    for d in result.get("personal") or []:
+        all_dashboards.append({
+            "id": d.get("id"),
+            "title": d.get("title"),
+            "visibility": d.get("visibility"),
+            "owner": "you",
+            "updated_at": d.get("updated_at"),
+        })
+    for d in result.get("team") or []:
+        all_dashboards.append({
+            "id": d.get("id"),
+            "title": d.get("title"),
+            "visibility": d.get("visibility"),
+            "owner": _owner_label(d.get("owner"), user),
+            "updated_at": d.get("updated_at"),
+        })
+
+    if not all_dashboards:
+        print_info("No dashboards found")
+        print_info("Create one with: dataspring dashboards create 'My Dashboard'")
+        return
+
+    format_output(
+        all_dashboards,
+        format=format,
+        columns=["id", "title", "visibility", "owner", "updated_at"],
+        title="Dashboards",
+    )
+
+
+@dashboards_app.command("show")
+def dashboards_show(
+    dashboard_id: Annotated[str, typer.Argument(help="Dashboard ID")],
+    format: Annotated[
+        OutputFormat,
+        typer.Option("--format", "-f", help="Output format"),
+    ] = "table",
+):
+    """Show details for a specific dashboard.
+
+    Displays dashboard metadata and page/widget structure.
+    """
+    user = require_auth()
+    token = auth.get_access_token()
+
+    try:
+        dashboard = _get_dashboard(dashboard_id, token)
+    except Exception as e:
+        fail(e, role_action="view this dashboard")
+
+    if format == "json":
+        format_output(dashboard, format=format)
+        return
+
+    pages = dashboard.get("pages") or []
+    summary = {
+        "id": dashboard.get("id"),
+        "title": dashboard.get("title"),
+        "description": dashboard.get("description") or "-",
+        "visibility": dashboard.get("visibility"),
+        "owner": _owner_label(dashboard.get("owner"), user),
+        "created_at": dashboard.get("created_at"),
+        "updated_at": dashboard.get("updated_at"),
+        "pages": len(pages),
+        "widgets": sum(_page_widgets(page) for page in pages),
+    }
+    format_output(summary, format=format, title=f"Dashboard: {dashboard.get('title')}")
+
+    if pages:
+        console.print()
+        pages_data = [
+            {
+                "index": i,
+                "title": page.get("title"),
+                "sections": len(page.get("sections") or []),
+                "widgets": _page_widgets(page),
+            }
+            for i, page in enumerate(pages)
+        ]
+        format_output(
+            pages_data,
+            format="table",
+            columns=["index", "title", "sections", "widgets"],
+            title="Pages",
+        )
+
+
+_DASHBOARD_METADATA_KEYS = {"title", "description", "visibility"}
+
+
+@dashboards_app.command("update")
+def dashboards_update(
+    dashboard_id: Annotated[str, typer.Argument(help="Dashboard ID to update")],
+    file: Annotated[
+        Optional[Path],
+        typer.Argument(help="Path to YAML or JSON file with updates (optional)"),
+    ] = None,
+    title: Annotated[
+        Optional[str],
+        typer.Option("--title", "-t", help="New dashboard title"),
+    ] = None,
+    description: Annotated[
+        Optional[str],
+        typer.Option("--description", "-d", help="New dashboard description"),
+    ] = None,
+    visibility: Annotated[
+        Optional[str],
+        typer.Option(
+            "--visibility",
+            "-v",
+            help="New visibility: 'private' (only you) or 'org' (team)",
+        ),
+    ] = None,
+    format: Annotated[
+        OutputFormat,
+        typer.Option("--format", "-f", help="Output format"),
+    ] = "table",
+):
+    """Update a dashboard's metadata.
+
+    You can update using command-line options, a file, or both.
+    Command-line options override values from the file.
+
+    Examples:
+        dataspring dashboards update abc123 --title 'New Title'
+        dataspring dashboards update abc123 --description 'Updated description'
+        dataspring dashboards update abc123 --visibility org
+        dataspring dashboards update abc123 dashboard.yaml
+        dataspring dashboards update abc123 updates.yaml --title 'Override Title'
+    """
+    require_auth()
+
+    import uuid
+
+    def ensure_ids(data: dict) -> dict:
+        """Ensure all pages, sections, and widgets have IDs."""
+        if "pages" in data:
+            for page in data["pages"]:
+                if not page.get("id"):  # Missing, None, or empty string
+                    page["id"] = str(uuid.uuid4())
+                for section in page.get("sections", []):
+                    # Sections don't have IDs by default, but widgets do
+                    for widget in section.get("widgets", []):
+                        if not widget.get("id"):  # Missing, None, or empty string
+                            widget["id"] = str(uuid.uuid4())
+        return data
+
+    # Build updates dict
+    updates = {}
+
+    # Load from file if provided
+    if file:
+        file_updates = load_definition_file(file)
+        # Auto-generate IDs for widgets/pages that don't have them
+        file_updates = ensure_ids(file_updates)
+        updates.update(file_updates)
+
+    # Override with command-line options
+    if title is not None:
+        updates["title"] = title
+    if description is not None:
+        updates["description"] = description
+    if visibility is not None:
+        # Validate visibility
+        if visibility not in ("private", "org"):
+            print_error(
+                f"Invalid visibility: {visibility}",
+                hint="Use 'private' or 'org'",
+            )
+            raise typer.Exit(1)
+        updates["visibility"] = visibility
+
+    # Check that we have something to update
+    if not updates:
+        print_error(
+            "No updates provided",
+            hint="Use --title, --description, --visibility, or provide a file",
+        )
+        raise typer.Exit(1)
+
+    token = auth.get_access_token()
+
+    try:
+        if set(updates) <= _DASHBOARD_METADATA_KEYS:
+            result = call_tool("dashboard_edit", "update", {"id": dashboard_id, **updates}, token=token)
+            updated = result.get("dashboard", {})
+        else:
+            # A whole-definition edit (pages, controls, ...) has no dispatch
+            # action; the REST route validates and saves the document.
+            updated = api_put(f"/api/dashboards/{dashboard_id}", updates, token)
+    except Exception as e:
+        fail(e, role_action="update this dashboard")
+
+    print_success(f"Updated dashboard: {updated.get('title')}")
+    format_output(_dashboard_summary(updated), format=format, title="Updated Dashboard")
+
+
+@dashboards_app.command("add-widget")
+def add_widget_cmd(
+    dashboard_id: Annotated[str, typer.Argument(help="Dashboard ID")],
+    widget_type: Annotated[
+        str,
+        typer.Option("--type", "-t", help="Widget type: kpi, line_chart, bar_chart, area_chart, donut, table, heatmap"),
+    ],
+    title: Annotated[str, typer.Option("--title", help="Widget title")],
+    metrics: Annotated[
+        list[str],
+        typer.Option("-m", "--metrics", help="Metric names to query"),
+    ],
+    dimensions: Annotated[
+        Optional[list[str]],
+        typer.Option("-d", "--dimensions", help="Dimensions to group by"),
+    ] = None,
+    grain: Annotated[
+        Optional[str],
+        typer.Option("-g", "--grain", help="Time grain: day, week, month, quarter, year, or $grain for dashboard control"),
+    ] = None,
+    page: Annotated[
+        int,
+        typer.Option("--page", help="Page index (0-based)"),
+    ] = 0,
+    section: Annotated[
+        int,
+        typer.Option("--section", help="Section index (0-based)"),
+    ] = 0,
+    width: Annotated[
+        Optional[int],
+        typer.Option("--width", "-w", help="Widget width (1-10). Defaults: kpi=2, donut=3, heatmap=5, charts/tables=10"),
+    ] = None,
+    time_scope: Annotated[
+        Optional[str],
+        typer.Option("--time-scope", help="Date scope: range (full), latest (current period), latest_complete (last complete period)"),
+    ] = None,
+    pivot_on: Annotated[
+        Optional[str],
+        typer.Option("--pivot-on", help="Pivot dimension (table only): dimension values become columns"),
+    ] = None,
+    pivot_totals: Annotated[
+        bool,
+        typer.Option("--pivot-totals", help="Show row/column totals in pivot table"),
+    ] = False,
+    stacked: Annotated[
+        bool,
+        typer.Option("--stacked", help="Stack bars by second dimension (bar_chart only)"),
+    ] = False,
+    format: Annotated[
+        OutputFormat,
+        typer.Option("--format", "-f", help="Output format"),
+    ] = "table",
+):
+    """Add a new widget to a dashboard.
+
+    Creates a new widget with the specified configuration and adds it
+    to the specified page and section. Uses a 10-column grid layout.
+
+    Default widths by type (if --width not specified):
+        kpi: 2 columns (5 per row)
+        donut: 3 columns (3 per row)
+        heatmap: 5 columns (2 per row)
+        area_chart, line_chart, bar_chart, table: 10 columns (full width)
+
+    Time scope (for non-time-series widgets):
+        range: Use full dashboard date range (default)
+        latest: Current period only (may be incomplete)
+        latest_complete: Last complete period
+
+    Stacked bar charts (bar_chart only):
+        Use --stacked with 2 dimensions: first for x-axis, second for stack segments.
+
+    Pivot tables (table type only):
+        Use --pivot-on to transform dimension values into columns.
+        The pivot dimension must be included in --dimensions.
+
+    Examples:
+        dataspring dashboards add-widget abc123 --type kpi --title "Revenue" -m total_revenue
+        dataspring dashboards add-widget abc123 -t line_chart --title "Trends" -m revenue -g month
+        dataspring dashboards add-widget abc123 -t kpi --title "Last Month" -m revenue --time-scope latest_complete
+        dataspring dashboards add-widget abc123 -t kpi --title "Custom" -m revenue --width 4
+        dataspring dashboards add-widget abc123 -t bar_chart --title "Spend by Platform" \\
+            -m ad_spend -d metric_time -d platform -g month --stacked
+        dataspring dashboards add-widget abc123 -t table --title "Revenue by Region and Category" \\
+            -m revenue -d region -d category --pivot-on category
+        dataspring dashboards add-widget abc123 -t table --title "Monthly Revenue by Region" \\
+            -m revenue -d region -g month --pivot-on region --pivot-totals
+    """
+    require_auth()
+
+    metrics = split_commas(metrics) or []
+    dimensions = split_commas(dimensions)
+
+    # Build widget definition
+    widget = {
+        "type": widget_type,
+        "title": title,
+        "query": {
+            "metrics": metrics,
+        },
+    }
+
+    if dimensions:
+        widget["query"]["dimensions"] = dimensions
+    if grain:
+        widget["query"]["grain"] = grain
+    if width:
+        widget["width"] = width
+    if time_scope:
+        if time_scope not in ("range", "latest", "latest_complete"):
+            print_error(f"Invalid time_scope: {time_scope}. Must be: range, latest, latest_complete")
+            raise typer.Exit(1)
+        widget["time_scope"] = time_scope
+
+    if pivot_on:
+        if widget_type != "table":
+            print_error("--pivot-on can only be used with table widgets")
+            raise typer.Exit(1)
+        if not dimensions or pivot_on not in dimensions:
+            print_error(f"Pivot dimension '{pivot_on}' must be included in --dimensions")
+            raise typer.Exit(1)
+        widget["pivot"] = {"on": pivot_on, "show_totals": pivot_totals}
+
+    if stacked:
+        if widget_type != "bar_chart":
+            print_error("--stacked can only be used with bar_chart widgets")
+            raise typer.Exit(1)
+        if not dimensions or len(dimensions) < 2:
+            print_error("Stacked bar charts require 2 dimensions: first for x-axis, second for stack segments")
+            raise typer.Exit(1)
+        widget["stacked"] = True
+
+    token = auth.get_access_token()
+
+    try:
+        result = call_tool(
+            "widget_edit",
+            "add",
+            {"dashboard_id": dashboard_id, "widget": widget, "page_index": page, "section_index": section},
+            token=token,
+        )
+    except Exception as e:
+        fail(e, role_action="edit this dashboard")
+
+    dashboard = result.get("dashboard", {})
+    print_success(f"Added widget '{title}' to dashboard")
+    summary = {
+        "dashboard_id": dashboard.get("id"),
+        "widget_title": title,
+        "widget_type": widget_type,
+        "page_index": page,
+        "section_index": section,
+    }
+    _print_dashboard_result(result, format, summary, "Widget Added")
+
+
+@dashboards_app.command("remove-widget")
+def remove_widget_cmd(
+    dashboard_id: Annotated[str, typer.Argument(help="Dashboard ID")],
+    widget_id: Annotated[str, typer.Argument(help="Widget ID to remove")],
+    yes: Annotated[
+        bool,
+        typer.Option("--yes", "-y", help="Skip confirmation"),
+    ] = False,
+    format: Annotated[
+        OutputFormat,
+        typer.Option("--format", "-f", help="Output format"),
+    ] = "table",
+):
+    """Remove a widget from a dashboard.
+
+    Permanently deletes a widget from the dashboard.
+
+    Examples:
+        dataspring dashboards remove-widget abc123 widget-1
+        dataspring dashboards remove-widget abc123 widget-1 --yes
+    """
+    require_auth()
+
+    if not yes:
+        confirm = typer.confirm(f"Remove widget '{widget_id}'?")
+        if not confirm:
+            print_info("Cancelled")
+            return
+
+    token = auth.get_access_token()
+
+    try:
+        # Resolve widget ID to page/section/widget indices
+        loc = _find_widget_location(_get_dashboard(dashboard_id, token), widget_id)
+        if loc is None:
+            print_error(f"Widget '{widget_id}' not found in dashboard")
+            raise typer.Exit(1)
+        page_index, section_index, widget_index = loc
+
+        result = call_tool(
+            "widget_edit",
+            "remove",
+            {
+                "dashboard_id": dashboard_id,
+                "page_index": page_index,
+                "section_index": section_index,
+                "widget_index": widget_index,
+            },
+            token=token,
+        )
+    except Exception as e:
+        fail(e, role_action="edit this dashboard")
+
+    dashboard = result.get("dashboard", {})
+    print_success(f"Removed widget '{widget_id}'")
+    summary = {
+        "dashboard_id": dashboard.get("id"),
+        "removed_widget_id": widget_id,
+    }
+    _print_dashboard_result(result, format, summary, "Widget Removed")
+
+
+@dashboards_app.command("update-widget")
+def update_widget_cmd(
+    dashboard_id: Annotated[str, typer.Argument(help="Dashboard ID")],
+    widget_id: Annotated[str, typer.Argument(help="Widget ID to update")],
+    title: Annotated[
+        Optional[str],
+        typer.Option("--title", help="New widget title"),
+    ] = None,
+    metrics: Annotated[
+        Optional[list[str]],
+        typer.Option("-m", "--metrics", help="New metric names"),
+    ] = None,
+    dimensions: Annotated[
+        Optional[list[str]],
+        typer.Option("-d", "--dimensions", help="New dimensions"),
+    ] = None,
+    grain: Annotated[
+        Optional[str],
+        typer.Option("-g", "--grain", help="New time grain"),
+    ] = None,
+    width: Annotated[
+        Optional[int],
+        typer.Option("--width", "-w", help="New widget width (1-10)"),
+    ] = None,
+    format: Annotated[
+        OutputFormat,
+        typer.Option("--format", "-f", help="Output format"),
+    ] = "table",
+):
+    """Update an existing widget.
+
+    Modify the configuration of an existing widget. Only specified
+    fields are updated; others remain unchanged.
+
+    Examples:
+        dataspring dashboards update-widget abc123 widget-1 --title "New Title"
+        dataspring dashboards update-widget abc123 widget-1 -m revenue -m orders
+        dataspring dashboards update-widget abc123 widget-1 --width 6
+    """
+    require_auth()
+
+    metrics = split_commas(metrics)
+    dimensions = split_commas(dimensions)
+
+    # Build updates dict
+    updates = {}
+    if title:
+        updates["title"] = title
+    if width:
+        updates["width"] = width
+
+    # Build query updates if any query fields provided
+    query_updates = {}
+    if metrics:
+        query_updates["metrics"] = metrics
+    if dimensions:
+        query_updates["dimensions"] = dimensions
+    if grain:
+        query_updates["grain"] = grain
+
+    if query_updates:
+        updates["query"] = query_updates
+
+    if not updates:
+        print_error("No updates specified")
+        raise typer.Exit(1)
+
+    token = auth.get_access_token()
+
+    try:
+        # Resolve widget ID to page/section/widget indices
+        loc = _find_widget_location(_get_dashboard(dashboard_id, token), widget_id)
+        if loc is None:
+            print_error(f"Widget '{widget_id}' not found in dashboard")
+            raise typer.Exit(1)
+        page_index, section_index, widget_index = loc
+
+        result = call_tool(
+            "widget_edit",
+            "update",
+            {
+                "dashboard_id": dashboard_id,
+                "page_index": page_index,
+                "section_index": section_index,
+                "widget_index": widget_index,
+                "updates": updates,
+            },
+            token=token,
+        )
+    except Exception as e:
+        fail(e, role_action="edit this dashboard")
+
+    dashboard = result.get("dashboard", {})
+    print_success(f"Updated widget '{widget_id}'")
+    summary = {
+        "dashboard_id": dashboard.get("id"),
+        "widget_id": widget_id,
+        "updated_fields": list(updates.keys()),
+    }
+    _print_dashboard_result(result, format, summary, "Widget Updated")
+
+
+@dashboards_app.command("reorder-widgets")
+def reorder_widgets_cmd(
+    dashboard_id: Annotated[str, typer.Argument(help="Dashboard ID")],
+    page_id: Annotated[str, typer.Option("--page", help="Page ID")],
+    section_index: Annotated[int, typer.Option("--section", help="Section index (0-based)")],
+    widget_ids: Annotated[
+        list[str],
+        typer.Argument(help="Widget IDs in desired order"),
+    ],
+    format: Annotated[
+        OutputFormat,
+        typer.Option("--format", "-f", help="Output format"),
+    ] = "table",
+):
+    """Reorder widgets within a section.
+
+    Specify the widget IDs in the desired order. All widgets in the
+    section must be included.
+
+    Examples:
+        dataspring dashboards reorder-widgets abc123 --page page-1 --section 0 widget-3 widget-1 widget-2
+    """
+    require_auth()
+    token = auth.get_access_token()
+
+    try:
+        # The action addresses the page by index; the option takes an id.
+        page_index = _page_index(_get_dashboard(dashboard_id, token), page_id)
+        if page_index is None:
+            print_error(f"Page '{page_id}' not found in dashboard")
+            raise typer.Exit(1)
+
+        result = call_tool(
+            "widget_edit",
+            "reorder",
+            {
+                "dashboard_id": dashboard_id,
+                "page_index": page_index,
+                "section_index": section_index,
+                "widget_ids": widget_ids,
+            },
+            token=token,
+        )
+    except Exception as e:
+        fail(e, role_action="edit this dashboard")
+
+    dashboard = result.get("dashboard", {})
+    print_success(f"Reordered {len(widget_ids)} widgets")
+    summary = {
+        "dashboard_id": dashboard.get("id"),
+        "page_id": page_id,
+        "section_index": section_index,
+        "new_order": widget_ids,
+    }
+    _print_dashboard_result(result, format, summary, "Widgets Reordered")
+
+
+# ============================================================================
+# Manifest sub-commands
+# ============================================================================
+#
+# ``status`` and ``export`` read ``GET /api/manifest`` and
+# ``GET /api/semantic-layer/export``; an upload is the generated ``dataspring
+# import_manifest --manifest-data-json @manifest.yaml``, whose replace
+# semantics and reference validation live on the server.
+
+
+@manifest_app.command("status")
+def manifest_status(
+    format: Annotated[
+        OutputFormat,
+        typer.Option("--format", "-f", help="Output format"),
+    ] = "table",
+):
+    """Show manifest status (project name, counts).
+
+    Displays information about the organization's semantic layer manifest
+    including project name, metric count, model count, and dimension count.
+    """
+    user = require_auth()
+    token = auth.get_access_token()
+
+    try:
+        result = api_get("/api/manifest", token)
+    except Exception as e:
+        fail(e, role_action="view the manifest")
+
+    summary = {
+        "organization": result.get("org_id", user.org_id),
+        "project": result.get("project_name") or "-",
+        "metrics": result.get("metrics", 0),
+        "models": result.get("semantic_models", 0),
+        "dimensions": result.get("dimensions", 0),
+        "last_updated": result.get("uploaded_at") or "-",
+    }
+    format_output(summary, format=format, title="Manifest Status")
+
+
+@manifest_app.command("export")
+def manifest_export(
+    output: Annotated[
+        str,
+        typer.Option("--output", "-o", help="Output file path (YAML or JSON)"),
+    ],
+):
+    """Export manifest to a file.
+
+    Exports the organization's semantic layer manifest to a YAML or JSON
+    file. The format is determined by the file extension.
+
+    Examples:
+        dataspring manifest export -o manifest.yaml
+        dataspring manifest export --output backup.json
+    """
+    require_auth()
+    token = auth.get_access_token()
+
+    # Determine format from extension
+    output_path = Path(output)
+    ext = output_path.suffix.lower()
+
+    if ext not in (".yaml", ".yml", ".json"):
+        print_error(
+            f"Unsupported file format: {ext}",
+            hint="Use .yaml, .yml, or .json",
+        )
+        raise typer.Exit(1)
+
+    try:
+        manifest = api_get("/api/semantic-layer/export", token)
+    except Exception as e:
+        fail(e, role_action="export the manifest")
+
+    # Check if manifest is empty
+    if not manifest.get("metrics") and not manifest.get("semantic_models"):
+        print_warning("Manifest is empty (no metrics or models)")
+
+    # Write to file
+    if ext in (".yaml", ".yml"):
+        with open(output_path, "w") as f:
+            yaml.dump(manifest, f, default_flow_style=False, sort_keys=False)
+    else:
+        with open(output_path, "w") as f:
+            json.dump(manifest, f, indent=2)
+
+    print_success(f"Exported manifest to {output}")
+    print_info(f"  Metrics: {len(manifest.get('metrics', []))}")
+    print_info(f"  Models: {len(manifest.get('semantic_models', []))}")
+
+
+# ============================================================================
+# Models sub-commands
+# ============================================================================
+#
+# ``list`` and ``show`` read ``GET /api/semantic-layer/models[/{name}]``;
+# writes are the generated ``dataspring semantic_model_edit`` (admin/owner,
+# checked on the server).
+
+
+@models_app.command("list")
+def models_list(
+    format: Annotated[
+        OutputFormat,
+        typer.Option("--format", "-f", help="Output format"),
+    ] = "table",
+):
+    """List semantic models.
+
+    Shows all semantic models with their name, description,
+    measure count, and dimension count.
+    """
+    require_auth()
+    token = auth.get_access_token()
+
+    try:
+        result = api_get("/api/semantic-layer/models", token)
+    except Exception as e:
+        fail(e, role_action="list semantic models")
+
+    models = result.get("models", [])
+    if not models:
+        print_info("No semantic models found")
+        return
+
+    model_data = [
+        {
+            "name": model.get("name", "-"),
+            "description": model.get("description", "-") or "-",
+            "measures": len(model.get("measures", [])),
+            "dimensions": len(model.get("dimensions", [])),
+        }
+        for model in models
+    ]
+    format_output(
+        model_data,
+        format=format,
+        columns=["name", "description", "measures", "dimensions"],
+        title="Semantic Models",
+    )
+
+
+@models_app.command("show")
+def models_show(
+    name: Annotated[str, typer.Argument(help="Model name")],
+    format: Annotated[
+        OutputFormat,
+        typer.Option("--format", "-f", help="Output format"),
+    ] = "table",
+):
+    """Show details for a semantic model.
+
+    Displays full model definition including all measures and dimensions.
+    """
+    require_auth()
+    token = auth.get_access_token()
+
+    try:
+        model = api_get(f"/api/semantic-layer/models/{name}", token)
+    except Exception as e:
+        fail(e, role_action="view semantic models")
+
+    if format in ("json", "yaml"):
+        format_output(model, format=format)
+        return
+
+    # Show model summary
+    summary = {
+        "name": model.get("name", "-"),
+        "description": model.get("description", "-") or "-",
+        "model_ref": model.get("model", "-"),
+        "measures": len(model.get("measures", [])),
+        "dimensions": len(model.get("dimensions", [])),
+    }
+    format_output(summary, format=format, title=f"Model: {name}")
+
+    for label, key in (("Measures", "measures"), ("Dimensions", "dimensions")):
+        entries = model.get(key, [])
+        if not entries:
+            continue
+        console.print()
+        format_output(
+            [
+                {
+                    "name": entry.get("name", "-"),
+                    "type": entry.get("type", "-"),
+                    "expr": entry.get("expr", "-"),
+                }
+                for entry in entries
+            ],
+            format="table",
+            columns=["name", "type", "expr"],
+            title=label,
+        )
+
+
+# ============================================================================
+# Schedules sub-commands
+# ============================================================================
+#
+# Writes are the generated ``dataspring report_edit``, which answers
+# "Scheduled reports coming soon" while the feature is off - the server
+# decides, not a local settings file. ``list`` and ``show`` read
+# ``GET /api/schedules`` / ``GET /api/schedules/{id}``, the REST twins of
+# ``dataspring://reports``; no other route exposes them.
+
+#: The read routes for scheduled reports.
+SCHEDULES_PATH = "/api/schedules"
+
+_WEEKDAYS = ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday"]
+
+
+def _schedules_from(result) -> list[dict]:
+    """A bare list or a ``{"schedules": [...]}`` envelope, either way."""
+    if isinstance(result, dict):
+        return result.get("schedules") or []
+    return list(result or [])
+
+
+def _short_time(value) -> str:
+    """``YYYY-MM-DD HH:MM`` from an ISO timestamp, "-" when absent."""
+    if not value:
+        return "-"
+    text = str(value)
+    return text[:16].replace("T", " ") if len(text) >= 16 else text
+
+
+def _frequency_description(freq: dict) -> str:
+    kind = freq.get("type")
+    time_ = freq.get("time")
+    if kind == "daily":
+        return f"Daily at {time_} UTC"
+    if kind == "weekly":
+        day = freq.get("day_of_week")
+        day_name = _WEEKDAYS[day] if isinstance(day, int) and 0 <= day < 7 else "?"
+        return f"Weekly on {day_name} at {time_} UTC"
+    return f"Monthly on day {freq.get('day_of_month')} at {time_} UTC"
+
+
+@schedules_app.command("list")
+def schedules_list(
+    format: Annotated[
+        OutputFormat,
+        typer.Option("--format", "-f", help="Output format"),
+    ] = "table",
+):
+    """List all scheduled reports.
+
+    Shows all schedules in your organization with their status
+    and configuration summary.
+
+    Examples:
+        dataspring schedules list
+        dataspring schedules list --format json
+    """
+    require_auth()
+    token = auth.get_access_token()
+
+    try:
+        schedules = _schedules_from(api_get(SCHEDULES_PATH, token))
+    except Exception as e:
+        fail(e, role_action="list scheduled reports")
+
+    if not schedules:
+        print_info("No scheduled reports found")
+        print_info("Create one with: dataspring schedules create 'My Report' ...")
+        return
+
+    schedules_data = [
+        {
+            "id": s.get("id"),
+            "name": s.get("name"),
+            "frequency": s.get("frequency_type"),
+            "time": s.get("frequency_time"),
+            "type": s.get("report_type"),
+            "enabled": s.get("enabled"),
+            "recipients": s.get("recipients_count"),
+            "last_run": _short_time(s.get("last_run_at")),
+            "status": s.get("last_run_status") or "-",
+        }
+        for s in schedules
+    ]
+    format_output(
+        schedules_data,
+        format=format,
+        columns=["id", "name", "frequency", "time", "type", "enabled", "recipients", "last_run", "status"],
+        title="Scheduled Reports",
+    )
+
+
+@schedules_app.command("show")
+def schedules_show(
+    schedule_id: Annotated[str, typer.Argument(help="Schedule ID")],
+    format: Annotated[
+        OutputFormat,
+        typer.Option("--format", "-f", help="Output format"),
+    ] = "table",
+):
+    """Show details of a scheduled report.
+
+    Displays full schedule configuration including frequency,
+    report type, and recipients.
+
+    Examples:
+        dataspring schedules show abc123
+        dataspring schedules show abc123 --format json
+    """
+    require_auth()
+    token = auth.get_access_token()
+
+    try:
+        schedule = api_get(f"{SCHEDULES_PATH}/{schedule_id}", token)
+    except Exception as e:
+        fail(e, role_action="view scheduled reports")
+
+    if format == "json":
+        format_output(schedule, format=format)
+        return
+
+    report = schedule.get("report") or {}
+    if report.get("dashboard_id"):
+        report_type = "dashboard"
+        report_details = f"Dashboard: {report.get('dashboard_id')} ({report.get('format')})"
+    else:
+        report_type = "query"
+        metrics_str = ", ".join(report.get("metrics") or [])
+        dims_str = ", ".join(report.get("dimensions") or []) or "-"
+        report_details = f"Metrics: {metrics_str}\nDimensions: {dims_str}\nFormat: {report.get('format')}"
+
+    summary = {
+        "id": schedule.get("id"),
+        "name": schedule.get("name"),
+        "enabled": schedule.get("enabled"),
+        "frequency": _frequency_description(schedule.get("frequency") or {}),
+        "report_type": report_type,
+        "report_details": report_details,
+        "recipients": ", ".join(schedule.get("recipients") or []),
+        "created_by": schedule.get("created_by"),
+        "created_at": _short_time(schedule.get("created_at")),
+        "updated_at": _short_time(schedule.get("updated_at")),
+        "last_run": _short_time(schedule.get("last_run_at")),
+        "last_status": schedule.get("last_run_status") or "-",
+    }
+    format_output(summary, format=format, title=f"Schedule: {schedule.get('name')}")
+
+
+# ============================================================================
+# Quick Metrics sub-commands
+# ============================================================================
+#
+# Writes are the generated ``dataspring quick_metric_edit``. ``list`` and
+# ``show`` read ``GET /api/quick-metrics`` / ``GET /api/quick-metrics/{id}`` -
+# the REST twins of the ``dataspring://quick_metrics`` resources; no other
+# route exposes them.
+
+#: The read routes for quick metrics.
+QUICK_METRICS_PATH = "/api/quick-metrics"
+
+
+def _quick_metrics_from(result) -> list[dict]:
+    """A bare list or a ``{"quick_metrics": [...]}`` envelope, either way."""
+    if isinstance(result, dict):
+        return result.get("quick_metrics") or []
+    return list(result or [])
+
+
+def _quick_metric_summary(metric: dict) -> dict:
+    return {
+        "id": metric.get("id"),
+        "name": metric.get("name"),
+        "query_name": metric.get("query_name") or f"qm:{metric.get('name')}",
+        "expression": metric.get("expression"),
+        "base_metrics": ", ".join(metric.get("base_metrics") or []),
+    }
+
+
+@quick_metrics_app.command("list")
+def quick_metrics_list(
+    format: Annotated[
+        OutputFormat,
+        typer.Option("--format", "-f", help="Output format"),
+    ] = "table",
+):
+    """List all quick metrics.
+
+    Quick metrics are user-defined calculated metrics that combine
+    base metrics with arithmetic expressions. Query them using the
+    qm: prefix (e.g., qm:revenue_per_order).
+
+    Examples:
+        dataspring quick-metrics list
+        dataspring quick-metrics list --format json
+    """
+    require_auth()
+    token = auth.get_access_token()
+
+    try:
+        metrics = _quick_metrics_from(api_get(QUICK_METRICS_PATH, token))
+    except Exception as e:
+        fail(e, role_action="list quick metrics")
+
+    if not metrics:
+        print_info("No quick metrics found")
+        print_info("Create one with: dataspring quick-metrics create revenue_per_order 'total_revenue / order_count'")
+        return
+
+    metrics_data = [
+        {
+            "id": m.get("id"),
+            "name": m.get("name"),
+            "expression": m.get("expression"),
+            "query_name": m.get("query_name") or f"qm:{m.get('name')}",
+            "description": m.get("description") or "-",
+        }
+        for m in metrics
+    ]
+    format_output(
+        metrics_data,
+        format=format,
+        columns=["id", "name", "expression", "query_name", "description"],
+        title="Quick Metrics",
+    )
+
+
+@quick_metrics_app.command("show")
+def quick_metrics_show(
+    metric_id: Annotated[str, typer.Argument(help="Quick metric ID")],
+    format: Annotated[
+        OutputFormat,
+        typer.Option("--format", "-f", help="Output format"),
+    ] = "table",
+):
+    """Show details of a quick metric.
+
+    Displays the full configuration of a quick metric including
+    its expression and the base metrics it references.
+
+    Examples:
+        dataspring quick-metrics show abc123
+        dataspring quick-metrics show abc123 --format json
+    """
+    require_auth()
+    token = auth.get_access_token()
+
+    try:
+        metric = api_get(f"{QUICK_METRICS_PATH}/{metric_id}", token)
+    except Exception as e:
+        fail(e, role_action="view quick metrics")
+
+    if format == "json":
+        format_output(metric, format=format)
+        return
+
+    summary = {
+        **_quick_metric_summary(metric),
+        "description": metric.get("description") or "-",
+        "created_by": metric.get("created_by"),
+        "created_at": metric.get("created_at"),
+        "updated_at": metric.get("updated_at"),
+    }
+    format_output(summary, format=format, title=f"Quick Metric: {metric.get('name')}")
+
+    # Show usage hint
+    console.print()
+    print_info(f"Query this metric with: dataspring query -m qm:{metric.get('name')} -g month")
+
+
+# ============================================================================
+# Context sub-commands
+# ============================================================================
+#
+# An update is the generated ``dataspring update_context --updates-json``
+# (validated and recorded on the learned trail by the server). ``get`` reads
+# ``GET /api/me/preferences`` - the REST twin of the ``dataspring://context``
+# MCP resource; no other route exposes a user's stored preferences.
+
+#: The read route for the caller's own query preferences.
+PREFERENCES_PATH = "/api/me/preferences"
+
+
+def _print_preferences(prefs: dict) -> None:
+    console.print("\n[bold]Preferences[/]")
+    has_prefs = False
+    for key in ("default_currency", "default_grain", "decimal_places", "preferred_chart_type"):
+        value = prefs.get(key)
+        if value is not None:
+            console.print(f"  {key}: {value}")
+            has_prefs = True
+    if not has_prefs:
+        console.print("  (none)")
+
+    console.print("\n[bold]Favorite Metrics[/]")
+    favorites = prefs.get("favorite_metrics") or []
+    if favorites:
+        for fav in favorites:
+            console.print(f"  - {fav}")
+    else:
+        console.print("  (none)")
+
+    standing = prefs.get("standing_filters") or []
+    substitutions = prefs.get("metric_substitutions") or {}
+    segment = prefs.get("default_segment")
+    if standing or substitutions or segment:
+        console.print("\n[bold]Standing query intent[/]")
+        for item in standing:
+            console.print(f"  filter: {item}")
+        for asked, preferred in substitutions.items():
+            console.print(f"  {asked} -> {preferred}")
+        if segment:
+            console.print(f"  default segment: {segment}")
+
+    console.print()
+
+
+@context_app.command("get")
+def context_get(
+    format: Annotated[
+        OutputFormat,
+        typer.Option("--format", "-f", help="Output format"),
+    ] = "table",
+):
+    """Get your accumulated user context.
+
+    Shows preferences and favorite metrics stored across sessions.
+    This context is used by agents to personalize responses.
+
+    Examples:
+        dataspring context get
+        dataspring context get --format json
+    """
+    require_auth()
+    token = auth.get_access_token()
+
+    try:
+        prefs = api_get(PREFERENCES_PATH, token)
+    except Exception as e:
+        fail(e, role_action="read your context")
+
+    if format == "json":
+        format_output(prefs, format=format)
+    else:
+        _print_preferences(prefs)
+
+
+# ============================================================================
+# business_context sub-commands  (T2.6 — plan task)
+# ============================================================================
+#
+# Reads ``GET /api/context``; writes are the ``business_context_edit``
+# dispatch family (``set``), whose 2000-byte UTF-8 cap and admin/owner check
+# live on the server. The CLI surfaces the server's answer verbatim.
+
+#: UTF-8 byte cap for business_context — locked in plan T1.0; mirrored
+#: on the server in mcp_dispatch.BUSINESS_CONTEXT_CAP_BYTES. Counted in
+#: bytes (not chars) so non-ASCII content (Danish ``ø/æ/å``, emoji)
+#: doesn't smuggle past the cap and then disappear at initialize time.
+_BUSINESS_CONTEXT_CAP_BYTES = 2000
+
+
+def _read_business_context(token: str) -> str:
+    """GET /api/context → ``content`` string (or empty)."""
+    return api_get("/api/context", token).get("content", "") or ""
+
+
+def _write_business_context(token: str, content: str) -> dict:
+    """``business_context_edit set`` - replaces the document."""
+    return call_tool("business_context_edit", "set", {"content": content}, token=token)
+
+
+@business_context_app.command("get")
+def business_context_get():
+    """Print the org's business_context document to stdout."""
+    require_auth()
+    token = auth.get_access_token()
+
+    try:
+        content = _read_business_context(token)
+    except Exception as e:
+        fail(e, role_action="read business_context")
+
+    if not content:
+        print_info("(no business_context set for this org)")
+        return
+    # Plain print so the output is shell-pipeable (e.g. `… get > file`).
+    typer.echo(content)
+
+
+@business_context_app.command("size")
+def business_context_size():
+    """Show the current business_context size against the 2000-byte UTF-8 cap."""
+    require_auth()
+    token = auth.get_access_token()
+
+    try:
+        content = _read_business_context(token)
+    except Exception as e:
+        fail(e, role_action="read business_context")
+
+    n = len(content.encode("utf-8"))
+    cap = _BUSINESS_CONTEXT_CAP_BYTES
+    remaining = max(0, cap - n)
+    console.print(f"{n} / {cap} bytes  ({remaining} remaining)")
+
+
+@business_context_app.command("set")
+def business_context_set():
+    """Replace the org's business_context. Reads new content from stdin.
+
+    Requires admin or owner role server-side.
+
+    Examples:
+        cat ctx.md | dataspring business-context set
+        echo "Org overview..." | dataspring business-context set
+    """
+    require_auth()
+    token = auth.get_access_token()
+
+    content = sys.stdin.read()
+    if not content:
+        print_error("No content on stdin", hint="Pipe the document or use `set` interactively")
+        raise typer.Exit(1)
+
+    try:
+        _write_business_context(token, content)
+    except Exception as e:
+        fail(e, role_action="set business_context")
+
+    print_success(
+        f"business_context updated ({len(content.encode('utf-8'))} bytes)"
+    )
+
+
+@business_context_app.command("edit")
+def business_context_edit_cmd():
+    """Open the current business_context in $EDITOR; save on exit.
+
+    Requires admin or owner role server-side.
+    """
+    # _cmd suffix avoids shadowing the ``business_context_edit`` MCP
+    # tool name (would mismatch surface naming if both were imported
+    # in the same module — defensive even though they're not yet).
+    import os
+    import subprocess
+    import tempfile
+
+    require_auth()
+    token = auth.get_access_token()
+
+    try:
+        existing = _read_business_context(token)
+    except Exception as e:
+        fail(e, role_action="read business_context")
+
+    editor = os.environ.get("VISUAL") or os.environ.get("EDITOR") or "vi"
+    with tempfile.NamedTemporaryFile(
+        suffix=".md", mode="w", delete=False, encoding="utf-8"
+    ) as tf:
+        tf.write(existing)
+        tmp_path = tf.name
+
+    try:
+        subprocess.call([editor, tmp_path])
+        with open(tmp_path, encoding="utf-8") as f:
+            new_content = f.read()
+    finally:
+        try:
+            os.unlink(tmp_path)
+        except OSError:
+            pass
+
+    if new_content == existing:
+        print_info("No changes")
+        return
+    if not new_content.strip():
+        print_warning("Empty content — aborting save")
+        raise typer.Exit(1)
+
+    try:
+        _write_business_context(token, new_content)
+    except Exception as e:
+        fail(e, role_action="set business_context")
+
+    print_success(
+        f"business_context updated ({len(new_content.encode('utf-8'))} bytes)"
+    )
+
+
+@business_context_app.command("import")
+def business_context_import(
+    file: Annotated[
+        Path,
+        typer.Argument(help="Path to the markdown file to import", exists=True),
+    ],
+):
+    """Replace the org's business_context with the contents of FILE.
+
+    Equivalent to ``cat FILE | dataspring business-context set``.
+    Requires admin or owner role server-side.
+    """
+    require_auth()
+    token = auth.get_access_token()
+
+    content = file.read_text(encoding="utf-8")
+
+    try:
+        _write_business_context(token, content)
+    except Exception as e:
+        fail(e, role_action="set business_context")
+
+    print_success(
+        f"business_context imported from {file} ({len(content.encode('utf-8'))} bytes)"
+    )
+
+
+@business_context_app.command("export")
+def business_context_export(
+    output: Annotated[
+        Optional[Path],
+        typer.Option("--output", "-o", help="Write to file instead of stdout"),
+    ] = None,
+):
+    """Write the org's business_context to a file (or stdout if no -o)."""
+    require_auth()
+    token = auth.get_access_token()
+
+    try:
+        content = _read_business_context(token)
+    except Exception as e:
+        fail(e, role_action="read business_context")
+
+    if output is None:
+        typer.echo(content)
+        return
+    output.write_text(content, encoding="utf-8")
+    print_success(
+        f"business_context exported to {output} ({len(content.encode('utf-8'))} bytes)"
+    )
+
+
+# ============================================================================
+# learned sub-commands  (tick rkn)
+# ============================================================================
+#
+# Reads ``GET /api/learned`` / ``GET /api/learned/{id}``; an undo is the
+# generated ``dataspring learned_edit undo [--learning-id]``, which enforces
+# who may revert what: org-scope entries need admin/owner, personal entries
+# their author.
+
+
+def _learned_row(entry: dict) -> dict:
+    summary = entry.get("summary", "")
+    if entry.get("kind") == "proposal":
+        summary = f"{summary} (proposed, not applied)"
+    return {
+        "id": entry.get("id"),
+        "when": entry.get("created_at"),
+        "who": entry.get("actor_email") or entry.get("actor_id"),
+        "surface": entry.get("actor_type"),
+        "scope": entry.get("scope"),
+        "summary": summary,
+        "reverted": entry.get("reverted", False),
+    }
+
+
+@learned_app.command("list")
+def learned_list(
+    limit: Annotated[
+        int, typer.Option("--limit", help="Max entries to show")
+    ] = 50,
+    include_reverted: Annotated[
+        bool, typer.Option("--include-reverted", help="Include already-reverted entries")
+    ] = False,
+    format: Annotated[
+        OutputFormat,
+        typer.Option("--format", "-f", help="Output format"),
+    ] = "table",
+):
+    """List what DataSpring learned for this org (plus your personal entries).
+
+    Examples:
+        dataspring learned list
+        dataspring learned list --limit 10 --include-reverted
+        dataspring learned list -f json
+    """
+    require_auth()
+    token = auth.get_access_token()
+
+    try:
+        data = api_get(
+            f"/api/learned?limit={limit}&include_reverted={str(include_reverted).lower()}",
+            token,
+        )
+    except Exception as e:
+        fail(e, role_action="view the learned trail")
+
+    entries = data.get("learnings", [])
+    if not entries:
+        print_info("Nothing learned yet")
+        return
+
+    if format == "json":
+        format_output(entries, format=format)
+        return
+
+    format_output(
+        [_learned_row(entry) for entry in entries],
+        format=format,
+        columns=["id", "when", "who", "surface", "scope", "summary", "reverted"],
+        title="Learned",
+    )
+
+
+@learned_app.command("show")
+def learned_show(
+    learning_id: Annotated[str, typer.Argument(help="Learning entry ID")],
+):
+    """Show one learned entry, with before/after as YAML."""
+    require_auth()
+    token = auth.get_access_token()
+
+    try:
+        entry = api_get(f"/api/learned/{learning_id}", token)
+    except Exception as e:
+        fail(e, role_action="view the learned trail")
+
+    print_yaml(entry)
+
+
+# ============================================================================
+# Warehouses sub-commands (docs/2026-09-17-datacore-chunk2-plan.md)
+# ============================================================================
+#
+# The read is ``GET /api/warehouses`` (the ``dataspring://warehouses``
+# payload); the writes are the generated ``dataspring warehouse_edit
+# activate|add_external|remove``.
+
+WAREHOUSES_PATH = "/api/warehouses"
+
+
+def _warehouses_from(result) -> list[dict]:
+    if isinstance(result, dict):
+        return list(result.get("warehouses") or [])
+    return list(result or [])
+
+
+def _warehouse_row(entry: dict) -> dict:
+    connection = entry.get("connection") or {}
+    where = connection.get("path") or (
+        f"{connection.get('project')}.{connection.get('dataset')}"
+        if connection.get("project")
+        else "-"
+    )
+    return {
+        "id": entry.get("id"),
+        "kind": entry.get("kind"),
+        "label": entry.get("label"),
+        "active": "*" if entry.get("active") else "",
+        "models": entry.get("semantic_models", 0),
+        "metrics": entry.get("metrics", 0),
+        "imported": (entry.get("manifest_imported_at") or "-")[:19],
+        "where": where,
+    }
+
+
+@warehouses_app.command("list")
+def warehouses_list(
+    format: Annotated[
+        OutputFormat,
+        typer.Option("--format", "-f", help="Output format"),
+    ] = "table",
+):
+    """List the org's warehouses: id, kind, label, which is active, manifest counts.
+
+    Examples:
+        dataspring warehouses list
+        dataspring warehouses list -f json
+    """
+    require_auth()
+    token = auth.get_access_token()
+
+    try:
+        entries = _warehouses_from(api_get(WAREHOUSES_PATH, token))
+    except Exception as e:
+        fail(e, role_action="list warehouses")
+
+    if not entries:
+        print_info("No warehouses configured")
+        return
+
+    if format == "json":
+        format_output(entries, format=format)
+        return
+
+    format_output(
+        [_warehouse_row(entry) for entry in entries],
+        format=format,
+        columns=["id", "kind", "label", "active", "models", "metrics", "imported", "where"],
+        title="Warehouses",
+    )
+
+
+# ============================================================================
+# Secrets, both directions, and run_sql  (datacore chunk 3, step 2)
+# ============================================================================
+#
+# `dataspring secret set <name> --stdin` is the terminal door of D17: the
+# value is read from stdin here and posted straight to the paste link the
+# server minted (`POST /api/secret-links/<nonce>`), so it goes terminal to
+# API and an agent driving the CLI sees only the exit status. `dataspring
+# airbyte credentials` prints the one-time reveal link (`--stdout` fetches
+# the value for a terminal user). `dataspring sql` is `run_sql`.
+
+secret_app = typer.Typer(help="Customer secrets: set a value without it passing through an agent")
+app.add_typer(secret_app, name="secret")
+airbyte_app = typer.Typer(help="The tenant's Airbyte destination: its issued credentials")
+app.add_typer(airbyte_app, name="airbyte")
+
+
+def _link_nonce(link: str) -> str:
+    """The nonce at the end of a `https://dataspring.app/s/<nonce>` link."""
+    return link.rstrip("/").rsplit("/", 1)[-1]
+
+
+@secret_app.command("set")
+def secret_set_cmd(
+    name: Annotated[str, typer.Argument(help="The secret: t-<org>-<connection>-<field>")],
+    stdin: Annotated[
+        bool,
+        typer.Option("--stdin", help="Read the value from stdin and post it to the paste link (required)"),
+    ] = False,
+):
+    """Set or rotate a customer secret from stdin, never from an argument.
+
+    Examples:
+        printf '%s' "$KEY" | dataspring secret set t-acme-kanpla-api_key --stdin
+        dataspring secret set t-acme-kanpla-api_key --stdin < key.txt
+    """
+    require_auth()
+    token = auth.get_access_token()
+    if not stdin:
+        print_error(
+            "The value is read from stdin only; pass --stdin",
+            hint="printf '%s' \"$VALUE\" | dataspring secret set <name> --stdin. Never put a secret in an argument: it lands in shell history.",
+        )
+        raise typer.Exit(2)
+    value = sys.stdin.read()
+    if value.endswith("\n") and not value.endswith("\n\n"):
+        value = value[:-1]  # the one trailing newline a shell adds; a JSON key keeps its shape
+    if not value.strip():
+        print_error("stdin was empty; nothing was set")
+        raise typer.Exit(2)
+
+    try:
+        minted = call_tool("secret_edit", "set", {"name": name}, token=token, timeout=30.0)
+        result = api_post(f"/api/secret-links/{_link_nonce(minted['link'])}", {"value": value}, token, timeout=60.0)
+    except Exception as e:
+        fail(e, role_action="set secrets", prefix="Failed to set the secret")
+
+    destroyed = result.get("destroyed") or []
+    verb = "created" if result.get("created") else "rotated"
+    print_success(f"Secret {result.get('secret', name)} {verb}: version {result.get('version')}")
+    if destroyed:
+        print_info(f"Previous version(s) destroyed: {', '.join(destroyed)}")
+
+
+@airbyte_app.command("credentials")
+def airbyte_credentials(
+    stdout: Annotated[
+        bool,
+        typer.Option("--stdout", help="Fetch the key through the link and print it (for a terminal user; it is one-time)"),
+    ] = False,
+):
+    """A one-time link to the tenant's Airbyte destination key (admin).
+
+    Examples:
+        dataspring airbyte credentials            # prints the link to hand to the person entering it in Airbyte
+        dataspring airbyte credentials --stdout   # prints the key itself, once
+    """
+    require_auth()
+    token = auth.get_access_token()
+    try:
+        minted = call_tool("secret_edit", "reveal", {}, token=token, timeout=30.0)
+    except Exception as e:
+        fail(e, role_action="reveal issued credentials", prefix="Failed to mint a reveal link")
+
+    if not stdout:
+        console.print(minted["link"])
+        print_info(f"Shows {minted.get('secret')} once, valid until {minted.get('expires_at')}; never paste it into a chat.")
+        return
+    try:
+        result = api_post(f"/api/secret-links/{_link_nonce(minted['link'])}/reveal", {}, token, timeout=30.0)
+    except Exception as e:
+        fail(e, prefix="Failed to read the key through the link")
+    sys.stdout.write(result["value"])
+    if not result["value"].endswith("\n"):
+        sys.stdout.write("\n")
+
+
+SqlFormat = Literal["table", "json", "csv", "markdown"]
+
+
+@app.command("sql")
+def sql_cmd(
+    statement: Annotated[str, typer.Argument(help="One SQL statement; '-' reads it from stdin")],
+    warehouse: Annotated[
+        Optional[str],
+        typer.Option("--warehouse", help="Which of the org's warehouses to run against (see `warehouses list`); default: the active one"),
+    ] = None,
+    max_rows: Annotated[int, typer.Option("--max-rows", help="Rows to return at most (cap 10000)")] = 1000,
+    dry_run: Annotated[bool, typer.Option("--dry-run", help="Estimate the bytes only; run nothing")] = False,
+    format: Annotated[SqlFormat, typer.Option("--format", "-f", help="Output format")] = "table",
+):
+    """Run one read-only SQL statement as the org's reader identity (ungoverned).
+
+    Examples:
+        dataspring sql "SELECT venue, SUM(revenue) FROM acme_marts.fct_orders GROUP BY 1"
+        dataspring sql "SELECT COUNT(*) FROM acme_staging.stg_orders" --dry-run
+        dataspring sql - --format csv < query.sql > rows.csv
+    """
+    require_auth()
+    token = auth.get_access_token()
+    if statement == "-":
+        statement = sys.stdin.read()
+
+    body: dict = {"sql": statement, "max_rows": max_rows}
+    if warehouse:
+        body["warehouse"] = warehouse
+    if dry_run:
+        body["dry_run"] = True
+    if format in ("csv", "markdown"):
+        body["format"] = format
+
+    try:
+        result = call_tool("run_sql", None, body, token=token, timeout=120.0)
+    except Exception as e:
+        if isinstance(e, (typer.Exit, typer.Abort)):
+            raise
+        msg, hint = format_api_error(e, role_action="run SQL")
+        print_error(f"SQL failed: {msg}", hint=hint)
+        raise typer.Exit(1)
+
+    if dry_run:
+        print_success(f"Dry run: {result.get('bytes_processed') or 0:,} bytes would be processed as {result.get('identity')}")
+        return
+    if format in ("csv", "markdown"):
+        sys.stdout.write(result.get("content") or "")
+        return
+    data = result.get("data", [])
+    columns = result.get("columns", [])
+    format_output(data, format=format, columns=columns, title=f"SQL ({len(data)} rows, ungoverned)")
+    if format == "table":
+        bytes_processed = result.get("bytes_processed")
+        console.print(f"[dim]{result.get('note')}[/]")
+        console.print(
+            f"[dim]{bytes_processed:,} bytes processed[/]" if bytes_processed is not None else "",
+            f"[dim]as {result.get('identity')}; job {result.get('job_id')}[/]",
+        )
+
+
+# ============================================================================
+# datacore sub-commands (chunk 3): the local-folder door to the datacore
+# ============================================================================
+#
+# `pull` writes the deployed snapshot to a directory; `push` sends every
+# changed file back as a `datacore_edit` (kind connection, pipeline or model
+# by path, each with the previous edit's `version` as `expect_version`);
+# `check` and `deploy` are `datacore_run` actions, as are `run` and `reset`;
+# `status` reads. Reads are the `/api/datacore/*` routes, the same
+# payloads as the `dataspring://datacore/*` resources.
+
+DATACORE_FILES_PATH = "/api/datacore/files"
+DATACORE_RUNS_PATH = "/api/datacore/runs"
+
+
+def _datacore_family(path: str) -> tuple[str, str] | None:
+    """Which `datacore_edit` kind writes a workspace path, and the name it takes."""
+    if path.startswith("connections/") and path.count("/") == 1 and path.endswith((".yaml", ".yml")):
+        return "connection", path.split("/", 1)[1].rsplit(".", 1)[0]
+    if path.startswith("pipelines/") and path.count("/") == 1 and path.endswith((".yaml", ".yml")):
+        return "pipeline", path.split("/", 1)[1].rsplit(".", 1)[0]
+    if path.startswith("models/"):
+        return "model", path
+    return None
+
+
+def _sha256_of(data: bytes) -> str:
+    import hashlib
+
+    return hashlib.sha256(data).hexdigest()
+
+
+def _local_files(directory: Path) -> dict[str, bytes]:
+    out = {}
+    for path in sorted(directory.rglob("*")):
+        if not path.is_file():
+            continue
+        rel = path.relative_to(directory).as_posix()
+        if rel.startswith(".") or "/." in rel or any(part in ("target", "dbt_packages", "logs") for part in rel.split("/")):
+            continue
+        out[rel] = path.read_bytes()
+    return out
+
+
+@datacore_app.command("pull")
+def datacore_pull(
+    directory: Annotated[Path, typer.Argument(help="Where to write the workspace")],
+    snapshot: Annotated[
+        str, typer.Option("--snapshot", help="deployed (default) or draft")
+    ] = "deployed",
+):
+    """Write the deployed snapshot (or the draft) to a directory, file by file.
+
+    Example:
+        dataspring datacore pull ./noon-datacore
+    """
+    require_auth()
+    token = auth.get_access_token()
+    if snapshot not in ("deployed", "draft"):
+        print_error("--snapshot is deployed or draft")
+        raise typer.Exit(1)
+    try:
+        files = api_get(DATACORE_FILES_PATH, token)
+    except Exception as e:
+        fail(e, role_action="read the datacore")
+    listing = files.get(snapshot)
+    if not listing:
+        print_error(f"the org has no {snapshot} snapshot")
+        raise typer.Exit(1)
+    snapshot_id = listing["id"]
+    paths = [f["path"] for f in listing.get("files") or []]
+    directory.mkdir(parents=True, exist_ok=True)
+    written = 0
+    for rel in paths:
+        try:
+            doc = api_get(f"/api/datacore/file/{rel}?snapshot={snapshot_id}", token)
+        except Exception as e:
+            fail(e, prefix=rel)
+        if doc.get("binary"):
+            print_warning(f"skipped binary file {rel}")
+            continue
+        target = directory / rel
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(doc.get("content") or "", encoding="utf-8")
+        written += 1
+    (directory / ".dataspring-snapshot").write_text(snapshot_id + "\n", encoding="utf-8")
+    print_success(f"pulled snapshot {snapshot_id}: {written} files into {directory}")
+
+
+@datacore_app.command("push")
+def datacore_push(
+    directory: Annotated[Path, typer.Argument(help="A pulled (and edited) workspace directory")],
+    prune: Annotated[bool, typer.Option("--prune", help="Also delete remote files absent locally")] = False,
+    dry_run: Annotated[bool, typer.Option("--dry-run", help="Show what would change, send nothing")] = False,
+):
+    """Upload every changed file as an edit into the draft (connections,
+    pipelines and the dbt project each through their own edit family), then
+    print the new version. Run `dataspring datacore check` next.
+
+    Example:
+        dataspring datacore push ./noon-datacore
+    """
+    require_auth()
+    token = auth.get_access_token()
+    if not directory.is_dir():
+        print_error(f"{directory} is not a directory")
+        raise typer.Exit(1)
+    try:
+        files = api_get(DATACORE_FILES_PATH, token)
+    except Exception as e:
+        fail(e, role_action="read the datacore")
+    remote = {f["path"]: f for f in ((files.get("draft") or files.get("deployed") or {}).get("files") or [])}
+    version = files.get("version")
+    local = _local_files(directory)
+
+    changes: list[tuple[str, str]] = []
+    for rel, data in local.items():
+        if _datacore_family(rel) is None:
+            continue
+        if rel not in remote or remote[rel].get("sha256") != _sha256_of(data):
+            changes.append(("apply", rel))
+    if prune:
+        for rel in remote:
+            if rel not in local and _datacore_family(rel) is not None:
+                changes.append(("delete", rel))
+    if not changes:
+        print_info(f"nothing to push: the directory matches version {version}")
+        return
+    for verb, rel in changes:
+        typer.echo(f"{verb:6} {rel}")
+    if dry_run:
+        return
+
+    for verb, rel in changes:
+        kind, name = _datacore_family(rel)  # type: ignore[misc]
+        try:
+            fields: dict = {"kind": kind, "name": name, "expect_version": version}
+            if verb == "delete":
+                result = call_tool("datacore_edit", "delete", fields, token=token)
+            elif kind == "model":
+                result = call_tool("datacore_edit", "apply", {**fields, "content": local[rel].decode("utf-8")}, token=token)
+            else:
+                document = yaml.safe_load(local[rel].decode("utf-8")) or {}
+                result = call_tool("datacore_edit", "apply", {**fields, "document": document}, token=token)
+        except Exception as e:
+            fail(e, prefix=rel)
+        version = result.get("version", version)
+    print_success(f"pushed {len(changes)} change(s); draft version {version}")
+
+
+def _print_check_report(run: dict) -> None:
+    report = run.get("check") or {}
+    status = run.get("status")
+    line = f"check {run.get('id')}: {status}"
+    if report.get("snapshot"):
+        line += f" (snapshot {report['snapshot']})"
+    (print_success if status == "succeeded" else print_error)(line)
+    for entry in report.get("pipelines") or []:
+        mark = "ok " if entry.get("ok") else "ERR"
+        typer.echo(f"  pipeline   {mark} {entry['name']}" + ("" if entry.get("ok") else f": {entry.get('error')}"))
+    for entry in report.get("connections") or []:
+        mark = "ok " if entry.get("ok") else "ERR"
+        typer.echo(f"  connection {mark} {entry['name']}" + ("" if entry.get("ok") else f": {entry.get('error')}"))
+    dbt = report.get("dbt") or {}
+    if dbt:
+        typer.echo(
+            f"  dbt        {dbt.get('status')}: {dbt.get('models', 0)} models, {dbt.get('tests', 0)} tests, "
+            f"{dbt.get('seeds', 0)} seeds" + (f" -> {dbt.get('target')}" if dbt.get("target") else "")
+        )
+        for failure in dbt.get("failures") or []:
+            typer.echo(f"             FAIL {failure.get('node')}: {failure.get('message')}")
+        for warning in dbt.get("warnings") or []:
+            typer.echo(f"             warn {warning.get('node')}: {warning.get('message')}")
+    if report.get("dry_run"):
+        typer.echo(f"  dry run    {report.get('dry_run_bytes', 0):,} bytes over {len(report['dry_run'])} models")
+    for error in report.get("errors") or []:
+        typer.echo(f"  error      {error}")
+    if run.get("error") and not report:
+        typer.echo(f"  error      {run['error'].get('message')}")
+
+
+def _poll_run(run_id: str, token: str, *, interval: float = 10.0, timeout: float = 1800.0) -> dict:
+    import time
+
+    deadline = time.monotonic() + timeout
+    last = None
+    while True:
+        run = api_get(f"{DATACORE_RUNS_PATH}/{run_id}", token)
+        if run.get("status") != last:
+            last = run.get("status")
+            print_info(f"run {run_id}: {last}")
+        if last in ("succeeded", "failed"):
+            return run
+        if time.monotonic() > deadline:
+            print_error(f"run {run_id} still {last} after {int(timeout)}s")
+            raise typer.Exit(1)
+        time.sleep(interval)
+
+
+@datacore_app.command("check")
+def datacore_check_cmd(
+    wait: Annotated[bool, typer.Option("--wait/--no-wait", help="Poll the check run to its end")] = True,
+):
+    """Check the draft: schema validation here, then a check run of the
+    tenant's job (compile, dbt build into <org>_dev, tests, dry-run bytes).
+
+    Example:
+        dataspring datacore check
+    """
+    require_auth()
+    token = auth.get_access_token()
+    try:
+        result = call_tool("datacore_run", "check", {}, token=token)
+    except Exception as e:
+        fail(e, role_action="check the datacore")
+    if not result.get("ok"):
+        print_error(f"check failed at {result.get('stage')} for snapshot {result.get('snapshot')}")
+        for error in result.get("errors") or []:
+            typer.echo(f"  {error}")
+        raise typer.Exit(1)
+    run_id = result["run_id"]
+    print_info(f"check run {run_id} {result.get('status')} for snapshot {result.get('snapshot')}")
+    if not wait:
+        return
+    try:
+        run = _poll_run(run_id, token)
+    except typer.Exit:
+        raise
+    except Exception as e:
+        fail(e, role_action="read the check run")
+    _print_check_report(run)
+    if run.get("status") != "succeeded":
+        raise typer.Exit(1)
+
+
+@datacore_app.command("deploy")
+def datacore_deploy_cmd(
+    snapshot: Annotated[Optional[str], typer.Option("--snapshot", help="A previously deployed snapshot id to roll back to")] = None,
+    note: Annotated[Optional[str], typer.Option("--note", help="Why, for the learned trail")] = None,
+):
+    """Promote the checked draft to deployed (or roll back to a snapshot).
+
+    Example:
+        dataspring datacore deploy --note "orders mart reads the new partner tables"
+    """
+    require_auth()
+    token = auth.get_access_token()
+    fields: dict = {}
+    if snapshot:
+        fields["snapshot"] = snapshot
+    if note:
+        fields["note"] = note
+    try:
+        result = call_tool("datacore_run", "deploy", fields, token=token)
+    except Exception as e:
+        fail(e, role_action="deploy the datacore")
+    print_success(f"deployed snapshot {result.get('deployed_snapshot')} (was {result.get('previous_snapshot') or 'none'})")
+    for run in result.get("runs_triggered") or []:
+        typer.echo(f"  run {run['run_id']} started for pipeline {run['pipeline']}")
+    for skipped in result.get("runs_skipped") or []:
+        typer.echo(f"  pipeline {skipped['pipeline']} not started: run {skipped['active_run']} is active")
+
+
+@datacore_app.command("run")
+def datacore_run_cmd(
+    pipeline: Annotated[str, typer.Argument(help="Pipeline name")],
+    start: Annotated[Optional[str], typer.Option("--start", help="Window start, YYYY-MM-DD")] = None,
+    end: Annotated[Optional[str], typer.Option("--end", help="Window end, YYYY-MM-DD")] = None,
+    chunk: Annotated[Optional[str], typer.Option("--chunk", help="Backfill chunk: 7d, 2w or 1M")] = None,
+    cursor_from: Annotated[Optional[str], typer.Option("--from", help="Cursor value to re-pull from")] = None,
+    wait: Annotated[bool, typer.Option("--wait", help="Poll the run to its end")] = False,
+):
+    """Run a pipeline now, over a window, or as a chunked backfill.
+
+    Examples:
+        dataspring datacore run kanpla
+        dataspring datacore run kanpla --start 2026-01-01 --end 2026-06-30 --chunk 1M
+    """
+    require_auth()
+    token = auth.get_access_token()
+    if bool(start) != bool(end):
+        print_error("--start and --end go together")
+        raise typer.Exit(1)
+    fields: dict = {"pipeline": pipeline}
+    if start and end:
+        fields["window"] = {"start": start, "end": end}
+    if chunk:
+        fields["backfill_chunk"] = chunk
+    if cursor_from:
+        fields["cursor"] = {"from": cursor_from}
+    try:
+        result = call_tool("datacore_run", "run", fields, token=token)
+    except Exception as e:
+        fail(e, role_action="run a pipeline")
+    if result.get("kind") == "backfill":
+        print_success(f"backfill {result['run_id']} of {pipeline}: {result.get('total')} chunks, first child {result.get('children', [None])[0]}")
+    else:
+        print_success(f"run {result['run_id']} of {pipeline}: {result.get('status')}")
+    if wait:
+        try:
+            run = _poll_run(result["run_id"], token, timeout=6 * 3600)
+        except typer.Exit:
+            raise
+        except Exception as e:
+            fail(e, role_action="read the run")
+        if run.get("status") != "succeeded":
+            print_error(f"run {run['id']} failed: {(run.get('error') or {}).get('message')}")
+            raise typer.Exit(1)
+
+
+@datacore_app.command("reset")
+def datacore_reset_cmd(
+    pipeline: Annotated[str, typer.Argument(help="Pipeline name")],
+    approve: Annotated[bool, typer.Option("--approve", help="Required: the reset is irreversible")] = False,
+):
+    """Delete a pipeline's dlt state and drop its raw tables (irreversible).
+
+    Example:
+        dataspring datacore reset kanpla --approve
+    """
+    require_auth()
+    token = auth.get_access_token()
+    if not approve:
+        print_error(f"resetting {pipeline} deletes its dlt state and drops its raw tables; repeat with --approve")
+        raise typer.Exit(1)
+    try:
+        result = call_tool("datacore_run", "reset", {"pipeline": pipeline, "approve": True}, token=token)
+    except Exception as e:
+        fail(e, role_action="reset a pipeline")
+    print_success(f"reset {pipeline}: dropped {', '.join(result.get('tables') or []) or 'no tables'}")
+
+
+@datacore_app.command("status")
+def datacore_status(
+    format: Annotated[OutputFormat, typer.Option("--format", "-f", help="Output format")] = "table",
+):
+    """The deployed and draft snapshots, the draft's check, and recent runs.
+
+    Example:
+        dataspring datacore status
+    """
+    require_auth()
+    token = auth.get_access_token()
+    try:
+        files = api_get(DATACORE_FILES_PATH, token)
+        runs = api_get(DATACORE_RUNS_PATH, token).get("runs") or []
+    except Exception as e:
+        fail(e, role_action="read the datacore")
+    if format == "json":
+        format_output({"files": files, "runs": runs}, format=format)
+        return
+    deployed, draft = files.get("deployed"), files.get("draft")
+    typer.echo(f"deployed  {deployed['id'] if deployed else 'none'}" + (f"  ({deployed['file_count']} files, {deployed.get('deployed_at') or deployed.get('created_at')})" if deployed else ""))
+    if draft:
+        checks = draft.get("checks") or {}
+        typer.echo(f"draft     {draft['id']}  ({draft['file_count']} files, check: {checks.get('status') or 'not run'}" + (f", run {checks['run_id']}" if checks.get("run_id") else "") + ")")
+    else:
+        typer.echo("draft     none")
+    typer.echo(f"version   {files.get('version')}   auto_deploy: {'on' if files.get('auto_deploy') else 'off'}")
+    rows = [
+        {
+            "id": r.get("id"),
+            "pipeline": r.get("pipeline"),
+            "trigger": r.get("trigger"),
+            "status": r.get("status") + (f" {r.get('done')}/{r.get('total')}" if r.get("kind") == "backfill" else ""),
+            "window": f"{r['window']['start']}..{r['window']['end']}" if r.get("window") else "",
+            "requested": r.get("requested_at"),
+            "error": ((r.get("error") or {}).get("message") or "")[:60],
+        }
+        for r in runs[:15]
+    ]
+    if rows:
+        format_output(rows, format=format, columns=["id", "pipeline", "trigger", "status", "window", "requested", "error"], title="Recent runs")
+
+
+# ============================================================================
+# Skill command  (T3.5 — plan task)
+# ============================================================================
+#
+# Hits the no-auth /api/v1/skill/* endpoints. Useful even when the user
+# isn't logged in — the skills are public conventions, not org data.
+#
+# Forms:
+#   dataspring skill                          — list personas
+#   dataspring skill <persona>                — frontmatter
+#   dataspring skill <persona> instructions   — full body
+
+
+def _skill_url(path: str) -> str:
+    """Compute the public skill URL from the configured base."""
+    return f"{get_api_base()}{path}"
+
+
+def _fetch_skill_markdown(path: str) -> str:
+    """GET text/markdown without auth; surface friendly errors."""
+    import httpx
+
+    url = _skill_url(path)
+    try:
+        response = httpx.get(url, timeout=30.0)
+        response.raise_for_status()
+        return response.text
+    except httpx.HTTPStatusError as e:
+        # Use the server's body verbatim — the 404 includes the list
+        # of available personas, which is the most helpful thing.
+        body = (e.response.text or "").strip()
+        if e.response.status_code == 404 and body:
+            print_error(body)
+        else:
+            print_error(f"Server error {e.response.status_code} fetching {url}")
+        raise typer.Exit(1)
+    except httpx.ConnectError:
+        print_error(
+            f"Could not connect to {url}",
+            hint="Check the API base URL or your network.",
+        )
+        raise typer.Exit(1)
+    except httpx.RequestError as e:
+        print_error(
+            f"Network error fetching skills: {e}",
+            hint="Check the API base URL or your network.",
+        )
+        raise typer.Exit(1)
+
+
+skill_app = typer.Typer(
+    invoke_without_command=True,
+    help="Fetch published DataSpring skills (no authentication required)",
+)
+app.add_typer(skill_app, name="skill")
+
+
+@skill_app.callback(invoke_without_command=True)
+def _skill_callback(ctx: typer.Context):
+    """List all personas when invoked without a subcommand.
+
+    ``dataspring skill`` → index. ``dataspring skill <persona>`` and
+    ``dataspring skill <persona> instructions`` are explicit subcommands
+    below — keeps Typer in charge of dispatch instead of magic
+    positional strings.
+    """
+    if ctx.invoked_subcommand is not None:
+        return
+    body = _fetch_skill_markdown("/api/v1/skill")
+    # The server's index includes hints like
+    #     Fetch full body: `GET /api/v1/skill/<persona>/instructions`
+    # which is helpful for curl users but irritating for CLI users
+    # ("why are you telling me to curl?"). Rewrite to the CLI form so
+    # the next step the user takes is `dataspring skill instructions ...`.
+    import re
+
+    body = re.sub(
+        r"Fetch full body: `GET /api/v1/skill/([^/`]+)/instructions`",
+        r"Fetch full body: `dataspring skill instructions \1`",
+        body,
+    )
+    typer.echo(body)
+
+
+@skill_app.command("show")
+def skill_show(
+    persona: Annotated[
+        str,
+        typer.Argument(help="Skill persona name (e.g. author, consume)"),
+    ],
+):
+    """Print a persona's frontmatter."""
+    typer.echo(_fetch_skill_markdown(f"/api/v1/skill/{persona}"))
+
+
+@skill_app.command("instructions")
+def skill_instructions(
+    persona: Annotated[
+        str,
+        typer.Argument(help="Skill persona name (e.g. author, consume)"),
+    ],
+):
+    """Print a persona's full body (the SKILL.md content)."""
+    typer.echo(_fetch_skill_markdown(f"/api/v1/skill/{persona}/instructions"))
+
+
+# ============================================================================
+# The generated tree: every registry operation, by its key
+# ============================================================================
+#
+# `dataspring <key> --<field>` and `dataspring <key> <verb> --<field>`, from
+# cli/generated.py. Mounted last so `--help` lists the human layer first.
+
+mount_generated(app)
+
+
+if __name__ == "__main__":
+    app()