pipecatcloud 1.4.0__tar.gz → 1.6.0__tar.gz

{pipecatcloud-1.4.0 → pipecatcloud-1.6.0}/CHANGELOG.md

@@ -5,6 +5,158 @@ All notable changes to **Pipecat Cloud** will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.6.0] - 2026-11-12
+
+### Added
+
+- `project` is the command group for everything you deploy and run. A project
+  is an agent with environments; each environment is an agent of its own, and
+  `--env` addresses one through its project.
+
+  ```
+  pipecat cloud project list
+  pipecat cloud project status my-bot --env staging
+  pipecat cloud project logs my-bot --env pr-7
+  ```
+
+  Every command that took an agent name takes `--env` as well: `status`,
+  `logs`, `sessions`, `deployments`, `delete`, `start`, `stop`, `link`,
+  `unlink` and `deploy`. A positional agent name still works, so
+  `project status my-bot-pr-7` resolves the same preview.
+
+- `project env` manages a project's environments.
+
+  - `project env add <project> <name> --agent <agent>` links an existing agent
+    as an environment. `project env remove` unlinks it, leaving it running as
+    a project of its own. `project env list` lists them: `production`, which
+    is the project's own agent, then the named environments and then the PR
+    previews.
+  - `--env production` is the project itself, which is the environment it
+    doubles as, so it means the same as naming the project with no `--env`.
+    `env promote` and `env remove` name an environment to act on, so they
+    refuse `production` and say why.
+  - `project env promote <project> <name>` deploys an environment's running
+    build, or the image it was deployed from, onto the project. Code only: the
+    project keeps its own secrets, scaling and profile. It confirms first, and
+    `--force` skips the prompt.
+
+- `project previews enable <project> --secret-set <set>` turns PR previews on,
+  with `--bot-pull-requests` to include pull requests opened by bots.
+  `project previews disable` turns them off and deletes the previews it has.
+  `project previews status` shows the setting and the open previews.
+
+- `project watch-paths set <project> <pattern>...` sets the glob patterns a
+  change has to match to deploy, `clear` removes them, and `show` prints them. They are a
+  project setting: its environments and previews follow the same list.
+
+- `project list --all` includes environments and PR previews. Without it the
+  listing is projects only, as the dashboard shows them. Both carry columns for
+  a project's environment count and preview setting, and `--all` names each
+  environment's project.
+
+- `deploy`, when it runs a cloud build, and `docker build-push` warn when the
+  Dockerfile builds `FROM dailyco/pipecat-base:latest`, or from
+  `dailyco/pipecat-base` with no tag. That tag names no Python, runs Python
+  3.12, and stops building on 2027-04-05. The warning names the line, and the
+  tag that keeps the same Python: `dailyco/pipecat-base:latest-py3.12`.
+
+### Changed
+
+- `agent` is **deprecated**. It is the same group under its old name: every
+  command goes on working and `agent list` goes on listing every agent, with a
+  notice on stderr pointing at `project`. Use `project`, and `--env` to address
+  an environment.
+- `status` reports the project and environment of an agent that is one, its
+  watch paths, and, for a project, whether PR previews are on and whether bot
+  pull requests get them. For a PR preview it names the pull request.
+
+### Removed
+
+- `agent scale` is gone. It was never implemented: it printed "Not implemented"
+  and exited. Set an agent's instance counts with `pipecat cloud deploy
+  --min-agents/--max-agents`, or the `[scaling]` section of `pcc-deploy.toml`.
+
+### Fixed
+
+- A command no longer reports an operation as done when the CLI never managed
+  to make the request. A mistake inside the client, such as a call made with a
+  name the API method does not take, was handed back as an empty result, and
+  every command reads an empty error as success: a build promotion printed
+  "Promoted build ..." having sent no request at all. Such a failure now ends
+  the command with a non-zero exit code.
+- A command that cannot reach the API, or cannot read its answer, now says so
+  and exits 1. A dropped connection, a host that does not resolve, a request
+  that timed out and an answer that stops part way through were all read as an
+  empty answer, which most commands reported as success. `secrets set`
+  already said so, and still says whether a write it got no answer for may have
+  been stored. `deploy` and `github connect` still treat it as a blip while
+  they are waiting, and keep polling.
+
+## [1.5.0] - 2026-11-05
+
+### Added
+
+- `secrets keys --region <region>` shows your organization's secret keys in a
+  region: each key's fingerprint, state, created and retired times, and how
+  many secrets it holds, as text or with `--output json`. The fingerprint is
+  the one a security notice names and, in a self-hosted region, the one your
+  cluster shows for the key. It never shows key material. Against a server
+  that does not offer this yet, it says so and exits 1.
+
+### Changed
+
+- `secrets set` with several values now writes them in one request, which the
+  server applies whole or not at all, so a large set takes one write in place
+  of one per key. Against a server that does not take this yet, including one
+  part way through an update, it writes one key at a time as before, and still
+  says how far it got if one fails.
+- `secrets set`, `secrets unset` and `secrets image-pull-secret` now wait and
+  retry when the API answers a write with a 503 and a `Retry-After` of up to
+  30 seconds, as a region can on its first secrets write. They retry up to 3 times, say they
+  are waiting, and fail as before if the 503 persists. Other errors, and a 503
+  without a usable `Retry-After`, are not retried. A `Retry-After` above 30
+  seconds is not waited out; the error says how long the region asked for.
+  A write that ends in a 503 may still have reached the region, unless the
+  error says nothing was stored. Running the same command again settles it.
+
+### Fixed
+
+- `--region` is now checked against the regions of the organization given
+  with `--organization`, not only the organization in your config file. This
+  affects `secrets set`, `secrets list`, `secrets image-pull-secret`,
+  `secrets reference`, `agent list` and `deploy`. A region that belongs only
+  to the other organization, such as a self-hosted region, was refused as
+  invalid.
+- `secrets set` no longer reports success when a write gets no answer from the
+  server, as when the connection drops. It says so and exits 1.
+
+### Security
+
+- Logs no longer contain secret values or other request data. With debug
+  logging on (`PIPECAT_CLI_LOG_LEVEL=DEBUG` for the CLI, `PCC_LOG_LEVEL=DEBUG`
+  for the Python package), `secrets set` wrote the values it was given to
+  stderr, and every API request wrote its body and query there, including
+  image pull credentials and session data. Requests now log their method,
+  path and how much they carry. Tokens were not in these lines. If you ran
+  with debug logging on and the output was kept, for example in CI logs,
+  change the values it contains.
+- An unexpected error in the CLI could print its local variables in the
+  traceback, including secret values and your token. Tracebacks now show code
+  only. To see them as before, set `TYPER_STANDARD_TRACEBACK` to an empty value.
+- A failed build context upload now logs its status and S3 error code, not
+  S3's error document, which can repeat signed upload details. This line is
+  logged at the default level.
+- `secrets set` no longer shows the first characters of each value when it asks
+  you to confirm. It shows a fixed mask, the same for any value. Without
+  `--skip` and without a terminal, as in CI, it printed those characters and
+  then failed; it now fails first. If such output was kept, change the values
+  it contains.
+- The locked versions of `virtualenv`, `packaging`, `distlib`, `Pillow` and
+  `setuptools` are upgraded for security fixes. These are the versions in
+  `uv.lock`, used to develop and test this package. What it requires when you
+  install it has not changed, so upgrade your own environment if it holds an
+  older one.
+
 ## [1.4.0] - 2026-10-22
 
 ### Added

{pipecatcloud-1.4.0 → pipecatcloud-1.6.0}/CLAUDE.md

@@ -103,6 +103,7 @@ pcc-deploy.toml          Example deployment config consumed by `pipecat cloud de
 - Auth uses OAuth2 with PKCE (RFC 7636). OAuth endpoints are discovered from the API server, not hardcoded. The callback server tries ports 8400-8404.
 - The session argument types in `agent.py` subclass pipecat-ai's runner types and need pipecat-ai (>= 1.0.0); there are no fallback definitions. `MOQSessionArguments` needs 1.12.0 (`MOQRunnerArguments.relay_url`), so it is imported and defined under its own guard: on older pipecat-ai the module still imports and only that name is missing. It stays out of `__all__` for the same reason.
 - Krisp VIVA audio filter names are `Literal["tel", "pro"]` in `constants.py`. These must match the server-side ConfigMap, so coordinate changes with the backend.
