blobhub-cli 0.5.0__tar.gz → 0.7.0__tar.gz

{blobhub_cli-0.5.0 → blobhub_cli-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: blobhub-cli
-Version: 0.5.0
+Version: 0.7.0
 Summary: BlobHub command line interface — work with blobs, revisions, and their contents from the terminal
 Project-URL: Homepage, https://blobhub.io/
 Project-URL: Documentation, https://docs.blobhub.io/
@@ -106,6 +106,9 @@ For CI, skip the credentials file entirely — set `BLOBHUB_API_KEY` (and option
 `BLOBHUB_PROFILE`); the environment always wins over a stored profile, and a key from the environment alone
 works with no credentials file present at all.
 
+The root `--profile` selects a stored profile for any command (`blobhub --profile staging workflow events …`),
+as `BLOBHUB_PROFILE` does. An exported `BLOBHUB_API_KEY` or `BLOBHUB_API_URL` still wins over the profile it names.
+
 `login` itself can also run non-interactively and still store a profile, which the environment-only approach
 above does not:
 
@@ -178,9 +181,10 @@ blobhub workflow deploy -f manifest.yaml
 `deploy` builds every bound component locally (inlining local imports from `pkg/`, stripping sandbox-pre-bound
 and allowlisted imports, rejecting anything else), uploads only the definitions whose serialized document
 actually changed, and runs the platform's `check_definition` against each workflow definition it uploaded.
-Re-running `deploy` with nothing changed uploads nothing and says so. `--dry-run` on every mutating command
-prints the exact intended calls without performing them; `--json` emits a single machine-readable object instead
-of the rendered output.
+Re-running `deploy` with nothing changed uploads nothing and says so. `--dry-run` (on `workflow pull|push|build|deploy|
+prune` and `scheduler deploy`) prints the exact intended calls without performing them; `--json` emits a single
+machine-readable object instead of the rendered output. The exception is `workflow events --follow --json`, which
+writes JSON Lines, one `{"event", "schema_version"}` object per event and no final object.
 
 Other commands in the `workflow` group:
 
@@ -196,6 +200,43 @@ it with `REMOTE_EDIT` (or `UNMANAGED_CODE` for hand-typed code the CLI never bui
 or reconcile by hand first. See `docs/reference/error-codes.md` for the full catalog of error and advisory codes,
 what each one means, and how to resolve it.
 
+### Listeners and session events
+
+A **listener** is a definition with `category: listener` that acts on a session's event stream: it filters events,
+batches them, and invokes a workflow, a thread item or an object write. It lives in the manifest beside the
+workflows and deploys, diffs, pulls and checks like any other definition. The source file holds the whole body
+(`type: listener_definition`, `filter`, `batch`, `concurrency`, `invocation_target_type`, `invocation_target`,
+`receipt`); a listener entry takes no `components`.
+
+```yaml
+definitions:
+  - alias: orchestrate
+    category: listener                  # or inferred from `type: listener_definition` in the file
+    source: listeners/orchestrate.yaml
+```
+
+A session is named as `<session>` (with `-f manifest.yaml` naming its blob and revision),
+`<blob-id>/<revision>/<session>` or `<org>/<blob>/<revision>/<session>`; a qualified reference takes no `-f`.
+
+```sh
+blobhub workflow events my-session -f manifest.yaml                      # newest 20 events
+blobhub workflow events my-session -f manifest.yaml --types object.written --aliases 'worker/**' --follow
+blobhub workflow events my-session -f manifest.yaml --listener orchestrate --after 2026-11-09T17:00:00Z
+blobhub workflow events my-session -f manifest.yaml --cursor <token>     # continue the page a listing printed
+blobhub workflow listeners my-session -f manifest.yaml [--listener orchestrate]
+blobhub workflow listener disable my-session orchestrate -f manifest.yaml   # enable | disable, for this session
+```
+
+`--types`, `--aliases` and `--executions` repeat, and take globs where the platform does. A listing ends with
+`more: --cursor <token>` when there is another page; the token carries its own filter and direction, so pass it alone.
+`--follow` prints new events until interrupted without missing a late commit. `workflow execute --watch` follows the
+run's log the same way and ends once the platform reports the execution finished.
+
+With `--json`, the new commands print these keys: `workflow events` `{session, events, cursor}`; `workflow listeners`
+`{session_id, listeners, connections}`, or with `--listener` `{session_id, listener, executions, last_execution_id}`;
+`workflow listener enable|disable` `{session_id, listener}`. `workflow diff` adds `body_changed` and `validation_error`
+to a listener's report, and `scheduler ls` adds `invocation_target_type` and `target_alias` to each schedule.
+
 ## License
 
 MIT. See `LICENSE`.

{blobhub_cli-0.5.0 → blobhub_cli-0.7.0}/README.md

@@ -53,6 +53,9 @@ For CI, skip the credentials file entirely — set `BLOBHUB_API_KEY` (and option
 `BLOBHUB_PROFILE`); the environment always wins over a stored profile, and a key from the environment alone
 works with no credentials file present at all.
 
+The root `--profile` selects a stored profile for any command (`blobhub --profile staging workflow events …`),
+as `BLOBHUB_PROFILE` does. An exported `BLOBHUB_API_KEY` or `BLOBHUB_API_URL` still wins over the profile it names.
+
 `login` itself can also run non-interactively and still store a profile, which the environment-only approach
 above does not:
 
@@ -125,9 +128,10 @@ blobhub workflow deploy -f manifest.yaml
 `deploy` builds every bound component locally (inlining local imports from `pkg/`, stripping sandbox-pre-bound
 and allowlisted imports, rejecting anything else), uploads only the definitions whose serialized document
 actually changed, and runs the platform's `check_definition` against each workflow definition it uploaded.
-Re-running `deploy` with nothing changed uploads nothing and says so. `--dry-run` on every mutating command
-prints the exact intended calls without performing them; `--json` emits a single machine-readable object instead
-of the rendered output.
+Re-running `deploy` with nothing changed uploads nothing and says so. `--dry-run` (on `workflow pull|push|build|deploy|
+prune` and `scheduler deploy`) prints the exact intended calls without performing them; `--json` emits a single
+machine-readable object instead of the rendered output. The exception is `workflow events --follow --json`, which
+writes JSON Lines, one `{"event", "schema_version"}` object per event and no final object.
 
 Other commands in the `workflow` group:
 
@@ -143,6 +147,43 @@ it with `REMOTE_EDIT` (or `UNMANAGED_CODE` for hand-typed code the CLI never bui
 or reconcile by hand first. See `docs/reference/error-codes.md` for the full catalog of error and advisory codes,
 what each one means, and how to resolve it.
 
+### Listeners and session events
+
+A **listener** is a definition with `category: listener` that acts on a session's event stream: it filters events,
+batches them, and invokes a workflow, a thread item or an object write. It lives in the manifest beside the
+workflows and deploys, diffs, pulls and checks like any other definition. The source file holds the whole body
+(`type: listener_definition`, `filter`, `batch`, `concurrency`, `invocation_target_type`, `invocation_target`,
+`receipt`); a listener entry takes no `components`.
+
+```yaml
+definitions:
+  - alias: orchestrate
+    category: listener                  # or inferred from `type: listener_definition` in the file
+    source: listeners/orchestrate.yaml
+```
+
+A session is named as `<session>` (with `-f manifest.yaml` naming its blob and revision),
+`<blob-id>/<revision>/<session>` or `<org>/<blob>/<revision>/<session>`; a qualified reference takes no `-f`.
+
+```sh
+blobhub workflow events my-session -f manifest.yaml                      # newest 20 events
+blobhub workflow events my-session -f manifest.yaml --types object.written --aliases 'worker/**' --follow
+blobhub workflow events my-session -f manifest.yaml --listener orchestrate --after 2026-11-09T17:00:00Z
+blobhub workflow events my-session -f manifest.yaml --cursor <token>     # continue the page a listing printed
+blobhub workflow listeners my-session -f manifest.yaml [--listener orchestrate]
+blobhub workflow listener disable my-session orchestrate -f manifest.yaml   # enable | disable, for this session
+```
+
+`--types`, `--aliases` and `--executions` repeat, and take globs where the platform does. A listing ends with
+`more: --cursor <token>` when there is another page; the token carries its own filter and direction, so pass it alone.
+`--follow` prints new events until interrupted without missing a late commit. `workflow execute --watch` follows the
+run's log the same way and ends once the platform reports the execution finished.
+
+With `--json`, the new commands print these keys: `workflow events` `{session, events, cursor}`; `workflow listeners`
+`{session_id, listeners, connections}`, or with `--listener` `{session_id, listener, executions, last_execution_id}`;
+`workflow listener enable|disable` `{session_id, listener}`. `workflow diff` adds `body_changed` and `validation_error`
+to a listener's report, and `scheduler ls` adds `invocation_target_type` and `target_alias` to each schedule.
+
 ## License
 
 MIT. See `LICENSE`.

{blobhub_cli-0.5.0 → blobhub_cli-0.7.0}/src/blobhub_cli/__init__.py

@@ -5,4 +5,4 @@ Contract: this module is the sole source of the package version — hatchling re
 Invariant: no other file in this package defines `__version__`.
 """
 
-__version__ = "0.5.0"
+__version__ = "0.7.0"

{blobhub_cli-0.5.0 → blobhub_cli-0.7.0}/src/blobhub_cli/api/client.py

@@ -3,6 +3,8 @@
 Contract: `get`, `query`, `command`, and `raw_query` route every response through `_handle`,
 which maps HTTP status and the body's `status` field onto the `api.errors` hierarchy;
 `raw_query` alone skips the status gate, and `probe` skips both the gate and the retry loop.
+`get`, `query` and `raw_query` retry every transient failure; `command` retries only
+`errors.NEVER_RAN`, because any other failure can follow a write the platform already committed.
 Neither `query`, `command`, nor `raw_query` names which component serves a data-channel call --
 the target revision's blob type decides that server-side, so there is nothing for a caller to
 supply here at all, even for a scheduler `deploy` that legitimately writes schedules against one
@@ -20,19 +22,29 @@ import time
 import httpx
 
 from blobhub_cli.api.errors import (
+    NEVER_RAN,
+    TRANSIENT,
     ApiAuthError,
     ApiCommandError,
+    ApiConnectError,
+    ApiLimitExceeded,
     ApiNetworkError,
     ApiRateLimited,
     ApiTransientError,
 )
 
-_TRANSIENT = (ApiRateLimited, ApiTransientError, ApiNetworkError)
 _ATTEMPTS = 3
 _BASE_DELAY = 0.5
 _MAX_DELAY = 8.0
 
 
+def _network_error(exc: httpx.TransportError) -> ApiNetworkError:
+    """The transport failure as an `ApiNetworkError`, or an `ApiConnectError` when nothing was sent."""
+    error_type = ApiConnectError if isinstance(exc, (httpx.ConnectError, httpx.ConnectTimeout)) else ApiNetworkError
+    # str() of an httpx transport error is often empty (ReadError("")); the class name is then the only cause.
+    return error_type(str(exc) or type(exc).__name__)
+
+
 class Client:
     def __init__(
         self,
@@ -62,7 +74,7 @@ class Client:
         # parameters instead of ignoring them, so `?limit=` or `?cursor=None` is a 400.
         if params is not None:
             params = {key: value for key, value in params.items() if value is not None}
-        return self._send("GET", path, gate_status=True, params=params or None)
+        return self._send("GET", path, gate_status=True, idempotent=True, params=params or None)
 
     def probe(self, path: str = "/users/me") -> tuple[int, float]:
         """One unretried request, returning (status_code, elapsed_ms) without gating the body.
@@ -75,7 +87,7 @@ class Client:
         try:
             resp = self._http.request("GET", path)
         except httpx.TransportError as exc:
-            raise ApiNetworkError(str(exc)) from exc
+            raise _network_error(exc) from exc
         return resp.status_code, (time.monotonic() - start) * 1000
 
     def query(self, revision_id: str, command: str, **args: object) -> dict:
@@ -92,20 +104,26 @@ class Client:
     ) -> dict:
         path = f"/revisions/{revision_id}/data/{channel}"
         body = {"command": command, **args}
-        return self._send("POST", path, gate_status=gate_status, json=body)
+        return self._send("POST", path, gate_status=gate_status, idempotent=(channel == "query"), json=body)
 
-    def _send(self, method: str, path: str, *, gate_status: bool, **kwargs: object) -> dict:
+    def _send(
+        self, method: str, path: str, *, gate_status: bool, idempotent: bool, **kwargs: object
+    ) -> dict:
+        # A write retries only what proves it never ran (docs/specs/2026-10-06-safe-retries.md).
+        retryable = TRANSIENT if idempotent else NEVER_RAN
         last_error: Exception
         for attempt in range(_ATTEMPTS):
             try:
                 resp = self._http.request(method, path, **kwargs)
             except httpx.TransportError as exc:
-                last_error = ApiNetworkError(str(exc))
+                last_error = _network_error(exc)
             else:
                 try:
                     return self._handle(resp, gate_status=gate_status)
-                except _TRANSIENT as exc:
+                except TRANSIENT as exc:
                     last_error = exc
+            if not isinstance(last_error, retryable):
+                break
             if attempt < _ATTEMPTS - 1:
                 self._sleep(random.random() * min(_MAX_DELAY, _BASE_DELAY * 2**attempt))
         raise last_error
@@ -122,5 +140,7 @@ class Client:
         except ValueError as exc:
             raise ApiTransientError(f"non-JSON response: HTTP {resp.status_code}") from exc
         if gate_status and data.get("status") != "success":
-            raise ApiCommandError(data.get("error", "unknown"), data.get("message", ""))
+            if data.get("error") == "limit_exceeded":
+                raise ApiLimitExceeded(data.get("message", ""), data.get("limit"))
+            raise ApiCommandError(data.get("error", "unknown"), data.get("message", ""), data.get("limit"))
         return data

{blobhub_cli-0.5.0 → blobhub_cli-0.7.0}/src/blobhub_cli/api/commands.py

@@ -41,8 +41,8 @@ class Api:
             f"/blobs/{org}/{blob}/revisions", {"limit": limit, "cursor": cursor})
         return body["revisions"], body["cursor"]
 
-    def get_blob_limits(self, org: str, blob: str) -> dict:
-        return self._client.get(f"/blobs/{org}/{blob}/limits")["limits"]
+    def get_blob_limits(self, org: str, blob: str) -> list[dict]:
+        return self._client.get(f"/blobs/{org}/{blob}/limits")["groups"]
 
     def list_definitions(self, revision_id: str, category: str) -> list[dict]:
         return self._client.query(revision_id, "list_definitions", category=category)["definitions"]
@@ -85,32 +85,64 @@ class Api:
     def get_execution(self, revision_id: str, execution_id: str) -> dict:
         return self._client.query(revision_id, "get_execution", execution_id=execution_id)["execution"]
 
+    def list_session_events(
+        self,
+        revision_id: str,
+        session: str,
+        *,
+        filter: dict | None = None,
+        after: str | None = None,
+        ascending: bool | None = None,
+        limit: int | None = None,
+        cursor: str | None = None,
+    ) -> tuple[list[dict], str | None]:
+        args = self._page_args(filter, after, ascending, limit, cursor)
+        body = self._client.query(revision_id, "list_session_events", session=session, **args)
+        return body["events"], body["cursor"]
+
     def list_execution_events(
         self,
         revision_id: str,
         execution_id: str,
         *,
-        created_since: str | None = None,
-        ascending: bool = True,
+        filter: dict | None = None,
+        after: str | None = None,
+        ascending: bool | None = None,
         limit: int | None = None,
-    ) -> list[dict]:
+        cursor: str | None = None,
+    ) -> tuple[list[dict], str | None]:
+        args = self._page_args(filter, after, ascending, limit, cursor)
+        body = self._client.query(revision_id, "list_execution_events", execution_id=execution_id, **args)
+        return body["events"], body["cursor"]
+
+    @staticmethod
+    def _page_args(
+        filter: dict | None, after: str | None, ascending: bool | None, limit: int | None, cursor: str | None
+    ) -> dict[str, object]:
         # Keys are omitted rather than sent as null: every command schema is
         # additionalProperties: false, so one stray key is a 400, not an ignored field.
