deepcell-cli 0.6.1__py3-none-any.whl

deepcell_cli/commands/query.py

@@ -0,0 +1,718 @@
+"""Query commands: query, cell-meta, relationships."""
+
+from __future__ import annotations
+
+import re
+
+import click
+
+from deepcell_cli.context import Ctx, pass_ctx
+from deepcell_cli.output import echo_warning, output, print_plain
+
+#: ``ITEM[CONTEXT]`` — the ref syntax formulas are written in, and therefore the
+#: first thing an agent types at the query prompt after reading a CalcDef. It
+#: matches no ``itemId``, so ``item_values`` answered ``[]`` with
+#: ``success: true`` — a green empty result that reads as "this row has no
+#: data" rather than "you passed the wrong shape" (#1197 item 1).
+#:
+#: Deliberately anchored and bracket-free on both sides: only a token that is
+#: *entirely* ``name[name]`` is rescued. An id that merely contains a bracket is
+#: passed through so the server answers with its own did-you-mean list — a
+#: fail-loud guard that over-triggers is worse than the silence it replaces.
+_FORMULA_REF_RE = re.compile(r"^([^\[\]\s]+)\[([^\[\]]+)\]$")
+
+
+def _reject_formula_ref(filename: str, ref: str | None) -> None:
+    """Raise if *ref* is written as a formula ref rather than a query argument."""
+    match = _FORMULA_REF_RE.match((ref or "").strip())
+    if not match:
+        return
+    item, context = match.group(1), match.group(2).strip()
+    raise click.UsageError(
+        f"unknown item '{ref}' — `{ref}` is formula ref syntax, not a query "
+        "argument. `query` takes ITEM and CONTEXT as separate positional "
+        "arguments:\n"
+        f"  One cell:      deepcell query {filename} {item} {context}\n"
+        f"  Every context: deepcell query {filename} {item}"
+    )
+
+
+#: Prefix marking a displayed number that is NOT the stored number.
+_ROUNDED = "~"
+
+
+def _format_value(value: object, data_type: str | None) -> str:
+    """Format a value for display based on data type.
+
+    Rounded output is marked with a leading ``~``. Monetary values print with
+    no decimals, so a stored 13.44 rendered as a bare ``13`` — for an audit
+    confirming a claimed figure that is a 3.3% discrepancy the reader cannot
+    see, and the only way to notice was to re-run with ``-f json``. The marker
+    is cheap, survives inside table cells, and says exactly one thing: ask for
+    JSON if you need the exact value. Values that round-trip exactly are
+    unmarked, so ``~`` never appears on a number that is what it says.
+    """
+    if not isinstance(value, (int, float)):
+        return str(value)
+    if isinstance(value, bool):  # bool is an int; formatting it as one is wrong
+        return str(value)
+
+    if data_type == "percentage":
+        shown, exact = f"{value * 100:.1f}%", value * 100
+    elif data_type == "monetary":
+        shown, exact = f"{value:,.0f}", value
+    elif data_type == "ratio":
+        shown, exact = f"{value:.1f}x", value
+    elif data_type in ("quantity", "count"):
+        shown, exact = f"{value:.1f}", value
+    else:
+        return str(value)
+
+    decimals = 0 if data_type == "monetary" else 1
+    # Compare against the same rounding the format applied, rather than
+    # re-parsing the formatted string (thousands separators, the % and x
+    # suffixes).
+    if abs(exact - round(exact, decimals)) > 1e-9:
+        return _ROUNDED + shown
+    return shown
+
+
+def _get_xml(ctx: Ctx, filename: str) -> str:
+    """Compatibility loader for legacy reasoning commands (see issue #1118)."""
+    slug = ctx.require_workspace()
+    file_data = ctx.client.get(f"/workspaces/{slug}/files/{filename}")
+    xml = file_data.get("content", "") if isinstance(file_data, dict) else ""
+    if not xml:
+        raise click.ClickException(f"File '{filename}' is empty or not found.")
+    return xml
+
+
+def _parse_cells(spec: str) -> list[tuple[str, str, str | None]]:
+    """Parse ``ITEM@CONTEXT[@STATUS],...`` into coordinate triples.
+
+    ``@`` rather than a second delimiter inside a comma list because item and
+    context ids are themselves free-form and both may contain ``_`` and ``-``;
+    ``@`` appears in neither (`ref:selector`). A token with no ``@`` is a
+    caller who meant the one-cell form, and is told so rather than being
+    read as an item with an empty context.
+    """
+    out: list[tuple[str, str, str | None]] = []
+    for raw in spec.split(","):
+        token = raw.strip()
+        if not token:
+            continue
+        parts = [p.strip() for p in token.split("@")]
+        if len(parts) < 2 or not parts[0] or not parts[1]:
+            raise click.UsageError(
+                f"--cells entry {token!r} is not ITEM@CONTEXT. Each entry "
+                "names one cell:\n"
+                "  --cells Revenue@FY2025E,EBIT@FY2025E\n"
+                "  --cells Revenue@FY2025E@actual   (pin one cell's status)\n"
+                "For every period of ONE item, use the positional form: "
+                "`query FILE Revenue`."
+            )
+        if len(parts) > 3:
+            raise click.UsageError(
+                f"--cells entry {token!r} has too many '@' segments — "
+                "ITEM@CONTEXT@STATUS is the most an entry carries."
+            )
+        out.append((parts[0], parts[1], parts[2] if len(parts) == 3 else None))
+    if not out:
+        raise click.UsageError("--cells was empty — list at least one ITEM@CONTEXT.")
+    return out
+
+
+def _query_cells(
+    ctx: Ctx,
+    slug: str,
+    filename: str,
+    spec: str,
+    *,
+    status_ref: str | None,
+    scenario_ref: str | None,
+    custom_dimensions: str | None,
+) -> None:
+    """Read every listed cell in one invocation.
+
+    Still one POST per cell — the server has no multi-cell read and inventing
+    one would be a second implementation of resolution to keep in step. What
+    this collapses is *rounds*, which is what the cost is: the eval corpus has
+    a run that verified twenty-one headline cells with twenty-one separate
+    commands, each one a full context round-trip for a ~150-byte answer.
+
+    A cell that fails does not abort the rest. Aborting would hand back one
+    error and no values, and the caller would pay another round for the cells
+    that were fine — so every cell is reported and the exit code is nonzero
+    if any of them failed.
+    """
+    from deepcell_cli.errors import APIError
+
+    coords = _parse_cells(spec)
+    for item, context, _ in coords:
+        _reject_formula_ref(filename, item)
+        _reject_formula_ref(filename, context)
+
+    rows: list[dict] = []
+    failed = 0
+    for item, context, per_cell_status in coords:
+        body: dict = {
+            "workspace_slug": slug,
+            "filename": filename,
+            "query_type": "value",
+            "item_ref": item,
+            "context_ref": context,
+        }
+        effective_status = per_cell_status or status_ref
+        if effective_status:
+            body["status_ref"] = effective_status
+        if scenario_ref:
+            body["scenario_ref"] = scenario_ref
+        if custom_dimensions:
+            body["custom_dimensions"] = custom_dimensions
+
+        label = f"{item}@{context}" + (f"@{per_cell_status}" if per_cell_status else "")
+        try:
+            data = ctx.client.post("/query", json=body)
+        except APIError as exc:
+            failed += 1
+            echo_warning(f"{label}: {exc}")
+            rows.append({"cell": label, "item_ref": item, "context_ref": context,
+                         "error": str(exc)})
+            continue
+
+        result = data.get("result") if isinstance(data, dict) else None
+        if isinstance(result, dict):
+            for w in result.get("warnings") or []:
+                echo_warning(f"{label}: {w}")
+            if result.get("error_kind"):
+                echo_warning(f"{label}: " + _format_cell_error_warning(result))
+        rows.append({"cell": label, "item_ref": item, "context_ref": context,
+                     "result": result})
+
+    if ctx.fmt == "plain":
+        lines = []
+        for r in rows:
+            if "error" in r:
+                lines.append(f"{r['cell']}: (error)")
+                continue
+            res = r.get("result")
+            if isinstance(res, dict) and res.get("value") is not None:
+                lines.append(
+                    f"{r['cell']}: "
+                    + _format_value(res.get("value"), res.get("data_type"))
+                )
+            else:
+                lines.append(f"{r['cell']}: (empty)")
+        print_plain("\n".join(lines))
+    else:
+        output(
+            {"query_type": "cells", "results": rows, "success": failed == 0},
+            ctx.fmt,
+        )
+
+    if failed:
+        raise click.exceptions.Exit(1)
+
+
+class _QueryCommand(click.Command):
+    """Lets `query` report extra positionals itself.
+
+    Click's own "Got unexpected extra arguments" never mentions that slot 3 is
+    STATUS_REF, so a caller listing periods positionally has already had one
+    silently read as a status. Allowing extra args here (they are rejected in the
+    callback) keeps that error ours *without* declaring a variadic argument —
+    which would publish a fake positional into the surface manifest and read, to
+    an agent, as license to pass any number of periods.
+    """
+
+    def parse_args(self, ctx: click.Context, args: list[str]) -> list[str]:
+        ctx.allow_extra_args = True
+        return super().parse_args(ctx, args)
+
+
+@click.command(cls=_QueryCommand)
+@click.argument("filename")
+@click.argument("item_ref", required=False)
+@click.argument("context_ref", required=False)
+@click.argument("status_ref", required=False)
+@click.option(
+    "--status", "status_opt", default=None,
+    help=(
+        "Status dimension — the same thing as the third positional. `edit`, "
+        "`defs add-calc` and `cell-meta` all spell it this way; accepted here "
+        "so the four agree."
+    ),
+)
+@click.option("--scenario", "scenario_ref", default=None, help="Scenario dimension (omit for default scenario).")
+@click.option("--custom-dimensions", "custom_dimensions", default=None,
+              help="Custom dimensions as 'dim:member;dim:member', e.g. 'geography:na'.")
+@click.option(
+    "--cells",
+    "cells_arg",
+    default=None,
+    help=(
+        "Read several cells that do NOT share a row, in one call: "
+        "'ITEM@CONTEXT,ITEM@CONTEXT,...' (add a third '@STATUS' segment per "
+        "cell to pin its status). This is the check-my-outputs form — a "
+        "comma-separated CONTEXT_REF only walks one item."
+    ),
+)
+@click.option("--sheet", "sheet_id", help="Render a full sheet as markdown table.")
+@click.option("--block", "block_id", help="Render a specific block within a sheet.")
+@click.option("--workspace", "workspace_slug", help="Override active workspace.")
+@pass_ctx
+def query(
+    ctx: Ctx,
+    filename: str,
+    item_ref: str | None,
+    context_ref: str | None,
+    status_ref: str | None,
+    status_opt: str | None,
+    scenario_ref: str | None,
+    custom_dimensions: str | None,
+    cells_arg: str | None,
+    sheet_id: str | None,
+    block_id: str | None,
+    workspace_slug: str | None,
+) -> None:
+    """Query a .deepcell file.
+
+    \b
+    Values are addressed by up to five dimensions:
+      ITEM_REF     what to query (e.g. Revenue, COGS)
+      CONTEXT_REF  time period (e.g. FY2025E, Q1_2024)
+      STATUS_REF   a statusRef the file declares — `describe` lists them;
+                   actual | projected are the common pair (optional, default: all)
+      --status     the same status dimension, as a flag
+      --scenario   scenario dimension (optional, default: default scenario)
+      --custom-dimensions  custom dimensions (optional, default: base cell)
+
+    \b
+    All values:     deepcell query model.deepcell Revenue
+    Single value:   deepcell query model.deepcell Revenue FY2025E projected
+    Some periods:   deepcell query model.deepcell Revenue FY2025E,FY2026E
+    Scenario cell:  deepcell query model.deepcell Revenue FY2025E --scenario bull
+    Scenario row:   deepcell query model.deepcell Revenue --scenario bull
+    Custom dim:     deepcell query model.deepcell Revenue FY2025E --custom-dimensions geography:na
+    Full sheet:     deepcell query model.deepcell --sheet income_statement
+    Sheet in world: deepcell query model.deepcell --sheet income_statement --scenario bull
+    Many cells:     deepcell query model.deepcell --cells EV@FY2026E,WACC@FY2026E,EV_Check@FY2026E
+
+    \b
+    Reading back what you built is a read, not a conversation: `--sheet` for a
+    whole block and `--cells` for scattered outputs each answer in ONE call.
+    Checking a dozen headline cells one command at a time costs a dozen
+    round-trips and tells you nothing extra.
+
+    \b
+    ITEM and CONTEXT are SEPARATE arguments. `Revenue[FY2025E]` is formula
+    syntax and is rejected here — it is not an item id.
+
+    Omitting --scenario returns the default-scenario value; omitting
+    --custom-dimensions returns the base (no-dimension) cell. On --sheet,
+    --scenario names the world the WHOLE sheet is read in and answers with
+    the numbers the grid shows at that scenario; --custom-dimensions has no
+    meaning there (a sheet renders every member) and is rejected. For
+    scenario analysis details see `deepcell guide revise/scenarios`. To view
+    in the browser instead, see `deepcell guide present/deliver`.
+    """
+    slug = workspace_slug or ctx.require_workspace()
+    # `query` took status positionally while `edit`, `defs add-calc` and
+    # `cell-meta` took `--status`, so the flag fell through to Click's generic
+    # "No such option" — an answer that says the dimension is unavailable
+    # rather than that it is spelled differently here.
+    if status_opt is not None:
+        if status_ref is not None and status_ref != status_opt:
+            raise click.UsageError(
+                f"--status {status_opt!r} contradicts the third positional "
+                f"argument {status_ref!r}. They are the same dimension; pass "
+                f"one."
+            )
+        status_ref = status_opt
+    extra_args = tuple(click.get_current_context().args)
+    if extra_args:
+        # Periods listed positionally: slot 3 is STATUS_REF, so the first extra
+        # was already misread as a status before we got here. Name both working
+        # forms rather than leaving the caller to re-derive them.
+        listed = [a for a in (context_ref, status_ref, *extra_args) if a]
+        raise click.UsageError(
+            "Too many positional arguments — the third slot is STATUS_REF, not "
+            "another period.\n"
+            f"  Every period:  deepcell query {filename} {item_ref}\n"
+            f"  Some periods:  deepcell query {filename} {item_ref} "
+            + ",".join(listed)
+            + "\n"
+            f"  One cell:      deepcell query {filename} {item_ref} {listed[0]} "
+            "[STATUS_REF]"
+        )
+    _reject_formula_ref(filename, item_ref)
+    _reject_formula_ref(filename, context_ref)
+    if block_id and not sheet_id:
+        raise click.UsageError("--block requires --sheet.")
+    if sheet_id and (item_ref or context_ref or status_ref):
+        raise click.UsageError(
+            "Use either positional item/context/status or --sheet/--block, "
+            "not both."
+        )
+    if cells_arg is not None:
+        # --status / --scenario / --custom-dimensions stay legal here: they
+        # narrow every listed cell the same way, which is what a read-back of
+        # one scenario's headline numbers wants. Only the coordinates conflict.
+        if item_ref or context_ref or sheet_id or block_id:
+            raise click.UsageError(
+                "--cells carries its own coordinates. Use either "
+                "ITEM_REF/CONTEXT_REF positionals, or --sheet/--block, or "
+                "--cells — not two of them."
+            )
+        _query_cells(
+            ctx,
+            slug,
+            filename,
+            cells_arg,
+            status_ref=status_ref,
+            scenario_ref=scenario_ref,
+            custom_dimensions=custom_dimensions,
+        )
+        return
+    # --scenario is the exception: it names the WORLD the sheet is read in,
+    # not a cell coordinate, so it composes with --sheet. --custom-dimensions
+    # does not — a sheet renders every member, so there is no slice to name.
+    if sheet_id and custom_dimensions:
+        raise click.UsageError(
+            "--custom-dimensions does not apply to --sheet: a sheet renders "
+            "every dimension member. Drop it, or query a cell with "
+            "ITEM_REF CONTEXT_REF."
+        )
+    # --scenario / --custom-dimensions name a cell coordinate, so they need an
+    # ITEM_REF — but NOT a CONTEXT_REF (#1197 item 4). Reading one scenario's
+    # whole trajectory used to cost one call per period. A --sheet read has
+    # already been settled above: there the scenario names the world, not a
+    # cell, and no ITEM_REF exists to require.
+    if (scenario_ref or custom_dimensions) and not item_ref and not sheet_id:
+        raise click.UsageError(
+            "--scenario / --custom-dimensions require an ITEM_REF (add a "
+            "CONTEXT_REF for a single cell, omit it for every context)."
+        )
+
+    # A comma-separated CONTEXT_REF reads a subset of periods. It has to be a
+    # list inside one token rather than several positionals, because slot 3 is
+    # STATUS_REF and `projected` must stay distinguishable from a period id.
+    contexts = [c.strip() for c in (context_ref or "").split(",") if c.strip()]
+    if item_ref and len(contexts) > 1:
+        rows = []
+        for one in contexts:
+            body = {
+                "workspace_slug": slug,
+                "filename": filename,
+                "query_type": "value",
+                "item_ref": item_ref,
+                "context_ref": one,
+            }
+            if status_ref:
+                body["status_ref"] = status_ref
+            if scenario_ref:
+                body["scenario_ref"] = scenario_ref
+            if custom_dimensions:
+                body["custom_dimensions"] = custom_dimensions
+            data = ctx.client.post("/query", json=body)
+            result = data.get("result") if isinstance(data, dict) else None
+            if isinstance(result, dict):
+                for w in result.get("warnings") or []:
+                    echo_warning(f"{one}: {w}")
+            rows.append({"context_ref": one, "result": result})
+        if ctx.fmt == "plain":
+            print_plain("\n".join(
+                f"{r['context_ref']}: " + (
+                    _format_value(
+                        (r["result"] or {}).get("value", ""),
+                        (r["result"] or {}).get("data_type"),
+                    )
+                    if isinstance(r["result"], dict)
+                    and r["result"].get("value") is not None
+                    else "(empty)"
+                )
+                for r in rows
+            ))
+        else:
+            output({"query_type": "value", "results": rows, "success": True}, ctx.fmt)
+        return
+    if contexts:
+        context_ref = contexts[0]
+
+    if sheet_id:
+        # Sheet query
+        body: dict = {
+            "workspace_slug": slug,
+            "filename": filename,
+            "query_type": "sheet",
+            "sheet_id": sheet_id,
+        }
+        if block_id:
+            body["block_id"] = block_id
+        # The world the sheet is read in. Same flag, same meaning as on a cell
+        # read; the server names it to the builder rather than baking it, so
+        # this answers with the numbers the grid shows at that scenario.
+        if scenario_ref:
+            body["scenario_ref"] = scenario_ref
+    elif item_ref and context_ref:
+        # Value query
+        body = {
+            "workspace_slug": slug,
+            "filename": filename,
+            "query_type": "value",
+            "item_ref": item_ref,
+            "context_ref": context_ref,
+        }
+        if status_ref:
+            body["status_ref"] = status_ref
+        if scenario_ref:
+            body["scenario_ref"] = scenario_ref
+        if custom_dimensions:
+            body["custom_dimensions"] = custom_dimensions
+    elif item_ref:
+        # Item values query (all contexts)
+        body = {
+            "workspace_slug": slug,
+            "filename": filename,
+            "query_type": "item_values",
+            "item_ref": item_ref,
+        }
+        if status_ref:
+            body["status_ref"] = status_ref
+        # The scenario / custom-dimension axes narrow the row the same way they
+        # narrow a single cell (#1197 item 4).
+        if scenario_ref:
+            body["scenario_ref"] = scenario_ref
+        if custom_dimensions:
+            body["custom_dimensions"] = custom_dimensions
+    else:
+        raise click.UsageError(
+            "Provide ITEM_REF for item query, ITEM_REF CONTEXT_REF for value query, or --sheet for sheet query."
+        )
+
+    data = ctx.client.post("/query", json=body)
+
+    # Server-side read warnings (e.g. a value resolved from an orphan cell
+    # tagged with an undefined scenario id, #1149) go to stderr so the value
+    # on stdout never reads as unconditionally clean.
+    if isinstance(data, dict) and isinstance(data.get("result"), dict):
+        for w in data["result"].get("warnings") or []:
+            echo_warning(str(w))
+
+        # #1272 step (iii). `query` is the surface where this matters most:
+        # the answer is a bare number, so a formula that collapsed to 0
+        # through #REF! or #DIV/0 prints as `0` and reads as a real zero.
+        # Emitted here, before every formatting branch below returns early,
+        # so no output shape can swallow it.
+        if data["result"].get("error_kind"):
+            echo_warning(_format_cell_error_warning(data["result"]))
+
+    # For sheet queries the result is usually markdown — print as plain
+    if sheet_id and isinstance(data, dict):
+        result = data.get("result", data)
+        if isinstance(result, str):
+            print_plain(result)
+            return
+
+    # For item_values queries, truncate and format the result list
+    if body.get("query_type") == "item_values" and isinstance(data, dict):
+        result = data.get("result", [])
+        if isinstance(result, list):
+            max_display = 20
+            total = len(result)
+            truncated = result[:max_display]
+            if ctx.fmt == "plain":
+                # Tag the status when present — the same context can carry a
+                # value per status, and untagged duplicate lines are unreadable.
+                lines = [
+                    (
+                        f"{r.get('context_ref', '')}"
+                        + (f" [{r['status_ref']}]" if r.get("status_ref") else "")
+                        + f": {_format_value(r.get('value', ''), r.get('data_type'))}"
+                    )
+                    for r in truncated
+                ]
+                if total > max_display:
+                    lines.append(f"... and {total - max_display} more")
+                print_plain("\n".join(lines))
+            else:
+                if total > max_display:
+                    data["result"] = truncated
+                    data["truncated"] = total - max_display
+                output(data, ctx.fmt)
+            return
+
+    # Value query that resolved to no single value: the cell is empty, or it is
+    # populated under multiple statuses (no single status resolves). Surface the
+    # per-status breakdown for plain output rather than a raw JSON blob.
+    if (
+        body.get("query_type") == "value"
+        and ctx.fmt == "plain"
+        and isinstance(data, dict)
+    ):
+        result = data.get("result")
+        if isinstance(result, dict) and result.get("value") is None:
+            vbs = result.get("values_by_status") or []
+            if vbs:
+                dtype = result.get("data_type")
+                lines = (
+                    ["(value differs by status — specify a status)"]
+                    if len(vbs) > 1
+                    else []
+                )
+                lines += [
+                    f"{e.get('status_ref', '')}: {_format_value(e.get('value', ''), dtype)}"
+                    for e in vbs
+                ]
+                print_plain("\n".join(lines))
+            else:
+                print_plain("(empty)")
+            return
+
+    # Format percentage values for plain output on single-value queries
+    if ctx.fmt == "plain" and isinstance(data, dict):
+        result = data.get("result", data)
+        if isinstance(result, dict) and result.get("data_type") == "percentage":
+            val = result.get("value")
+            if isinstance(val, (int, float)):
+                print_plain(_format_value(val, "percentage"))
+                return
+
+    output(data, ctx.fmt)
+
+
+@click.command()
+@click.argument("filename")
+@click.argument("item_ref_pos", metavar="[ITEM_REF]", required=False)
+@click.argument("context_ref_pos", metavar="[CONTEXT_REF]", required=False)
+@click.option("--item", "item_opt", default=None,
+              help="Item ref (alternative to the ITEM_REF positional).")
+@click.option("--context", "context_opt", default=None,
+              help="Context ref (alternative to the CONTEXT_REF positional).")
+@click.option(
+    "--status",
+    "status_ref",
+    default=None,
+    help=(
+        "Status reference (e.g. 'actual'). A CONSTRAINT, not a hint: the read "
+        "may answer from that bucket or the untagged one, never from a third. "
+        "Omit to let the document decide which status answers."
+    ),
+)
+@click.option("--scenario", "scenario_ref", default=None, help="Scenario dimension (omit for the base cell).")
+@click.option("--custom-dimensions", "custom_dimensions", default=None,
+              help="Custom dimensions as 'dim:member;dim:member', e.g. 'geography:na'.")
+@pass_ctx
+def cell_meta(
+    ctx: Ctx,
+    filename: str,
+    item_ref_pos: str | None,
+    context_ref_pos: str | None,
+    item_opt: str | None,
+    context_opt: str | None,
+    status_ref: str | None,
+    scenario_ref: str | None,
+    custom_dimensions: str | None,
+) -> None:
+    """Show metadata for a single cell (formula, dependencies, data source).
+
+    The coordinate can be positional (`cell-meta FILE ITEM CONTEXT`) or
+    flags (`--item` / `--context`) — most other commands take flags, and the
+    required-positional-only form was a measurable trap (eval U5).
+
+    Returns the cell's formula (if calculated), dependency graph, and
+    <Source> provenance (if the value was imported from an external source).
+    Run `deepcell guide generate/values` for more on data provenance.
+
+    Also returns which status answered: `status_ref` is the bucket the read
+    resolved to, and `status_alternatives` lists EVERY bucket that cell holds,
+    including the one that answered and including the untagged bucket as null.
+    More than one entry means the cell carries more than one number and you are
+    seeing one of them — see `deepcell guide verify/query-back`.
+    """
+    if item_ref_pos and item_opt:
+        raise click.UsageError("Pass ITEM_REF positionally or via --item, not both.")
+    if context_ref_pos and context_opt:
+        raise click.UsageError(
+            "Pass CONTEXT_REF positionally or via --context, not both."
+        )
+    item_ref = item_ref_pos or item_opt
+    context_ref = context_ref_pos or context_opt
+    if not item_ref or not context_ref:
+        raise click.UsageError(
+            "A complete cell coordinate is required: ITEM_REF and CONTEXT_REF "
+            "(positional, or --item/--context)."
+        )
+    slug = ctx.require_workspace()
+    body: dict = {
+        "workspace_slug": slug,
+        "source_filename": filename,
+        "item_ref": item_ref,
+        "context_ref": context_ref,
+    }
+    if status_ref:
+        body["status_ref"] = status_ref
+    if scenario_ref:
+        body["scenario_ref"] = scenario_ref
+    if custom_dimensions:
+        body["custom_dimensions"] = custom_dimensions
+
+    data = ctx.client.post("/cell-meta", json=body)
+    output(data, ctx.fmt)
+
+    # #1272 step (iii) — a typed formula error is IN the payload above, but a
+    # `#REF!` inside a one-line JSON blob is exactly the thing that gets
+    # skimmed past, and a cell that collapsed to 0 through a broken reference
+    # reads as a cell nobody filled in. On stderr, so stdout stays the machine
+    # contract. A warning and not an exit code, matching `describe`: the
+    # document still opens and renders.
+    if isinstance(data, dict) and data.get("error_kind"):
+        echo_warning(_format_cell_error_warning(data))
+
+
+def _format_cell_error_warning(data: dict) -> str:
+    """Human line for a cell's typed formula error (#1272 step iii).
+
+    Names the undefined ids behind a `#REF!` when the server reported them:
+    the kind alone tells the reader something is broken, `missing_refs` tells
+    them *which* reference, which is the difference between a fix and a hunt.
+    """
+    kind = data.get("error_kind")
+    missing = [r for r in (data.get("missing_refs") or []) if r]
+    lines = [
+        f"this cell did not compute — {kind}. Its value is not a number you "
+        "can rely on."
+    ]
+    if missing:
+        names = ", ".join(missing)
+        plural = "" if len(missing) == 1 else "s"
+        lines.append(
+            f"         Undefined item reference{plural}: {names}. Define "
+            "the item, or fix the"
+        )
+        lines.append("         formula to name one that exists.")
+    return "\n".join(lines)
+
+
+@click.command()
+@click.argument("filename")
+@click.option(
+    "--type",
+    "graph_type",
+    default="unified",
+    type=click.Choice(["items", "dependencies", "blocks", "business", "unified"]),
+    help="Graph type. 'business' is the Item-centric Relationships workspace.",
+)
+@pass_ctx
+def relationships(ctx: Ctx, filename: str, graph_type: str) -> None:
+    """Show the relationship graph of a .deepcell file."""
+    slug = ctx.require_workspace()
+    data = ctx.client.post(
+        "/relationships",
+        json={
+            "workspace_slug": slug,
+            "source_filename": filename,
+            "graph_type": graph_type,
+        },
+    )
+    output(data, ctx.fmt)