xmemcli 0.0.1__py3-none-any.whl

xmemcli/cli.py

@@ -0,0 +1,1826 @@
+"""``xmem`` — single-command CLI for the xmemory HTTP API.
+
+This file is the CLI entry point. It deliberately uses only the standard
+library so the demo runs anywhere a Python 3.12+ interpreter exists without
+``pip install``. The interesting structural decision is that **commands do
+not format output themselves** — every subcommand builds a
+:class:`_output.CliOutput` and returns ``(output, exit_code)``. The
+``main`` dispatch then emits via :func:`_output.emit`, which picks
+between strict JSON (machine consumption) and a one-line human summary
+(interactive terminal) per the rules documented in :mod:`_output`.
+
+Endpoints exercised (under ``$XMEM_API_URL`` unless noted; default
+``https://api.xmemory.ai``):
+
+- ``POST /instances/{instance_id}/write``                     — sync write
+- ``POST /instances/{instance_id}/write_async``               — queue an async write
+- ``POST /instances/{instance_id}/write_status``              — poll an async write
+- ``POST /instances/{instance_id}/read``                      — read
+- ``GET  /api-keys``                                          — list your keys
+- ``GET  /whoami``                                            — whose key / session is this?
+- ``GET  /clusters`` · ``GET /clusters/{id}/quotas`` ·
+  ``GET /clusters/{id}/quotas/{quota_id}`` — ``quota get``
+- ``POST /cli/token`` (via ``cli/_login.py`` during ``auth login``) — PKCE key redeem
+
+The CLI exposes only the parameters the API already supports.
+
+Curated output
+--------------
+
+The CLI does NOT echo the raw API payload. Every subcommand reduces the
+server response to the fields the user actually asked for (see the
+``_curate_*`` helpers): a read returns the answer / rows, a write returns
+its ``write_id``, a status poll returns ``write_id`` + ``write_status``.
+Server internals — ``sql``, ``diff_plan``, the raw ``cleaned_objects``
+tree, ``pending_suggestions`` — are never emitted, in either output mode.
+``--verbose`` adds *extra* (still non-internal) context: ``trace_id`` and
+``console_url``, when the server provided them.
+
+Sync vs async writes
+--------------------
+
+``xmem write "<text>"`` is **synchronous** by default — the CLI blocks on
+``POST …/write`` until the server has finished extraction and applied the
+diff. Use ``--no-wait`` to queue the work via ``POST …/write_async`` and
+get back a ``write_id`` immediately. Poll that id with
+``xmemcli write-status <write_id>``; the command accepts **one or
+more** ids and waits for *all* of them to reach a terminal state
+(``completed`` / ``failed`` / ``not_found``) before printing one JSON
+array. That's the bulk-status capability — a single round of CLI work
+covers three concurrently-queued writes.
+
+The choice between sync and async matters for the operator:
+
+- Synchronous writes are simpler — one round-trip, the server finishes
+  extraction before responding, and the CLI exits with a meaningful
+  status. Best for one-off facts.
+- Asynchronous writes return in milliseconds and let the server batch
+  extraction work in the queue worker. Best when you're pushing many
+  facts in a short window — e.g. seeding an instance from a script —
+  because the CLI doesn't have to hold a connection open per fact.
+
+Both paths are covered by the Harness-First Test
+([`HARNESS-FIRST-TEST.md`](HARNESS-FIRST-TEST.md)) and unit tests under `tests/`.
+"""
+
+from __future__ import annotations
+
+import argparse
+import concurrent.futures
+import json
+import os
+import sys
+import time
+import urllib.error
+import urllib.request
+import webbrowser
+from pathlib import Path
+from typing import Any
+from urllib.parse import urlsplit
+
+from . import _help  # noqa: E402  (sibling-script import)
+from . import _login  # noqa: E402  (sibling-script import)
+from ._envelope import batch_envelope_error  # noqa: E402  (sibling-script import)
+from ._output import CliOutput, OutputKind, emit, make_error, stdout_is_tty  # noqa: E402  (sibling-script import)
+from ._rc import (  # noqa: E402  (sibling-script import)
+    ENV_RC_DIR,
+    RC_FILENAME,
+    RcError,
+    RcRecord,
+    find_rc,
+    gitignore_warning,
+    load_rc,
+    remove_rc,
+    resolve_rc,
+    write_rc,
+)
+from ._version import CLI_NAME, __version__  # noqa: E402  (sibling-script import)
+
+# Single source of truth for env var names. Mirrored in cli/README.md.
+ENV_API_KEY = "XMEM_API_KEY"
+ENV_INSTANCE_ID = "XMEM_INSTANCE_ID"
+ENV_API_URL = "XMEM_API_URL"
+ENV_CLUSTER_ID = "XMEM_CLUSTER_ID"
+ENV_CONSOLE_URL = "XMEM_CONSOLE_URL"
+DEFAULT_API_URL = "https://api.xmemory.ai"
+
+# Warn on stderr when a quota window is at or above this fraction used.
+_QUOTA_WARN_RATIO = 0.9
+
+# Exit codes. Distinguishing "no key" from "rejected key" from "request
+# failed" lets the Playwright authorisation scenario assert specifically on
+# EXIT_AUTH_ERROR instead of "any non-zero".
+EXIT_OK = 0
+EXIT_USAGE = 2
+EXIT_HTTP_ERROR = 3
+EXIT_AUTH_ERROR = 4
+EXIT_TIMEOUT = 5
+# Distinct exit code for quota-exceeded responses so callers can branch on
+# "wait / upgrade" instead of the generic EXIT_HTTP_ERROR. Carries the
+# ``QuotaExceededKind`` discriminator on the wire body so the printed
+# message can match (TRIAL ENDED / DAILY QUOTA / MONTHLY QUOTA).
+EXIT_QUOTA_EXCEEDED = 6
+# Conventional shell exit for SIGINT (128 + 2) — no stack trace, not a usage error.
+EXIT_INTERRUPTED = 130
+
+
+def _eprint(message: str) -> None:
+    sys.stderr.write(f"{message}\n")
+
+
+def _note_cli_warning(args: argparse.Namespace, message: str) -> None:
+    """Record a warning for stderr and, in machine JSON mode, the stdout document."""
+    _eprint(f"warning: {message}")
+    warnings = getattr(args, "_cli_warnings", None)
+    if warnings is None:
+        warnings = []
+        setattr(args, "_cli_warnings", warnings)
+    warnings.append(message)
+
+
+def _with_cli_warnings(output: CliOutput, args: argparse.Namespace, *, force_json: bool) -> CliOutput:
+    if not force_json:
+        return output
+    warnings = getattr(args, "_cli_warnings", None)
+    if not warnings or not isinstance(output.payload, dict) or output.kind == OutputKind.ERROR:
+        return output
+    payload = dict(output.payload)
+    existing = payload.get("warnings")
+    if isinstance(existing, list):
+        payload["warnings"] = [*existing, *warnings]
+    else:
+        payload["warnings"] = list(warnings)
+    return CliOutput(output.kind, payload)
+
+
+# ── HTTP helper ────────────────────────────────────────────────────────────
+
+
+class ApiError(Exception):
+    """An HTTP error response from the API, carrying status + raw body."""
+
+    def __init__(self, status: int, body: str, message: str):
+        super().__init__(message)
+        self.status = status
+        self.body = body
+
+
+# Human-friendly copy for each ``QuotaExceededKind`` the API may surface
+# via ``ApiError.body``'s structured ``details.kind`` field. Mirrors the
+# console SPA's ``QUOTA_KIND_LABELS``.
+_QUOTA_KIND_MESSAGES: dict[str, str] = {
+    "trial_exceeded": "Your trial token cap is exhausted. Upgrade your plan to continue using xmemory.",
+    "daily_quota_exceeded": (
+        "Your daily quota is exhausted. Retry once the daily window resets, or request a higher limit."
+    ),
+    "monthly_quota_exceeded": (
+        "Your monthly quota is exhausted. Wait until the next monthly window, or request a higher limit."
+    ),
+}
+
+
+# Deliberately mirrors ``xmemory/exceptions.py::quota_exceeded_from_body`` (same
+# ``_QUOTA_ERROR_CODES`` set and ``errors[0] -> details.kind`` walk). The two cannot
+# share one helper: this CLI is stdlib-only and standalone — it runs without a
+# ``pip install`` of the ``xmemory`` library (see the module docstring) — and the
+# published library cannot depend on the CLI. Keep this walk in sync by hand if the
+# error-envelope shape ever changes.
+_QUOTA_ERROR_CODES = frozenset({"QUOTA_EXCEEDED", "TRIAL_ENDED"})
+
+
+def _quota_exceeded_message(exc: ApiError) -> str | None:
+    """If the API responded with a quota-class error, project the
+    structured body into a human-friendly message. Returns ``None`` for
+    any other error so the caller falls through to the generic HTTP path.
+
+    Two server-side sources land here:
+
+    * ``QUOTA_EXCEEDED`` carries a ``details.kind`` discriminator
+      (``trial_exceeded`` / ``daily_quota_exceeded`` /
+      ``monthly_quota_exceeded``); we look up the kind-specific copy.
+    * ``TRIAL_ENDED`` is emitted by the paywall middleware before the
+      endpoint runs, with no ``details`` payload. Fall back to the
+      server-supplied ``errors[0].message`` in that case so the caller
+      sees the actual reason rather than a generic stub.
+    """
+    try:
+        body = json.loads(exc.body)
+    except (json.JSONDecodeError, TypeError):
+        return None
+    errors = body.get("errors") if isinstance(body, dict) else None
+    if not isinstance(errors, list) or not errors:
+        return None
+    first = errors[0]
+    if not isinstance(first, dict) or first.get("code") not in _QUOTA_ERROR_CODES:
+        return None
+    details = first.get("details") if isinstance(first.get("details"), dict) else {}
+    kind = details.get("kind") if isinstance(details, dict) else None
+    if kind is None:
+        # ``TRIAL_ENDED`` (paywall) and any future quota code that opts
+        # out of details: surface the server message verbatim.
+        server_message = first.get("message")
+        return str(server_message) if isinstance(server_message, str) and server_message else "Quota exceeded."
+    base = _QUOTA_KIND_MESSAGES.get(str(kind), "Quota exceeded.")
+    retry_after = details.get("retry_after_seconds") if isinstance(details, dict) else None
+    if isinstance(retry_after, int) and retry_after > 0:
+        return f"{base} (retry_after: {retry_after}s)"
+    return base
+
+
+def _post(url: str, body: dict[str, Any], api_key: str, timeout_s: float = 60.0) -> dict[str, Any]:
+    data = json.dumps(body).encode("utf-8")
+    req = urllib.request.Request(
+        url,
+        data=data,
+        method="POST",
+        headers={
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+            "Authorization": f"Bearer {api_key}",
+        },
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=timeout_s) as resp:
+            raw = resp.read().decode("utf-8")
+    except urllib.error.HTTPError as e:
+        raw = e.read().decode("utf-8", errors="replace")
+        raise ApiError(e.code, raw, f"HTTP {e.code}: {raw[:200]}") from None
+    except urllib.error.URLError as e:
+        raise ApiError(0, "", f"Network error: {e.reason}") from None
+    try:
+        return json.loads(raw)
+    except json.JSONDecodeError:
+        raise ApiError(200, raw, f"API returned non-JSON body: {raw[:200]}") from None
+
+
+def _put(url: str, body: dict[str, Any], api_key: str, timeout_s: float = 60.0) -> dict[str, Any]:
+    data = json.dumps(body).encode("utf-8")
+    req = urllib.request.Request(
+        url,
+        data=data,
+        method="PUT",
+        headers={
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+            "Authorization": f"Bearer {api_key}",
+        },
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=timeout_s) as resp:
+            raw = resp.read().decode("utf-8")
+    except urllib.error.HTTPError as e:
+        raw = e.read().decode("utf-8", errors="replace")
+        raise ApiError(e.code, raw, f"HTTP {e.code}: {raw[:200]}") from None
+    except urllib.error.URLError as e:
+        raise ApiError(0, "", f"Network error: {e.reason}") from None
+    try:
+        return json.loads(raw)
+    except json.JSONDecodeError:
+        raise ApiError(200, raw, f"API returned non-JSON body: {raw[:200]}") from None
+
+
+def _delete(url: str, api_key: str, timeout_s: float = 60.0) -> dict[str, Any]:
+    req = urllib.request.Request(
+        url,
+        method="DELETE",
+        headers={"Accept": "application/json", "Authorization": f"Bearer {api_key}"},
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=timeout_s) as resp:
+            raw = resp.read().decode("utf-8")
+    except urllib.error.HTTPError as e:
+        raw = e.read().decode("utf-8", errors="replace")
+        raise ApiError(e.code, raw, f"HTTP {e.code}: {raw[:200]}") from None
+    except urllib.error.URLError as e:
+        raise ApiError(0, "", f"Network error: {e.reason}") from None
+    if not raw.strip():
+        return {}
+    try:
+        return json.loads(raw)
+    except json.JSONDecodeError:
+        raise ApiError(200, raw, f"API returned non-JSON body: {raw[:200]}") from None
+
+
+def _get(url: str, api_key: str, timeout_s: float = 30.0) -> dict[str, Any]:
+    req = urllib.request.Request(
+        url,
+        method="GET",
+        headers={"Accept": "application/json", "Authorization": f"Bearer {api_key}"},
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=timeout_s) as resp:
+            raw = resp.read().decode("utf-8")
+    except urllib.error.HTTPError as e:
+        raw = e.read().decode("utf-8", errors="replace")
+        raise ApiError(e.code, raw, f"HTTP {e.code}: {raw[:200]}") from None
+    except urllib.error.URLError as e:
+        raise ApiError(0, "", f"Network error: {e.reason}") from None
+    try:
+        return json.loads(raw)
+    except json.JSONDecodeError:
+        raise ApiError(200, raw, f"API returned non-JSON body: {raw[:200]}") from None
+
+
+def _console_url_for_args(args: argparse.Namespace) -> str | None:
+    explicit = getattr(args, "console_url", None) or os.environ.get(ENV_CONSOLE_URL)
+    return explicit.strip() if isinstance(explicit, str) and explicit.strip() else None
+
+
+def _fetch_whoami(base: str, api_key: str, *, console_url: str | None = None) -> dict[str, Any]:
+    """``GET /whoami`` with bearer auth, trying Console proxy URLs before direct API origins."""
+    last_err: ApiError | None = None
+    for url in _login.whoami_urls(api_url=base, console_url=console_url):
+        try:
+            return _get(url, api_key)
+        except ApiError as e:
+            last_err = e
+    if last_err is not None:
+        raise last_err
+    raise ApiError(0, "", "whoami unreachable")
+
+
+def _unwrap_items(envelope: dict[str, Any]) -> dict[str, Any]:
+    """Unwrap the API's ``{"items":[T], "errors":[]}`` envelope.
+
+    Every endpoint we call returns exactly one item on success. We unwrap
+    in the CLI so the JSON the user sees is the actual payload, not the
+    batch wrapper. Rejects a non-empty ``errors`` array before reading
+    ``items`` — even on HTTP 200.
+    """
+    err = batch_envelope_error(envelope)
+    if err:
+        raise ApiError(200, json.dumps(envelope), err)
+    if isinstance(envelope, dict) and isinstance(envelope.get("items"), list):
+        items = envelope["items"]
+        if items:
+            return items[0] if isinstance(items[0], dict) else {"value": items[0]}
+    return envelope
+
+
+# ── Output curation ────────────────────────────────────────────────────────
+# The CLI never echoes the raw API payload. Each ``_curate_*`` helper keeps
+# only the fields the user asked for; ``--verbose`` adds the extra (but still
+# non-internal) context below. Internals — ``sql``, ``diff_plan``, the raw
+# ``cleaned_objects`` tree, ``pending_suggestions`` — are dropped in BOTH
+# output modes, verbose or not.
+
+#: Fields ``--verbose`` is allowed to surface when the server sent them.
+_VERBOSE_EXTRAS = ("trace_id", "console_url")
+
+
+def _add_verbose_extras(curated: dict[str, Any], item: dict[str, Any], verbose: bool) -> dict[str, Any]:
+    """Copy the whitelisted ``--verbose`` fields from ``item`` into ``curated``."""
+    if verbose:
+        for key in _VERBOSE_EXTRAS:
+            value = item.get(key)
+            if value is not None and key not in curated:
+                curated[key] = value
+    return curated
+
+
+def _summarize_extracted(item: dict[str, Any]) -> list[str]:
+    """Reduce the write response's ``cleaned_objects`` tree to ``Type(name)`` tags.
+
+    The full tree is an internal — what the user cares about is *what got
+    stored*, so we keep a compact summary and drop the rest.
+    """
+    objs = ((item.get("cleaned_objects") or {}).get("objects")) or []
+    parts: list[str] = []
+    for obj in objs:
+        if not isinstance(obj, dict):
+            continue
+        kind = obj.get("type") or obj.get("kind") or "?"
+        name = obj.get("name") or obj.get("first_name") or obj.get("title") or "…"
+        parts.append(f"{kind}({name})")
+    return parts
+
+
+def _curate_write(item: dict[str, Any], *, sync: bool, verbose: bool) -> dict[str, Any]:
+    curated: dict[str, Any] = {"write_id": item.get("write_id")}
+    if sync:
+        curated["extracted"] = _summarize_extracted(item)
+    return _add_verbose_extras(curated, item, verbose)
+
+
+def _curate_write_status(item: dict[str, Any], verbose: bool) -> dict[str, Any]:
+    curated: dict[str, Any] = {
+        "write_id": item.get("write_id"),
+        "write_status": item.get("write_status", "unknown"),
+    }
+    # Carry the failure / bookkeeping fields only when they say something.
+    for key in ("error_detail", "completed_at", "error", "http_status", "timed_out"):
+        value = item.get(key)
+        if value is not None:
+            curated[key] = value
+    return _add_verbose_extras(curated, item, verbose)
+
+
+def _extract_single_answer(reader_result: dict[str, Any]) -> str | None:
+    """Pull the most likely "headline" string out of a ReaderResult.
+
+    The reader can put the answer in any of several spots depending on the
+    code path that produced it. We probe the most common ones in order and
+    return the first non-empty string. None ⇒ caller falls back to the
+    reader_result subtree rather than inventing an answer.
+    """
+    for key in ("answer", "text", "summary"):
+        v = reader_result.get(key)
+        if isinstance(v, str) and v.strip():
+            return v
+    single = reader_result.get("single_answer")
+    if isinstance(single, dict):
+        v = single.get("text") or single.get("answer")
+        if isinstance(v, str) and v.strip():
+            return v
+    elif isinstance(single, str) and single.strip():
+        return single
+    return None
+
+
+def _curate_read(item: dict[str, Any], *, read_mode: str, verbose: bool) -> dict[str, Any]:
+    rr = item.get("reader_result")
+    rr_dict = rr if isinstance(rr, dict) else {}
+    if read_mode == "single":
+        answer = _extract_single_answer(rr_dict)
+        # No extractable answer string → emit the reader_result subtree so
+        # the user still sees something truthful rather than `answer: null`.
+        curated = {"answer": answer} if answer is not None else dict(rr_dict)
+    else:
+        # raw / xresponse: the reader_result IS the thing the user asked for.
+        curated = dict(rr_dict)
+    return _add_verbose_extras(curated, item, verbose)
+
+
+#: Per-key fields ``xmem keys list`` shows. The raw DTO additionally carries
+#: ids (key/user/role/cluster) that are internals at the CLI surface.
+_KEY_LIST_FIELDS = ("name", "key_prefix", "is_active")
+
+
+def _curate_key(item: dict[str, Any], verbose: bool) -> dict[str, Any]:
+    if verbose:
+        return item
+    return {k: item[k] for k in _KEY_LIST_FIELDS if k in item}
+
+
+# ── Argument resolution ────────────────────────────────────────────────────
+
+
+class UsageError(Exception):
+    """A pre-flight argument / credential error raised before a subcommand can
+    build its own ``CliOutput`` — a missing API key, a malformed ``.xmemrc.json``,
+    an unset instance id, or the localhost-key-at-prod guard.
+
+    It carries an ``OutputKind.ERROR`` payload so ``main`` renders it through
+    :func:`emit` like any other result. That keeps the machine-mode invariant:
+    a failed command still emits **exactly one** JSON document on stdout, never
+    bare prose to stderr (see ``cli/_output.py``).
+    """
+
+    def __init__(self, message: str, *, exit_code: int = EXIT_USAGE):
+        super().__init__(message)
+        self.output = make_error(message, stage="usage")
+        self.exit_code = exit_code
+
+
+def _normalize_api_origin(url: str) -> str | None:
+    """Canonical API origin for comparison: scheme + lowercased host + explicit port.
+
+    Ignores path, query, fragment, and trailing slashes. Returns ``None`` when the
+    URL does not carry a usable scheme + host (the localhost-key-at-prod guard then
+    falls back to a direct string compare).
+    """
+    raw = url.strip()
+    if not raw:
+        return None
+    parsed = urlsplit(raw)
+    if not parsed.scheme or not parsed.hostname:
+        return None
+    scheme = parsed.scheme.lower()
+    host = parsed.hostname.lower()
+    port = parsed.port
+    if port is None:
+        port = 443 if scheme == "https" else 80
+    if (scheme == "http" and port == 80) or (scheme == "https" and port == 443):
+        return f"{scheme}://{host}"
+    return f"{scheme}://{host}:{port}"
+
+
+def _origins_match(a: str, b: str) -> bool:
+    norm_a = _normalize_api_origin(a)
+    norm_b = _normalize_api_origin(b)
+    if norm_a is not None and norm_b is not None:
+        return norm_a == norm_b
+    return a.rstrip("/") == b.rstrip("/")
+
+
+def _rc_record(args: argparse.Namespace) -> RcRecord | None:
+    """Resolve the project-local ``.xmemrc.json`` (or ``None``); raise on a malformed one."""
+    try:
+        return resolve_rc(getattr(args, "rc_dir", None))
+    except RcError as exc:
+        raise UsageError(str(exc)) from exc
+
+
+def _require(args: argparse.Namespace, *, need_instance: bool) -> tuple[str, str | None]:
+    # Precedence: --api-key → $XMEM_API_KEY → .xmemrc.json. Resolve the rc ONLY when neither
+    # explicit source supplies a key, so a malformed .xmemrc.json never breaks a command that
+    # already passed --api-key / set $XMEM_API_KEY (the explicit key wins before the rc is read).
+    explicit_key = args.api_key or os.environ.get(ENV_API_KEY)
+    rc = None if explicit_key else _rc_record(args)
+    api_key = explicit_key or (rc.api_key if rc else "")
+    if not api_key:
+        raise UsageError(f"Not logged in — run `{CLI_NAME} auth login` first.")
+    # localhost-key-at-prod guard: a key read from .xmemrc.json is bound to that file's api_url;
+    # refuse to send it to a different, explicitly-set origin (pass --api-key to override). Only
+    # reachable when the key came from the rc — `rc` is None whenever an explicit key was given.
+    if rc is not None:
+        explicit_url = args.api_url or os.environ.get(ENV_API_URL)
+        if explicit_url and not _origins_match(explicit_url, rc.api_url):
+            raise UsageError(
+                f"refusing to use the {RC_FILENAME} key (bound to {rc.api_url}) against "
+                f"{explicit_url}; pass --api-key to use a key against a different origin."
+            )
+    instance_id: str | None = None
+    if need_instance:
+        instance_id = args.instance_id or os.environ.get(ENV_INSTANCE_ID) or ""
+        if not instance_id:
+            resolved, auto_warn = _auto_resolve_single_instance_id(args, api_key)
+            if auto_warn:
+                _note_cli_warning(args, auto_warn)
+            instance_id = resolved or ""
+        if not instance_id:
+            raise UsageError(f"instance id not provided. Pass --instance-id or set {ENV_INSTANCE_ID}.")
+    return api_key, instance_id
+
+
+def _api_url(args: argparse.Namespace) -> str:
+    # Precedence: --api-url → $XMEM_API_URL → .xmemrc.json api_url → built-in default.
+    explicit_url = args.api_url or os.environ.get(ENV_API_URL)
+    if explicit_url:
+        return _normalize_api_origin(explicit_url) or explicit_url.rstrip("/")
+    # No explicit origin. The rc supplies the default origin ONLY when the rc is also the
+    # credential source — i.e. when no explicit key was given. With an explicit --api-key /
+    # $XMEM_API_KEY the rc is irrelevant (its api_url binds only the rc's own key), and a
+    # malformed .xmemrc.json must not block such a command — so fall back to the built-in
+    # default WITHOUT reading the rc. This mirrors the same explicit-key escape hatch in
+    # _require(), so `--api-key` + a broken rc + no --api-url resolves cleanly end to end.
+    if args.api_key or os.environ.get(ENV_API_KEY):
+        return _normalize_api_origin(DEFAULT_API_URL) or DEFAULT_API_URL.rstrip("/")
+    rc = _rc_record(args)
+    fallback = (rc.api_url if rc else None) or DEFAULT_API_URL
+    return _normalize_api_origin(fallback) or fallback.rstrip("/")
+
+
+def _explicit_api_url(args: argparse.Namespace) -> str | None:
+    """Origin from flags/env only — never from ``.xmemrc.json``."""
+    explicit = args.api_url or os.environ.get(ENV_API_URL)
+    if not explicit:
+        return None
+    return _normalize_api_origin(explicit) or explicit.rstrip("/")
+
+
+def _rc_dir(args: argparse.Namespace) -> Path:
+    return Path(getattr(args, "rc_dir", None) or os.environ.get(ENV_RC_DIR) or os.getcwd())
+
+
+# ── Subcommand handlers ────────────────────────────────────────────────────
+# Each handler returns ``(CliOutput, exit_code)``. ``main`` is responsible
+# for emitting the CliOutput on stdout — handlers never print directly.
+
+
+def cmd_write(args: argparse.Namespace) -> tuple[CliOutput, int]:
+    api_key, instance_id = _require(args, need_instance=True)
+    base = _api_url(args)
+    payload: dict[str, Any] = {"text": args.text, "extraction_logic": args.extraction}
+    url_path = "write_async" if args.no_wait else "write"
+    kind = OutputKind.WRITE_ASYNC if args.no_wait else OutputKind.WRITE_SYNC
+    try:
+        envelope = _post(
+            f"{base}/instances/{instance_id}/{url_path}",
+            payload,
+            api_key,
+            timeout_s=30.0 if args.no_wait else 120.0,
+        )
+    except ApiError as e:
+        if e.status in (401, 403):
+            return (
+                make_error(
+                    "write rejected: the key may not have write permission",
+                    status=e.status,
+                    stage="auth",
+                ),
+                EXIT_AUTH_ERROR,
+            )
+        quota_msg = _quota_exceeded_message(e)
+        if quota_msg is not None:
+            return (make_error(quota_msg, status=e.status or None, stage="quota"), EXIT_QUOTA_EXCEEDED)
+        return (make_error(str(e), status=e.status or None, stage="request"), EXIT_HTTP_ERROR)
+    try:
+        item = _unwrap_items(envelope)
+    except ApiError as e:
+        return (make_error(str(e), status=e.status or None, stage="request"), EXIT_HTTP_ERROR)
+    curated = _curate_write(item, sync=not args.no_wait, verbose=args.verbose)
+    return (CliOutput(kind, curated), EXIT_OK)
+
+
+def _parse_scope_arg(raw: str) -> dict[str, Any]:
+    """Parse one ``--scope`` token ``TYPE:ID`` into a scope-object dict.
+
+    ``ID`` is a user-defined primary key when it contains ``=`` (one or more
+    ``field=value`` pairs, comma-separated), otherwise an xuid.
+    """
+    type_name, sep, identifier = raw.partition(":")
+    if not sep or not type_name.strip() or not identifier.strip():
+        raise ValueError(f"Invalid --scope {raw!r}; expected 'TYPE:<xuid>' or 'TYPE:field=value'.")
+    type_name = type_name.strip()
+    if "=" in identifier:
+        key: dict[str, str] = {}
+        for pair in identifier.split(","):
+            field, eq, value = pair.partition("=")
+            if not eq or not field.strip():
+                raise ValueError(f"Invalid --scope key {pair!r} in {raw!r}; expected 'field=value'.")
+            key[field.strip()] = value
+        return {"type": type_name, "key": {"key": key}}
+    return {"type": type_name, "key": {"xuid": identifier.strip()}}
+
+
+def cmd_read(args: argparse.Namespace) -> tuple[CliOutput, int]:
+    api_key, instance_id = _require(args, need_instance=True)
+    base = _api_url(args)
+    mode_map = {
+        "single": ("single-answer", OutputKind.READ_SINGLE),
+        "raw": ("raw-tables", OutputKind.READ_RAW),
+        "xresponse": ("xresponse", OutputKind.READ_XRESPONSE),
+    }
+    api_mode, kind = mode_map[args.read_mode]
+    payload: dict[str, Any] = {"query": args.query, "mode": api_mode}
+    scope_args = getattr(args, "scope", None)
+    if scope_args:
+        try:
+            scope_objects = [_parse_scope_arg(raw) for raw in scope_args]
+        except ValueError as e:
+            return (make_error(str(e), stage="request"), EXIT_USAGE)
+        payload["scope"] = {
+            "objects": scope_objects,
+            "relations_scope": "all_relations" if getattr(args, "scope_relations", False) else "no_relations",
+        }
+    try:
+        envelope = _post(
+            f"{base}/instances/{instance_id}/read",
+            payload,
+            api_key,
+            timeout_s=120.0,
+        )
+    except ApiError as e:
+        if e.status in (401, 403):
+            return (
+                make_error(
+                    "read rejected: check the API key permissions",
+                    status=e.status,
+                    stage="auth",
+                ),
+                EXIT_AUTH_ERROR,
+            )
+        quota_msg = _quota_exceeded_message(e)
+        if quota_msg is not None:
+            return (make_error(quota_msg, status=e.status or None, stage="quota"), EXIT_QUOTA_EXCEEDED)
+        return (make_error(str(e), status=e.status or None, stage="request"), EXIT_HTTP_ERROR)
+    try:
+        item = _unwrap_items(envelope)
+    except ApiError as e:
+        return (make_error(str(e), status=e.status or None, stage="request"), EXIT_HTTP_ERROR)
+    curated = _curate_read(item, read_mode=args.read_mode, verbose=args.verbose)
+    return (CliOutput(kind, curated), EXIT_OK)
+
+
+def cmd_write_status(args: argparse.Namespace) -> tuple[CliOutput, int]:
+    """Poll one or more queued async writes until terminal or timeout.
+
+    The bulk shape is intentional: ``xmem write --no-wait`` is the way to
+    push many facts quickly, so we want the operator to be able to "wait for
+    all of them" in a single command — without having to script a shell
+    loop with retries. We poll the ids concurrently with a thread pool so a
+    bulk of three writes finishes in roughly ``max(individual_latencies)``
+    rather than the sum.
+
+    Output:
+
+    - One id    → emits the single status object (same shape as the
+                  per-write payload).
+    - Multiple  → emits a list of status objects, one per requested id,
+                  preserving the order the user passed them.
+
+    Either way it is exactly one JSON document on stdout in JSON mode.
+    """
+    api_key, instance_id = _require(args, need_instance=True)
+    base = _api_url(args)
+    deadline = time.monotonic() + args.timeout
+
+    def poll(write_id: str) -> dict[str, Any]:
+        """Block until ``write_id`` reaches a terminal status (or deadline)."""
+        last_status = "unknown"
+        last_body: dict[str, Any] = {"write_id": write_id, "write_status": last_status}
+        while True:
+            try:
+                envelope = _post(
+                    f"{base}/instances/{instance_id}/write_status",
+                    {"write_id": write_id},
+                    api_key,
+                    timeout_s=30.0,
+                )
+            except ApiError as e:
+                # Carry the error inline so a single failing id doesn't kill
+                # the bulk call — the other writes' final statuses are still
+                # useful to the caller.
+                return {
+                    "write_id": write_id,
+                    "write_status": "error",
+                    "error": str(e),
+                    "http_status": e.status,
+                }
+            try:
+                item = _unwrap_items(envelope)
+            except ApiError as e:
+                return {
+                    "write_id": write_id,
+                    "write_status": "error",
+                    "error": str(e),
+                    "http_status": e.status,
+                }
+            last_status = item.get("write_status", "unknown")
+            last_body = item
+            if last_status in ("completed", "failed", "not_found"):
+                return item
+            if time.monotonic() >= deadline:
+                last_body["timed_out"] = True
+                return last_body
+            time.sleep(0.5)
+
+    write_ids: list[str] = list(args.write_ids)
+    if len(write_ids) == 1:
+        result = poll(write_ids[0])
+        kind = OutputKind.WRITE_STATUS
+        exit_code = EXIT_OK if result.get("write_status") == "completed" else EXIT_HTTP_ERROR
+        if result.get("timed_out"):
+            exit_code = EXIT_TIMEOUT
+        return (CliOutput(kind, _curate_write_status(result, args.verbose)), exit_code)
+
+    # Bulk: poll in parallel, preserve input order, decide exit code from
+    # the worst individual outcome (timeout > error > failed > completed).
+    results: list[dict[str, Any]] = [{} for _ in write_ids]
+    with concurrent.futures.ThreadPoolExecutor(max_workers=min(len(write_ids), 8)) as pool:
+        futures = {pool.submit(poll, wid): i for i, wid in enumerate(write_ids)}
+        for fut in concurrent.futures.as_completed(futures):
+            results[futures[fut]] = fut.result()
+
+    statuses = {r.get("write_status", "unknown") for r in results}
+    if any(r.get("timed_out") for r in results):
+        exit_code = EXIT_TIMEOUT
+    elif "error" in statuses or "failed" in statuses or "not_found" in statuses:
+        exit_code = EXIT_HTTP_ERROR
+    else:
+        exit_code = EXIT_OK if statuses == {"completed"} else EXIT_HTTP_ERROR
+    curated = [_curate_write_status(r, args.verbose) for r in results]
+    return (CliOutput(OutputKind.WRITE_STATUS, curated), exit_code)
+
+
+
+def cmd_auth_status(args: argparse.Namespace) -> tuple[CliOutput, int]:
+    """``xmem auth status`` — report whether the CLI holds a credential and if it resolves.
+
+    No credential (after ``auth logout``, or before ``auth login``) →
+    ``{authenticated: false, logged_in: false}``, exit ``0``.
+
+    Credential present but ``/whoami`` returns ``AuthNone`` →
+    ``{authenticated: false, logged_in: true, key_prefix}``, exit ``EXIT_AUTH_ERROR``.
+
+    Valid key → ``{authenticated: true, email, key_prefix}``, exit ``0``.
+    """
+    explicit_key = args.api_key or os.environ.get(ENV_API_KEY)
+    rc = None if explicit_key else _rc_record(args)
+    api_key = explicit_key or (rc.api_key if rc else "")
+    if not api_key:
+        return (
+            CliOutput(OutputKind.AUTH_STATUS, {"authenticated": False, "logged_in": False}),
+            EXIT_OK,
+        )
+
+    if rc is not None:
+        explicit_url = args.api_url or os.environ.get(ENV_API_URL)
+        if explicit_url and not _origins_match(explicit_url, rc.api_url):
+            return (
+                make_error(
+                    f"refusing to use the {RC_FILENAME} key (bound to {rc.api_url}) against "
+                    f"{explicit_url}; pass --api-key to use a key against a different origin.",
+                    stage="usage",
+                ),
+                EXIT_USAGE,
+            )
+
+    base = _api_url(args)
+    console = _console_url_for_args(args)
+    try:
+        whoami = _fetch_whoami(base, api_key, console_url=console)
+    except ApiError as e:
+        if e.status in (401, 403):
+            return (
+                make_error("auth status rejected: check the key", status=e.status, stage="auth"),
+                EXIT_AUTH_ERROR,
+            )
+        return (make_error(f"/whoami failed: {e}", status=e.status), EXIT_HTTP_ERROR)
+    auth_api_key = whoami.get("AuthApiKey")
+    if not isinstance(auth_api_key, dict) or not auth_api_key.get("email"):
+        return (
+            CliOutput(
+                OutputKind.AUTH_STATUS,
+                {"authenticated": False, "logged_in": True, "key_prefix": api_key[:8]},
+            ),
+            EXIT_AUTH_ERROR,
+        )
+    return (
+        CliOutput(
+            OutputKind.AUTH_STATUS,
+            {
+                "authenticated": True,
+                "logged_in": True,
+                "email": auth_api_key.get("email"),
+                "key_prefix": api_key[:8],
+            },
+        ),
+        EXIT_OK,
+    )
+
+
+def cmd_auth_login(args: argparse.Namespace) -> tuple[CliOutput, int]:
+    """``xmem auth login`` — PKCE handoff via the Console, store in ``.xmemrc.json``."""
+    explicit_api = _explicit_api_url(args) or os.environ.get(ENV_API_URL, "").strip()
+    console = _console_url_for_args(args)
+    api_origin = explicit_api or DEFAULT_API_URL
+    base = _normalize_api_origin(api_origin) or api_origin.rstrip("/")
+    verifier = _login.new_verifier()
+    interactive = stdout_is_tty()
+    offer_paste = interactive and _login.paste_from_stdin_supported()
+
+    def on_url(url: str) -> None:
+        _login.write_login_handoff_prompt(url, offer_paste=offer_paste)
+        if not args.no_browser:
+            try:
+                webbrowser.open(url)
+            except OSError:
+                pass
+
+    try:
+        result = _login.run_pkce_login(
+            base,
+            console_url=console,
+            verifier=verifier,
+            on_url=on_url,
+            timeout_s=args.timeout,
+            interactive=interactive,
+            notify=_eprint,
+        )
+    except (_login.LoginAborted, KeyboardInterrupt):
+        return (CliOutput(OutputKind.LOGIN, {"status": "aborted"}), EXIT_INTERRUPTED)
+    except _login.LoginTimeout as e:
+        return (make_error(str(e), stage="login"), EXIT_TIMEOUT)
+    except _login.LoginError as e:
+        return (make_error(str(e), stage="login"), EXIT_USAGE)
+
+    if not result.email:
+        return (
+            make_error("login did not return a validated account email", stage="login"),
+            EXIT_USAGE,
+        )
+
+    target_dir = _rc_dir(args)
+    rc_path = write_rc(target_dir, email=result.email, api_url=base, api_key=result.api_key)
+    warning = gitignore_warning(rc_path)
+    if warning:
+        _eprint(f"warning: {warning}")
+    env_key = os.environ.get(ENV_API_KEY, "").strip()
+    if env_key and env_key != result.api_key:
+        _eprint(
+            f"warning: {ENV_API_KEY} is set (prefix {env_key[:8]}…) and overrides the key "
+            f"just saved to {rc_path}; unset it or update it to use the new key."
+        )
+    payload: dict[str, Any] = {
+        "status": "authorized",
+        "email": result.email,
+        "api_url": base,
+        "key_prefix": result.key_prefix,
+        "rc_file": str(rc_path),
+    }
+    return (CliOutput(OutputKind.LOGIN, payload), EXIT_OK)
+
+
+def cmd_auth_logout(args: argparse.Namespace) -> tuple[CliOutput, int]:
+    """``xmem auth logout`` — remove the active ``.xmemrc.json``."""
+    try:
+        path = find_rc(_rc_dir(args))
+        if path is None:
+            return (CliOutput(OutputKind.LOGIN, {"status": "not_logged_in"}), EXIT_OK)
+        load_rc(path)
+    except RcError as exc:
+        return (make_error(str(exc), stage="usage"), EXIT_USAGE)
+    remove_rc(path)
+    return (CliOutput(OutputKind.LOGIN, {"status": "logged_out", "rc_file": str(path)}), EXIT_OK)
+
+
+def _operator_cluster_override(args: argparse.Namespace) -> str | None:
+    """Advanced cluster override for operators (``$XMEM_CLUSTER_ID`` or suppressed ``--cluster-id``)."""
+    explicit = getattr(args, "cluster_id", None) or os.environ.get(ENV_CLUSTER_ID)
+    return str(explicit) if explicit else None
+
+
+def _cluster_id_from_instance_context(
+    args: argparse.Namespace, base: str, api_key: str
+) -> tuple[str | None, tuple[CliOutput, int] | None]:
+    """Derive cluster from ``--instance-id`` / ``$XMEM_INSTANCE_ID`` via ``GET /instances/{id}``."""
+    instance_id = getattr(args, "instance_id", None) or os.environ.get(ENV_INSTANCE_ID)
+    if not instance_id:
+        return None, None
+    try:
+        envelope = _get(f"{base.rstrip('/')}/instances/{instance_id}", api_key)
+    except ApiError as e:
+        if e.status in (401, 403):
+            return None, (
+                make_error("instance lookup rejected: check the key", status=e.status, stage="auth"),
+                EXIT_AUTH_ERROR,
+            )
+        if e.status == 404:
+            return None, (
+                make_error(
+                    f"instance {instance_id} not found or not visible to this key",
+                    status=e.status,
+                    stage="usage",
+                ),
+                EXIT_USAGE,
+            )
+        return None, (
+            make_error(f"could not load instance {instance_id}: {e}", status=e.status or None, stage="request"),
+            EXIT_HTTP_ERROR,
+        )
+    err = batch_envelope_error(envelope)
+    if err:
+        return None, (make_error(f"instance lookup failed: {err}", stage="request"), EXIT_HTTP_ERROR)
+    items = envelope.get("items") or []
+    if not items or not isinstance(items[0], dict):
+        return None, (
+            make_error(f"instance {instance_id} response missing cluster", stage="request"),
+            EXIT_HTTP_ERROR,
+        )
+    cluster_id = items[0].get("cluster_id")
+    if not cluster_id:
+        return None, (
+            make_error(f"instance {instance_id} response missing cluster_id", stage="request"),
+            EXIT_HTTP_ERROR,
+        )
+    return str(cluster_id), None
+
+
+def _resolve_cluster_id(
+    args: argparse.Namespace, base: str, api_key: str
+) -> tuple[str | None, tuple[CliOutput, int] | None]:
+    """Resolve cluster for cluster-scoped calls (e.g. ``quota get``).
+
+    Order: operator override → instance context → sole visible cluster.
+    Agent-facing errors steer toward ``--instance-id``, not cluster ID
+    (see ``maxims/API-CLIENTS.yml`` — *One addressing axis for agents*).
+    """
+    override = _operator_cluster_override(args)
+    if override:
+        return override, None
+    from_instance, instance_err = _cluster_id_from_instance_context(args, base, api_key)
+    if instance_err is not None:
+        return None, instance_err
+    if from_instance:
+        return from_instance, None
+    try:
+        envelope = _get(f"{base}/clusters", api_key)
+    except ApiError as e:
+        if e.status in (401, 403):
+            return None, (
+                make_error("cluster lookup rejected: check the key", status=e.status, stage="auth"),
+                EXIT_AUTH_ERROR,
+            )
+        return None, (
+            make_error(f"could not list clusters: {e}", status=e.status or None, stage="request"),
+            EXIT_HTTP_ERROR,
+        )
+    err = batch_envelope_error(envelope)
+    if err:
+        return None, (make_error(f"cluster lookup failed: {err}", stage="request"), EXIT_HTTP_ERROR)
+    clusters = envelope.get("items") or []
+    ids = [c["id"] for c in clusters if isinstance(c, dict) and c.get("id")]
+    if len(ids) == 1:
+        return str(ids[0]), None
+    if not ids:
+        return None, (
+            make_error(
+                f"no clusters visible to this key; pass --instance-id or set {ENV_INSTANCE_ID}",
+                stage="usage",
+            ),
+            EXIT_USAGE,
+        )
+    return None, (
+        make_error(
+            f"{len(ids)} clusters visible; pass --instance-id or set {ENV_INSTANCE_ID} to pin an instance",
+            stage="usage",
+        ),
+        EXIT_USAGE,
+    )
+
+
+def _flatten_quota_row(row: dict[str, Any]) -> dict[str, Any]:
+    """Lift nested ``usage`` (per-quota GET) into the flat shape ``_curate_quota_row`` expects."""
+    usage = row.get("usage")
+    if not isinstance(usage, dict):
+        return row
+    flat = dict(row)
+    for key in ("window_start", "used_tokens", "remaining_tokens"):
+        if key in usage:
+            flat[key] = usage[key]
+    return flat
+
+
+def _fetch_single_quota_row(
+    base: str, cluster_id: str, api_key: str, item: dict[str, Any]
+) -> tuple[dict[str, Any], tuple[CliOutput, int] | None]:
+    """Fetch one quota row with live usage (list endpoint omits counters)."""
+    quota_id = item.get("id")
+    if quota_id is None:
+        return item, None
+    try:
+        detail_env = _get(f"{base}/clusters/{cluster_id}/quotas/{quota_id}", api_key)
+    except ApiError as e:
+        if e.status in (401, 403):
+            return item, (
+                make_error("quota read rejected: check the key permissions", status=e.status, stage="auth"),
+                EXIT_AUTH_ERROR,
+            )
+        return item, (make_error(str(e), status=e.status or None, stage="request"), EXIT_HTTP_ERROR)
+    detail_err = batch_envelope_error(detail_env)
+    if detail_err:
+        return item, (make_error(f"quota read failed: {detail_err}", stage="request"), EXIT_HTTP_ERROR)
+    detail_items = detail_env.get("items")
+    if isinstance(detail_items, list) and detail_items and isinstance(detail_items[0], dict):
+        return detail_items[0], None
+    return item, None
+
+
+def _fetch_cluster_quota_rows(
+    base: str, cluster_id: str, api_key: str
+) -> tuple[list[dict[str, Any]], tuple[CliOutput, int] | None]:
+    """Return quota rows with current-window usage for ``quota get``.
+
+    ``GET /clusters/{id}/quotas`` (verbose list) omits usage.
+    Each quota needs a detail GET for live window counters.
+    Conscious N+1 (we are not fixing this in PR2): there is no batch usage endpoint.
+    Typical clusters expose a small handful of rows; a few sequential round-trips are fine for ``quota get``.
+    Parallel fetch would shave wall-clock marginally while adding executor complexity.
+    Revisit if the list endpoint starts returning usage.
+    """
+    try:
+        envelope = _get(f"{base}/clusters/{cluster_id}/quotas?verbose=true", api_key)
+    except ApiError as e:
+        if e.status in (401, 403):
+            return [], (
+                make_error("quota read rejected: check the key permissions", status=e.status, stage="auth"),
+                EXIT_AUTH_ERROR,
+            )
+        return [], (make_error(str(e), status=e.status or None, stage="request"), EXIT_HTTP_ERROR)
+    err = batch_envelope_error(envelope)
+    if err:
+        return [], (make_error(f"quota list failed: {err}", stage="request"), EXIT_HTTP_ERROR)
+    listed = envelope.get("items") or []
+    detailed: list[dict[str, Any]] = []
+    for item in listed:
+        if not isinstance(item, dict):
+            continue
+        row, fetch_err = _fetch_single_quota_row(base, cluster_id, api_key, item)
+        if fetch_err is not None:
+            return [], fetch_err
+        detailed.append(row)
+    return detailed, None
+
+
+def _curate_quota_row(row: dict[str, Any]) -> dict[str, Any]:
+    window = row.get("quota_window") or row.get("window")
+    limit = row.get("token_limit")
+    used = row.get("used_tokens", row.get("tokens_used", row.get("used")))
+    window_start = row.get("window_start")
+    remaining: int | float | None = None
+    usage_ratio: float | None = None
+    near_limit = False
+    server_remaining = row.get("remaining_tokens")
+    if isinstance(server_remaining, (int, float)) and not isinstance(server_remaining, bool):
+        remaining = server_remaining
+    # Reject bool JSON values — ``True``/``False`` are ints in Python and would skew arithmetic.
+    if (
+        isinstance(limit, (int, float))
+        and not isinstance(limit, bool)
+        and isinstance(used, (int, float))
+        and not isinstance(used, bool)
+    ):
+        limit_num: int | float = limit
+        used_num: int | float = used
+        if remaining is None:
+            remaining = limit_num - used_num
+        if limit_num > 0:
+            usage_ratio = round(used_num / limit_num, 4)
+            near_limit = usage_ratio >= _QUOTA_WARN_RATIO
+    return {
+        "quota_window": window,
+        "token_limit": limit,
+        "used_tokens": used,
+        "remaining_tokens": remaining,
+        "usage_ratio": usage_ratio,
+        "near_limit": near_limit,
+        "window_start": window_start,
+    }
+
+
+def cmd_quota_get(args: argparse.Namespace) -> tuple[CliOutput, int]:
+    """``xmem quota`` — usage / limit / window start for the key's cluster."""
+    api_key, _ = _require(args, need_instance=False)
+    base = _api_url(args)
+    cluster_id, err = _resolve_cluster_id(args, base, api_key)
+    if err is not None:
+        return err
+    if cluster_id is None:
+        return (
+            make_error(
+                f"cluster could not be resolved; pass --instance-id or set {ENV_INSTANCE_ID}",
+                stage="usage",
+            ),
+            EXIT_USAGE,
+        )
+    rows, fetch_err = _fetch_cluster_quota_rows(base, cluster_id, api_key)
+    if fetch_err is not None:
+        return fetch_err
+    curated = [_curate_quota_row(_flatten_quota_row(r)) for r in rows]
+    fail_threshold: float | None = None
+    raw_fail = getattr(args, "fail_if_under", None)
+    if raw_fail is not None:
+        try:
+            fail_threshold = _parse_remaining_threshold(str(raw_fail))
+        except ValueError:
+            return (
+                make_error(
+                    f"invalid --fail-if-under value {raw_fail!r}; use a fraction (0.1) or percent (10%)",
+                    stage="usage",
+                ),
+                EXIT_USAGE,
+            )
+    exit_code = EXIT_OK
+    for row in curated:
+        if row.get("near_limit"):
+            pct = round((row.get("usage_ratio") or 0) * 100)
+            _eprint(
+                f"warning: the {row.get('quota_window') or 'quota'} window is {pct}% used "
+                f"({row.get('used_tokens')} / {row.get('token_limit')} tokens)."
+            )
+        if fail_threshold is not None:
+            limit = row.get("token_limit")
+            remaining = row.get("remaining_tokens")
+            if (
+                isinstance(limit, (int, float))
+                and not isinstance(limit, bool)
+                and limit > 0
+                and isinstance(remaining, (int, float))
+                and not isinstance(remaining, bool)
+                and (remaining / limit) < fail_threshold
+            ):
+                exit_code = EXIT_QUOTA_EXCEEDED
+    return (CliOutput(OutputKind.QUOTA, curated), exit_code)
+
+
+def cmd_version(_args: argparse.Namespace) -> tuple[CliOutput, int]:
+    """``xmem version`` — print the CLI release version (no network)."""
+    return (CliOutput(OutputKind.VERSION, {"version": __version__}), EXIT_OK)
+
+
+def cmd_status(args: argparse.Namespace) -> tuple[CliOutput, int]:
+    """``xmem status`` — local release health: version + credential file presence (no network)."""
+    rc_path = find_rc(_rc_dir(args))
+    payload: dict[str, Any] = {
+        "version": __version__,
+        "cli": CLI_NAME,
+        "authenticated": False,
+        "status": "not_logged_in",
+    }
+    if rc_path is not None:
+        payload["rc_file"] = str(rc_path)
+        try:
+            rc = load_rc(rc_path)
+        except RcError as exc:
+            payload["status"] = "invalid_rc"
+            payload["error"] = str(exc)
+        else:
+            payload["authenticated"] = True
+            payload["status"] = "credentials_present"
+            payload["email"] = rc.email
+            payload["api_url"] = rc.api_url
+            payload["key_prefix"] = rc.api_key[:8]
+    return (CliOutput(OutputKind.STATUS, payload), EXIT_OK)
+
+
+from ._instance_schema import (  # noqa: E402 — after ``xmem`` helpers; avoids import cycle at module start
+    cmd_instance_create,
+    cmd_instance_delete,
+    cmd_instance_get,
+    cmd_schema_dry_run,
+    cmd_schema_get,
+    cmd_schema_migrations_get,
+    cmd_schema_migrations_list,
+    cmd_schema_update,
+    cmd_xmd_convert,
+    cmd_xmd_enhance,
+    cmd_xmd_generate,
+    cmd_xmd_validate,
+    cmd_xmd_validate_json,
+    cmd_xmd_validate_yaml,
+)
+from ._org_cluster import (  # noqa: E402
+    cmd_org_list_clusters,
+    cmd_org_list_instances,
+    cmd_org_list_keys,
+)
+
+
+# ── argparse plumbing ──────────────────────────────────────────────────────
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    p = _help.XmemCliArgumentParser(
+        prog=CLI_NAME,
+        description="xmemcli — CLI for the xmemory HTTP API (read/write, instance ops, key list).",
+    )
+    p.add_argument("--api-url", help=f"API origin (default ${ENV_API_URL} or {DEFAULT_API_URL})")
+    p.add_argument("--api-key", help=f"API key (default ${ENV_API_KEY})")
+    p.add_argument("--instance-id", help=f"Target instance id (default ${ENV_INSTANCE_ID})")
+    p.add_argument(
+        "--rc-dir",
+        help=f"Directory for {RC_FILENAME} (auth login writes here; reads walk up to $HOME)",
+    )
+    # Operator-only override; omitted from --help (maxims/API-CLIENTS.yml — One addressing axis for agents).
+    p.add_argument("--cluster-id", help=argparse.SUPPRESS)
+    p.add_argument(
+        "--json",
+        action="store_true",
+        help=(
+            "Force JSON output (a single JSON document) even when stdout is "
+            "an interactive terminal. The default for a TTY is a short "
+            "human-readable summary; the default for anything else (pipe, "
+            "redirect, captured subprocess) is already JSON."
+        ),
+    )
+    p.add_argument(
+        "--verbose",
+        action="store_true",
+        help=(
+            "Include extra context in the output (trace_id, console_url) "
+            "when the server provides it. Server internals (SQL, diff "
+            "plans) are never shown, verbose or not."
+        ),
+    )
+
+    sub = p.add_subparsers(dest="command", required=True, parser_class=_help.XmemCliArgumentParser)
+
+    pw = sub.add_parser("write", help="Write a fact to the active instance", add_help=False)
+    pw.add_argument("text", help="Text to write")
+    pw.add_argument(
+        "--extraction",
+        choices=["fast", "deep"],
+        default="fast",
+        help="extraction_logic on the API (default: fast)",
+    )
+    pw.add_argument(
+        "--no-wait",
+        action="store_true",
+        help=(
+            "Queue the write via write_async and return immediately with "
+            f"the assigned write_id. Use `{CLI_NAME} write-status "
+            "<write_id>` to wait for the queued write to land."
+        ),
+    )
+    pw.set_defaults(func=cmd_write)
+
+    pr = sub.add_parser("read", help="Read from the active instance", add_help=False)
+    pr.add_argument("query", help="Free-form query")
+    pr.add_argument(
+        "--read-mode",
+        choices=["single", "raw", "xresponse"],
+        default="single",
+        help=(
+            "Read mode passed to the API: single→single-answer, "
+            "raw→raw-tables, xresponse→xresponse (default: single). "
+            "This is the SERVER-side answer shape — output format "
+            "(JSON vs pretty) is governed by --json / the TTY rule."
+        ),
+    )
+    pr.add_argument(
+        "--scope",
+        action="append",
+        metavar="TYPE:ID",
+        help=(
+            "Restrict the read to a concrete object (repeatable). Identify it by "
+            "xuid — 'Person:<uuid>' — or by user-defined primary key — "
+            "'Person:name=Alice' (composite: 'Order:customer=Alice,sku=ABC'). "
+            "When any --scope is given the reader only sees/queries those objects."
+        ),
+    )
+    pr.add_argument(
+        "--scope-relations",
+        action="store_true",
+        help="With --scope, also expose relations among the in-scope objects (opt-in).",
+    )
+    pr.set_defaults(func=cmd_read)
+
+    ps = sub.add_parser(
+        "write-status",
+        help="Poll async writes until they complete (one or more write_ids).",
+        add_help=False,
+    )
+    ps.add_argument(
+        "write_ids",
+        nargs="+",
+        help=f"One or more write_ids returned by `{CLI_NAME} write --no-wait`",
+    )
+    ps.add_argument(
+        "--timeout",
+        type=float,
+        default=60.0,
+        help="Seconds to wait per id before giving up (default: 60)",
+    )
+    ps.set_defaults(func=cmd_write_status)
+
+    sub.add_parser("version", help="Print the CLI release version (no network)", add_help=False).set_defaults(
+        func=cmd_version
+    )
+    sub.add_parser(
+        "status",
+        help="Local health: version and whether .xmemrc.json is present (no network)",
+        add_help=False,
+    ).set_defaults(func=cmd_status)
+
+    po = sub.add_parser("org", help="Org-scoped inventory (permission-filtered account view)", add_help=False)
+    po_sub = po.add_subparsers(dest="org_command", required=True, parser_class=_help.XmemCliArgumentParser)
+    pol = po_sub.add_parser("list", help="List org resources visible to this credential", add_help=False)
+    pol_sub = pol.add_subparsers(dest="org_list_target", required=True, parser_class=_help.XmemCliArgumentParser)
+    pol_sub.add_parser("clusters", help="List clusters visible to this credential", add_help=False).set_defaults(
+        func=cmd_org_list_clusters
+    )
+    poli = pol_sub.add_parser(
+        "instances",
+        help="List instances visible to this credential",
+        add_help=False,
+    )
+    poli.add_argument("--cluster", help=argparse.SUPPRESS)
+    poli.set_defaults(func=cmd_org_list_instances)
+    pol_sub.add_parser("keys", help="List API keys visible to this credential", add_help=False).set_defaults(
+        func=cmd_org_list_keys
+    )
+
+    pi = sub.add_parser("instance", help="Instance operations (list, get, create, delete, schema)", add_help=False)
+    pi_sub = pi.add_subparsers(dest="instance_command", required=True, parser_class=_help.XmemCliArgumentParser)
+    pil = pi_sub.add_parser(
+        "list",
+        help="List instances visible to this credential",
+        add_help=False,
+    )
+    pil.set_defaults(func=cmd_org_list_instances)
+    pig = pi_sub.add_parser("get", help="Get a single instance by id", add_help=False)
+    pig.add_argument("instance_id_arg", metavar="instance_id", help="Instance id to fetch")
+    pig.add_argument("--cluster", help=argparse.SUPPRESS)
+    pig.set_defaults(func=cmd_instance_get)
+    pic = pi_sub.add_parser(
+        "create",
+        help="Create a new instance from an XMD/JSON schema",
+        add_help=False,
+    )
+    pic.add_argument("--name", required=True, help="Instance name")
+    pic.add_argument("--description", help="Free-form description (optional)")
+    pic.add_argument("--schema-file", help="Path to an XMD/JSON schema file")
+    pic.add_argument(
+        "--schema-stdin",
+        action="store_true",
+        help="Read the schema from stdin (mutually exclusive with --schema-file)",
+    )
+    pic.add_argument(
+        "--schema-type",
+        choices=["yaml", "json"],
+        help="Schema format (default: inferred from file extension; falls back to yaml)",
+    )
+    pic.set_defaults(func=cmd_instance_create)
+    pid = pi_sub.add_parser(
+        "delete",
+        help=argparse.SUPPRESS,
+        add_help=False,
+    )
+    pid.add_argument(
+        "instance_id_arg",
+        metavar="instance_id",
+        nargs="?",
+        help=f"Instance id (default ${ENV_INSTANCE_ID} or --instance-id)",
+    )
+    pid.set_defaults(func=cmd_instance_delete)
+
+    psch = sub.add_parser(
+        "schema",
+        help="Live-instance schema get / update / dry-run / migration history",
+        add_help=False,
+    )
+    psch_sub = psch.add_subparsers(dest="schema_command", required=True, parser_class=_help.XmemCliArgumentParser)
+    pschg = psch_sub.add_parser("get", help="Get the live schema of an instance", add_help=False)
+    pschg.add_argument(
+        "instance_id_arg",
+        metavar="instance_id",
+        nargs="?",
+        help=f"Instance id (default ${ENV_INSTANCE_ID} or --instance-id)",
+    )
+    pschg.add_argument("--output", "-o", help="Write the XMD schema (YAML) to this file")
+    pschg.set_defaults(func=cmd_schema_get)
+    pschu = psch_sub.add_parser("update", help="Replace the schema of an existing instance", add_help=False)
+    pschu.add_argument(
+        "instance_id_arg",
+        metavar="instance_id",
+        nargs="?",
+        help=f"Instance id (default ${ENV_INSTANCE_ID} or --instance-id)",
+    )
+    pschu.add_argument("--schema-file", required=True, help="Path to the new XMD/JSON schema")
+    pschu.add_argument(
+        "--schema-type",
+        choices=["yaml", "json"],
+        help="Schema format (default: inferred from file extension; falls back to yaml)",
+    )
+    pschu.add_argument(
+        "--migration-plan",
+        help="Path to migration_plan JSON (from `xmd enhance --plan-output`)",
+    )
+    pschu.add_argument(
+        "--confirm-destructive",
+        action="store_true",
+        help="Required acknowledgment for destructive ops (drops, lossy casts)",
+    )
+    pschu.set_defaults(func=cmd_schema_update)
+    pschd = psch_sub.add_parser(
+        "dry-run",
+        help="Preview what schema update would do without applying (MCP dry_run_schema_migration)",
+        add_help=False,
+    )
+    pschd.add_argument(
+        "instance_id_arg",
+        metavar="instance_id",
+        nargs="?",
+        help=f"Instance id (default ${ENV_INSTANCE_ID} or --instance-id)",
+    )
+    pschd.add_argument("--schema-file", required=True, help="Path to the candidate XMD/JSON schema")
+    pschd.add_argument(
+        "--schema-type",
+        choices=["yaml", "json"],
+        help="Schema format (default: inferred from file extension; falls back to yaml)",
+    )
+    pschd.add_argument(
+        "--migration-plan",
+        help="Path to migration_plan JSON (from `xmd enhance --plan-output`)",
+    )
+    pschd.add_argument(
+        "--confirm-destructive",
+        action="store_true",
+        help="Preview destructive ops without the destructive gate rejecting",
+    )
+    pschd.set_defaults(func=cmd_schema_dry_run)
+    pschm = psch_sub.add_parser(
+        "migrations",
+        help="Applied schema migration history for an instance",
+        add_help=False,
+    )
+    pschm_sub = pschm.add_subparsers(
+        dest="schema_migrations_command",
+        required=True,
+        parser_class=_help.XmemCliArgumentParser,
+    )
+    pschml = pschm_sub.add_parser(
+        "list",
+        help="List applied migrations, newest first (MCP list_schema_migrations)",
+        add_help=False,
+    )
+    pschml.add_argument(
+        "instance_id_arg",
+        metavar="instance_id",
+        nargs="?",
+        help=f"Instance id (default ${ENV_INSTANCE_ID} or --instance-id)",
+    )
+    pschml.add_argument("--limit", type=int, default=50, help="Max records (1-200, default 50)")
+    pschml.add_argument(
+        "--before-id",
+        help="Pagination cursor: return migrations applied before this migration id",
+    )
+    pschml.add_argument(
+        "--include-yaml",
+        action="store_true",
+        help="Include before/after YAML snapshots (can be large)",
+    )
+    pschml.set_defaults(func=cmd_schema_migrations_list)
+    pschmg = pschm_sub.add_parser(
+        "get",
+        help="Fetch one migration record by id (MCP get_schema_migration)",
+        add_help=False,
+    )
+    pschmg.add_argument(
+        "migration_id_arg",
+        metavar="migration_id",
+        help="UUID of the migration record (from `schema migrations list`)",
+    )
+    pschmg.add_argument(
+        "--include-yaml",
+        action="store_true",
+        help="Include before/after YAML snapshots for the record",
+    )
+    pschmg.set_defaults(func=cmd_schema_migrations_get)
+
+    px = sub.add_parser("xmd", help="Work with XMD (xmemory Data) schemas", add_help=False)
+    px_sub = px.add_subparsers(dest="xmd_command", required=True, parser_class=_help.XmemCliArgumentParser)
+    pxg = px_sub.add_parser("generate", help="Synthesize an XMD schema from a description", add_help=False)
+    pxg.add_argument("description", help="Natural-language description of what to store")
+    pxg.add_argument("--output", "-o", help="Write the YAML schema to this file")
+    pxg.set_defaults(func=cmd_xmd_generate)
+    pxe = px_sub.add_parser(
+        "enhance",
+        help="Enhance (augment) an existing XMD schema",
+        add_help=False,
+    )
+    pxe.add_argument(
+        "schema_file",
+        nargs="?",
+        help="Path to the existing schema (.yml/.yaml/.json); omit with --from-instance",
+    )
+    pxe.add_argument("description", help="Natural-language description of the change")
+    pxe.add_argument(
+        "--from-instance",
+        action="store_true",
+        help="Use live schema from instance (MCP enhance_schema on bound instance)",
+    )
+    pxe.add_argument("--output", "-o", help="Write the enhanced YAML to this file")
+    pxe.add_argument(
+        "--plan-output",
+        help="Write migration_plan JSON (feed to `schema update --migration-plan`)",
+    )
+    pxe.set_defaults(func=cmd_xmd_enhance)
+    pxv = px_sub.add_parser(
+        "validate",
+        help="Validate an XMD schema (format inferred from .json extension, else YAML)",
+        add_help=False,
+    )
+    pxv.add_argument("schema_file", help="Path to schema (.yml/.yaml/.json)")
+    pxv.set_defaults(func=cmd_xmd_validate)
+    pxvy = px_sub.add_parser("validate-yaml", help="Validate an XMD YAML schema against the server", add_help=False)
+    pxvy.add_argument("schema_file", help="Path to schema (.yml/.yaml)")
+    pxvy.set_defaults(func=cmd_xmd_validate_yaml)
+    pxvj = px_sub.add_parser("validate-json", help="Validate a JSON Schema against the server", add_help=False)
+    pxvj.add_argument("schema_file", help="Path to a JSON Schema file (.json)")
+    pxvj.set_defaults(func=cmd_xmd_validate_json)
+    pxc = px_sub.add_parser(
+        "convert",
+        help="Convert JSON Schema to XMD YAML via the API (validate_json_schema)",
+        add_help=False,
+    )
+    pxc.add_argument("schema_file", help="Path to a JSON Schema file (.json)")
+    pxc.add_argument("--output", "-o", help="Write XMD YAML to this file (default: same basename with .yml)")
+    pxc.add_argument(
+        "--root-object",
+        dest="root_object",
+        help="Root object name for the converted schema (default: MainObject)",
+    )
+    pxc.set_defaults(func=cmd_xmd_convert)
+
+    pa = sub.add_parser("auth", help="Acquire / drop / inspect credentials (.xmemrc.json)", add_help=False)
+    pa_sub = pa.add_subparsers(dest="auth_command", required=True, parser_class=_help.XmemCliArgumentParser)
+    pal = pa_sub.add_parser(
+        "login",
+        help="Acquire a key via the Console PKCE handoff → .xmemrc.json (key never printed)",
+        add_help=False,
+    )
+    pal.add_argument("--no-browser", action="store_true", help="Print the URL only; do not open a browser")
+    pal.add_argument("--timeout", type=float, default=300.0, help="Seconds to wait for the browser (default: 300)")
+    pal.add_argument(
+        "--console-url",
+        help=f"Console origin (default ${ENV_CONSOLE_URL} or {_login.DEFAULT_CONSOLE_URL})",
+    )
+    pal.set_defaults(func=cmd_auth_login)
+    palo = pa_sub.add_parser("logout", help="Remove the credential from the active .xmemrc.json", add_help=False)
+    palo.set_defaults(func=cmd_auth_logout)
+    pas = pa_sub.add_parser("status", help="Report whose key the CLI is holding (via /whoami)", add_help=False)
+    pas.set_defaults(func=cmd_auth_status)
+
+    pq = sub.add_parser(
+        "quota",
+        help="Show usage / limit / window start for the key's cluster",
+        add_help=False,
+    )
+    pq.add_argument(
+        "--fail-if-under",
+        metavar="THRESHOLD",
+        help=(
+            "Exit non-zero when remaining quota falls below THRESHOLD of the limit "
+            "(fraction 0.1 or whole-number percent like 10). Default: exit 0 whenever quota is readable."
+        ),
+    )
+    pq.set_defaults(func=cmd_quota_get)
+
+    return p
+
+
+_WRITE_STATUS_ALIASES = frozenset({
+    "write_status",
+    "writestatus",
+    "async_write_status",
+    "asyncwritestatus",
+    "async-write-status",
+})
+
+# Silent auth shortcuts — normalized before parse; not listed in the overview.
+_AUTH_LOGIN_ALIASES = frozenset({"login", "signin"})
+_AUTH_LOGOUT_ALIASES = frozenset({"logout", "logoff", "signout"})
+
+
+def _parse_remaining_threshold(raw: str) -> float:
+    """Parse ``--fail-if-under`` value: ``0.1`` or ``10%`` → minimum remaining fraction."""
+    text = raw.strip()
+    if text.endswith("%"):
+        value = float(text[:-1].strip())
+        return value / 100.0
+    value = float(text)
+    if value > 1:
+        return value / 100.0
+    return value
+
+
+def _auto_resolve_single_instance_id(args: argparse.Namespace, api_key: str) -> tuple[str | None, str | None]:
+    """When exactly one instance is visible, use it and return a warning message."""
+    base = _api_url(args)
+    try:
+        envelope = _get(f"{base}/instances?verbose=true", api_key)
+    except ApiError:
+        return None, None
+    err = batch_envelope_error(envelope)
+    if err:
+        return None, None
+    items = [i for i in (envelope.get("items") or []) if isinstance(i, dict) and i.get("id")]
+    if len(items) != 1:
+        return None, None
+    instance_id = str(items[0]["id"])
+    name = items[0].get("name") or instance_id
+    warning = (
+        f"no --instance-id / ${ENV_INSTANCE_ID}; using the only visible instance "
+        f"{instance_id} ({name})."
+    )
+    return instance_id, warning
+
+
+def _normalize_auth_argv(stripped: list[str]) -> list[str] | None:
+    """Map silent login/logout spellings to ``auth login`` / ``auth logout``."""
+    if not stripped:
+        return None
+    head, *rest = stripped
+    if head in _AUTH_LOGIN_ALIASES:
+        return ["auth", "login", *rest]
+    if head in _AUTH_LOGOUT_ALIASES:
+        return ["auth", "logout", *rest]
+    if head == "sign" and rest:
+        if rest[0] == "in":
+            return ["auth", "login", *rest[1:]]
+        if rest[0] == "out":
+            return ["auth", "logout", *rest[1:]]
+    if head == "log" and rest:
+        if rest[0] == "in":
+            return ["auth", "login", *rest[1:]]
+        if rest[0] == "out":
+            return ["auth", "logout", *rest[1:]]
+    if head == "auth" and rest:
+        sub, *tail = rest[0], *rest[1:]
+        if sub in _AUTH_LOGIN_ALIASES:
+            return ["auth", "login", *tail]
+        if sub in _AUTH_LOGOUT_ALIASES:
+            return ["auth", "logout", *tail]
+        if sub == "sign" and tail:
+            if tail[0] == "in":
+                return ["auth", "login", *tail[1:]]
+            if tail[0] == "out":
+                return ["auth", "logout", *tail[1:]]
+        if sub == "log" and tail:
+            if tail[0] == "in":
+                return ["auth", "login", *tail[1:]]
+            if tail[0] == "out":
+                return ["auth", "logout", *tail[1:]]
+    return None
+
+
+def _normalize_argv(argv: list[str]) -> list[str]:
+    """Map silent command aliases to canonical parser paths (after global flags)."""
+    stripped = _help.argv_without_globals(argv)
+    if not stripped:
+        return stripped
+    if stripped[0] in _WRITE_STATUS_ALIASES:
+        return ["write-status", *stripped[1:]]
+    if len(stripped) >= 2 and stripped[0] == "quota" and stripped[1] == "get":
+        return ["quota", *stripped[2:]]
+    auth_normalized = _normalize_auth_argv(stripped)
+    if auth_normalized is not None:
+        return auth_normalized
+    return stripped
+
+
+def _global_prefix(argv: list[str]) -> list[str]:
+    """Return leading global flags from ``argv`` (preserving order)."""
+    out: list[str] = []
+    i = 0
+    while i < len(argv):
+        tok = argv[i]
+        if tok in _help.GLOBAL_STORE_TRUE_FLAGS:
+            out.append(tok)
+            i += 1
+            continue
+        if tok in _help.GLOBAL_OPTION_FLAGS:
+            out.append(tok)
+            if i + 1 < len(argv) and not argv[i + 1].startswith("-"):
+                out.append(argv[i + 1])
+                i += 2
+            else:
+                i += 1
+            continue
+        break
+    return out
+
+
+def _parse_argv(argv: list[str]) -> list[str]:
+    """``argv`` for :func:`argparse.ArgumentParser.parse_args` — globals + normalized command."""
+    globals_part, stripped = _help.collect_global_flags(argv)
+    command = _normalize_argv(stripped)
+    if not command:
+        return globals_part
+    return globals_part + command
+
+
+def _emit_help(
+    parser: argparse.ArgumentParser,
+    path: tuple[str, ...],
+    *,
+    machine_json: bool,
+) -> None:
+    doc = _help.build_help_document(parser, path)
+    if machine_json:
+        emit(CliOutput(OutputKind.HELP, doc), force_json=True)
+    else:
+        _help.render_help_document(doc)
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv_list = list(argv) if argv is not None else sys.argv[1:]
+    parser = _build_parser()
+    machine_json = "--json" in argv_list or not stdout_is_tty()
+    command = _normalize_argv(argv_list)
+    if not command:
+        _emit_help(parser, (), machine_json=machine_json)
+        return EXIT_OK
+    help_path = _help.help_target(command)
+    if help_path is not None:
+        _emit_help(parser, help_path, machine_json=machine_json)
+        return EXIT_OK
+    try:
+        args = parser.parse_args(_parse_argv(argv_list))
+    except _help.CliParseError as exc:
+        if machine_json:
+            emit(make_error(exc.message, stage="usage"), force_json=True)
+        else:
+            _help.print_parse_error(exc.message)
+        return EXIT_USAGE
+    except SystemExit as exc:
+        code = int(exc.code) if isinstance(exc.code, int) else EXIT_USAGE
+        if machine_json:
+            if code != 0:
+                emit(make_error("invalid usage", stage="usage"), force_json=True)
+            else:
+                emit(CliOutput(OutputKind.STATUS, {"ok": True}), force_json=True)
+        return code if code != 0 else EXIT_OK
+    try:
+        output, exit_code = args.func(args)
+    except UsageError as exc:
+        # Pre-flight resolution errors (missing key, malformed rc, …) still go
+        # through emit() so machine mode gets a single JSON ERROR document.
+        emit(_with_cli_warnings(exc.output, args, force_json=machine_json or args.json), force_json=machine_json or args.json)
+        return exc.exit_code
+    except KeyboardInterrupt:
+        if machine_json or args.json:
+            emit(make_error("interrupted", stage="interrupt"), force_json=True)
+        else:
+            _eprint("Interrupted.")
+        return EXIT_INTERRUPTED
+    force_json = machine_json or args.json
+    emit(_with_cli_warnings(output, args, force_json=force_json), force_json=force_json)
+    return exit_code
+
+
+if __name__ == "__main__":
+    sys.exit(main())