-        args: dict[str, object] = {"execution_id": execution_id, "ascending": ascending}
-        if created_since is not None:
-            args["created_since"] = created_since
-        if limit is not None:
-            args["limit"] = limit
-        return self._client.query(revision_id, "list_execution_events", **args)["execution_events"]
+        given = {"filter": filter or None, "after": after, "ascending": ascending, "limit": limit, "cursor": cursor}
+        return {key: value for key, value in given.items() if value is not None}
+
+    def list_session_listeners(self, revision_id: str, session: str) -> list[dict]:
+        return self._client.query(revision_id, "list_session_listeners", session=session)["listeners"]
+
+    def set_session_listener(self, revision_id: str, session: str, listener: str, enabled: bool) -> dict:
+        return self._client.command(
+            revision_id, "set_session_listener", session=session, listener=listener, enabled=enabled
+        )["listener"]
 
     def list_executions(
-        self, revision_id: str, session_id: str, *, start_execution_id: str | None = None
+        self,
+        revision_id: str,
+        session_id: str,
+        *,
+        listener: str | None = None,
+        start_execution_id: str | None = None,
     ) -> tuple[list[dict], str | None]:
-        # start_execution_id is omitted rather than sent as null, same reason list_schedules omits
-        # start_schedule_id: LIST_EXECUTIONS_SCHEMA is additionalProperties: false. One page and the
-        # next cursor -- this method deliberately does not loop; the loop belongs to the caller that
-        # knows why it's paging (deploy's saturation count stops early on purpose).
         args: dict[str, object] = {"session_id": session_id}