+- Never log a request or response body, a header, or an exception's text: they can hold secret values and tokens. Use `_utils/log_utils.py`. `tests/test_log_redaction.py` fails on a log call that reads a name or attribute it knows can hold one, however it is formatted, or that uses `logger.opt`, `logger.exception` or `logger.catch`. Only `describe_*` and `len` calls are exempt.
 
 ## Release flow
 

{pipecatcloud-1.4.0/src/pipecatcloud.egg-info → pipecatcloud-1.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pipecatcloud
-Version: 1.4.0
+Version: 1.6.0
 Summary: Cloud hosting for Pipecat AI applications
 License: BSD 2-Clause License
 Project-URL: Website, https://docs.pipecat.ai/pipecat-cloud
@@ -70,6 +70,10 @@ To use Pipecat Cloud programmatically (without the CLI), install the package dir
 
 4. Build and deploy your agent `pipecat cloud deploy`
 
+### Seeing your secret keys
+
+`pipecat cloud secrets keys --region <region>` shows your organization's secret keys in a region: each key's fingerprint, state, created and retired times, and how many secrets it holds. The fingerprint is the one a security notice names and, in a self-hosted region, the one your cluster shows for the key, so you can compare them. Add `--output json` before `secrets` for a single JSON document. Key material is never shown.
+
 ### Usage in Python scripts
 
 If want to programmatically start an agent within a Python script, you can use the `pipecatcloud.session` module.

{pipecatcloud-1.4.0 → pipecatcloud-1.6.0}/README.md

@@ -47,6 +47,10 @@ To use Pipecat Cloud programmatically (without the CLI), install the package dir
 
 4. Build and deploy your agent `pipecat cloud deploy`
 
+### Seeing your secret keys
+
+`pipecat cloud secrets keys --region <region>` shows your organization's secret keys in a region: each key's fingerprint, state, created and retired times, and how many secrets it holds. The fingerprint is the one a security notice names and, in a self-hosted region, the one your cluster shows for the key, so you can compare them. Add `--output json` before `secrets` for a single JSON document. Key material is never shown.
+
 ### Usage in Python scripts
 
 If want to programmatically start an agent within a Python script, you can use the `pipecatcloud.session` module.

{pipecatcloud-1.4.0 → pipecatcloud-1.6.0}/pyproject.toml

@@ -41,7 +41,7 @@ dev = [
     "pytest>=9.0.0,<10",
     "pytest-asyncio>=1.0.0,<2",
     "ruff>=0.12.11,<1",
-    "setuptools>=83.0.0,<84",
+    "setuptools>=84.1.0,<85",
     "setuptools_scm~=8.3.1",
     # Imported by the tests to compare pipecat-ai versions.
     "packaging>=25.0",

pipecatcloud-1.6.0/src/pipecatcloud/_utils/base_image.py

@@ -0,0 +1,89 @@
+#
+# Copyright (c) 2026, Daily
+#
+# SPDX-License-Identifier: BSD 2-Clause License
+#
+
+"""Warnings about the base image an agent's Dockerfile builds from.
+
+``dailyco/pipecat-base:latest`` names no Python, so it carries Python 3.12, and
+it stops building on ``LATEST_RETIRES``. A Dockerfile that takes it is warned
+before its build. Version tags without ``-py3.X``, such as ``0.3.0``, are
+deprecated too, but each is fixed to one image and stays published, so a
+Dockerfile pinned to one keeps building and is not warned.
+"""
+
+import re
+from pathlib import Path
+
+from rich.markup import escape
+
+from pipecatcloud._utils.console_utils import console
+
+LATEST_RETIRES = "2027-04-05"
+LATEST_PYTHON = "3.12"
+
+# Docker Hub's own names for the repository, which Docker resolves alike.
+_BASE_IMAGE = re.compile(
+    r"(?:(?:docker\.io|index\.docker\.io|registry-1\.docker\.io)/)?dailyco/pipecat-base"
+    r"(?::(?P<tag>[\w][\w.-]*))?(?P<digest>@\S+)?"
+)
+_FROM = re.compile(r"\s*FROM\s+(?:--\S+\s+)*(?P<image>\S+)", re.IGNORECASE)
+
+
+def _instructions(text: str):
+    """Each instruction with the line it starts on, continuation lines joined.
+
+    Comment lines are dropped, inside a continuation too, as Docker drops them.
+    """
+    start, parts = None, []
+    for number, line in enumerate(text.splitlines(), start=1):
+        if line.lstrip().startswith("#"):
+            continue
+        if start is None:
+            start = number
+        if line.rstrip().endswith("\\"):
+            parts.append(line.rstrip()[:-1])
+            continue
+        parts.append(line)
+        yield start, " ".join(parts)
+        start, parts = None, []
+    if parts:
+        yield start, " ".join(parts)
+
+
+def latest_base_images(text: str) -> list[tuple[int, str]]:
+    """The FROM instructions that take ``dailyco/pipecat-base:latest``.
+
+    Returns each one's line number and image, as written. A FROM with no tag
+    takes ``latest`` too. One pinned by digest is fixed, and one built from a
+    variable cannot be read here, so neither is returned.
+    """
+    found = []
+    for number, instruction in _instructions(text):
+        match = _FROM.match(instruction)
+        if not match:
+            continue
+        image = match["image"]
+        base = _BASE_IMAGE.fullmatch(image)
+        if base and not base["digest"] and base["tag"] in (None, "latest"):
+            found.append((number, image))
+    return found
+
+
+def warn_latest_base_image(dockerfile: Path) -> None:
+    """Warn for each FROM in ``dockerfile`` that takes the base image's ``latest``.
+
+    An unreadable Dockerfile is left to the build to report.
+    """
+    try:
+        text = dockerfile.read_text(errors="replace")
+    except OSError:
+        return
+    for number, image in latest_base_images(text):
+        console.print(
+            f"[yellow]Warning: {escape(dockerfile.name)} line {number} builds FROM "
+            f"{escape(image)}, which stops building on {LATEST_RETIRES}. It names no "
+            f"Python, and runs Python {LATEST_PYTHON}: to keep it, use "
+            f"dailyco/pipecat-base:latest-py{LATEST_PYTHON}.[/yellow]"
+        )

{pipecatcloud-1.4.0 → pipecatcloud-1.6.0}/src/pipecatcloud/_utils/build_utils.py

@@ -17,6 +17,7 @@ import gzip
 import hashlib
 import io
 import os
+import re
 import tarfile
 import time
 from collections.abc import Callable
@@ -26,6 +27,8 @@ from pathlib import Path
 import aiohttp
 from loguru import logger
 
+from pipecatcloud._utils.log_utils import describe_exception
+
 # Default patterns to exclude from build context
 DEFAULT_EXCLUSIONS: set[str] = {
     # Version control
@@ -189,7 +192,7 @@ def load_dockerignore(context_dir: Path) -> set[str] | None:
                 if normalized:
                     patterns.add(normalized)
     except Exception as e:
-        logger.warning(f"Failed to read .dockerignore: {e}")
+        logger.warning(f"Failed to read .dockerignore: {describe_exception(e)}")
         return None
 
     return patterns
@@ -375,11 +378,15 @@ async def upload_to_s3(
                     logger.debug(f"Upload successful: {response.status}")
                     return True
                 else:
-                    body = await response.text()
-                    logger.error(f"Upload failed: {response.status} - {body}")
+                    # S3's error document can echo the signed policy and the
+                    # credential it was given, so only its code is logged.
+                    code = re.search(r"<Code>(\w+)</Code>", await response.text())
+                    logger.error(
+                        f"Upload failed: {response.status}{f' ({code[1]})' if code else ''}"
+                    )
                     return False
     except Exception as e:
-        logger.error(f"Upload error: {e}")
+        logger.error(f"Upload error: {describe_exception(e)}")
         return False
 
 

{pipecatcloud-1.4.0 → pipecatcloud-1.6.0}/src/pipecatcloud/_utils/deploy_utils.py

@@ -17,6 +17,7 @@ import typer
 from attr import dataclass, field
 from loguru import logger
 
+from pipecatcloud._utils.log_utils import describe_exception
 from pipecatcloud.cli import PIPECAT_DEPLOY_CONFIG_PATH
 from pipecatcloud.constants import KRISP_VIVA_MODELS, KrispVivaAudioFilter
 from pipecatcloud.exception import ConfigFileError
@@ -607,7 +608,7 @@ def load_deploy_config_file() -> DeployConfigParams | None:
         return validated_config
 
     except Exception as e:
-        logger.debug(e)
+        logger.debug(describe_exception(e))
         raise ConfigFileError(str(e))
 
 
@@ -762,7 +763,7 @@ def report_git_deploy_result(
     from pipecatcloud.cli import PIPECAT_CLI_NAME
 
     check_hint = (
-        f"[dim]Check it with [bold]{PIPECAT_CLI_NAME} agent status {agent_name}[/bold].[/dim]"
+        f"[dim]Check it with [bold]{PIPECAT_CLI_NAME} project status {agent_name}[/bold].[/dim]"
     )
     label = "First deploy" if first_deploy else "Deploy"
 

pipecatcloud-1.6.0/src/pipecatcloud/_utils/environment_utils.py

@@ -0,0 +1,136 @@
+#
+# Copyright (c) 2026, Daily
+#
+# SPDX-License-Identifier: BSD 2-Clause License
+#
+
+"""Shared helpers for projects and environments (PCC-1255).
+
+An environment is an agent of its own, linked to the project it belongs to.
+The project doubles as its own `production` environment, so a project is
+simply an agent with no parent. These helpers read that shape out of the
+service payloads the API already returns, and mirror the name rules it
+enforces so a typo fails before the round trip.
+"""
+
+import re
+
+#: What the project itself is called among its environments.
+PRODUCTION_ENVIRONMENT_NAME = "production"
+
+#: PR previews are named `pr-<n>`, so the API reserves the prefix.
+PREVIEW_ENVIRONMENT_PREFIX = "pr-"
+
+#: The width of the environments.name column.
+MAX_ENVIRONMENT_NAME_LENGTH = 50
+
+# The agent-name rule, which environment names follow too.
+_ENVIRONMENT_NAME_SHAPE = re.compile(r"^[a-z0-9]([-a-z0-9]*[a-z0-9])$")
+
+_PREVIEW_NAME = re.compile(r"^pr-(\d+)$")
+
+
+def environment_name_problem(name: str) -> str | None:
+    """Why the API would refuse this environment name, or None when it's fine."""
+    if not name:
+        return "Enter a name for the environment."
+    if name == PRODUCTION_ENVIRONMENT_NAME:
+        return f"'{PRODUCTION_ENVIRONMENT_NAME}' is the project itself, so it can't be an environment name."
+    if name.startswith(PREVIEW_ENVIRONMENT_PREFIX):
+        return f"Names starting with '{PREVIEW_ENVIRONMENT_PREFIX}' are reserved for PR previews."
+    if len(name) > MAX_ENVIRONMENT_NAME_LENGTH:
+        return f"Use at most {MAX_ENVIRONMENT_NAME_LENGTH} characters."
+    if not _ENVIRONMENT_NAME_SHAPE.match(name):
+        return (
+            "Use two or more lowercase letters, digits and dashes, starting and "
+            "ending with a letter or digit."
+        )
+    return None
+
+
+def is_preview_name(name: str | None) -> bool:
+    """Whether an environment's name is a PR preview's."""
+    return bool(name and _PREVIEW_NAME.match(name))
+
+
+def environment_sort_key(name: str) -> tuple[int, int, str]:
+    """Named environments by name, then PR previews, newest pull request first."""
+    preview = _PREVIEW_NAME.match(name or "")
+    if preview:
+        return (1, -int(preview.group(1)), "")
+    return (0, 0, name or "")
+
+
+def is_environment(service: dict) -> bool:
+    """Whether this agent is an environment of another agent."""
+    return bool(service.get("parentServiceId"))
+
+
+def projects_in(services: list[dict]) -> list[dict]:
+    """The agents that are projects: the ones that are not environments."""
+    return [service for service in services if not is_environment(service)]
+
+
+def environments_of(services: list[dict], project: dict) -> list[dict]:
+    """A project's environments, named ones first and then its PR previews."""
+    children = [
+        service for service in services if service.get("parentServiceId") == project.get("id")
+    ]
+    return sorted(children, key=lambda s: environment_sort_key(s.get("environmentName") or ""))
+
+
+def environments_with_production(services: list[dict], project: dict) -> list[dict]:
+    """A project's environments, the project itself first as `production`.
+
+    The project doubles as that environment, so a listing that left it out
+    would contradict the model the rest of the group works to. Callers that
+    mean only the agents linked to the project use `environments_of`.
+    """
+    return [
+        {**project, "environmentName": PRODUCTION_ENVIRONMENT_NAME},
+        *environments_of(services, project),
+    ]
+
+
+def promotion_source(environment: dict) -> dict | None:
+    """What promoting this environment deploys: its build, or the image it runs.
+
+    None when it has nothing deployed. Promotion moves code only, so this is
+    the whole payload the project is updated with.
+    """
+    deployment = environment.get("deployment") or {}
+    build_id = deployment.get("buildId")
+    if build_id:
+        return {"buildId": build_id}
+    image = ((deployment.get("manifest") or {}).get("spec") or {}).get("image")
+    if image:
+        return {"image": image}
+    return None
+
+
+def describe_promotion_source(source: dict) -> str:
+    """A promotion source as a short phrase, for confirmations and messages."""
+    build_id = source.get("buildId")
+    return f"build {build_id}" if build_id else str(source.get("image"))
+
+
+def previews_on(service: dict) -> bool:
+    """Whether this project has PR previews on.
+
+    Choosing the secret set previews mount is what turns them on, so the set
+    being present is the setting.
+    """
+    git = service.get("git") or {}
+    return bool(git.get("previewSecretSet"))
+
+
+def project_label(service: dict, project_names: dict[str, str]) -> str:
+    """`project > environment` for an environment, or a dash for a project.
+
+    `project_names` maps agent id to name, which is how a parent's name is
+    resolved: the service payload carries only `parentServiceId`.
+    """
+    if not is_environment(service):
+        return "—"
+    parent = project_names.get(service.get("parentServiceId") or "", "?")
+    return f"{parent} > {service.get('environmentName') or '?'}"

pipecatcloud-1.6.0/src/pipecatcloud/_utils/log_utils.py

@@ -0,0 +1,42 @@
+#
+# Copyright (c) 2025, Daily
+#
+# SPDX-License-Identifier: BSD 2-Clause License
+#
+
+"""
+What a log line may say about a request, a response or a failure.
+
+Request and response bodies can hold secret values and credentials, under any name
+and at any depth, and an exception's text can quote them. So a log line says how
+much is there and what kind of thing it is, and never quotes any of it. Headers are
+not logged at all: they carry the token.
+"""
+
+
+def describe_url(url: str) -> str:
+    """A URL without its query string, whose values are not for a log."""
+    return url.split("?", 1)[0]
+
+
+def describe_body(body: object) -> str:
+    """How much a request or response body holds, and never what."""
+    if body is None:
+        return "none"
+    if isinstance(body, dict | list | tuple):
+        return f"{type(body).__name__} of {len(body)}"
+    return type(body).__name__
+
+
+def describe_exception(exc: BaseException) -> str:
+    """An exception's type, and its HTTP status if it has one, without its text."""
+    status = getattr(exc, "status", None)
+    return (
+        f"{type(exc).__name__} (status {status})" if isinstance(status, int) else type(exc).__name__
+    )
+
+
+def describe_api_error(error: object) -> str:
+    """The code of an error body from the API, without its text."""
+    code = error.get("code") if isinstance(error, dict) else None
+    return f"code {code}" if code else "no code"

pipecatcloud-1.6.0/src/pipecatcloud/_utils/regions.py

@@ -0,0 +1,99 @@
+#
+# Copyright (c) 2025, Daily
+#
+# SPDX-License-Identifier: BSD 2-Clause License
+#
+
+"""
+Region utilities for Pipecat Cloud CLI.
+
+Provides functions to fetch and cache available regions from the API.
+"""
+
+from pipecatcloud.cli.api import API
+from pipecatcloud.cli.config import config
+
+# Module-level cache of region lists, keyed by organization. Each organization
+# has its own list (a self-hosted region is visible only to its organization),
+# so one list must never answer for another.
+_regions_cache: dict[str, list[dict[str, str]]] | None = None
+
+
+async def get_regions(org: str | None = None) -> list[dict[str, str]]:
+    """
+    Fetch available regions for an organization from the API with caching.
+
+    The list is cached per organization, so the API is called once per
+    organization per CLI session.
+
+    Args:
+        org: Organization to list regions for. Defaults to the organization in
+            the config file.
+
+    Returns:
+        List of region objects with 'code' and 'display_name' fields, or an
+        empty list when the list cannot be fetched.
+        Example: [
+            {"code": "us-west", "display_name": "US West"},
+            {"code": "eu-central", "display_name": "EU Central"}
+        ]
+    """
+    global _regions_cache
+
+    org = org or config.get("org")
+    if _regions_cache is None:
+        _regions_cache = {}
+
+    if org not in _regions_cache:
+        # API returns (data, error) tuple
+        data, error = await API.regions(org=org)
+        if error or not data:
+            return []
+        _regions_cache[org] = data
+
+    return _regions_cache[org]
+
+
+async def region_error(region: str, org: str | None = None) -> str | None:
+    """
+    Check a region code against the regions of the organization in use.
+
+    Fetches the list once. Returns None when the region is valid, otherwise a
+    message for the user. When the list cannot be fetched, the message says so
+    rather than calling the region invalid. The API client prints its own error
+    for the failed call before this message is returned (in json mode that error
+    goes to stdout as the error object), so the caller shows both: why the call
+    failed, then that the command stopped.
+    """
+    org = org or config.get("org")
+    regions = await get_regions(org)
+    if not regions:
+        return (
+            f"Could not list the regions of organization '{org}', so region "
+            f"'{region}' could not be checked. Not continuing."
+        )
+    codes = [r["code"] for r in regions]
+    if region in codes:
+        return None
+    return f"Invalid region '{region}'. Valid regions are: {', '.join(codes)}"
+
+
+def validate_architecture_for_region(
+    architecture: str, region: str, regions: list[dict]
+) -> str | None:
+    """Pre-validate an architecture choice against a region's capability
+    (PCC-1105). Returns an error message, or None when the choice is valid
+    or cannot be checked locally.
+
+    The regions payload carries ``supported_architectures`` only on newer
+    APIs — when absent, defer to the server's own validation (its 400 names
+    the supported list).
+    """
+    entry = next((r for r in regions if r.get("code") == region), None)
+    supported = (entry or {}).get("supported_architectures")
+    if not supported or architecture in supported:
+        return None
+    return (
+        f"Architecture '{architecture}' is not supported in region '{region}' "
+        f"(supported: {', '.join(supported)})"
+    )