cloudsmith-cli 1.27.0__tar.gz → 1.28.0__tar.gz

{cloudsmith_cli-1.27.0/cloudsmith_cli.egg-info → cloudsmith_cli-1.28.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cloudsmith-cli
-Version: 1.27.0
+Version: 1.28.0
 Summary: Cloudsmith Command-Line Interface (CLI)
 Author-email: Cloudsmith Ltd <support@cloudsmith.io>
 License-Expression: Apache-2.0
@@ -23,6 +23,7 @@ Classifier: Topic :: Utilities
 Requires-Python: >=3.10.0
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Requires-Dist: certifi>=2024.7.4
 Requires-Dist: click!=8.3.0,>=8.2
 Requires-Dist: click-configfile>=0.2.3
 Requires-Dist: click-didyoumean>=0.0.3
@@ -33,10 +34,10 @@ Requires-Dist: keyring>=25.4.1
 Requires-Dist: keyrings-alt>=5.0.2
 Requires-Dist: keyrings-cryptfile>=1.3.9
 Requires-Dist: cryptography>=50.0.0
-Requires-Dist: mcp==1.28.1
+Requires-Dist: mcp==2.2.0
 Requires-Dist: pydantic-settings>=2.14.2
 Requires-Dist: PyJWT[crypto]>=2.13.0
-Requires-Dist: python-toon==0.1.2
+Requires-Dist: python-toon==0.1.3
 Requires-Dist: requests>=2.18.4
 Requires-Dist: requests_toolbelt>=1.0.0
 Requires-Dist: rich>=13.0.0

{cloudsmith_cli-1.27.0 → cloudsmith_cli-1.28.0}/cloudsmith_cli/cli/commands/credential_helper/__init__.py

@@ -27,18 +27,20 @@ def credential_helper():
     manager automatically, or run the runtime command directly for debugging.
 
     Examples:
+
+    \b
         # Install Docker credential helper
         $ cloudsmith credential-helper install docker
-
+    \b
         # Install pnpm credential helper
         $ cloudsmith credential-helper install pnpm
-
+    \b
         # Install cargo credential helper
         $ cloudsmith credential-helper install cargo
-
+    \b
         # Test Docker credential helper directly
         $ echo "docker.cloudsmith.io" | cloudsmith credential-helper docker
-
+    \b
         # Test pnpm credential helper directly
         $ cloudsmith credential-helper pnpm npm.cloudsmith.io
     """

{cloudsmith_cli-1.27.0 → cloudsmith_cli-1.28.0}/cloudsmith_cli/cli/commands/credential_helper/docker.py

@@ -33,23 +33,30 @@ def docker(opts, operation):
     ``workspace`` in ``config.ini``; legacy aliases are also accepted - and a
     valid API key/token).
 
+    \b
     Input (stdin):
         Server URL as plain text (e.g. "docker.cloudsmith.io")
 
+    \b
     Output (stdout):
         JSON: {"Username": "token", "Secret": "<cloudsmith-token>"}
 
+    \b
     Exit codes:
         0: Success
         1: Error (no credentials available, not a Cloudsmith registry, etc.)
 
+    \b
     Examples:
+
+    \b
         # Manual testing
         $ echo "docker.cloudsmith.io" | cloudsmith credential-helper docker
-
+    \b
         # Called by Docker via launcher
         $ echo "docker.cloudsmith.io" | docker-credential-cloudsmith get
 
+    \b
     Environment variables:
         CLOUDSMITH_API_KEY: API key for authentication (optional)
         CLOUDSMITH_WORKSPACE: Workspace slug (CLOUDSMITH_ORG is also accepted)

{cloudsmith_cli-1.27.0 → cloudsmith_cli-1.28.0}/cloudsmith_cli/cli/commands/credential_helper/terraform.py

@@ -92,13 +92,15 @@ def terraform(opts, repo, params):
 
     \b
     Examples:
+
+    \b
         # Direct usage
         $ cloudsmith credential-helper terraform --repo my-repo terraform.cloudsmith.io
         {"token": "..."}
-
+    \b
         # Terraform's calling convention (verb + hostname)
         $ cloudsmith credential-helper terraform --repo my-repo get terraform.cloudsmith.io
-
+    \b
         # Select an org and profile explicitly (no env vars needed)
         $ cloudsmith credential-helper terraform --org=acme -P ci get terraform.cloudsmith.io
 

{cloudsmith_cli-1.27.0 → cloudsmith_cli-1.28.0}/cloudsmith_cli/cli/commands/domains.py

@@ -162,6 +162,7 @@ def list_domains(  # pylint: disable=too-many-arguments
     paginated endpoint, so there is no benefit to hiding entries by default.
     Passing --page or --page-size switches to paged output.
 
+    \b
     Output (stdout):
         JSON: {"version": 1, "domains": [{"host": ..., "format": ...,
         "type": ..., "domain_type": ..., "workspace": ..., "repository": ...,

{cloudsmith_cli-1.27.0 → cloudsmith_cli-1.28.0}/cloudsmith_cli/cli/commands/entitlements.py

@@ -775,14 +775,15 @@ def restrict(
 
     Full CLI example:
 
-      $ cloudsmith entitlements restrict cloudsmith/testing-private/9xGSdAxlIqIV \
-        --limit-bandwidth=1 \
-        --limit-bandwidth-unit=gigabyte \
-        --limit-num-clients=10 \
-        --limit-num-downloads=1000 \
-        --limit-package-query="package-darwin-amd64 OR package-windows-amd64 OR package-linux-amd64" \
-        --limit-path-query=tag:latest \
-        --limit-date-range-from=2020-01-01T00:00:00Z \
+    \b
+      $ cloudsmith entitlements restrict cloudsmith/testing-private/9xGSdAxlIqIV \\
+        --limit-bandwidth=1 \\
+        --limit-bandwidth-unit=gigabyte \\
+        --limit-num-clients=10 \\
+        --limit-num-downloads=1000 \\
+        --limit-package-query="package-darwin-amd64 OR package-windows-amd64 OR package-linux-amd64" \\
+        --limit-path-query=tag:latest \\
+        --limit-date-range-from=2020-01-01T00:00:00Z \\
         --limit-date-range-to=2077-01-01T00:00:00Z
     """
     owner, repo, identifier = owner_repo_identifier

{cloudsmith_cli-1.27.0 → cloudsmith_cli-1.28.0}/cloudsmith_cli/cli/commands/list_.py

@@ -195,6 +195,7 @@ def packages(ctx, opts, owner_repo, page, page_size, query, sort, page_all):
 
     --query 'name:^foo$ filename:.zip$ architecture:~x86'
 
+    \b
     You can sort the results using --sort with these fields:
       - date/-date: Sort by creation date
       - downloads/-downloads: Sort by download count

{cloudsmith_cli-1.27.0 → cloudsmith_cli-1.28.0}/cloudsmith_cli/cli/commands/main.py

@@ -2,6 +2,7 @@
 
 import click
 
+from ...core import update_check
 from ...core.api.version import get_version as get_api_version
 from ...core.utils import get_github_website, get_help_website
 from ...core.version import get_version as get_cli_version
@@ -56,13 +57,22 @@ For issues/contributing: {get_github_website()}
     is_flag=True,
     is_eager=True,
 )