+        if listener is not None:
+            args["listener"] = listener
         if start_execution_id is not None:
             args["start_execution_id"] = start_execution_id
         body = self._client.query(revision_id, "list_executions", **args)

blobhub_cli-0.7.0/src/blobhub_cli/api/errors.py

@@ -0,0 +1,90 @@
+"""Error hierarchy raised by `client.Client`.
+
+Contract: every failure raised is one of these classes, each carrying a `code` class attribute
+from `blobhub_cli.codes`; `ApiCommandError` additionally carries `.error`, the server's
+machine-readable failure string, kept separate from the human-readable `.message`, and `.limit`,
+the served limit object any refusal may carry -- `ApiLimitExceeded` is the `limit_exceeded` one.
+`outcome_unknown` says which failures leave a write's outcome unknown (the SDK-modernization
+epic's D5, `docs/specs/2026-10-06-safe-retries.md`).
+Invariant: no instance of any of these classes ever carries the API key — the client that
+raises them holds the only copy, and it is never included in a message here.
+"""
+
+import json
+
+from blobhub_cli import codes
+
+
+class ApiError(Exception):
+    """Base class for every error `Client` raises."""
+
+    code = "API_ERROR"
+
+
+class ApiAuthError(ApiError):
+    """The API key was rejected or the resource is forbidden (HTTP 401/403)."""
+
+    code = codes.AUTH_INVALID
+
+
+class ApiRateLimited(ApiError):
+    """API Gateway throttled the request (HTTP 429) before anything ran. Retried for every request."""
+
+    code = codes.API_RATE_LIMITED
+
+
+class ApiTransientError(ApiError):
+    """A server-side or malformed-response failure (HTTP 5xx, non-JSON body). Retried for reads only."""
+
+    code = codes.API_TRANSIENT_ERROR
+
+
+class ApiNetworkError(ApiError):
+    """A transport failure: no usable response arrived. Retried for reads only."""
+
+    code = codes.API_NETWORK_ERROR
+
+
+class ApiConnectError(ApiNetworkError):
+    """The connection was never established, so the request was never sent. Retried for every request."""
+
+
+class ApiCommandError(ApiError):
+    """A successful HTTP response whose body reports `status` other than `success`."""
+
+    code = codes.API_COMMAND_FAILED
+
+    def __init__(self, error: str, message: str = "", limit: dict | None = None) -> None:
+        message = with_limit(message, limit)
+        super().__init__(message or error)
+        self.error = error
+        self.message = message or error
+        self.limit = limit
+
+
+class ApiLimitExceeded(ApiCommandError):
+    """A `limit_exceeded` refusal: a quota or a configurable ceiling has been reached."""
+
+    code = codes.LIMIT_EXCEEDED
+
+    def __init__(self, message: str = "", limit: dict | None = None) -> None:
+        super().__init__("limit_exceeded", message, limit)
+
+
+def with_limit(message: str, limit: dict | None) -> str:
+    """`message` with the served limit appended, as `(limit <id>: value <v>[, held <h>])`."""
+    if not limit:
+        return message
+    held = f", held {json.dumps(limit['held'])}" if "held" in limit else ""
+    named = f"limit {limit.get('id')}: value {json.dumps(limit.get('value'))}{held}"
+    return f"{message} ({named})" if message else named
+
+
+TRANSIENT = (ApiRateLimited, ApiTransientError, ApiNetworkError)
+# A write may retry only these: a 429 is refused before any handler runs, and a failed connect sent nothing.
+NEVER_RAN = (ApiRateLimited, ApiConnectError)
+
+
+def outcome_unknown(error: BaseException) -> bool:
+    """Whether a failed request may still have been carried out by the platform."""
+    return isinstance(error, TRANSIENT) and not isinstance(error, NEVER_RAN)

