cmpnd 0.66.0__tar.gz → 0.68.0__tar.gz

{cmpnd-0.66.0 → cmpnd-0.68.0}/AGENTS.md

@@ -92,7 +92,7 @@ knowing:
   Run `uv lock` and commit the result. A stale lock makes every `uv` command
   rewrite it.
 - `basedpyright` takes no path argument. A path overrides pyproject's
-  `include`, so `basedpyright cmpnd` skips `tests/e2e` and `tests/stress` and
+  `include`, so `basedpyright cmpnd` skips `tests/e2e` and `tests/real_models` and
   passes changes CI rejects.
 
 **This tree's SDK and CLI run against each live self-host release.**
@@ -234,7 +234,10 @@ first. Its failures name the attribute or class that moved.
 
 To add a verb to both front-ends, add a `Verb(...)` row to `cli/verbs.py`, add
 its `add_parser` call in `top.register()`, and add the entity method or the
-`_make_namespace` function. The parity test fails until all three agree.
+`_make_namespace` function. The parity test fails until all three agree. A
+verb that repeats a namespaced command sets `shortcut_for`, and its help then
+starts with "Shortcut for `cmpnd deployments list`". The parity test checks
+that the named command exists.
 
 When you touch a handler:
 

{cmpnd-0.66.0 → cmpnd-0.68.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cmpnd
-Version: 0.66.0
+Version: 0.68.0
 Summary: DSPy observability and deployment SDK for cmpnd
 Project-URL: Homepage, https://cmpnd.ai
 Author-email: cmpnd <hello@cmpnd.ai>
@@ -669,6 +669,12 @@ global config. Use it as a context manager or as a plain object.
   its best `DeployedProgram`.
 - `list_traces(**filters)` and `get_trace(trace_id)` read traces with the
   client's credentials. They flush the client's traces first.
+- `list_deployments(status=None, since=None, limit=50, offset=0)` and
+  `get_deployment(deployment_id)` read deployment records, as
+  `cmpnd deployments list` and `show` do.
+- `get_deployment_source(deployment_id, path=None)` returns the program file a
+  deployment stores, as `cmpnd inspect --source` does. A continuation's
+  deployment holds the program the continuation runs.
 - `close()` flushes the client's traces and closes the client. A closed
   client raises `RuntimeError` on every method.
 

{cmpnd-0.66.0 → cmpnd-0.68.0}/README.md

@@ -618,6 +618,12 @@ global config. Use it as a context manager or as a plain object.
   its best `DeployedProgram`.
 - `list_traces(**filters)` and `get_trace(trace_id)` read traces with the
   client's credentials. They flush the client's traces first.
+- `list_deployments(status=None, since=None, limit=50, offset=0)` and
+  `get_deployment(deployment_id)` read deployment records, as
+  `cmpnd deployments list` and `show` do.
+- `get_deployment_source(deployment_id, path=None)` returns the program file a
+  deployment stores, as `cmpnd inspect --source` does. A continuation's
+  deployment holds the program the continuation runs.
 - `close()` flushes the client's traces and closes the client. A closed
   client raises `RuntimeError` on every method.
 

cmpnd-0.68.0/cmpnd/_deployments.py

@@ -0,0 +1,105 @@
+"""Deployment reads behind ``cmpnd.Client``: the record list, one record, its stored source and its typed metadata."""
+
+from __future__ import annotations
+
+import io
+import tokenize
+from typing import Any, Protocol
+
+from . import _http
+from .deployment_metadata import DeploymentMetadataError, DeploymentSignatureResponse
+
+MAX_DEPLOYMENTS_PER_PAGE = 500
+
+
+class _JSONReader(Protocol):
+    def get(self, path: str) -> Any: ...
+
+
+def read_signature(client: _JSONReader, deployment_id: str) -> DeploymentSignatureResponse:
+    """Read one deployment's persisted signature through an existing client."""
+    value = client.get(f"/api/v1/deployments/{deployment_id}/signature")
+    response = DeploymentSignatureResponse.from_dict(value)
+    if response.deployment_id != deployment_id:
+        raise DeploymentMetadataError(
+            f"response deployment_id {response.deployment_id!r} does not match {deployment_id!r}"
+        )
+    return response
+
+
+def get_signature(
+    deployment_id: str,
+    *,
+    api_key: str,
+    endpoint: str,
+    timeout: float | None = None,
+) -> DeploymentSignatureResponse:
+    """Read one deployment's persisted signature with explicit credentials."""
+    client = (
+        _http.ApiClient(api_key, endpoint) if timeout is None else _http.ApiClient(api_key, endpoint, timeout=timeout)
+    )
+    return read_signature(client, deployment_id)
+
+
+def list_deployments(
+    *,
+    status: str | None = None,
+    since: str | None = None,
+    limit: int = 50,
+    offset: int = 0,
+    api_key: str,
+    endpoint: str,
+) -> dict[str, Any]:
+    """List the organization's deployments, newest first.
+
+    Returns ``{"deployments": [...], "has_more": bool, ...}``. ``status`` is one
+    of ``pending``, ``parsing``, ``optimizing``, ``ready`` or ``failed``, and
+    ``since`` is an ISO 8601 timestamp. The route pages by page number, so
+    ``offset`` must be a whole multiple of ``limit``. The route returns at most
+    500 deployments per page, so ``limit`` must not exceed 500.
+    """
+    if limit <= 0:
+        raise _http.ApiError("limit must be positive")
+    if limit > MAX_DEPLOYMENTS_PER_PAGE:
+        raise _http.ApiError(
+            f"limit must not exceed {MAX_DEPLOYMENTS_PER_PAGE}; the deployments route returns at most "
+            f"{MAX_DEPLOYMENTS_PER_PAGE} per page"
+        )
+    if offset < 0:
+        raise _http.ApiError("offset must not be negative")
+    if offset % limit != 0:
+        lower = (offset // limit) * limit
+        raise _http.ApiError(
+            f"offset must be a multiple of limit (the deployments route pages by page number); "
+            f"try offset {lower} or {lower + limit}"
+        )
+    params = {"per_page": str(limit), "page": str(offset // limit + 1)}
+    if status is not None:
+        params["status"] = status
+    if since is not None:
+        params["since"] = since
+    return _http.ApiClient(api_key, endpoint).get("/api/v1/deployments", params=params)
+
+
+def get_deployment(deployment_id: str, *, api_key: str, endpoint: str) -> dict[str, Any]:
+    """Read one deployment's record: its status, program, model and metadata."""
+    return _http.ApiClient(api_key, endpoint).get(f"/api/v1/deployments/{deployment_id}")
+
+
+def get_source(deployment_id: str, *, path: str | None = None, api_key: str, endpoint: str) -> str:
+    """Read one file of a deployment's stored source as text.
+
+    Without ``path`` it reads the program file the stored bundle names. With
+    ``path`` it reads that archive-relative member. It decodes the file with the
+    encoding the file declares in a PEP 263 coding comment, and with UTF-8 when
+    the file declares none.
+    """
+    client = _http.ApiClient(api_key, endpoint)
+    route = f"/api/v1/deployments/{deployment_id}/source"
+    if path is None:
+        path = client.get(route).get("program")
+        if not path:
+            raise _http.ApiError(f"the stored source of deployment {deployment_id} names no program file")
+    raw = client.get_bytes(route, params={"path": path})
+    encoding, _lines = tokenize.detect_encoding(io.BytesIO(raw).readline)
+    return raw.decode(encoding)

{cmpnd-0.66.0 → cmpnd-0.68.0}/cmpnd/cli/__init__.py

@@ -107,7 +107,11 @@ def parse(parser: argparse.ArgumentParser, argv: list[str]) -> argparse.Namespac
 def main() -> None:
     parser = tree_help.TreeHelpParser(
         prog="cmpnd",
-        description="CMPND platform CLI — deploy, run, and inspect DSPy programs.",
+        description=(
+            "CMPND platform CLI — deploy, run, and inspect DSPy programs.\n\n"
+            "The top-level commands are the Docker-style deploy-and-run loop. ps, run and inspect are\n"
+            "shortcuts for deployments list, run and show."
+        ),
         epilog=_EPILOG,
         formatter_class=argparse.RawDescriptionHelpFormatter,
     )

{cmpnd-0.66.0 → cmpnd-0.68.0}/cmpnd/cli/commands/programs.py

@@ -207,6 +207,19 @@ def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
     purge.add_argument("--force", action="store_true", help="Skip the confirmation (required when not on a terminal)")
     purge.set_defaults(func=handle_purge)
 
+    rename = sub.add_parser(
+        "rename",
+        help="Name or rename a program",
+        description=(
+            "Make NAME the current name of PROGRAM. The name it had keeps resolving to it, so code that still "
+            "declares the old name reaches the same program, with its id and history. A name another program "
+            "answers to is refused."
+        ),
+    )
+    rename.add_argument("program", metavar="PROGRAM", help="Program name or p_ id")
+    rename.add_argument("new_name", metavar="NAME", help="The program's new name, unique in your organization")
+    rename.set_defaults(func=handle_rename)
+
     select = sub.add_parser("select", help="Pin an optimization run as this program's chosen version")
     select.add_argument("id", help=_COMPILED_HASH_HELP)
     select.add_argument("--run", dest="run_id", required=True, help="Optimization run ID (op_...) to pin")
@@ -624,6 +637,38 @@ def handle_purge(client: api_client.ApiClient, args: Any) -> Any:
     return _trash_write(client, f"/api/v1/programs/{program_id}/purge")
 
 
+def handle_rename(client: api_client.ApiClient, args: Any) -> Any:
+    """Make ``args.new_name`` the current name of the program ``args.program`` names, keeping its id."""
+    from ... import programs
+    from . import top
+
+    try:
+        programs.validate_program_name(args.new_name)
+    except ValueError as exc:
+        raise api_client.CliError(str(exc)) from exc
+    program_id, trashed = resolve(client, args.program, old_server_remedy=_rename_remedy())
+    if trashed:
+        raise api_client.CliError(
+            f"{args.program} is in the Trash. Restore it with `{top.hint_programs('restore', args.program)}` "
+            "before you rename it."
+        )
+    try:
+        return client.post(f"/api/v1/programs/{program_id}/rename", json={"name": args.new_name})
+    except api_client.CliError as exc:
+        # A server from before the rename route answers 405, because its GET dispatcher owns the path.
+        if exc.status_code == 405:
+            _refuse_if_old(client, exc, _rename_remedy(program_id))
+            raise api_client.CliError(
+                f"this cmpnd server predates renaming a program through the API. {_rename_remedy(program_id)}"
+            ) from exc
+        raise
+
+
+def _rename_remedy(program_id: str = "") -> str:
+    where = f"on its page in the web app, at /ui/programs/{program_id}" if program_id else "in the web app"
+    return f"Rename the program {where}, or upgrade the server."
+
+
 def _trash_listing(client: api_client.ApiClient) -> Any:
     """GET the Trash. On a server from before the Trash API it answers 404, which is the old-server signal."""
     try:

{cmpnd-0.66.0 → cmpnd-0.68.0}/cmpnd/cli/commands/provider_credentials.py

@@ -5,7 +5,7 @@ platform spend on your behalf when a program of yours runs?
 
     cmpnd credentials create --name luna-exec --preset lunaroute       # a model provider
     cmpnd credentials create --kind mcp --server URL --name n …         # an MCP tool server
-    cmpnd credentials list
+    cmpnd credentials list --text
     cmpnd credentials protocols luna-exec --add system_one
     cmpnd credentials default luna-exec
     cmpnd credentials delete --name luna-exec --force
@@ -70,7 +70,7 @@ import sys
 from argparse import ArgumentParser, _SubParsersAction
 from typing import Any
 
-from .. import api_client, deprecation
+from .. import api_client, deprecation, views
 
 #: The placements the platform's credentialed egress can compose a credential into.
 #: Closed set, and the same three strings `cmpnd.mcp_tools`'s auth shapes record.
@@ -156,7 +156,7 @@ def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
     deprecation.alias(sub, "add", "create", func=handle_create, configure=_seal_args)
 
     listing = sub.add_parser("list", help="Show your org's credentials, their protocols and the default")
-    listing.add_argument("--json", action="store_true", help="Emit the raw JSON instead of the rendering")
+    views.add_text_flag(listing)
     listing.set_defaults(func=handle_list)
 
     protocols = sub.add_parser(
@@ -393,7 +393,7 @@ def handle_list(client: api_client.ApiClient, args: Any) -> Any:
     # Metadata only: the platform's projection carries no key material, not even its
     # length, so there is nothing here to redact.
     payload = client.get(_ROOT)
-    if getattr(args, "json", False) or not isinstance(payload, dict):
+    if not getattr(args, "text", False) or not isinstance(payload, dict):
         return payload
     credentials = [c for c in payload.get("credentials") or [] if isinstance(c, dict)]
     default = payload.get("default")

{cmpnd-0.66.0 → cmpnd-0.68.0}/cmpnd/cli/commands/tool_servers.py

@@ -6,8 +6,8 @@ agreed those declarations may reach. A server here carries the credential it is
 with, and the allow-list of tools on it a deploy is permitted to name.
 
     cmpnd tool-servers create --url https://mcp.exa.ai/mcp --credential exa-prod
-    cmpnd tool-servers list
-    cmpnd tool-servers show <server_id>
+    cmpnd tool-servers list --text
+    cmpnd tool-servers show <server_id> --text
     cmpnd tool-servers allow <server_id> web_search_exa
     cmpnd tool-servers deny <server_id> --all
     cmpnd tool-servers refresh <server_id>
@@ -48,7 +48,7 @@ import json
 from argparse import ArgumentParser, _SubParsersAction
 from typing import Any
 
-from .. import api_client
+from .. import api_client, views
 from . import provider_credentials
 
 _ROOT = "/api/v1/org/tool-servers"
@@ -66,7 +66,7 @@ def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
     create.set_defaults(func=handle_create)
 
     listing = sub.add_parser("list", help="Show the tool servers your org has registered")
-    listing.add_argument("--json", action="store_true", help="Emit the raw JSON instead of the rendering")
+    views.add_text_flag(listing)
     listing.set_defaults(func=handle_list)
 
     show = sub.add_parser("show", help="Show one server, its credential, and its tools")
@@ -74,9 +74,9 @@ def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
     show.add_argument(
         "--schemas",
         action="store_true",
-        help="Also print each tool's reduced argument schema — the shape the platform will enforce",
+        help="With --text, also print each tool's reduced argument schema — the shape the platform will enforce",
     )
-    show.add_argument("--json", action="store_true", help="Emit the raw JSON instead of the rendering")
+    views.add_text_flag(show)
     show.set_defaults(func=handle_show)
 
     for verb, effect in (
@@ -232,7 +232,7 @@ def handle_create(client: api_client.ApiClient, args: Any) -> Any:
 
 def handle_list(client: api_client.ApiClient, args: Any) -> Any:
     payload = client.get(_ROOT)
-    if getattr(args, "json", False):
+    if not getattr(args, "text", False):
         return payload
     servers = _servers(payload)
     if not servers:
@@ -246,13 +246,13 @@ def handle_list(client: api_client.ApiClient, args: Any) -> Any:
             f"{str(server.get('id', '')).ljust(14)} {str(server.get('name') or '').ljust(16)} "
             f"{server.get('url', '')}  [{server.get('credential_name') or 'no credential'}]"
         )
-    print("Read one server's tools and its allow-list with `cmpnd tool-servers show <server_id>`.")
+    print("Read one server's tools and its allow-list with `cmpnd tool-servers show <server_id> --text`.")
     return None
 
 
 def handle_show(client: api_client.ApiClient, args: Any) -> Any:
     server = client.get(f"{_ROOT}/{args.server_id}")
-    if getattr(args, "json", False):
+    if not getattr(args, "text", False):
         return server
     _render_server(server if isinstance(server, dict) else {}, schemas=getattr(args, "schemas", False))
     return None
@@ -283,7 +283,7 @@ def _grant(client: api_client.ApiClient, args: Any, verb: str) -> Any:
     if not getattr(args, "all", False) and not tools:
         raise SystemExit(
             f"`tool-servers {verb}` needs at least one tool name, or --all. Run "
-            f"`cmpnd tool-servers show {args.server_id}` to see what this server lists."
+            f"`cmpnd tool-servers show {args.server_id} --text` to see what this server lists."
         )
     body: dict[str, Any] = {"all": True} if getattr(args, "all", False) else {"tools": tools}
     server = client.post(f"{_ROOT}/{args.server_id}/{verb}", json=body)

{cmpnd-0.66.0 → cmpnd-0.68.0}/cmpnd/cli/commands/top.py

@@ -1301,10 +1301,22 @@ def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
     def _handler(name: str) -> Any:
         return verbs.by_name(name).handler
 
+    # A verb that repeats a namespaced command says so first, from its VERBS
+    # row, so `cmpnd -h` tells a shortcut from a separate feature.
+    def _help(name: str, text: str = "") -> str:
+        shortcut_for = verbs.by_name(name).shortcut_for
+        if not shortcut_for:
+            return text
+        prefix = f"Shortcut for `cmpnd {shortcut_for}`"
+        return f"{prefix}; {text}" if text else prefix
+
     ps = subparsers.add_parser(
         "ps",
-        help="List deployments (Docker-style)",
-        description="List deployments belonging to the calling org, newest first.",
+        help=_help("ps", "renders a table"),
+        description=(
+            "List deployments belonging to the calling org, newest first. Shortcut for "
+            "`cmpnd deployments list` that renders a table; --json prints the same response."
+        ),
         epilog="Examples:\n  cmpnd ps\n  cmpnd ps --status ready --json\n",
         formatter_class=raw,
     )
@@ -1352,8 +1364,11 @@ def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
 
     insp = subparsers.add_parser(
         "inspect",
-        help="Full JSON for a deployment",
-        description="Print the full deployment record as JSON. Equivalent to `cmpnd status <id> --json`.",
+        help=_help("inspect", "--source prints the stored program"),
+        description=(
+            "Print the full deployment record as JSON, as `cmpnd deployments show` does. "
+            "--source prints the deployment's stored program file instead."
+        ),
         formatter_class=raw,
     )
     insp.add_argument("id")
@@ -1396,8 +1411,11 @@ def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
 
     rn = subparsers.add_parser(
         "run",
-        help="Run a deployment with a JSON input body",
-        description="Submit one durable run to a ready deployment and wait for its result.",
+        help=_help("run"),
+        description=(
+            "Submit one durable run to a ready deployment and wait for its result. "
+            "Shortcut for `cmpnd deployments run`."
+        ),
         epilog=(
             "Examples:\n"
             '  cmpnd run d_a1b2c3d4 \'{"question": "what is dspy?"}\'\n'

{cmpnd-0.66.0 → cmpnd-0.68.0}/cmpnd/cli/verbs.py

@@ -41,7 +41,9 @@ class Verb:
     ``deploy(path)``); ``"entity"`` binds it as a method on
     ``shell_entity`` (e.g. ``deps.d_xxx.status()``). ``shell_method``
     defaults to ``name`` and gives the registry a single hook to rename
-    a method without the hint helpers going stale.
+    a method without the hint helpers going stale. ``shortcut_for`` names the
+    namespaced command a verb repeats, such as ``"deployments list"`` for
+    ``ps``. Its CLI help starts with "Shortcut for `cmpnd deployments list`".
     """
 
     name: str
@@ -49,6 +51,7 @@ class Verb:
     shell_kind: Literal["top_level", "entity"]
     shell_entity: str | None = None
     shell_method: str | None = None
+    shortcut_for: str | None = None
 
     def __post_init__(self) -> None:
         if self.shell_kind == "entity" and not self.shell_entity:
@@ -65,13 +68,13 @@ class Verb:
 # functions (`_shell_method`, `register`), never at module scope.
 # Module-scope binding also makes the table trivially inspectable.
 _VERBS: tuple["Verb", ...] = (
-    Verb("ps", commands.top.cmd_ps, "top_level"),
+    Verb("ps", commands.top.cmd_ps, "top_level", shortcut_for="deployments list"),
     Verb("deploy", commands.top.cmd_deploy, "top_level"),
     Verb("optimize", commands.top.cmd_optimize, "top_level"),
     Verb("status", commands.top.cmd_status, "entity", "Deployment"),
     Verb("logs", commands.top.cmd_logs, "entity", "Deployment"),
-    Verb("inspect", commands.top.cmd_inspect, "entity", "Deployment"),
-    Verb("run", commands.top.cmd_run, "entity", "Deployment"),
+    Verb("inspect", commands.top.cmd_inspect, "entity", "Deployment", shortcut_for="deployments show"),
+    Verb("run", commands.top.cmd_run, "entity", "Deployment", shortcut_for="deployments run"),
     Verb("schema", commands.top.cmd_schema, "entity", "Deployment"),
     Verb("sample", commands.top.cmd_sample, "entity", "Deployment"),
 )
@@ -164,6 +167,7 @@ DOMAIN_VERBS: dict[str, str] = {
     "trash": "moves a program to the Trash, where it stays restorable, and delete would read as the permanent purge",
     "restore": "returns a program from the Trash with its history, which create would not",
     "purge": "deletes a program in the Trash for good, the irreversible step after trash",
+    "rename": "gives a program a new current name and keeps the old one resolving to it, which update would hide",
 }
 
 #: Leaves naming a related collection or sub-record rather than an action.

cmpnd-0.68.0/cmpnd/cli/views.py

@@ -0,0 +1,25 @@
+"""The output rule for namespaced commands.
+
+A namespaced read, such as `cmpnd traces show` or `cmpnd tool-servers list`, prints
+the platform's JSON by default, and a human view is an opt-in flag: `--tree` and
+`--timeline` on `traces show`, `--text` on the reads below. An action command may
+print a short result instead and take `--json` for the whole answer, as
+`cmpnd programs create` prints the id. The top-level commands (`cmpnd ps`,
+`cmpnd status`) are the human loop: they render text and take `--json`.
+`tests/test_cli/test_parity.py` refuses a namespaced read that offers `--json`.
+"""
+
+from __future__ import annotations
+
+import argparse
+
+
+def add_text_flag(parser: argparse.ArgumentParser) -> None:
+    """Give a namespaced read the opt-in `--text` view.
+
+    Some reads rendered text by default and took `--json` before the CLI settled on
+    the rule, so `--json` stays accepted and hidden, and a script that passes it
+    keeps working.
+    """
+    parser.add_argument("--text", action="store_true", help="Render for a person instead of printing JSON")
+    parser.add_argument("--json", action="store_true", help=argparse.SUPPRESS)

{cmpnd-0.66.0 → cmpnd-0.68.0}/cmpnd/client.py

@@ -836,6 +836,47 @@ class Client:
 
         return optimization.list_candidates(run_id, cfg=self._config)
 
+    def list_deployments(
+        self, *, status: str | None = None, since: str | None = None, limit: int = 50, offset: int = 0
+    ) -> list[dict[str, Any]]:
+        """The organization's deployments, newest first.
+
+        Returns the list itself, not the response envelope. ``status`` is one of
+        ``pending``, ``parsing``, ``optimizing``, ``ready`` or ``failed``, and
+        ``since`` is an ISO 8601 timestamp. ``offset`` must be a whole multiple of
+        ``limit``, because the route pages by page number. ``limit`` must not
+        exceed 500, the most deployments the route returns per page.
+        """
+        self._check_active()
+        page = _deployments.list_deployments(
+            status=status,
+            since=since,
+            limit=limit,
+            offset=offset,
+            api_key=self._config.api_key,
+            endpoint=self._config.endpoint,
+        )
+        return page.get("deployments", [])
+
+    def get_deployment(self, deployment_id: str) -> dict[str, Any]:
+        """Fetch one deployment's record: its status, program, model and metadata."""
+        self._check_active()
+        return _deployments.get_deployment(deployment_id, api_key=self._config.api_key, endpoint=self._config.endpoint)
+
+    def get_deployment_source(self, deployment_id: str, path: str | None = None) -> str:
+        """Read the program source a deployment stores, as text.
+
+        Without ``path`` it returns the program file the deployment runs. A
+        continuation's deployment holds the chosen candidate's program, so this
+        reads what the continuation runs. ``path`` names another archive-relative
+        file of the stored bundle. The file decodes with the encoding its PEP 263
+        coding comment declares, and with UTF-8 when it declares none.
+        """
+        self._check_active()
+        return _deployments.get_source(
+            deployment_id, path=path, api_key=self._config.api_key, endpoint=self._config.endpoint
+        )
+
     def get_deployment_signature(self, deployment_id: str) -> DeploymentSignatureResponse:
         """Fetch one deployment's persisted artifact metadata."""
         self._check_active()

{cmpnd-0.66.0 → cmpnd-0.68.0}/cmpnd/deployment.py

@@ -345,7 +345,7 @@ def _resolve_mcp_tool_references(client: httpx.Client, config, references: list[
                 f"your organization's registry holds no tool named {reference.tool_name!r} on "
                 f"{reference.server_url}, so this deploy cannot pin the schema its calls would be "
                 "validated against. Read what the registry does hold with "
-                f"`cmpnd tool-servers show {server_id}`, and if the server has grown the tool since it "
+                f"`cmpnd tool-servers show {server_id} --text`, and if the server has grown the tool since it "
                 f"was registered, `cmpnd tool-servers refresh {server_id}` re-reads its listing."
             )
         pinned[(reference.server_url, reference.tool_name)] = mcp_servers.PinnedTool(

{cmpnd-0.66.0 → cmpnd-0.68.0}/docs/cli.md

@@ -99,6 +99,24 @@ also names the `cmpnd programs optimized` command for a compiled program hash.
 program hash, the value in the `program_hash` column of
 `cmpnd programs optimized list`, as `cmpnd programs select` does.
 
+## Renaming a program
+
+`cmpnd programs rename PROGRAM NAME` makes NAME the current name of PROGRAM,
+which is a program name or a `p_` id. The program keeps its id and its
+history. The CLI checks NAME's syntax before it sends anything, looks a
+PROGRAM name up as the other `cmpnd programs` commands do, and sends
+`POST /api/v1/programs/{id}/rename`. The command needs `traces:write` or
+`optimizations:write`.
+
+The old name keeps resolving to the program, so code that still declares it
+reaches the same program. A program with no name takes its first name this
+way, and code that declares the new name with `cmpnd.Program(name, ...)`
+traces to it. Serve refuses a name another live
+program answers to, as its current or a retired name. A program in the Trash
+is refused until `cmpnd programs restore` returns it. A server from before the
+rename route says so, and the error points at the program's page in the web
+app, which renames it too.
+
 ## The Trash
 
 A program in the Trash leaves every view, and its traces with it, until it is
@@ -154,11 +172,28 @@ release without the warning, set `CMPND_NO_UPGRADE_WARNING=1`. In code,
 `warnings.filterwarnings("ignore", category=cmpnd.UpgradeRequiredWarning)`
 does the same.
 
+## Output of namespaced and top-level commands
+
+A namespaced read, such as `cmpnd traces show`, `cmpnd deployments list` or
+`cmpnd tool-servers list`, prints the API's JSON by default, so a script can
+pipe it to `jq`. A human view is an opt-in flag: `--tree` and `--timeline` on
+`traces show`, and `--text` on `tool-servers list`, `tool-servers show` and
+`credentials list`. Those three accept `--json` as well, so older scripts keep
+working. An action command may print a short result and take `--json` for the
+whole answer: `cmpnd programs create` prints the new id, and
+`cmpnd optimizations continue` prints the best deployment. The top-level
+commands below are the human loop: they render text and take `--json`.
+`cmpnd/cli/views.py` states the rule, and `tests/test_cli/test_parity.py`
+refuses a namespaced read that offers `--json`.
+
 ## Deploy flow (Docker-style)
 
 These commands print human-readable output by default. Each takes `--json` for
 a stable, scriptable shape. A deployment ID may be any unambiguous prefix,
-such as `d_a1b2c3d4`.
+such as `d_a1b2c3d4`. Three of them are shortcuts, and their help says so:
+`cmpnd ps` repeats `cmpnd deployments list`, `cmpnd run` repeats
+`cmpnd deployments run`, and `cmpnd inspect` repeats `cmpnd deployments show`.
+`Verb.shortcut_for` in `cmpnd/cli/verbs.py` declares each one.
 
 - `cmpnd deploy <source.py|-> PROGRAM_NAME [--entrypoint ATTRIBUTE]
   [--source-root DIR] [--include PATH ...] [--run <json>] [--metadata <json>]`
@@ -560,10 +595,10 @@ cmpnd credentials create --name luna-exec --preset lunaroute < key.txt
 op read 'op://vault/openai/key' | cmpnd credentials create --name openai --preset openai
 ```
 
-`cmpnd credentials list` shows each credential's protocols, whether its host
-implies them, its address and the org's default. A member sees the scheme and
-host of the address, and an owner sees the whole of it. `--json` prints the
-listing as the API returns it.
+`cmpnd credentials list` prints the listing as the API returns it: each
+credential's protocols, whether its host implies them, its address and the
+org's default. `--text` renders it for a person. A member sees the scheme and
+host of the address, and an owner sees the whole of it.
 
 `cmpnd credentials protocols NAME` shows a credential's protocols. `--add` and
 `--remove` start from them, whether stated or implied by the host, and `--set`
@@ -620,18 +655,19 @@ server, the credential it uses and the allow-list of tools a deploy may name.
 
 ```bash
 cmpnd tool-servers create --url https://mcp.exa.ai/mcp --credential exa-prod [--name exa]
-cmpnd tool-servers list
-cmpnd tool-servers show <server_id> [--schemas]
+cmpnd tool-servers list [--text]
+cmpnd tool-servers show <server_id> [--text [--schemas]]
 cmpnd tool-servers refresh <server_id>
 cmpnd tool-servers delete <server_id> --force
 ```
 
 `create` registers the server and has the platform list its tools. The
 platform contacts the server, and the CLI never does. `refresh` lists the
-tools again after a vendor changes them. `show` prints each tool with its
-allow-list state and a one-line description. `--schemas` adds the reduced
-argument schema the platform enforces. Every command takes `--json` for the
-raw payload.
+tools again after a vendor changes them. `list` and `show` print the API's
+JSON. With `--text`, `show` prints each tool with its allow-list state and a
+one-line description, and `--schemas` adds the reduced argument schema the
+platform enforces. `create`, `allow`, `deny` and `refresh` render the server
+as it now stands, and `--json` prints the raw payload instead.
 
 When the platform cannot list a server's tools because of the server itself,
 `create` and `refresh` fail with a `424` that names the URL, the credential and
@@ -881,7 +917,7 @@ creator after the creator leaves. The customer then:
    same name, and `cmpnd credentials create --kind mcp --server URL
    --name NAME` with the same server and name, replace the sealed keys in
    place. The tool server and the deployment keep pointing at them.
-3. Runs `cmpnd tool-servers show SERVER_ID` and
+3. Runs `cmpnd tool-servers show SERVER_ID --text` and
    `cmpnd tool-servers refresh SERVER_ID` to read the tools and allow-list
    under the new key.
 4. Runs `cmpnd ps`, `cmpnd sample ID` and `cmpnd run ID '<json>'`. The

{cmpnd-0.66.0 → cmpnd-0.68.0}/docs/client.md

@@ -211,8 +211,13 @@ methods:
 
 - Traces: `sdk.list_traces(**filters)` and `sdk.get_trace(trace_id)`. The
   `program=` filter takes a program name or a `p_` id.
-- Deployments: `sdk.get_deployment_signature(deployment_id)` returns the
-  selected artifact's typed metadata. It reads no worker status or executions.
+- Deployments: `sdk.list_deployments(status=..., since=..., limit=...,
+  offset=...)` lists the organization's deployments, newest first.
+  `sdk.get_deployment(deployment_id)` returns one deployment's record.
+  `sdk.get_deployment_source(deployment_id, path=None)` returns the program
+  file the deployment stores, or the archive-relative file `path` names.
+  `sdk.get_deployment_signature(deployment_id)` returns the selected
+  artifact's typed metadata. It reads no worker status or executions.
 - Assessments, in development behind `CMPND_CLI_DEV=1`:
   `sdk.create_assessment(trace_id, conclusion=..., body=...,
   annotations=...)`, `sdk.list_assessments(program=... | trace_id=...,