cmpnd 0.62.0__tar.gz → 0.64.0__tar.gz

{cmpnd-0.62.0 → cmpnd-0.64.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cmpnd
-Version: 0.62.0
+Version: 0.64.0
 Summary: DSPy observability and deployment SDK for cmpnd
 Project-URL: Homepage, https://cmpnd.ai
 Author-email: cmpnd <hello@cmpnd.ai>
@@ -51,9 +51,9 @@ Description-Content-Type: text/markdown
 
 # cmpnd
 
-The `cmpnd` package traces DSPy programs and deploys and optimizes them on the
-cmpnd platform. One call turns on tracing, and a client deploys, runs and
-optimizes named programs.
+The `cmpnd` package traces, deploys and optimizes DSPy programs on the cmpnd
+platform. You give a program a name, and a client records its traces,
+deployments and optimization runs under that name.
 
 ## Installation
 
@@ -66,46 +66,15 @@ uv add cmpnd      # or: pip install cmpnd
 The `cmpnd` library works with the cmpnd service at
 [platform.cmpnd.ai](https://platform.cmpnd.ai). Create an API key on the
 platform under Settings → API keys, and pass it as `api_key=` to
-`cmpnd.configure()` or `cmpnd.Client()`. For a self-hosted cmpnd install, also
+`cmpnd.Client()` or `cmpnd.configure()`. For a self-hosted cmpnd install, also
 pass the install's URL as `endpoint=`.
 
 ## Quick start
 
-`cmpnd.auto_instrument()` records a trace of every DSPy call in the process.
-Your code needs no other change. Use it to sketch a [DSPy program](https://dspy.ai/) and see what it
-does.
-
-```python
-import cmpnd
-import dspy
-
-cmpnd.configure(api_key="ck_xxx", project_tags="my-project")
-cmpnd.auto_instrument()
-
-dspy.configure(lm=dspy.LM("openai/gpt-6-luna"))
-
-cot = dspy.ChainOfThought("question -> answer")
-result = cot(question="What is DSPy?")   # the trace goes to cmpnd
-
-cmpnd.trace_id(result)  # "a1b2c3d4-...", or None outside instrumentation
-```
-
-`cmpnd.trace_id()` links a result to its platform trace, for example to attach
-feedback later. Traces recorded this way have no program name. The platform
-groups them by the structure of the program's modules. The API reference
-below lists the other options of `cmpnd.configure()`.
-
-## Program names
-
-When you’re ready to name programs, evolve them, and share them with your team, switch
-to `cmpnd.Client`. A client replaces `configure()` and `auto_instrument()` and offers
-more features. A client records only the programs you run through it, and each of
-those programs has a program name. A client takes most of the same arguments as `configure()`.
-
-A program name is the name your organization gives a program, such as `question-answerer`.
-Traces, deployments and optimization runs under one program name go to one
-program. The platform makes the program the first time your organization uses
-the program name.
+A program name is the name your organization gives a program, such as
+`question-answerer`. Traces, deployments and optimization runs under one
+program name go to one program. The platform makes the program the first time
+your organization uses the program name.
 
 `@cmpnd.program(name)` above a `dspy.Module` class gives the class a program
 name. Building the class takes its own arguments and a required `lm=`. The
@@ -128,17 +97,23 @@ class QA(dspy.Predict):
 qa1 = QA(lm=dspy.LM("openai/gpt-6-luna"))
 ```
 
-A client runs the program and records its trace under the program name:
+A `cmpnd.Client` runs the program and records its trace under the program
+name:
 
 ```python
 gepa = dspy.GEPA(metric=metric, reflection_lm=dspy.LM("openai/gpt-6-luna"), auto="light")
 
 with cmpnd.Client(api_key="ck_xxx", project_tags="my-project") as sdk:
-    # the trace will go to the program "question-answerer"
+    # the trace goes to the program "question-answerer"
     result = sdk.run_program(qa1, question="What is DSPy?")
     qa2 = sdk.optimize_program(qa1, gepa, trainset=train, valset=val)
+
+cmpnd.trace_id(result)  # "a1b2c3d4-...", the trace of this run
 ```
 
+`cmpnd.trace_id()` links a result to its platform trace, for example to attach
+feedback later. A client records only the programs you run through it.
+
 A client is active from construction. The `with` form flushes the client's
 traces and closes it on exit. Without `with`, the client stays active until
 you call `close()` or the process exits, and its traces go out at exit:
@@ -167,8 +142,26 @@ qa3 = cmpnd.Program(
 - `optimize_program` runs the optimizer in your process and returns a copy of
   the program that holds the optimized module. The copy keeps the program name
   and the LM.
-- Calling a `cmpnd.Program` directly while `auto_instrument()` is on raises a
-  `TypeError` that points to `cmpnd.Client`.
+
+## Sketching with `auto_instrument()`
+
+`cmpnd.auto_instrument()` records a trace of every DSPy call in the process,
+with no other change to your code. Use it to sketch a
+[DSPy program](https://dspy.ai/) and see what it does:
+
+```python
+cmpnd.configure(api_key="ck_xxx", project_tags="my-project")
+cmpnd.auto_instrument()
+
+dspy.configure(lm=dspy.LM("openai/gpt-6-luna"))
+dspy.ChainOfThought("question -> answer")(question="What is DSPy?")
+```
+
+These traces carry no program, so the platform files them under Unattributed.
+The first one in a process logs a warning that points to `@cmpnd.program` and
+`cmpnd.Client`. Calling a `cmpnd.Program` directly while `auto_instrument()` is
+on raises a `TypeError` that points to the client. The API reference below
+lists the options of `cmpnd.configure()`.
 
 ## Deployed programs
 
@@ -531,7 +524,7 @@ describes one:
 
 ```
 usage: cmpnd [-h] [--version] [--api-key API_KEY] [--endpoint ENDPOINT]
-             {auth,login,logout,org,credentials,tool-servers,optimizations,programs,signatures,traces,evals,datasets,deployments,ps,status,logs,inspect,schema,sample,run,deploy,optimize}
+             {auth,login,logout,org,credentials,tool-servers,optimizations,programs,traces,evals,datasets,deployments,ps,status,logs,inspect,schema,sample,run,deploy,optimize}
              ...
 
 CMPND platform CLI — deploy, run, and inspect DSPy programs.
@@ -625,7 +618,8 @@ captured input and output size limits, 65,536 bytes each by default.
 
 ### `cmpnd.auto_instrument()`
 
-Registers the callback with DSPy, so every DSPy call records a trace.
+Registers the callback with DSPy, so every DSPy call records a trace. The
+traces carry no program and land in Unattributed.
 
 ### `cmpnd.Client()`
 

{cmpnd-0.62.0 → cmpnd-0.64.0}/README.md

@@ -1,8 +1,8 @@
 # cmpnd
 
-The `cmpnd` package traces DSPy programs and deploys and optimizes them on the
-cmpnd platform. One call turns on tracing, and a client deploys, runs and
-optimizes named programs.
+The `cmpnd` package traces, deploys and optimizes DSPy programs on the cmpnd
+platform. You give a program a name, and a client records its traces,
+deployments and optimization runs under that name.
 
 ## Installation
 
@@ -15,46 +15,15 @@ uv add cmpnd      # or: pip install cmpnd
 The `cmpnd` library works with the cmpnd service at
 [platform.cmpnd.ai](https://platform.cmpnd.ai). Create an API key on the
 platform under Settings → API keys, and pass it as `api_key=` to
-`cmpnd.configure()` or `cmpnd.Client()`. For a self-hosted cmpnd install, also
+`cmpnd.Client()` or `cmpnd.configure()`. For a self-hosted cmpnd install, also
 pass the install's URL as `endpoint=`.
 
 ## Quick start
 
-`cmpnd.auto_instrument()` records a trace of every DSPy call in the process.
-Your code needs no other change. Use it to sketch a [DSPy program](https://dspy.ai/) and see what it
-does.
-
-```python
-import cmpnd
-import dspy
-
-cmpnd.configure(api_key="ck_xxx", project_tags="my-project")
-cmpnd.auto_instrument()
-
-dspy.configure(lm=dspy.LM("openai/gpt-6-luna"))
-
-cot = dspy.ChainOfThought("question -> answer")
-result = cot(question="What is DSPy?")   # the trace goes to cmpnd
-
-cmpnd.trace_id(result)  # "a1b2c3d4-...", or None outside instrumentation
-```
-
-`cmpnd.trace_id()` links a result to its platform trace, for example to attach
-feedback later. Traces recorded this way have no program name. The platform
-groups them by the structure of the program's modules. The API reference
-below lists the other options of `cmpnd.configure()`.
-
-## Program names
-
-When you’re ready to name programs, evolve them, and share them with your team, switch
-to `cmpnd.Client`. A client replaces `configure()` and `auto_instrument()` and offers
-more features. A client records only the programs you run through it, and each of
-those programs has a program name. A client takes most of the same arguments as `configure()`.
-
-A program name is the name your organization gives a program, such as `question-answerer`.
-Traces, deployments and optimization runs under one program name go to one
-program. The platform makes the program the first time your organization uses
-the program name.
+A program name is the name your organization gives a program, such as
+`question-answerer`. Traces, deployments and optimization runs under one
+program name go to one program. The platform makes the program the first time
+your organization uses the program name.
 
 `@cmpnd.program(name)` above a `dspy.Module` class gives the class a program
 name. Building the class takes its own arguments and a required `lm=`. The
@@ -77,17 +46,23 @@ class QA(dspy.Predict):
 qa1 = QA(lm=dspy.LM("openai/gpt-6-luna"))
 ```
 
-A client runs the program and records its trace under the program name:
+A `cmpnd.Client` runs the program and records its trace under the program
+name:
 
 ```python
 gepa = dspy.GEPA(metric=metric, reflection_lm=dspy.LM("openai/gpt-6-luna"), auto="light")
 
 with cmpnd.Client(api_key="ck_xxx", project_tags="my-project") as sdk:
-    # the trace will go to the program "question-answerer"
+    # the trace goes to the program "question-answerer"
     result = sdk.run_program(qa1, question="What is DSPy?")
     qa2 = sdk.optimize_program(qa1, gepa, trainset=train, valset=val)
+
+cmpnd.trace_id(result)  # "a1b2c3d4-...", the trace of this run
 ```
 
+`cmpnd.trace_id()` links a result to its platform trace, for example to attach
+feedback later. A client records only the programs you run through it.
+
 A client is active from construction. The `with` form flushes the client's
 traces and closes it on exit. Without `with`, the client stays active until
 you call `close()` or the process exits, and its traces go out at exit:
@@ -116,8 +91,26 @@ qa3 = cmpnd.Program(
 - `optimize_program` runs the optimizer in your process and returns a copy of
   the program that holds the optimized module. The copy keeps the program name
   and the LM.
-- Calling a `cmpnd.Program` directly while `auto_instrument()` is on raises a
-  `TypeError` that points to `cmpnd.Client`.
+
+## Sketching with `auto_instrument()`
+
+`cmpnd.auto_instrument()` records a trace of every DSPy call in the process,
+with no other change to your code. Use it to sketch a
+[DSPy program](https://dspy.ai/) and see what it does:
+
+```python
+cmpnd.configure(api_key="ck_xxx", project_tags="my-project")
+cmpnd.auto_instrument()
+
+dspy.configure(lm=dspy.LM("openai/gpt-6-luna"))
+dspy.ChainOfThought("question -> answer")(question="What is DSPy?")
+```
+
+These traces carry no program, so the platform files them under Unattributed.
+The first one in a process logs a warning that points to `@cmpnd.program` and
+`cmpnd.Client`. Calling a `cmpnd.Program` directly while `auto_instrument()` is
+on raises a `TypeError` that points to the client. The API reference below
+lists the options of `cmpnd.configure()`.
 
 ## Deployed programs
 
@@ -480,7 +473,7 @@ describes one:
 
 ```
 usage: cmpnd [-h] [--version] [--api-key API_KEY] [--endpoint ENDPOINT]
-             {auth,login,logout,org,credentials,tool-servers,optimizations,programs,signatures,traces,evals,datasets,deployments,ps,status,logs,inspect,schema,sample,run,deploy,optimize}
+             {auth,login,logout,org,credentials,tool-servers,optimizations,programs,traces,evals,datasets,deployments,ps,status,logs,inspect,schema,sample,run,deploy,optimize}
              ...
 
 CMPND platform CLI — deploy, run, and inspect DSPy programs.
@@ -574,7 +567,8 @@ captured input and output size limits, 65,536 bytes each by default.
 
 ### `cmpnd.auto_instrument()`
 
-Registers the callback with DSPy, so every DSPy call records a trace.
+Registers the callback with DSPy, so every DSPy call records a trace. The
+traces carry no program and land in Unattributed.
 
 ### `cmpnd.Client()`
 

{cmpnd-0.62.0 → cmpnd-0.64.0}/cmpnd/_assessments.py

@@ -13,7 +13,7 @@ import os
 from collections.abc import Sequence
 from typing import Any, Literal
 
-from . import _http, configuration
+from . import _http, configuration, programs
 
 DEFAULT_ENDPOINT = "https://platform.cmpnd.ai"
 
@@ -58,22 +58,23 @@ def list(
 ) -> dict[str, Any]:
     """List assessments by program or by trace, newest first.
 
-    Pass exactly one of ``program`` (every assessment of that program) or
-    ``trace_id`` (only that trace's assessments). Returns
+    Pass exactly one of ``program`` (every assessment of that program, named by its
+    name or ``p_`` id) or ``trace_id`` (only that trace's assessments). Returns
     ``{"assessments": [...], "total": N, "limit", "offset", "has_more"}``.
     ``limit`` (max rows) and ``offset`` (skip this many) page the full set — the
     server clamps ``limit`` to at most 200.
     """
     if program is not None and trace_id is not None:
         raise ValueError("pass exactly one of program or trace_id")
+    client = _client(api_key, endpoint)
     if trace_id is not None:
         scope: dict[str, str] = {"trace_id": trace_id}
     elif program is not None:
-        scope = {"program": program}
+        scope = {"program": programs.program_id_for(client, program)}
     else:
         raise ValueError("pass exactly one of program or trace_id")
     params = {**scope, "limit": str(limit), "offset": str(offset)}
-    return _client(api_key, endpoint).get("/api/v1/assessments", params=params)
+    return client.get("/api/v1/assessments", params=params)
 
 
 def get(assessment_id: str, *, api_key: str | None = None, endpoint: str | None = None) -> dict[str, Any]:

{cmpnd-0.62.0 → cmpnd-0.64.0}/cmpnd/_traces.py

@@ -4,7 +4,7 @@ The implementation of ``list`` and ``show`` over the shared ``_http`` transport.
 :class:`cmpnd.Client`'s ``list_traces`` / ``get_trace`` call these directly; the
 deprecated :mod:`cmpnd.traces` shim wraps them with a warning. The filter and
 verb names match the ``cmpnd traces`` CLI vocabulary — ``list`` filtered by
-``query`` / ``program`` / ``module`` / ``hash`` / ``deployment`` / ``since`` / ``until`` /
+``query`` / ``program`` / ``module`` / ``deployment`` / ``since`` / ``until`` /
 ``all_history``, and ``show`` for one trace — so the surfaces do not drift.
 """
 
@@ -29,7 +29,6 @@ def list(
     model: str | None = None,
     program: str | None = None,
     module: str | None = None,
-    hash: str | None = None,
     deployment: str | None = None,
     metadata: dict[str, str] | None = None,
     tags: list[str] | None = None,
@@ -49,11 +48,10 @@ def list(
     ``ignored_fields`` naming any request field an older server did not understand.
 
     The filters mirror ``cmpnd traces list``: ``query`` searches indexed span text;
-    ``program`` names the program by name, and ``hash`` by its program id (``p_…``)
-    or a legacy signature hash; ``module`` is the root module's class, matched exactly.
-    No index serves the class, so without ``program`` or a program id in ``hash`` it
-    reads every trace in the time range and slows as the range grows. Pair it with a program or a shorter
-    ``since``;
+    ``program`` names the program by its name or its program id (``p_…``);
+    ``module`` is the root module's class, matched exactly. No index serves the
+    class, so without ``program`` it reads every trace in the time range and slows
+    as the range grows. Pair it with a program or a shorter ``since``;
     ``deployment`` is a deployment id; ``metadata`` is matched by containment (every
     pair must be present); ``tags`` matches any of the given tags. ``since`` /
     ``until`` accept an ISO 8601 timestamp, a bare date (``YYYY-MM-DD``), or a
@@ -71,15 +69,14 @@ def list(
         ("status", status),
         ("q", query),
         ("model", model),
-        ("program_name", program),
         ("module_class", module),
         ("deployment_id", deployment),
         ("tags", tags),
     ):
         if val is not None:
             body[wire_key] = val
-    if hash is not None:
-        body.update(program_filter(hash))
+    if program is not None:
+        body.update(program_filter(program))
     if metadata is not None:
         body["metadata"] = dict(metadata)
     if since is not None:
@@ -92,14 +89,14 @@ def list(
 def program_filter(value: str) -> dict[str, str]:
     """The search-body key for one program filter value.
 
-    A program id (``p_…``) goes in ``program_id`` and a legacy signature hash in
-    ``program_signature_hash``, which the route decodes as a typed hash and would
-    refuse an id in. One helper for the CLI and the SDK, so the two cannot split.
+    A program id (``p_…``) goes in ``program_id`` and anything else is a program
+    name, since no name starts with ``p_``. One helper for the CLI and the SDK,
+    so the two cannot split.
     """
     text = value.strip()
     if identity.is_program_id(text):
         return {"program_id": text}
-    return {"program_signature_hash": value}
+    return {"program_name": value}
 
 
 def show(trace_id: str, *, api_key: str | None = None, endpoint: str | None = None) -> dict[str, Any]:

{cmpnd-0.62.0 → cmpnd-0.64.0}/cmpnd/_valsets.py

@@ -15,7 +15,7 @@ import datetime
 import os
 from typing import Any
 
-from . import _http, configuration
+from . import _http, configuration, programs
 
 DEFAULT_ENDPOINT = "https://platform.cmpnd.ai"
 
@@ -30,22 +30,24 @@ def default_name() -> str:
 def create(
     program: str, *, name: str | None = None, api_key: str | None = None, endpoint: str | None = None
 ) -> dict[str, Any]:
-    """Create a program-owned valset. ``name`` is auto-assigned when omitted."""
-    payload = {"program": program, "name": name or default_name()}
-    return _client(api_key, endpoint).post("/api/v1/valsets", json=payload)
+    """Create a valset owned by ``program``, a program name or ``p_`` id. ``name`` is auto-assigned when omitted."""
+    client = _client(api_key, endpoint)
+    payload = {"program": programs.program_id_for(client, program), "name": name or default_name()}
+    return client.post("/api/v1/valsets", json=payload)
 
 
 def list(
     program: str, *, limit: int = 50, offset: int = 0, api_key: str | None = None, endpoint: str | None = None
 ) -> dict[str, Any]:
-    """List a program's valsets, newest first.
+    """List the valsets of ``program``, a program name or ``p_`` id, newest first.
 
     Returns ``{"valsets": [...], "total": N, "limit", "offset", "has_more"}``.
     ``limit`` / ``offset`` page the full set — the server clamps ``limit`` to at
     most 200.
     """
-    params = {"program": program, "limit": str(limit), "offset": str(offset)}
-    return _client(api_key, endpoint).get("/api/v1/valsets", params=params)
+    client = _client(api_key, endpoint)
+    params = {"program": programs.program_id_for(client, program), "limit": str(limit), "offset": str(offset)}
+    return client.get("/api/v1/valsets", params=params)
 
 
 def get(valset_id: str, *, api_key: str | None = None, endpoint: str | None = None) -> dict[str, Any]:

{cmpnd-0.62.0 → cmpnd-0.64.0}/cmpnd/callback.py

@@ -39,6 +39,27 @@ def _declared_program_name() -> str | None:
     return name if isinstance(name, str) else None
 
 
+# Set once the process has warned that a trace names no program, so the warning
+# appears once per process, whichever callback records the trace.
+_warned_unattributed = False
+
+
+def _warn_once_if_unattributed(trace: models.TraceBuilder) -> None:
+    """Warn the first time a trace in this process names neither a program name nor a program id.
+
+    Such a trace belongs to no program, and the platform files it under Unattributed.
+    """
+    global _warned_unattributed
+    if _warned_unattributed or trace.declared_name is not None or trace.program_id is not None:
+        return
+    _warned_unattributed = True
+    logger.warning(
+        "cmpnd: this trace names no program, so the platform files it under Unattributed. Give the program a "
+        "name with @cmpnd.program(name) and run it through cmpnd.Client, and its traces go to that program. "
+        "This warning appears once per process."
+    )
+
+
 def trace_id(prediction: Any) -> str | None:
     """Return the cmpnd trace id for a prediction returned by an instrumented program.
 
@@ -1193,6 +1214,10 @@ class _ModuleMixin(_CallbackBase):
             module_class=instance.__class__.__name__,
         )
         self._stamp(trace)
+        # A root module call is where a program runs, so it is where an unnamed one
+        # is caught. GEPA's own LM calls (_emit_optimization_lm_trace) belong to the
+        # optimization run, which names the program, so they never warn.
+        _warn_once_if_unattributed(trace)
 
         # Attach the run ids this trace starts under, from this callback's own
         # state right now — not at finalize (on_module_end), where the

{cmpnd-0.62.0 → cmpnd-0.64.0}/cmpnd/cli/__init__.py

@@ -24,7 +24,6 @@ from .commands import (
     org,
     programs,
     provider_credentials,
-    signatures,
     tool_servers,
     top,
     traces,
@@ -164,7 +163,6 @@ def main() -> None:
     # gates each read on scope, so a caller without it gets a 403, not a
     # hidden command.
     programs.register(subparsers)
-    signatures.register(subparsers)
     traces.register(subparsers)
     evals.register(subparsers)
     datasets.register(subparsers)

{cmpnd-0.62.0 → cmpnd-0.64.0}/cmpnd/cli/commands/assessments.py

@@ -56,7 +56,8 @@ def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
     scope.add_argument(
         "program",
         nargs="?",
-        help="Program id (p_…), or a legacy signature hash (16-hex, as `cmpnd signatures list` shows)",
+        metavar="PROGRAM",
+        help="Program name or p_ id",
     )
     scope.add_argument("--trace", dest="trace_id", metavar="TRACE_ID", help="A single trace's assessments")
     pagination.add_args(ls, with_page_aliases=False, default_limit=50)
@@ -88,7 +89,15 @@ def handle_create(client: api_client.ApiClient, args: Any) -> Any:
 
 
 def handle_list(client: api_client.ApiClient, args: Any) -> Any:
-    scope = {"trace_id": args.trace_id} if args.trace_id else {"program": args.program}
+    if args.trace_id:
+        scope = {"trace_id": args.trace_id}
+    else:
+        from . import programs
+
+        program_id, _ = programs.resolve(
+            client, args.program, old_server_remedy="Upgrade the server to name a program."
+        )
+        scope = {"program": program_id}
     params = {**scope, **pagination.wire(args, "limit_offset", as_str=True)}
     return client.get("/api/v1/assessments", params=params)
 

{cmpnd-0.62.0 → cmpnd-0.64.0}/cmpnd/cli/commands/evals.py

@@ -50,7 +50,7 @@ def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
     # `evals compare` is deliberately absent. The route requires a
     # `dataset_hash`, and no eval read returns one: neither the list nor the
     # detail projection carries it, and nor does the compare response itself.
-    # The only surface that emits one is `signatures evals`, so the command
+    # The only surface that emits one is `programs evals`, so the command
     # would ship with a required argument its own noun cannot produce. It goes
     # in once the projection carries the hash.
 

{cmpnd-0.62.0 → cmpnd-0.64.0}/cmpnd/cli/commands/org.py

@@ -29,17 +29,21 @@ adds one) and `switch` picks which stored key later commands use, the way the
 web app switches a session's active org. `list` reads
 /api/v1/auth/organizations and marks the orgs you hold a key for and the
 active one. `switch` needs no network call when the org's key is already
-stored. `cmpnd org leave` removes your own membership and drops that org's
-stored key.
+stored. When none is stored for an org you are an approved member of, it
+offers to mint one with the current key's scopes (`--mint` skips the
+question), stores it and switches to it. `cmpnd org leave` removes your own
+membership and drops that org's stored key.
 
 Always registered (no env gate); the server is the authority.
 """
 
 from __future__ import annotations
 
+import socket
 import sys
 import urllib.parse
 from argparse import ArgumentParser, _SubParsersAction
+from datetime import datetime, timezone
 from typing import Any
 
 from .. import api_client, credentials
@@ -91,6 +95,11 @@ def register(subparsers: _SubParsersAction[ArgumentParser]) -> None:
 
     switch = sub.add_parser("switch", help="Use the stored key for another of your organizations")
     switch.add_argument("org", help="Organization slug or id (from `org list`)")
+    switch.add_argument(
+        "--mint",
+        action="store_true",
+        help="When no key is stored for the org, mint one with the current key's scopes without asking",
+    )
     switch.set_defaults(func=handle_switch, _skip_resolve_config=True)
 
     leave = sub.add_parser("leave", help="Leave one of your organizations and drop its stored key")
@@ -214,12 +223,70 @@ def handle_switch(_unused_client: api_client.ApiClient | None, args: Any) -> Non
         api_key, _ = api_client.resolve_config(args)
     except api_client.CliError:
         raise _no_key_stored(f"'{target}'", endpoint, target) from None
-    for row in _memberships(api_client.ApiClient(api_key, endpoint)):
+    client = api_client.ApiClient(api_key, endpoint)
+    for row in _memberships(client):
         if target in (row.get("id"), row.get("slug")):
-            raise _no_key_stored(str(row.get("name") or target), endpoint, target)
+            _mint_and_switch(client, row, target, ask=not getattr(args, "mint", False))
+            return
     raise api_client.CliError(f"You are not a member of an organization '{target}' on {endpoint}.")
 
 
+def _mint_and_switch(client: api_client.ApiClient, row: dict[str, Any], target: str, *, ask: bool) -> None:
+    """Mint a key for a member org that has none stored, store it and switch.
+
+    The request names no scopes, so serve grants the calling key's own
+    non-admin scopes and the new key is never broader than the one in use.
+    serve refuses with 400 or 403 when the calling key cannot mint, and the
+    browser login is then the way to get the key.
+    """
+    endpoint = client._endpoint
+    label = str(row.get("name") or row.get("slug") or target)
+    if row.get("approved") is False:
+        raise api_client.CliError(
+            f"Your membership in {label} is not approved yet, so no key can be minted for it. "
+            "An owner of the org approves it."
+        )
+    if ask:
+        if not sys.stdin.isatty():
+            raise api_client.CliError(
+                f"No key is stored for {label} on {endpoint}. Run {top.hint_org_switch(target, mint=True)} "
+                f"to mint one with the current key's scopes, or {top.hint_login(target)}."
+            )
+        try:
+            answer = input(f"No key is stored for {label}. Mint one with the current key's scopes? [Y/n] ")
+        except EOFError:
+            # Ctrl-D at the prompt declines.
+            print(file=sys.stderr)
+            answer = "n"
+        if answer.strip().lower() not in ("", "y", "yes"):
+            raise _no_key_stored(label, endpoint, target)
+
+    hostname = socket.gethostname() or "unknown"
+    name = f"CLI: {hostname} {datetime.now(timezone.utc).strftime('%Y-%m-%d')}"
+    try:
+        created = client.post("/api/v1/org/keys", json={"name": name, "org_id": row.get("id") or target})
+    except api_client.CliError as exc:
+        if exc.status_code in (400, 403):
+            raise api_client.CliError(
+                f"The current key could not mint a key for {label}: {exc}. Run {top.hint_login(target)} to store one."
+            ) from exc
+        raise
+    token = created.get("token") if isinstance(created, dict) else None
+    org_id = created.get("org_id") if isinstance(created, dict) else None
+    if not isinstance(token, str) or not token or not isinstance(org_id, str) or not org_id:
+        raise api_client.CliError(f"The response did not include a key for {label}. Nothing was stored.")
+    name_out = created.get("org_name")
+    slug_out = created.get("org_slug")
+    credentials.save(
+        endpoint,
+        token,
+        org_id=org_id,
+        org_name=name_out if isinstance(name_out, str) else None,
+        org_slug=slug_out if isinstance(slug_out, str) else None,
+    )
+    print(f"Minted a key for {name_out or slug_out or org_id} ({org_id}) and switched to it on {endpoint}")
+
+
 def _say_active_moved(endpoint: str, moved_to: str | None) -> None:
     if moved_to:
         k = {k.org_id: k for k in credentials.stored_keys(endpoint)}.get(moved_to)