{blobhub_cli-0.5.0 → blobhub_cli-0.7.0}/src/blobhub_cli/blob/reference.py

@@ -40,12 +40,21 @@ def not_accessible(ref: BlobRef) -> CliExit:
     can add: an org-scoped key must address its org by UUID and gets exactly this 403 against an
     alias -- which is why it belongs to the message rather than to one of the two raise sites.
     """
-    message = f"blob {ref.label()} is absent or not accessible with this key"
+    message = _refused(ref.label())
     if not ids.looks_like_uuid(ref.org):
         message += f"; if this API key is org-scoped, it must address the org by UUID, not the alias {ref.org!r}"
     return CliExit(codes.BLOB_NOT_ACCESSIBLE, message, "blobhub whoami")
 
 
+def id_not_accessible(blob_id: str) -> CliExit:
+    """BLOB_NOT_ACCESSIBLE for a blob named by id alone, so no org clause applies."""
+    return CliExit(codes.BLOB_NOT_ACCESSIBLE, _refused(blob_id), "blobhub whoami")
+
+
+def _refused(label: str) -> str:
+    return f"blob {label} is absent or not accessible with this key"
+
+
 def parse(text: str, default_org: str | None, *, command: str = DEFAULT_COMMAND) -> BlobRef:
     # `command` is the sub-command the caller is running ("blob revisions", "blob limits", ...),
     # threaded in only so that every hint below is a command the user can actually paste. It is no

{blobhub_cli-0.5.0 → blobhub_cli-0.7.0}/src/blobhub_cli/cli/app.py

@@ -12,7 +12,7 @@ import typer
 from typer.completion import completion_init
 
 from blobhub_cli import __version__, codes, console
-from blobhub_cli.api.errors import ApiError
+from blobhub_cli.api.errors import ApiCommandError, ApiError
 from blobhub_cli.commands.completion import Shell as CompletionShell
 from blobhub_cli.config import settings
 from blobhub_cli.exit import CliExit
@@ -42,9 +42,10 @@ def build_app() -> typer.Typer:
         verbose: bool = typer.Option(False, "-v", "--verbose", help="Print extra diagnostic detail."),
         quiet: bool = typer.Option(False, "-q", "--quiet", help="Suppress advisory warnings."),
         org: str = typer.Option(None, "--org", help="Org a manifest's bare 'blob:' name belongs to."),
+        profile: str = typer.Option(None, "--profile", help="Profile to use for this command."),
     ) -> None:
         console.configure(json_output=json_output, verbose=verbose, quiet=quiet)
-        settings.configure(org=org)
+        settings.configure(org=org, profile=profile)
         if version:
             typer.echo(__version__)
             raise typer.Exit(0)
@@ -134,7 +135,10 @@ def build_app() -> typer.Typer:
 
         completion_cmd.emit(shell)
 
-    profile_app = typer.Typer(add_completion=False, help="Manage stored profiles.")
+    profile_app = typer.Typer(
+        add_completion=False,
+        help="Manage stored profiles. Takes names as arguments; ignores the root --profile.",
+    )
 
     @profile_app.command("ls")
     def profile_ls() -> None:
@@ -175,7 +179,7 @@ def build_app() -> typer.Typer:
         blob: str = typer.Argument(..., help="Blob as '<org>/<name>', or a bare name with --org."),
         refresh: bool = typer.Option(False, "--refresh", help="Also refresh the compiler's local allowlist cache."),
     ) -> None:
-        """Show a blob's limits, including the import allowlist. Requires an admin-scoped key."""
+        """Show a blob's limits by group: id, holding, source and value."""
         from blobhub_cli.commands import blob as blob_cmd
 
         blob_cmd.limits(blob, refresh)