+@click.option(
+    "--no-check-update",
+    is_flag=True,
+    default=False,
+    envvar="CLOUDSMITH_NO_UPDATE_CHECK",
+    help="Disable the once-a-day check for a newer version of the CLI.",
+)
 @decorators.common_cli_config_options
 @decorators.common_cli_output_options
 @click.pass_context
-def main(ctx, opts, version):
+def main(ctx, opts, version, no_check_update):
     """Handle entrypoint to CLI."""
     # pylint: disable=unused-argument
 
+    update_check.arm(ctx, opts, no_check_update)
+
     if version:
         print_version(opts)
     elif ctx.invoked_subcommand is None:

{cloudsmith_cli-1.27.0 → cloudsmith_cli-1.28.0}/cloudsmith_cli/cli/commands/mcp.py

@@ -200,6 +200,7 @@ def configure(ctx, opts, client, is_global):  # pylint: disable=unused-argument
     """
     Configure the Cloudsmith MCP server for supported clients.
 
+    \b
     This command automatically adds the Cloudsmith MCP server configuration
     to the specified client's configuration file. Supported clients are:
     - Claude Desktop
@@ -211,11 +212,12 @@ def configure(ctx, opts, client, is_global):  # pylint: disable=unused-argument
     For Claude Code, --global edits ~/.claude.json (user scope) and
     --local writes ./.mcp.json (project scope, intended to be committed).
 
-    Examples:\n
-        cloudsmith mcp configure --client claude\n
-        cloudsmith mcp configure --client claude-code\n
-        cloudsmith mcp configure --client cursor --local\n
-        cloudsmith mcp configure --client gemini-cli\n
+    \b
+    Examples:
+        cloudsmith mcp configure --client claude
+        cloudsmith mcp configure --client claude-code
+        cloudsmith mcp configure --client cursor --local
+        cloudsmith mcp configure --client gemini-cli
         cloudsmith mcp configure  # Auto-detect and configure all
     """
 

