nexla-cli 0.2.0__py3-none-any.whl

nexla_cli/mcp_client.py

@@ -0,0 +1,139 @@
+"""Thin JSON-RPC client for the Nexla monitoring MCP server (`nexla triage`).
+
+Separate from ``client.py`` because it's a different protocol (MCP
+``tools/call`` over a stateless streamable-HTTP transport, no session
+handshake needed against this server) and a different base URL
+(``NEXLA_MONITORING_URL``), but reuses the same bearer token
+(:func:`nexla_cli.client.auth_token`) and the same
+:class:`~nexla_cli.errors.CliError`/``EXIT`` mapping so `triage` commands
+fail the same way every other `nexla` command does.
+"""
+
+from __future__ import annotations
+
+import json as jsonlib
+import os
+from typing import Any
+
+import httpx
+import typer
+
+from . import client, dryrun
+from .errors import EXIT, CliError
+
+_HEADERS = {"Content-Type": "application/json", "Accept": "application/json, text/event-stream"}
+
+
+def _base() -> str:
+    url = os.environ.get("NEXLA_MONITORING_URL")
+    if not url:
+        raise CliError(EXIT.CONFIG, "NEXLA_MONITORING_URL is not set")
+    return url
+
+
+def _parse_rpc(r: httpx.Response) -> dict[str, Any]:
+    """Decode a JSON-RPC envelope from either a plain JSON or SSE body.
+
+    The server always answers with ``content-type: text/event-stream``
+    (confirmed live) even for a single, non-streaming reply -- one
+    ``data: {...}`` line. Handle a bare ``application/json`` body too
+    rather than assuming the SSE framing is permanent.
+    """
+    ctype = r.headers.get("content-type", "")
+    if "text/event-stream" in ctype:
+        lines = [ln[len("data:") :].strip() for ln in r.text.splitlines() if ln.startswith("data:")]
+        if not lines:
+            raise CliError(EXIT.UPSTREAM, "empty response from monitoring MCP server")
+        return jsonlib.loads(lines[-1])
+    try:
+        return r.json()
+    except ValueError as e:
+        raise CliError(EXIT.UPSTREAM, f"non-JSON response from monitoring MCP server: {e}") from e
+
+
+def _raise_on_rpc_error(resp: dict[str, Any]) -> None:
+    error = resp.get("error")
+    if error:
+        raise CliError(EXIT.ERROR, error.get("message", "MCP error"))
+
+
+def _post(payload: dict[str, Any]) -> dict[str, Any]:
+    headers = {**_HEADERS, "Authorization": f"Bearer {client.auth_token()}"}
+    with httpx.Client(base_url=_base(), timeout=30.0, headers=headers) as c:
+        try:
+            r = c.post("", json=payload)
+        except httpx.HTTPError as e:
+            raise CliError(EXIT.UPSTREAM, f"request failed: {e}") from e
+    if not r.is_success:
+        raise CliError(
+            EXIT.from_status(r.status_code), f"HTTP {r.status_code} from monitoring MCP server"
+        )
+    resp = _parse_rpc(r)
+    _raise_on_rpc_error(resp)
+    return resp
+
+
+def list_tools() -> list[dict[str, Any]]:
+    """Fetch the live tool catalog (name + ``inputSchema``) via `tools/list`."""
+    resp = _post({"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}})
+    return resp.get("result", {}).get("tools", [])
+
+
+def tool_schema(name: str) -> dict[str, Any] | None:
+    """Look up one tool's live ``inputSchema`` by name, or ``None`` if unknown."""
+    for tool in list_tools():
+        if tool.get("name") == name:
+            return tool.get("inputSchema")
+    return None
+
+
+def call_tool(name: str, arguments: dict[str, Any]) -> Any:
+    """Call one MCP tool and return its decoded JSON payload.
+
+    Unwraps the MCP envelope (``result.content[0].text``, itself a JSON
+    string) down to the plain object every `triage` command renders via
+    ``output.emit`` -- callers never see JSON-RPC/MCP framing.
+    """
+    resp = _post(
+        {
+            "jsonrpc": "2.0",
+            "id": 1,
+            "method": "tools/call",
+            "params": {"name": name, "arguments": arguments},
+        }
+    )
+    result = resp.get("result", {})
+    content = result.get("content") or []
+    text = content[0].get("text") if content and isinstance(content[0], dict) else None
+    if text is None:
+        raise CliError(EXIT.UPSTREAM, "empty tool result from monitoring MCP server")
+    try:
+        payload = jsonlib.loads(text)
+    except jsonlib.JSONDecodeError:
+        payload = {"text": text}
+    if result.get("isError"):
+        message = payload.get("error") if isinstance(payload, dict) else str(payload)
+        raise CliError(EXIT.ERROR, message or "tool reported an error")
+    return payload
+
+
+def run_dry_run(*, tool: str, arguments: dict[str, Any]) -> None:
+    """Validate ``arguments`` against the tool's live ``inputSchema``, then exit.
+
+    Mirrors ``dryrun.run_dry_run``'s contract (0/valid, 2/invalid,
+    same ``{"valid": ..., "body"|"errors": ...}`` shape) but sources its
+    schema from this server's own `tools/list` instead of
+    `/openapi.json` -- every `triage` tool is a read-only query, so there
+    is no mutating call to skip, only a local params check before the
+    round trip. Always exits the process; the caller never falls through
+    to the real ``call_tool`` after this returns.
+    """
+    schema = tool_schema(tool)
+    if schema is None:
+        raise CliError(EXIT.ERROR, f"unknown monitoring tool '{tool}' (server schema drift?)")
+    errors = dryrun.validate_body(schema, arguments)
+    if errors:
+        typer.echo(jsonlib.dumps({"valid": False, "errors": errors}, indent=2), err=True)
+        raise typer.Exit(EXIT.VALIDATION)
+    typer.echo(jsonlib.dumps({"valid": True, "body": arguments}, indent=2, default=str))
+    raise typer.Exit(EXIT.OK)

nexla_cli/openapi_client.py

@@ -0,0 +1,196 @@
+"""Shared live-schema fetch + resource/verb -> route lookup.
+
+Both ``nexla schema`` (``schema.py``) and ``--dry-run`` (``dryrun.py``) need
+the same thing: fetch ``/openapi.json`` (unauthenticated), filter to
+``/nexla/*`` paths, and resolve a ``(resource, verb)`` pair to its
+``(method, path, request_schema | None)``. Built once here so neither
+module duplicates the fetch-and-filter logic — if you find yourself
+writing a second ``client.request("GET", "/openapi.json", ...)`` call site
+outside this module, route it through :func:`fetch_openapi` instead.
+
+The live doc's ``operationId`` is FastAPI's verbose auto-generated form
+(e.g. ``create_source_nexla_sources_post``), not a clean ``sources.create``
+token (confirmed live 2026-07-08) — :data:`ROUTES` is a hand-maintained
+``(resource, verb) -> (method, path template)`` table instead, mirroring
+the exhaustive resource/verb surface documented in
+``plans/2026-07-07-nexla-agent-overview.md``'s "Resource / verb surface"
+table (17 resources, ~61 routes). Path templates use ``{id}`` (or a named
+placeholder for nested resources) purely as a human-readable token — they
+are matched against the live doc's own ``{...}`` path-parameter names
+positionally (see :func:`resolve`), not by exact placeholder-name string
+match, since the live doc may spell a given path parameter differently
+(e.g. ``{source_id}`` vs ``{id}``).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from . import client
+
+# (resource, verb) -> (HTTP method, path template). Hand-maintained against
+# the overview plan's "Resource / verb surface" table -- do NOT derive this
+# from `operationId` parsing (see module docstring for why).
+ROUTES: dict[tuple[str, str], tuple[str, str]] = {
+    ("sources", "list"): ("GET", "/nexla/sources"),
+    ("sources", "get"): ("GET", "/nexla/sources/{id}"),
+    ("sources", "create"): ("POST", "/nexla/sources"),
+    ("sources", "update"): ("PATCH", "/nexla/sources/{id}"),
+    ("sources", "activate"): ("POST", "/nexla/sources/{id}/activate"),
+    ("sources", "pause"): ("POST", "/nexla/sources/{id}/pause"),
+    ("sources", "delete"): ("DELETE", "/nexla/sources/{id}"),
+    ("sources", "sample"): ("POST", "/nexla/sources/{id}/sample"),
+    ("sources", "file-upload"): ("POST", "/nexla/sources/{id}/file_upload"),
+    ("sinks", "list"): ("GET", "/nexla/sinks"),
+    ("sinks", "get"): ("GET", "/nexla/sinks/{id}"),
+    ("sinks", "create"): ("POST", "/nexla/sinks"),
+    ("sinks", "update"): ("PATCH", "/nexla/sinks/{id}"),
+    ("sinks", "activate"): ("POST", "/nexla/sinks/{id}/activate"),
+    ("sinks", "pause"): ("POST", "/nexla/sinks/{id}/pause"),
+    ("sinks", "delete"): ("DELETE", "/nexla/sinks/{id}"),
+    ("nexsets", "list"): ("GET", "/nexla/nexsets"),
+    ("nexsets", "get"): ("GET", "/nexla/nexsets/{id}"),
+    ("nexsets", "transform"): ("POST", "/nexla/nexsets/{id}/transform"),
+    ("nexsets", "activate"): ("PUT", "/nexla/nexsets/{id}/activate"),
+    ("credentials", "list"): ("GET", "/nexla/credentials"),
+    ("credentials", "get"): ("GET", "/nexla/credentials/{id}"),
+    ("credentials", "create"): ("POST", "/nexla/credentials"),
+    ("credentials", "update"): ("PATCH", "/nexla/credentials/{id}"),
+    ("credentials", "delete"): ("DELETE", "/nexla/credentials/{id}"),
+    ("flows", "list"): ("GET", "/nexla/flows"),
+    ("flows", "get"): ("GET", "/nexla/flows/{id}"),
+    ("flows", "activate"): ("PUT", "/nexla/flows/{id}/activate"),
+    ("flows", "pause"): ("PUT", "/nexla/flows/{id}/pause"),
+    ("flows", "delete"): ("DELETE", "/nexla/flows/{id}"),
+    ("transforms", "test"): ("POST", "/nexla/transforms/test"),
+    ("probe", "run"): ("POST", "/nexla/probe"),
+    ("connectors", "search"): ("GET", "/nexla/connectors/search"),
+    ("connectors", "describe"): ("GET", "/nexla/connectors/describe/{name}"),
+    ("connectors", "describe-credential"): ("GET", "/nexla/connectors/describe/{name}/credential"),
+    ("connectors", "describe-credential-mode"): (
+        "GET",
+        "/nexla/connectors/describe/{name}/credential/{auth_mode}",
+    ),
+    ("connectors", "describe-source"): ("GET", "/nexla/connectors/describe/{name}/source"),
+    ("connectors", "describe-source-endpoint"): (
+        "GET",
+        "/nexla/connectors/describe/{name}/source/{endpoint}",
+    ),
+    ("connectors", "describe-sink"): ("GET", "/nexla/connectors/describe/{name}/sink"),
+    ("connectors", "describe-sink-endpoint"): (
+        "GET",
+        "/nexla/connectors/describe/{name}/sink/{endpoint}",
+    ),
+    ("toolsets", "list"): ("GET", "/nexla/toolsets"),
+    ("toolsets", "get"): ("GET", "/nexla/toolsets/{id}"),
+    ("toolsets", "create"): ("POST", "/nexla/toolsets"),
+    ("toolsets", "update"): ("PATCH", "/nexla/toolsets/{id}"),
+    ("toolsets", "delete"): ("DELETE", "/nexla/toolsets/{id}"),
+    ("toolsets", "add-nexsets"): ("POST", "/nexla/toolsets/{id}/nexsets"),
+    ("tools", "list"): ("GET", "/nexla/tools"),
+    ("tools", "get"): ("GET", "/nexla/tools/{id}"),
+    ("tools", "set-runtime-config"): ("PATCH", "/nexla/tools/{id}/runtime-config"),
+    ("tools", "clear-runtime-config"): ("DELETE", "/nexla/tools/{id}/runtime-config"),
+    ("tools", "delete"): ("DELETE", "/nexla/tools/{id}"),
+    ("mcp-servers", "list"): ("GET", "/nexla/toolsets/{toolset_id}/mcp-servers"),
+    ("mcp-servers", "attach"): ("POST", "/nexla/toolsets/{toolset_id}/mcp-servers"),
+    ("mcp-servers", "sync"): ("POST", "/nexla/toolsets/{toolset_id}/mcp-servers/{id}/sync"),
+    ("mcp-servers", "detach"): ("DELETE", "/nexla/toolsets/{toolset_id}/mcp-servers/{id}"),
+    ("context", "get"): ("GET", "/nexla/context"),
+    ("orgs", "list"): ("GET", "/nexla/orgs"),
+    ("orgs", "get"): ("GET", "/nexla/orgs/{id}"),
+    ("code-containers", "list"): ("GET", "/nexla/code-containers"),
+    ("metrics", "catalog"): ("GET", "/nexla/metrics/catalog"),
+    ("metrics", "for-resource"): ("GET", "/nexla/metrics/{resource_type}/{resource_id}"),
+    ("metrics", "get"): ("GET", "/nexla/metrics/{resource_type}/{resource_id}/{metric_type}"),
+    ("users", "list"): ("GET", "/nexla/users"),
+    ("users", "get"): ("GET", "/nexla/users/{id}"),
+    ("notifications", "list"): ("GET", "/nexla/notifications"),
+}
+
+
+def fetch_openapi() -> dict[str, Any]:
+    """Fetch the live, unauthenticated ``/openapi.json`` document.
+
+    One ``client.request(...)`` call site for the whole CLI — ``schema``
+    and ``--dry-run`` both go through this, never a second direct fetch.
+    """
+    spec: dict[str, Any] = client.request("GET", "/openapi.json", require_auth=False)
+    return spec
+
+
+def nexla_paths(spec: dict[str, Any]) -> dict[str, Any]:
+    """Filter ``spec['paths']`` down to the ``/nexla/*`` subset."""
+    paths: dict[str, Any] = spec.get("paths", {})
+    return {p: m for p, m in paths.items() if p.startswith("/nexla")}
+
+
+def _placeholder_shape(path: str) -> tuple[str, int]:
+    """Reduce a path to (literal-segments-joined, placeholder-count).
+
+    Used to match our hand-maintained ``ROUTES`` template against the live
+    doc's actual path string regardless of the exact placeholder name the
+    live doc happens to use (e.g. ``{id}`` vs ``{source_id}``) — only the
+    literal segments and the *position*/count of ``{...}`` placeholders
+    need to agree.
+    """
+    segments = path.strip("/").split("/")
+    literal = "/".join(s if not (s.startswith("{") and s.endswith("}")) else "\0" for s in segments)
+    count = sum(1 for s in segments if s.startswith("{") and s.endswith("}"))
+    return literal, count
+
+
+def resolve(spec: dict[str, Any], resource: str, verb: str) -> dict[str, Any] | None:
+    """Resolve ``(resource, verb)`` to its live path item + method.
+
+    Returns ``{"method": ..., "path": ..., "operation": <path-item's
+    method entry from the live doc>}`` or ``None`` if the (resource, verb)
+    pair isn't in :data:`ROUTES`, or the templated path can't be matched
+    against any path actually present in the live doc (drift between this
+    table and the deployed API).
+    """
+    key = (resource, verb)
+    if key not in ROUTES:
+        return None
+    method, template = ROUTES[key]
+    want_shape = _placeholder_shape(template)
+    paths = nexla_paths(spec)
+    for live_path, methods in paths.items():
+        if _placeholder_shape(live_path) != want_shape:
+            continue
+        operation = methods.get(method.lower())
+        if operation is not None:
+            return {"method": method, "path": live_path, "operation": operation}
+    return None
+
+
+def request_schema(spec: dict[str, Any], ref: str) -> dict[str, Any]:
+    """Dereference a single-level ``#/components/schemas/<Name>`` ``$ref``.
+
+    Only single-level dereferencing is implemented — the generated
+    schemas observed on the live API are flat with ``anyOf``-for-optional
+    fields rather than deeply nested ``$ref`` chains (confirmed by
+    inspecting ``CreateSourceIn`` this session). If a future schema nests
+    a ``$ref`` inside a property, this returns that property's raw
+    ``{"$ref": ...}`` object unresolved rather than silently guessing —
+    extend this function if/when that shape shows up for real.
+    """
+    name = ref.rsplit("/", 1)[-1]
+    schemas: dict[str, Any] = spec.get("components", {}).get("schemas", {})
+    result: dict[str, Any] = schemas.get(name, {})
+    return result
+
+
+def request_body_schema(spec: dict[str, Any], operation: dict[str, Any]) -> dict[str, Any] | None:
+    """Extract + dereference an operation's JSON request-body schema, if any."""
+    body = operation.get("requestBody")
+    if not isinstance(body, dict):
+        return None
+    content = body.get("content", {}).get("application/json", {})
+    schema = content.get("schema")
+    if not isinstance(schema, dict):
+        return None
+    ref = schema.get("$ref")
+    if isinstance(ref, str):
+        return request_schema(spec, ref)
+    return schema

nexla_cli/output.py

@@ -0,0 +1,146 @@
+"""Human-readable table/kv rendering plus agent-facing json/ndjson output.
+
+Deliberately kept to stdlib string formatting — no table library (rung 2/5
+is enough here).
+"""
+
+from __future__ import annotations
+
+import json as jsonlib
+import os
+import sys
+from typing import Any
+
+import typer
+
+from .sanitize import sanitize
+
+_DEFAULT_MAX_COL_WIDTH = 40
+
+
+def resolve_mode(flag: str | None) -> str:
+    """Resolve the active output mode: explicit flag > env > TTY autodetect."""
+    if flag:
+        return flag.lower()
+    env = os.environ.get("NEXLA_OUTPUT") or os.environ.get("OUTPUT_FORMAT")
+    if env:
+        return env.lower()
+    # ponytail: the whole human/agent split hinges on this one line.
+    return "table" if sys.stdout.isatty() else "json"
+
+
+def ctx_mode(ctx: typer.Context) -> str:
+    """Resolve the active output mode from the global callback's ``ctx.obj``."""
+    obj = ctx.obj or {}
+    return resolve_mode(obj.get("mode"))
+
+
+def ctx_fields(ctx: typer.Context) -> list[str] | None:
+    """Read the ``--fields`` mask stashed on ``ctx.obj`` by the global callback."""
+    obj = ctx.obj or {}
+    fields: list[str] | None = obj.get("fields")
+    return fields
+
+
+def ctx_page_all(ctx: typer.Context) -> bool:
+    """Read the ``--page-all`` flag stashed on ``ctx.obj`` by the global callback."""
+    obj = ctx.obj or {}
+    return bool(obj.get("page_all"))
+
+
+def _mask(data: Any, fields: list[str]) -> Any:
+    def keep(d: dict[str, Any]) -> dict[str, Any]:
+        return {k: d.get(k) for k in fields}
+
+    if isinstance(data, list):
+        return [keep(d) if isinstance(d, dict) else d for d in data]
+    if isinstance(data, dict):
+        return keep(data)
+    return data
+
+
+def emit(
+    data: Any,
+    *,
+    mode: str = "table",
+    columns: list[str] | None = None,
+    fields: list[str] | None = None,
+) -> None:
+    """Render ``data`` as a table/kv block (human), or json/ndjson (agent).
+
+    List endpoints return the ``Page[T]`` envelope
+    (``{items, page, per_page, next_page, truncated}``), never a bare
+    array — unwrap ``items`` before branching on type or masking,
+    otherwise every ``list`` command would render/mask the envelope dict
+    as a single row. In ``json`` mode the envelope (with masked items
+    spliced back in) is preserved so an agent can still see pagination
+    metadata.
+
+    Every value is run through :func:`nexla_cli.sanitize.sanitize` before
+    rendering, in every mode — API responses are untrusted data, and an
+    agent parsing JSON is exactly as exposed to a hidden zero-width
+    character or an embedded ANSI escape as a human reading a table.
+    """
+    if data is None:
+        return
+    data = sanitize(data)
+    envelope: dict[str, Any] | None = None
+    if isinstance(data, dict) and "items" in data:
+        envelope = data
+        data = data["items"]
+    if fields:
+        data = _mask(data, fields)
+    if mode == "ndjson":
+        for row in data if isinstance(data, list) else [data]:
+            typer.echo(jsonlib.dumps(row, default=str))
+    elif mode == "json":
+        payload: Any = {**envelope, "items": data} if envelope is not None else data
+        typer.echo(jsonlib.dumps(payload, indent=2, default=str))
+    elif isinstance(data, list):
+        _table(data, columns)
+    else:
+        _kv(data)
+
+
+def _stringify(value: Any) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    return str(value)
+
+
+def _truncate(value: str, width: int) -> str:
+    if len(value) <= width:
+        return value
+    return value[: width - 1] + "…"
+
+
+def _table(rows: list[Any], columns: list[str] | None) -> None:
+    if not rows:
+        typer.echo("(no results)")
+        return
+    dict_rows = [r for r in rows if isinstance(r, dict)]
+    if not dict_rows:
+        for r in rows:
+            typer.echo(_stringify(r))
+        return
+    cols = columns or list(dict_rows[0].keys())
+    str_rows = [[_truncate(_stringify(r.get(c)), _DEFAULT_MAX_COL_WIDTH) for c in cols] for r in dict_rows]
+    widths = [max(len(c), *(len(row[i]) for row in str_rows)) for i, c in enumerate(cols)]
+    header = "  ".join(c.upper().ljust(widths[i]) for i, c in enumerate(cols))
+    typer.echo(header)
+    for row in str_rows:
+        typer.echo("  ".join(cell.ljust(widths[i]) for i, cell in enumerate(row)))
+
+
+def _kv(data: Any) -> None:
+    if not isinstance(data, dict):
+        typer.echo(_stringify(data))
+        return
+    if not data:
+        typer.echo("(empty)")
+        return
+    width = max(len(str(k)) for k in data)
+    for k, v in data.items():
+        typer.echo(f"{str(k).ljust(width)} : {_stringify(v)}")

nexla_cli/resources/__init__.py

@@ -0,0 +1 @@
+"""One module per `/nexla/*` resource, each a thin typer command group."""

nexla_cli/resources/code_containers.py

@@ -0,0 +1,23 @@
+"""`nexla code-containers` — thin, 501 passthrough.
+
+Mirrors ``routers/nexla_agent_api/code_containers.py``. Scaffolded for a
+consistent help tree / stable exit code; nothing real behind it yet.
+"""
+
+from __future__ import annotations
+
+import typer
+
+from .. import client, output
+
+app = typer.Typer(name="code-containers", help="Manage Nexla code containers (not implemented in v1).", no_args_is_help=True)
+
+
+@app.command("list")
+def list_(ctx: typer.Context) -> None:
+    """List code containers. (Not implemented in v1.)"""
+    output.emit(
+        client.request("GET", "/nexla/code-containers"),
+        mode=output.ctx_mode(ctx),
+        fields=output.ctx_fields(ctx),
+    )

nexla_cli/resources/connectors.py

@@ -0,0 +1,125 @@
+"""`nexla connectors` — search + hierarchical describe.
+
+No plain list/get — this is a describe/search-only surface. Mirrors
+``routers/nexla_agent_api/connectors.py``.
+"""
+
+from __future__ import annotations
+
+import typer
+
+from .. import client, output, validate
+
+app = typer.Typer(name="connectors", help="Search and describe Nexla connectors.", no_args_is_help=True)
+
+
+@app.command("search")
+def search(
+    ctx: typer.Context,
+    query: str | None = typer.Argument(None, help="Search term, e.g. 's3'"),
+    kind: str | None = typer.Option(None),
+    supports: str | None = typer.Option(None, help="'credential', 'source', or 'sink'"),
+    include_unsupported: bool = typer.Option(False),
+    limit: int = typer.Option(25),
+) -> None:
+    """Search the connector catalog."""
+    params: dict[str, object] = {"include_unsupported": include_unsupported, "limit": limit}
+    if query is not None:
+        params["q"] = query
+    if kind is not None:
+        params["kind"] = kind
+    if supports is not None:
+        params["supports"] = supports
+    output.emit(
+        client.request("GET", "/nexla/connectors/search", params=params),
+        mode=output.ctx_mode(ctx),
+        fields=output.ctx_fields(ctx),
+        columns=["name", "display_name", "kind", "supported", "score"],
+    )
+
+
+@app.command("describe")
+def describe(
+    ctx: typer.Context,
+    name: str,
+    include: str | None = typer.Option(None, help="Comma-separated subset of credential,source,sink"),
+) -> None:
+    """Describe a connector's capabilities."""
+    name = validate.resource_id(name)
+    params: dict[str, object] = {}
+    if include is not None:
+        params["include"] = include
+    output.emit(
+        client.request("GET", f"/nexla/connectors/describe/{name}", params=params),
+        mode=output.ctx_mode(ctx),
+        fields=output.ctx_fields(ctx),
+    )
+
+
+@app.command("describe-credential")
+def describe_credential(ctx: typer.Context, name: str) -> None:
+    """List a connector's auth modes."""
+    name = validate.resource_id(name)
+    output.emit(
+        client.request("GET", f"/nexla/connectors/describe/{name}/credential"),
+        mode=output.ctx_mode(ctx),
+        fields=output.ctx_fields(ctx),
+    )
+
+
+@app.command("describe-credential-mode")
+def describe_credential_mode(ctx: typer.Context, name: str, auth_mode: str) -> None:
+    """Describe a specific auth mode's required fields."""
+    name = validate.resource_id(name)
+    auth_mode = validate.resource_id(auth_mode)
+    output.emit(
+        client.request("GET", f"/nexla/connectors/describe/{name}/credential/{auth_mode}"),
+        mode=output.ctx_mode(ctx),
+        fields=output.ctx_fields(ctx),
+    )
+
+
+@app.command("describe-source")
+def describe_source(ctx: typer.Context, name: str) -> None:
+    """Describe how to create a source for this connector."""
+    name = validate.resource_id(name)
+    output.emit(
+        client.request("GET", f"/nexla/connectors/describe/{name}/source"),
+        mode=output.ctx_mode(ctx),
+        fields=output.ctx_fields(ctx),
+    )
+
+
+@app.command("describe-source-endpoint")
+def describe_source_endpoint(ctx: typer.Context, name: str, endpoint: str) -> None:
+    """Describe a specific API-connector source endpoint."""
+    name = validate.resource_id(name)
+    endpoint = validate.resource_id(endpoint)
+    output.emit(
+        client.request("GET", f"/nexla/connectors/describe/{name}/source/{endpoint}"),
+        mode=output.ctx_mode(ctx),
+        fields=output.ctx_fields(ctx),
+    )
+
+
+@app.command("describe-sink")
+def describe_sink(ctx: typer.Context, name: str) -> None:
+    """Describe how to create a sink for this connector."""
+    name = validate.resource_id(name)
+    output.emit(
+        client.request("GET", f"/nexla/connectors/describe/{name}/sink"),
+        mode=output.ctx_mode(ctx),
+        fields=output.ctx_fields(ctx),
+    )
+
+
+@app.command("describe-sink-endpoint")
+def describe_sink_endpoint(ctx: typer.Context, name: str, endpoint: str) -> None:
+    """Describe a specific API-connector sink endpoint."""
+    name = validate.resource_id(name)
+    endpoint = validate.resource_id(endpoint)
+    output.emit(
+        client.request("GET", f"/nexla/connectors/describe/{name}/sink/{endpoint}"),
+        mode=output.ctx_mode(ctx),
+        fields=output.ctx_fields(ctx),
+    )

nexla_cli/resources/context.py

@@ -0,0 +1,22 @@
+"""`nexla context` — consolidated flows/sources/nexsets/credentials/connectors.
+
+Mirrors ``routers/nexla_agent_api/context.py``. Single ``get`` command.
+"""
+
+from __future__ import annotations
+
+import typer
+
+from .. import client, output
+
+app = typer.Typer(name="context", help="Fetch consolidated Nexla context.", no_args_is_help=True)
+
+
+@app.command("get")
+def get(ctx: typer.Context) -> None:
+    """Fetch flows/credentials/sources/nexsets/catalog for @-mentions."""
+    output.emit(
+        client.request("GET", "/nexla/context"),
+        mode=output.ctx_mode(ctx),
+        fields=output.ctx_fields(ctx),
+    )