@@ -234,13 +238,12 @@ def build_app() -> typer.Typer:
         manifest: Path = typer.Option(..., "-f", "--file", help="Path to the workflow manifest."),  # noqa: B008
         definition: list[str] = typer.Option([], "--definition", help="Limit to this alias, repeatable."),  # noqa: B008
         force: bool = typer.Option(False, "--force", help="Overwrite code edited outside the CLI."),
-        strict_imports: bool = typer.Option(False, "--strict-imports", help="Treat an unverifiable import as fatal."),
         dry_run: bool = typer.Option(False, "--dry-run", help="Report the intended calls and perform none."),
     ) -> None:
         """Build, upload only what changed, and check the workflow definitions that were uploaded."""
         from blobhub_cli.commands import workflow
 
-        workflow.deploy(manifest, tuple(definition), force, strict_imports, dry_run)
+        workflow.deploy(manifest, tuple(definition), force, dry_run)
 
     @workflow_app.command("eject")
     def workflow_eject(
@@ -271,6 +274,73 @@ def build_app() -> typer.Typer:
 
         execute_cmd.execute(manifest, definition, session, watch, open_browser)
 
+    @workflow_app.command("events")
+    def workflow_events(
+        session: str = typer.Argument(
+            ..., help="A session, or <blob-id>/<revision>/<session> or <org>/<blob>/<revision>/<session>."
+        ),
+        manifest: Path = typer.Option(  # noqa: B008
+            None, "-f", "--file", help="Manifest naming the blob and revision of a bare session."
+        ),
+        types: list[str] = typer.Option([], "--types", help="Event types, globs allowed; repeatable."),  # noqa: B008
+        aliases: list[str] = typer.Option([], "--aliases", help="Object aliases; repeatable."),  # noqa: B008
+        executions: list[str] = typer.Option([], "--executions", help="Execution ids; repeatable."),  # noqa: B008
+        listener: str = typer.Option(None, "--listener", help="Only events a listener caused: its alias or id."),
+        after: str = typer.Option(None, "--after", help="List events after this id, boundary or ISO 8601 time."),
+        cursor: str = typer.Option(None, "--cursor", help="Continue a listing from the token it printed."),
+        limit: int = typer.Option(20, "--limit", min=1, max=1000, help="Events per page."),
+        follow: bool = typer.Option(False, "--follow", help="Print new events as they arrive until interrupted."),
+    ) -> None:
+        """List a session's events, newest first unless --after is given, or follow them."""
+        from blobhub_cli.commands import events as events_cmd
+
+        events_cmd.events(
+            session, manifest, types=types, aliases=aliases, executions=executions, listener=listener,
+            after=after, cursor=cursor, limit=limit, follow=follow,
+        )
+
+    @workflow_app.command("listeners")
+    def workflow_listeners(
+        session: str = typer.Argument(
+            ..., help="A session, or <blob-id>/<revision>/<session> or <org>/<blob>/<revision>/<session>."
+        ),
+        manifest: Path = typer.Option(  # noqa: B008
+            None, "-f", "--file", help="Manifest naming the blob and revision of a bare session."
+        ),
+        listener: str = typer.Option(None, "--listener", help="Show one declared listener: its alias or id."),
+    ) -> None:
+        """List a session's listeners with their switch, slots and outcomes, or show one in detail."""
+        from blobhub_cli.commands import events as events_cmd
+
+        events_cmd.listeners(session, manifest, listener=listener)
+
+    listener_app = typer.Typer(add_completion=False, help="Switch a declared listener for one session.")
+
+    def _listener_switch(session: str, listener: str, manifest: Path | None, enabled: bool) -> None:
+        from blobhub_cli.commands import events as events_cmd
+
+        events_cmd.switch(session, manifest, listener, enabled)
+
+    @listener_app.command("enable")
+    def listener_enable(
+        session: str = typer.Argument(..., help="A session reference, as for `workflow events`."),
+        listener: str = typer.Argument(..., help="A declared listener's alias or id."),
+        manifest: Path = typer.Option(None, "-f", "--file", help="Manifest naming a bare session's blob."),  # noqa: B008
+    ) -> None:
+        """Enable a listener for this session, overriding its definition when it is off there."""
+        _listener_switch(session, listener, manifest, True)
+
+    @listener_app.command("disable")
+    def listener_disable(
+        session: str = typer.Argument(..., help="A session reference, as for `workflow events`."),
+        listener: str = typer.Argument(..., help="A declared listener's alias or id."),
+        manifest: Path = typer.Option(None, "-f", "--file", help="Manifest naming a bare session's blob."),  # noqa: B008
+    ) -> None:
+        """Disable a listener for this session, overriding its definition when it is on there."""
+        _listener_switch(session, listener, manifest, False)
+
+    workflow_app.add_typer(listener_app, name="listener")
+
     @workflow_app.command("check")
     def workflow_check(
         manifest: Path = typer.Option(..., "-f", "--file", help="Path to the workflow manifest."),  # noqa: B008
@@ -381,7 +451,8 @@ def main(argv: list[str] | None = None) -> int:
         # so wrap it in a CliExit rather than let a raw traceback reach the user. Only AUTH_INVALID
         # has a hint that's genuinely a runnable command; inventing one for the rest would be prose.
         hint = "blobhub login" if exc.code == codes.AUTH_INVALID else ""
-        console.error(CliExit(exc.code, str(exc), hint))
+        limit = exc.limit if isinstance(exc, ApiCommandError) else None
+        console.error(CliExit(exc.code, str(exc), hint, limit=limit))
         return 1
     except Exception as exc:  # usage errors carry exit_code; anything else is a real bug
         # Typer >=0.24 vendors its own click fork under `typer._click` rather than

{blobhub_cli-0.5.0 → blobhub_cli-0.7.0}/src/blobhub_cli/codes.py

@@ -31,7 +31,6 @@ MANIFEST_VERSION_UNSUPPORTED = "MANIFEST_VERSION_UNSUPPORTED"
 BLOB_REFERENCE_INVALID = "BLOB_REFERENCE_INVALID"
 BLOB_NOT_ACCESSIBLE = "BLOB_NOT_ACCESSIBLE"
 BLOB_NOT_WORKFLOW = "BLOB_NOT_WORKFLOW"
-LIMITS_NOT_ACCESSIBLE = "LIMITS_NOT_ACCESSIBLE"
 REVISION_NOT_ACCESSIBLE = "REVISION_NOT_ACCESSIBLE"
 REVISION_NOT_WRITABLE = "REVISION_NOT_WRITABLE"
 
@@ -40,11 +39,13 @@ DEFINITION_NOT_ACCESSIBLE = "DEFINITION_NOT_ACCESSIBLE"
 DEFINITION_ALIAS_INVALID = "DEFINITION_ALIAS_INVALID"
 DEFINITION_CATEGORY_UNKNOWN = "DEFINITION_CATEGORY_UNKNOWN"
 ALIAS_IN_USE = "ALIAS_IN_USE"
+LISTENER_INVALID = "LISTENER_INVALID"
 LIMIT_EXCEEDED = "LIMIT_EXCEEDED"
 PRUNE_NOT_CONFIRMED = "PRUNE_NOT_CONFIRMED"
 
 # Workflow references
 WORKFLOW_REFERENCE_INVALID = "WORKFLOW_REFERENCE_INVALID"
+SESSION_REFERENCE_INVALID = "SESSION_REFERENCE_INVALID"
 
 # Format
 FORMAT_UNSUPPORTED = "FORMAT_UNSUPPORTED"
@@ -82,6 +83,10 @@ SESSION_NOT_ACCESSIBLE = "SESSION_NOT_ACCESSIBLE"
 SESSION_NOT_OPEN = "SESSION_NOT_OPEN"
 DEFINITION_NOT_EXECUTABLE = "DEFINITION_NOT_EXECUTABLE"
 EXECUTION_FAILED = "EXECUTION_FAILED"
+EXECUTION_OUTCOME_UNKNOWN = "EXECUTION_OUTCOME_UNKNOWN"
+EVENT_FILTER_INVALID = "EVENT_FILTER_INVALID"
+EVENT_CURSOR_INVALID = "EVENT_CURSOR_INVALID"
+LISTENER_NOT_FOUND = "LISTENER_NOT_FOUND"
 
 # Schedules
 SCHEDULE_ALIAS_REQUIRED = "SCHEDULE_ALIAS_REQUIRED"

{blobhub_cli-0.5.0 → blobhub_cli-0.7.0}/src/blobhub_cli/commands/auth.py

@@ -7,7 +7,6 @@ hint, or the returned payload — only the profile name, URL, and realtime URL a
 """
 
 import getpass
-import os
 import sys
 from collections.abc import Callable
 from typing import NamedTuple
@@ -86,7 +85,7 @@ def login(
     stdin_read: Callable[[], str] | None = None,
     api_factory: Callable[[Settings], Api] = _default_api_factory,
 ) -> dict:
-    name = profile or os.environ.get("BLOBHUB_PROFILE") or "default"
+    name = settings.profile_name(profile, None) or "default"
 
     requests = [
         sources.Request("api-key", supplied.api_key, supplied.api_key_stdin, supplied.api_key_env),
@@ -179,7 +178,7 @@ def logout(profile: str | None, all_profiles: bool) -> dict:
         removed = sorted(profiles)
         credentials.save({}, None)
     else:
-        name = profile or default
+        name = settings.profile_name(profile, default)
         if name is None or name not in profiles:
             raise CliExit(codes.PROFILE_NOT_FOUND, f"no profile named {name!r}", "blobhub profile ls")
         del profiles[name]