{cloudsmith_cli-1.27.0 → cloudsmith_cli-1.28.0}/cloudsmith_cli/cli/commands/metadata.py

@@ -463,6 +463,7 @@ def remove_metadata(ctx, opts, owner_repo_package, metadata_slug_perm, yes):
     """
     Remove package metadata.
 
+    \b
     OWNER/REPO/PACKAGE: target package.
     METADATA_SLUG_PERM: permanent slug for the metadata entry.
 

{cloudsmith_cli-1.27.0 → cloudsmith_cli-1.28.0}/cloudsmith_cli/cli/commands/registry.py

@@ -37,6 +37,7 @@ LAZY_COMMANDS = {
     "status": f"{_PACKAGE}.status",
     "tags": f"{_PACKAGE}.tags",
     "tokens": f"{_PACKAGE}.tokens",
+    "update": f"{_PACKAGE}.update",
     "upstream": f"{_PACKAGE}.upstream",
     "vulnerabilities": f"{_PACKAGE}.vulnerabilities",
     "whoami": f"{_PACKAGE}.whoami",
@@ -56,4 +57,5 @@ LAZY_ALIASES = {
     "quarantine": ["block"],
     "repositories": ["repos"],
     "tags": ["tag"],
+    "update": ["upgrade"],
 }

cloudsmith_cli-1.28.0/cloudsmith_cli/cli/commands/update.py

@@ -0,0 +1,170 @@
+# Copyright 2026 Cloudsmith Ltd
+"""CLI/Commands - Update the CLI to the latest released version."""
+
+import click
+
+from ...core import installation, self_update, update_check
+from ...core.session import create_requests_session
+from ...core.version import get_version, parse_version
+from .. import decorators, utils
+from ..utils import maybe_spinner
+from .main import main
+
+
+def _fetch_manifest(opts, session, target):
+    import requests
+
+    # A non-standalone channel on a platform without a recognised standalone
+    # target has ``target is None``; the manifest is still fetched only to read
+    # the latest *version* (the channel prints its own upgrade command), so fall
+    # back to a known target rather than building a ``manifest-None`` URL. The
+    # standalone path guards ``target is None`` before reaching here.
+    target = target or update_check.VERSION_PROBE_TARGET
+    try:
+        with maybe_spinner(opts):
+            return update_check.fetch_latest_manifest(session, target=target)
+    except (requests.RequestException, ValueError) as exc:
+        raise click.ClickException(f"Failed to fetch the latest version: {exc}")
+
+
+def _is_up_to_date(latest, current):
+    try:
+        return parse_version(latest) <= parse_version(current)
+    except ValueError as exc:
+        raise click.ClickException(f"Cannot compare versions: {exc}")
+
+
+def _confirm_self_update(opts, current, latest, assume_yes):
+    """Return True to proceed with the self-update.
+
+    Auto-confirms when ``--yes`` is given, when output is machine-readable, or
+    when stderr is not a terminal (so scripted/piped invocations do not hang on
+    a prompt).
+    """
+    if assume_yes or utils.should_use_stderr(opts) or not update_check.stderr_is_tty():
+        return True
+    return click.confirm(
+        f"Update the Cloudsmith CLI from {current} to {latest}?", default=True
+    )
+
+
+def _run_self_update(opts, session, manifest, data):
+    import requests
+
+    use_stderr = utils.should_use_stderr(opts)
+    click.echo(
+        f"Downloading and installing version {manifest['version']} ... ",
+        nl=False,
+        err=use_stderr,
+    )
+    try:
+        with maybe_spinner(opts):
+            self_update.perform_self_update(manifest, session=session)
+    except (self_update.SelfUpdateError, requests.RequestException, OSError) as exc:
+        click.secho("ERROR", fg="red", err=use_stderr)
+        raise click.ClickException(str(exc))
+    click.secho("OK", fg="green", err=use_stderr)
+    data["upgraded"] = True
+    if utils.maybe_print_as_json(opts, data):
+        return
+    click.echo(f"The Cloudsmith CLI is now at version {manifest['version']}.")
+
+
+def _print_manual_update(opts, current, latest, manifest, data):
+    """Report a manual-update path when self-update cannot run (Windows).
+
+    The command already holds the host manifest, so it shows the exact archive
+    URL and checksum rather than a vague pointer; it exits 0 so scripts do not
+    treat "update available, self-update unsupported" as a failure.
+    """
+    changelog = installation.changelog_url(latest)
+    data["outcome"] = "manual"
+    data["download_url"] = manifest.get("url")
+    data["sha256"] = manifest.get("sha256")
+    data["archive"] = manifest.get("archive")
+    data["changelog_url"] = changelog
+    if utils.maybe_print_as_json(opts, data):
+        return
+    click.echo(
+        f"A new version of the Cloudsmith CLI is available: {current} \u2192 {latest}"
+    )
+    click.echo(f"See what's changed: {changelog}")
+    click.echo("Self-update is not supported for the standalone binary on Windows.")
+    click.echo(
+        "Download and extract this archive, then replace your install directory:"
+    )
+    click.echo(f"  URL:    {manifest['url']}")
+    click.echo(f"  SHA256: {manifest['sha256']}")
+
+
+@main.command(aliases=["upgrade"])
+@click.option(
+    "-y",
+    "--yes",
+    "assume_yes",
+    is_flag=True,
+    default=False,
+    help="Do not prompt for confirmation before installing an update.",
+)
+@decorators.common_cli_config_options
+@decorators.common_cli_output_options
+@click.pass_context
+def update(ctx, opts, assume_yes):
+    """Update the Cloudsmith CLI to the latest released version.
+
+    The check runs on every invocation, independent of the once-a-day
+    background version check. A standalone binary downloads and installs the
+    latest release in place; every other install channel is told the correct
+    upgrade command for that channel.
+    """
+    # pylint: disable=unused-argument
+    current = get_version()
+    channel = installation.detect_channel()
+    target = installation.detect_target()
+    if channel == installation.CHANNEL_STANDALONE and target is None:
+        raise click.ClickException(
+            "Cannot detect a supported platform for the standalone binary."
+        )
+
+    session = create_requests_session(user_agent=opts.api_user_agent)
+    manifest = _fetch_manifest(opts, session, target)
+    latest = manifest["version"]
+
+    # Stamp both timestamps regardless of the outcome: the user has just run an
+    # explicit check, so the background notice's daily re-nag is disarmed.
+    update_check.record_checked_and_notified(latest)
+
+    data = {"current_version": current, "latest_version": latest, "channel": channel}
+
+    if _is_up_to_date(latest, current):
+        data["up_to_date"] = True
+        if not utils.maybe_print_as_json(opts, data):
+            click.echo(f"The Cloudsmith CLI is up to date (version {current}).")
+        return
+
+    instruction = installation.upgrade_instruction(channel)
+    if instruction is not None:
+        changelog = installation.changelog_url(latest)
+        data["upgrade_command"] = instruction
+        data["changelog_url"] = changelog
+        if utils.maybe_print_as_json(opts, data):
+            return
+        click.echo(
+            f"A new version of the Cloudsmith CLI is available: {current} \u2192 {latest}"
+        )
+        click.echo(f"See what's changed: {changelog}")
+        click.echo(f"The CLI was installed via {channel}. To update, run:")
+        click.echo(f"  {instruction}")
+        return
+
+    if not installation.self_update_supported():
+        _print_manual_update(opts, current, latest, manifest, data)
+        return
+
+    if not _confirm_self_update(opts, current, latest, assume_yes):
+        data["upgraded"] = False
+        if not utils.maybe_print_as_json(opts, data):
+            click.echo("Update cancelled.")
+        return
+
+    _run_self_update(opts, session, manifest, data)

{cloudsmith_cli-1.27.0 → cloudsmith_cli-1.28.0}/cloudsmith_cli/cli/config.py

@@ -75,6 +75,7 @@ class ConfigSchema:
         oidc_detector_order = ConfigParam(name="oidc_detector_order", type=str)
         oidc_disabled_detectors = ConfigParam(name="oidc_disabled_detectors", type=str)
         metadata_failure_mode = ConfigParam(name="metadata_failure_mode", type=str)
+        check_for_update = ConfigParam(name="check_for_update", type=bool, default=True)
 
     @matches_section("profile:*")
     class Profile(Default):
@@ -602,6 +603,18 @@ class Options:  # pylint: disable=too-many-public-methods
             )
         self._set_option("metadata_failure_mode", normalised)
 
+    @property
+    def check_for_update(self):
+        """Get value for the once-a-day update check toggle."""
+        return self._get_option("check_for_update", default=True)
+
+    @check_for_update.setter
+    def check_for_update(self, value):
+        """Set value for the once-a-day update check toggle."""
+        if value is None:
+            return
+        self._set_option("check_for_update", bool(value))
+
     @property
     def output(self):
         """Get value for output format."""

{cloudsmith_cli-1.27.0 → cloudsmith_cli-1.28.0}/cloudsmith_cli/cli/utils.py

@@ -2,6 +2,7 @@
 
 import json
 import platform
+import sys
 from contextlib import contextmanager
 from datetime import date, datetime
 
@@ -75,7 +76,7 @@ def rich_print_table(headers, rows, title=None, show_lines=False):
     from rich.console import Console
     from rich.table import Table
 
-    console = Console()
+    console = Console(width=(None if sys.stdout.isatty() else 1000))
     table = Table(title=title, show_lines=show_lines)
 
     for header in headers:
@@ -231,8 +232,12 @@ def confirm_operation(prompt, prefix=None, assume_yes=False, err=False):
 @contextmanager
 def maybe_spinner(opts):
     """Only activate the spinner if not in debug mode or using json output."""
-    if should_use_stderr(opts) or get_output_format(opts) in ("json", "pretty_json"):
-        # No spinner
+    if (
+        getattr(opts, "debug", False)
+        or should_use_stderr(opts)
+        or get_output_format(opts) in ("json", "pretty_json")
+    ):
+        # No spinner (debug logs / machine output must not be clobbered)
         yield
     else:
         with spinner() as spin:

{cloudsmith_cli-1.27.0 → cloudsmith_cli-1.28.0}/cloudsmith_cli/cli/webserver.py

@@ -240,13 +240,18 @@ class AuthenticationWebRequestHandler(BaseHTTPRequestHandler):
         if self.server_instance:
             self.server_instance.sso_access_token = access_token
 
-        if not store_sso_tokens(
-            self.api_host, access_token, refresh_token, profile=self.profile
-        ):
-            click.echo(
-                "SSO tokens not stored (CLOUDSMITH_NO_KEYRING is set)",
-                err=True,
-            )
+        from keyring.errors import KeyringError
+
+        try:
+            if not store_sso_tokens(
+                self.api_host, access_token, refresh_token, profile=self.profile
+            ):
+                click.echo(
+                    "SSO tokens not stored (CLOUDSMITH_NO_KEYRING is set)",
+                    err=True,
+                )
+        except KeyringError as exc:
+            click.echo(f"SSO tokens not stored: {exc}", err=True)
 
         if self.refresh_api_on_success and self.server_instance:
             self.server_instance.refresh_api_config_after_auth()

{cloudsmith_cli-1.27.0 → cloudsmith_cli-1.28.0}/cloudsmith_cli/core/download.py

@@ -3,6 +3,7 @@
 import fnmatch
 import hashlib
 import os
+import sys
 
 import click
 import requests
@@ -309,7 +310,7 @@ def _display_multiple_packages(packages: list[dict]) -> None:
             _format_date(pkg.get("uploaded_at", "")),
         )
 
-    Console().print(table)
+    Console(width=(None if sys.stdout.isatty() else 1000)).print(table)
     click.echo()
 
 

cloudsmith_cli-1.28.0/cloudsmith_cli/core/installation.py

@@ -0,0 +1,156 @@
+# Copyright 2026 Cloudsmith Ltd
+"""Detect how the CLI was installed and how to upgrade it."""
+
+import os
+import platform
+import sys
+from importlib import metadata
+
+CHANNEL_STANDALONE = "standalone"
+CHANNEL_HOMEBREW = "homebrew"
+CHANNEL_DOCKER = "docker"
+CHANNEL_AQUA = "aqua"
+CHANNEL_PIP = "pip"
+CHANNEL_PIPX = "pipx"
+CHANNEL_UV_TOOL = "uv-tool"
+CHANNEL_UV_PIP = "uv-pip"
+CHANNEL_UNKNOWN = "unknown"
+
+_DISTRIBUTION_NAME = "cloudsmith-cli"
+
+#: Where a user downloads a fresh standalone build when self-update cannot run.
+RELEASES_LATEST_URL = "https://github.com/cloudsmith-io/cloudsmith-cli/releases/latest"
+
+#: Base for a version's GitHub release page. Each release is tagged ``v<version>``
+#: and its page renders that version's changelog, so it answers "what do I gain
+#: by upgrading?" for the exact version being offered.
+_RELEASE_TAG_URL_TEMPLATE = (
+    "https://github.com/cloudsmith-io/cloudsmith-cli/releases/tag/v{version}"
+)
+
+
+def changelog_url(version=None):
+    """Return the changelog URL for ``version`` (its release page), or the list.
+
+    With a version, points at that version's release page (tagged
+    ``v<version>``), which shows exactly what changed. Without one, points at
+    the releases listing.
+    """
+    if not version:
+        return RELEASES_LATEST_URL
+    return _RELEASE_TAG_URL_TEMPLATE.format(version=str(version).lstrip("v"))
+
+
+_UPGRADE_INSTRUCTIONS = {
+    CHANNEL_PIP: "pip install --upgrade cloudsmith-cli",
+    CHANNEL_PIPX: "pipx upgrade cloudsmith-cli",
+    CHANNEL_UV_TOOL: "uv tool upgrade cloudsmith-cli",
+    CHANNEL_UV_PIP: "uv pip install --upgrade cloudsmith-cli",
+    CHANNEL_HOMEBREW: "brew update && brew upgrade cloudsmith-cli",
+    CHANNEL_DOCKER: "docker pull cloudsmith/cloudsmith-cli:latest",
+    CHANNEL_AQUA: (
+        "update the cloudsmith-io/cloudsmith-cli version in your aqua "
+        "configuration, then run `aqua install`"
+    ),
+    CHANNEL_UNKNOWN: "pip install --upgrade cloudsmith-cli",
+}
+
+
+def _running_in_container():
+    if os.path.exists("/.dockerenv") or os.path.exists("/run/.containerenv"):
+        return True
+    return bool(
+        os.environ.get("container") or os.environ.get("KUBERNETES_SERVICE_HOST")
+    )
+
+
+def _distribution_location():
+    """Return the installed distribution's directory, or None."""
+    try:
+        distribution = metadata.distribution(_DISTRIBUTION_NAME)
+    except metadata.PackageNotFoundError:
+        return None
+    return str(distribution.locate_file(""))
+
+
+def _distribution_installer():
+    """Return the INSTALLER record of the installed distribution, or None."""
+    try:
+        distribution = metadata.distribution(_DISTRIBUTION_NAME)
+    except metadata.PackageNotFoundError:
+        return None
+    installer = distribution.read_text("INSTALLER")
+    return installer.strip() if installer else None
+
+
+def _detect_frozen_channel(executable_path):
+    normalized = os.path.realpath(executable_path).replace("\\", "/")
+    if "aquaproj-aqua" in normalized:
+        return CHANNEL_AQUA
+    if "/Cellar/" in normalized or "/linuxbrew/" in normalized:
+        return CHANNEL_HOMEBREW
+    if normalized.startswith("/opt/cloudsmith") and _running_in_container():
+        return CHANNEL_DOCKER
+    return CHANNEL_STANDALONE
+
+
+def _detect_package_channel():
+    location = _distribution_location()
+    if location is None:
+        return CHANNEL_UNKNOWN
+    normalized = location.replace("\\", "/")
+    if "/pipx/" in normalized:
+        return CHANNEL_PIPX
+    if "/uv/tools/" in normalized:
+        return CHANNEL_UV_TOOL
+    installer = _distribution_installer()
+    if installer == "uv":
+        return CHANNEL_UV_PIP
+    if installer == "pip":
+        return CHANNEL_PIP
+    return CHANNEL_UNKNOWN
+
+
+def detect_channel(frozen=None, executable_path=None):
+    """Detect the install channel of the running CLI."""
+    frozen = getattr(sys, "frozen", False) if frozen is None else frozen
+    if frozen:
+        return _detect_frozen_channel(executable_path or sys.executable)
+    return _detect_package_channel()
+
+
+def detect_target():
+    """Detect the standalone build target for this platform, or None."""
+    system = platform.system()
+    machine = platform.machine().lower()
+    arch = {"amd64": "x86_64", "x86_64": "x86_64"}.get(machine)
+    arm = machine in ("arm64", "aarch64")
+    if system == "Darwin":
+        return "macos-arm64" if arm else ("macos-x86_64" if arch else None)
+    if system == "Windows":
+        return "windows-x86_64" if arch else None
+    if system == "Linux":
+        if arm:
+            arch = "aarch64"
+        if arch is None:
+            return None
+        libc = "gnu" if platform.libc_ver()[0] == "glibc" else "musl"
+        return f"linux-{arch}-{libc}"
+    return None
+
+
+def upgrade_instruction(channel):
+    """Return the upgrade command for a channel, or None for self-update."""
+    if channel == CHANNEL_STANDALONE:
+        return None
+    return _UPGRADE_INSTRUCTIONS[channel]
+
+
+def self_update_supported():
+    """Whether the standalone binary can replace itself in place.
+
+    False on Windows: the running ``.exe`` is locked, so an in-place swap is
+    not possible (a deferred-swap helper is a future follow-up). Callers fall
+    back to manual-download instructions.
+    """
+    return os.name != "nt"