cloudsmith-cli 1.18.0__tar.gz → 1.20.0__tar.gz

{cloudsmith_cli-1.18.0/cloudsmith_cli.egg-info → cloudsmith_cli-1.20.0}/PKG-INFO

@@ -1,18 +1,15 @@
 Metadata-Version: 2.4
 Name: cloudsmith-cli
-Version: 1.18.0
+Version: 1.20.0
 Summary: Cloudsmith Command-Line Interface (CLI)
-Home-page: https://github.com/cloudsmith-io/cloudsmith-cli
-Author: Cloudsmith Ltd
-Author-email: support@cloudsmith.io
-License: Apache License 2.0
+Author-email: Cloudsmith Ltd <support@cloudsmith.io>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/cloudsmith-io/cloudsmith-cli
 Keywords: cloudsmith,cli,devops
-Platform: any
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: System Administrators
-Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Operating System :: POSIX :: Linux
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3.10
@@ -31,10 +28,10 @@ Requires-Dist: click-configfile>=0.2.3
 Requires-Dist: click-didyoumean>=0.0.3
 Requires-Dist: click-spinner>=0.1.7
 Requires-Dist: json5>=0.9.0
-Requires-Dist: cloudsmith-api<3.0,>=2.0.25
+Requires-Dist: cloudsmith-api<3.0,>=2.0.29
 Requires-Dist: keyring>=25.4.1
-Requires-Dist: mcp==1.9.1
-Requires-Dist: PyJWT>=2.0.0
+Requires-Dist: mcp==1.27.2
+Requires-Dist: PyJWT[crypto]>=2.0.0
 Requires-Dist: python-toon==0.1.2
 Requires-Dist: requests>=2.18.4
 Requires-Dist: requests_toolbelt>=1.0.0
@@ -45,20 +42,7 @@ Provides-Extra: aws
 Requires-Dist: boto3[crt]>=1.26.0; extra == "aws"
 Provides-Extra: all
 Requires-Dist: boto3[crt]>=1.26.0; extra == "all"
-Dynamic: author
-Dynamic: author-email
-Dynamic: classifier
-Dynamic: description
-Dynamic: description-content-type
-Dynamic: home-page
-Dynamic: keywords
-Dynamic: license
 Dynamic: license-file
-Dynamic: platform
-Dynamic: provides-extra
-Dynamic: requires-dist
-Dynamic: requires-python
-Dynamic: summary
 
 # Cloudsmith Command Line Interface (CLI)
 
@@ -203,6 +187,30 @@ Or you can get the latest pre-release version from Cloudsmith:
 pip install --upgrade cloudsmith-cli --extra-index-url=https://dl.cloudsmith.io/public/cloudsmith/cli/python/index/
 ```
 
+### Standalone Binaries
+
+Each release also ships self-contained binaries that bundle Python and all dependencies — no Python installation required. Download the archive for your platform from the [GitHub releases page](https://github.com/cloudsmith-io/cloudsmith-cli/releases) (or the [Cloudsmith CLI repository](https://cloudsmith.io/~cloudsmith/repos/cli/packages/)), verify it against the accompanying `.sha256` file, extract it, and add the extracted `cloudsmith` directory to your `PATH`:
+
+```bash
+tar -xzf cloudsmith-<version>-<target>.tar.gz
+./cloudsmith/cloudsmith --version
+```
+
+Available targets: `linux-x86_64-gnu`, `linux-x86_64-musl`, `linux-aarch64-gnu`, `linux-aarch64-musl`, `macos-arm64`, `macos-x86_64`, and `windows-x86_64` (as a `.zip`).
+
+Standalone binaries include all optional features, including AWS OIDC support.
+
+#### Verifying Linux binaries
+
+The four Linux archives (`linux-x86_64-gnu`, `linux-x86_64-musl`, `linux-aarch64-gnu`, `linux-aarch64-musl`) are GPG-signed with a detached binary signature published alongside each archive as `<archive>.sig`. To verify, import the Cloudsmith CLI release public key (`cloudsmith-cli-release-key.asc`, attached to each GitHub release) and check the signature:
+
+```
+gpg --import cloudsmith-cli-release-key.asc
+gpg --verify cloudsmith-<version>-linux-x86_64-gnu.tar.gz.sig cloudsmith-<version>-linux-x86_64-gnu.tar.gz
+```
+
+A successful verification reports a good signature from the Cloudsmith CLI release key. (The macOS and Windows binaries are not GPG-signed; native signing for those platforms is tracked separately.)
+
 ### Optional Dependencies
 
 The CLI supports optional extras for additional functionality:
@@ -227,6 +235,71 @@ pip install cloudsmith-cli[all]
 
 **Note:** If you don't install the AWS extra, the AWS OIDC detector will gracefully skip itself with no errors.
 
+#### Bitbucket Pipelines OIDC Support
+
+In Bitbucket Pipelines, OIDC credential discovery works out of the box with no extra dependencies. Set `oidc: true` on the pipeline step and the CLI reads the token from the `BITBUCKET_STEP_OIDC_TOKEN` variable that Bitbucket populates. The Cloudsmith OIDC provider must expect the workspace audience that Bitbucket mints (`ari:cloud:bitbucket::workspace/<workspace-uuid>`):
+
+```yaml
+pipelines:
+  default:
+    - step:
+        oidc: true
+        script:
+          - cloudsmith push ...
+```
+
+See the [Bitbucket Pipelines OIDC documentation](https://support.atlassian.com/bitbucket-cloud/docs/integrate-pipelines-with-resource-servers-using-oidc/).
+
+#### CircleCI OIDC Support
+
+In CircleCI, OIDC credential discovery works out of the box with no extra dependencies — the CLI reads the token from the `CIRCLE_OIDC_TOKEN_V2` (preferred) or `CIRCLE_OIDC_TOKEN` environment variable that CircleCI injects into every job. The Cloudsmith OIDC provider must expect the audience CircleCI mints, which is your CircleCI organization UUID. See the [Cloudsmith CircleCI integration guide](https://docs.cloudsmith.com/integrations/integrating-with-circleci).
+
+#### Azure DevOps OIDC Support
+
+In Azure DevOps Pipelines, OIDC credential discovery works out of the box with no extra dependencies — the CLI fetches an OIDC token from the `SYSTEM_OIDCREQUESTURI` endpoint using the pipeline's `SYSTEM_ACCESSTOKEN`. Make sure `SYSTEM_ACCESSTOKEN` is mapped into the step's environment. The Cloudsmith OIDC provider must expect the audience `api://AzureADTokenExchange`, which Azure DevOps always mints (any requested audience is ignored). See the [Cloudsmith Azure DevOps integration guide](https://docs.cloudsmith.com/integrations/integrating-with-azure-devops).
+
+#### GitHub Actions OIDC Support
+
+In GitHub Actions, OIDC credential discovery works out of the box with no extra dependencies — the CLI fetches an OIDC token from the Actions runtime when the workflow requests `id-token: write` permission. See the [Cloudsmith GitHub Actions OIDC guide](https://docs.cloudsmith.com/authentication/setup-cloudsmith-to-authenticate-with-oidc-in-github-actions).
+
+#### GitLab CI OIDC Support
+
+In GitLab CI/CD, OIDC credential discovery works out of the box with no extra dependencies. Configure an [`id_tokens`](https://docs.gitlab.com/ci/cloud_services/) entry in your `.gitlab-ci.yml` with an `aud` of `https://api.cloudsmith.io/openid/<your-org>` and expose it as `CLOUDSMITH_OIDC_TOKEN`, and the CLI will pick it up automatically:
+
+```yaml
+job:
+  id_tokens:
+    CLOUDSMITH_OIDC_TOKEN:
+      aud: https://api.cloudsmith.io/openid/<your-org>
+  script:
+    - cloudsmith push ...
+```
+
+See the [Cloudsmith GitLab CI/CD integration guide](https://docs.cloudsmith.com/integrations/integrating-with-gitlab-cicd).
+
+#### Generic OIDC Support (Jenkins, custom CI/CD)
+
+As a fallback for environments without a dedicated detector (for example Jenkins with the [credentials binding plugin](https://plugins.jenkins.io/credentials-binding/), or any custom CI/CD system), set the `CLOUDSMITH_OIDC_TOKEN` environment variable to an OIDC JWT and the CLI will exchange it for a Cloudsmith access token. This detector runs last, so a dedicated environment is always preferred when present. See the [Cloudsmith Jenkins OIDC guide](https://docs.cloudsmith.com/authentication/setup-jenkins-to-authenticate-to-cloudsmith-using-oidc).
+
+#### Controlling OIDC Detector Selection
+
+By default the CLI tries each detector in a fixed priority order and uses the first that matches. Two controls let you override this when a detector matches an environment you don't want it to (for example, the AWS detector matching ambient instance credentials):
+
+- **Disable a detector** — set `CLOUDSMITH_OIDC_<DETECTOR>_DISABLED=true` to skip it entirely. Only the literal value `true` (case-insensitive) disables; anything else leaves the detector enabled. For example, `CLOUDSMITH_OIDC_AWS_DISABLED=true` skips the AWS detector so an explicitly-set `CLOUDSMITH_OIDC_TOKEN` is picked up by the generic detector instead.
+- **Reorder evaluation** — use `--oidc-detector-order` (or the `CLOUDSMITH_OIDC_DETECTOR_ORDER` environment variable) with a comma-separated list of detector ids to control both which detectors are considered and the order they are tried in (first match wins). Ids not listed are skipped; unrecognised ids are ignored with a warning. For example, `--oidc-detector-order=generic,aws` tries the generic detector first and considers only those two.
+
+When both are set, the order list defines the candidate set and sequence, then the `*_DISABLED` flags are applied on top — so a disabled detector is always skipped even if it appears in the order list. Detector ids are: `aws`, `azure_devops`, `bitbucket`, `circleci`, `generic`, `github`, `gitlab`.
+
+Both controls can also be set in `config.ini`, under `[default]` or a profile section:
+
+```ini
+[default]
+oidc_detector_order = github, aws
+oidc_disabled_detectors = aws, gitlab
+```
+
+The `--oidc-detector-order` flag (or the `CLOUDSMITH_OIDC_DETECTOR_ORDER` environment variable) overrides the `oidc_detector_order` config value. The `oidc_disabled_detectors` config key is additive with the per-detector `CLOUDSMITH_OIDC_<DETECTOR>_DISABLED` environment variables — a detector disabled by either is skipped.
+
 ## Configuration
 
 There are two configuration files used by the CLI:

{cloudsmith_cli-1.18.0 → cloudsmith_cli-1.20.0}/README.md

@@ -141,6 +141,30 @@ Or you can get the latest pre-release version from Cloudsmith:
 pip install --upgrade cloudsmith-cli --extra-index-url=https://dl.cloudsmith.io/public/cloudsmith/cli/python/index/
 ```
 
+### Standalone Binaries
+
+Each release also ships self-contained binaries that bundle Python and all dependencies — no Python installation required. Download the archive for your platform from the [GitHub releases page](https://github.com/cloudsmith-io/cloudsmith-cli/releases) (or the [Cloudsmith CLI repository](https://cloudsmith.io/~cloudsmith/repos/cli/packages/)), verify it against the accompanying `.sha256` file, extract it, and add the extracted `cloudsmith` directory to your `PATH`:
+
+```bash
+tar -xzf cloudsmith-<version>-<target>.tar.gz
+./cloudsmith/cloudsmith --version
+```
+
+Available targets: `linux-x86_64-gnu`, `linux-x86_64-musl`, `linux-aarch64-gnu`, `linux-aarch64-musl`, `macos-arm64`, `macos-x86_64`, and `windows-x86_64` (as a `.zip`).
+
+Standalone binaries include all optional features, including AWS OIDC support.
+
+#### Verifying Linux binaries
+
+The four Linux archives (`linux-x86_64-gnu`, `linux-x86_64-musl`, `linux-aarch64-gnu`, `linux-aarch64-musl`) are GPG-signed with a detached binary signature published alongside each archive as `<archive>.sig`. To verify, import the Cloudsmith CLI release public key (`cloudsmith-cli-release-key.asc`, attached to each GitHub release) and check the signature:
+
+```
+gpg --import cloudsmith-cli-release-key.asc
+gpg --verify cloudsmith-<version>-linux-x86_64-gnu.tar.gz.sig cloudsmith-<version>-linux-x86_64-gnu.tar.gz
+```
+
+A successful verification reports a good signature from the Cloudsmith CLI release key. (The macOS and Windows binaries are not GPG-signed; native signing for those platforms is tracked separately.)
+
 ### Optional Dependencies
 
 The CLI supports optional extras for additional functionality:
@@ -165,6 +189,71 @@ pip install cloudsmith-cli[all]
 
 **Note:** If you don't install the AWS extra, the AWS OIDC detector will gracefully skip itself with no errors.
 
+#### Bitbucket Pipelines OIDC Support
+
+In Bitbucket Pipelines, OIDC credential discovery works out of the box with no extra dependencies. Set `oidc: true` on the pipeline step and the CLI reads the token from the `BITBUCKET_STEP_OIDC_TOKEN` variable that Bitbucket populates. The Cloudsmith OIDC provider must expect the workspace audience that Bitbucket mints (`ari:cloud:bitbucket::workspace/<workspace-uuid>`):
+
+```yaml
+pipelines:
+  default:
+    - step:
+        oidc: true
+        script:
+          - cloudsmith push ...
+```
+
+See the [Bitbucket Pipelines OIDC documentation](https://support.atlassian.com/bitbucket-cloud/docs/integrate-pipelines-with-resource-servers-using-oidc/).
+
+#### CircleCI OIDC Support
+
+In CircleCI, OIDC credential discovery works out of the box with no extra dependencies — the CLI reads the token from the `CIRCLE_OIDC_TOKEN_V2` (preferred) or `CIRCLE_OIDC_TOKEN` environment variable that CircleCI injects into every job. The Cloudsmith OIDC provider must expect the audience CircleCI mints, which is your CircleCI organization UUID. See the [Cloudsmith CircleCI integration guide](https://docs.cloudsmith.com/integrations/integrating-with-circleci).
+
+#### Azure DevOps OIDC Support
+
+In Azure DevOps Pipelines, OIDC credential discovery works out of the box with no extra dependencies — the CLI fetches an OIDC token from the `SYSTEM_OIDCREQUESTURI` endpoint using the pipeline's `SYSTEM_ACCESSTOKEN`. Make sure `SYSTEM_ACCESSTOKEN` is mapped into the step's environment. The Cloudsmith OIDC provider must expect the audience `api://AzureADTokenExchange`, which Azure DevOps always mints (any requested audience is ignored). See the [Cloudsmith Azure DevOps integration guide](https://docs.cloudsmith.com/integrations/integrating-with-azure-devops).
+
+#### GitHub Actions OIDC Support
+
+In GitHub Actions, OIDC credential discovery works out of the box with no extra dependencies — the CLI fetches an OIDC token from the Actions runtime when the workflow requests `id-token: write` permission. See the [Cloudsmith GitHub Actions OIDC guide](https://docs.cloudsmith.com/authentication/setup-cloudsmith-to-authenticate-with-oidc-in-github-actions).
+
+#### GitLab CI OIDC Support
+
+In GitLab CI/CD, OIDC credential discovery works out of the box with no extra dependencies. Configure an [`id_tokens`](https://docs.gitlab.com/ci/cloud_services/) entry in your `.gitlab-ci.yml` with an `aud` of `https://api.cloudsmith.io/openid/<your-org>` and expose it as `CLOUDSMITH_OIDC_TOKEN`, and the CLI will pick it up automatically:
+
+```yaml
+job:
+  id_tokens:
+    CLOUDSMITH_OIDC_TOKEN:
+      aud: https://api.cloudsmith.io/openid/<your-org>
+  script:
+    - cloudsmith push ...
+```
+
+See the [Cloudsmith GitLab CI/CD integration guide](https://docs.cloudsmith.com/integrations/integrating-with-gitlab-cicd).
+
+#### Generic OIDC Support (Jenkins, custom CI/CD)
+
+As a fallback for environments without a dedicated detector (for example Jenkins with the [credentials binding plugin](https://plugins.jenkins.io/credentials-binding/), or any custom CI/CD system), set the `CLOUDSMITH_OIDC_TOKEN` environment variable to an OIDC JWT and the CLI will exchange it for a Cloudsmith access token. This detector runs last, so a dedicated environment is always preferred when present. See the [Cloudsmith Jenkins OIDC guide](https://docs.cloudsmith.com/authentication/setup-jenkins-to-authenticate-to-cloudsmith-using-oidc).
+
+#### Controlling OIDC Detector Selection
+
+By default the CLI tries each detector in a fixed priority order and uses the first that matches. Two controls let you override this when a detector matches an environment you don't want it to (for example, the AWS detector matching ambient instance credentials):
+
+- **Disable a detector** — set `CLOUDSMITH_OIDC_<DETECTOR>_DISABLED=true` to skip it entirely. Only the literal value `true` (case-insensitive) disables; anything else leaves the detector enabled. For example, `CLOUDSMITH_OIDC_AWS_DISABLED=true` skips the AWS detector so an explicitly-set `CLOUDSMITH_OIDC_TOKEN` is picked up by the generic detector instead.
+- **Reorder evaluation** — use `--oidc-detector-order` (or the `CLOUDSMITH_OIDC_DETECTOR_ORDER` environment variable) with a comma-separated list of detector ids to control both which detectors are considered and the order they are tried in (first match wins). Ids not listed are skipped; unrecognised ids are ignored with a warning. For example, `--oidc-detector-order=generic,aws` tries the generic detector first and considers only those two.
+
+When both are set, the order list defines the candidate set and sequence, then the `*_DISABLED` flags are applied on top — so a disabled detector is always skipped even if it appears in the order list. Detector ids are: `aws`, `azure_devops`, `bitbucket`, `circleci`, `generic`, `github`, `gitlab`.
+
+Both controls can also be set in `config.ini`, under `[default]` or a profile section:
+
+```ini
+[default]
+oidc_detector_order = github, aws
+oidc_disabled_detectors = aws, gitlab
+```
+
+The `--oidc-detector-order` flag (or the `CLOUDSMITH_OIDC_DETECTOR_ORDER` environment variable) overrides the `oidc_detector_order` config value. The `oidc_disabled_detectors` config key is additive with the per-detector `CLOUDSMITH_OIDC_<DETECTOR>_DISABLED` environment variables — a detector disabled by either is skipped.
+
 ## Configuration
 
 There are two configuration files used by the CLI:

{cloudsmith_cli-1.18.0 → cloudsmith_cli-1.20.0}/cloudsmith_cli/cli/commands/__init__.py

@@ -4,6 +4,7 @@ from . import (
     auth,
     check,
     copy,
+    credential_helper,
     delete,
     dependencies,
     docs,

cloudsmith_cli-1.20.0/cloudsmith_cli/cli/commands/credential_helper/__init__.py

@@ -0,0 +1,39 @@
+# Copyright 2026 Cloudsmith Ltd
+"""
+Credential helper commands for Cloudsmith.
+
+This module provides credential helper commands for package managers
+that follow their respective credential helper protocols.
+"""
+
+import click
+
+from ..main import main
+from .docker import docker as docker_cmd
+from .manage import install_cmd, list_cmd, uninstall_cmd
+
+
+@click.group()
+def credential_helper():
+    """
+    Credential helpers for package managers.
+
+    These commands provide credentials for package managers like Docker.
+    Use ``install`` to set up the on-PATH launcher and configure the package
+    manager automatically, or run the runtime command directly for debugging.
+
+    Examples:
+        # Install Docker credential helper
+        $ cloudsmith credential-helper install docker
+
+        # Test Docker credential helper directly
+        $ echo "docker.cloudsmith.io" | cloudsmith credential-helper docker
+    """
+
+
+credential_helper.add_command(docker_cmd, name="docker")
+credential_helper.add_command(install_cmd, name="install")
+credential_helper.add_command(uninstall_cmd, name="uninstall")
+credential_helper.add_command(list_cmd, name="list")
+
+main.add_command(credential_helper, name="credential-helper")

cloudsmith_cli-1.20.0/cloudsmith_cli/cli/commands/credential_helper/docker.py

@@ -0,0 +1,66 @@
+# Copyright 2026 Cloudsmith Ltd
+"""
+Docker credential helper command.
+
+Implements the Docker credential helper protocol for Cloudsmith registries.
+
+See: https://github.com/docker/docker-credential-helpers
+"""
+
+import sys
+
+import click
+
+from ....credential_helpers.docker import execute
+from ...decorators import common_api_auth_options, resolve_credentials
+
+
+@click.command()
+@click.argument("operation", required=False, default="get")
+@common_api_auth_options
+@resolve_credentials
+def docker(opts, operation):
+    """
+    Docker credential helper for Cloudsmith registries.
+
+    Reads a Docker registry server URL from stdin and returns credentials in
+    JSON format.  Implements the full Docker credential helper protocol
+    (get/store/erase/list).
+
+    Provides credentials for all Cloudsmith Docker registries: ``*.cloudsmith.io``,
+    ``*.cloudsmith.com``, and any custom domains configured for the organisation
+    (requires CLOUDSMITH_ORG and a valid API key/token).
+
+    Input (stdin):
+        Server URL as plain text (e.g. "docker.cloudsmith.io")
+
+    Output (stdout):
+        JSON: {"Username": "token", "Secret": "<cloudsmith-token>"}
+
+    Exit codes:
+        0: Success
+        1: Error (no credentials available, not a Cloudsmith registry, etc.)
+
+    Examples:
+        # Manual testing
+        $ echo "docker.cloudsmith.io" | cloudsmith credential-helper docker
+
+        # Called by Docker via launcher
+        $ echo "docker.cloudsmith.io" | docker-credential-cloudsmith get
+
+    Environment variables:
+        CLOUDSMITH_API_KEY: API key for authentication (optional)
+        CLOUDSMITH_ORG:     Organisation slug (required for custom domain support)
+    """
+    exit_code, stdout, stderr = execute(
+        operation,
+        sys.stdin,
+        credential=opts.credential,
+        api_host=opts.api_host,
+    )
+
+    if stdout is not None:
+        click.echo(stdout)
+    if stderr is not None:
+        click.echo(stderr, err=True)
+    sys.exit(exit_code)

cloudsmith_cli-1.20.0/cloudsmith_cli/cli/commands/credential_helper/manage.py

@@ -0,0 +1,299 @@
+# Copyright 2026 Cloudsmith Ltd
+"""Install/uninstall/list commands for credential helpers.
+
+Provides ``credential-helper install``, ``credential-helper uninstall``, and
+``credential-helper list`` to manage the on-PATH launcher binary and the
+``config.json`` entries for each supported credential helper.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+
+import click
+
+from ....credential_helpers.docker.installer import DockerInstaller
+from ... import utils
+from ...decorators import (
+    common_api_auth_options,
+    common_cli_config_options,
+    common_cli_output_options,
+    resolve_credentials,
+)
+
+# ---------------------------------------------------------------------------
+# Helper registry — extend here when new helpers are added
+# ---------------------------------------------------------------------------
+
+_INSTALLERS: dict[str, type] = {
+    "docker": DockerInstaller,
+}
+
+
+def _get_installer(name: str):
+    """Return an instantiated installer for *name*, or exit with a clear error.
+
+    Parameters
+    ----------
+    name:
+        The helper name as supplied by the user (e.g. ``"docker"``).
+
+    Returns
+    -------
+    DockerInstaller
+        An instance of the appropriate installer class.
+
+    Raises
+    ------
+    SystemExit
+        If *name* is not in :data:`_INSTALLERS`.
+    """
+    cls = _INSTALLERS.get(name)
+    if cls is None:
+        available = ", ".join(sorted(_INSTALLERS))
+        click.echo(
+            f"Error: unknown helper {name!r}. Available helpers: {available}",
+            err=True,
+        )
+        sys.exit(1)
+    return cls()
+
+
+# ---------------------------------------------------------------------------
+# install
+# ---------------------------------------------------------------------------
+
+
+@click.command("install")
+@click.argument("helper")
+@click.option(
+    "--bin-dir", default=None, help="Directory to install the launcher binary."
+)
+@click.option(
+    "--domain",
+    "domains",
+    multiple=True,
+    help="Additional registry hostname to configure (repeatable).",
+)
+@click.option(
+    "--dry-run",
+    is_flag=True,
+    default=False,
+    help="Show what would be done without making any changes.",
+)
+@click.option(
+    "--no-discover",
+    is_flag=True,
+    default=False,
+    help="Disable automatic discovery of custom Docker domains.",
+)
+@click.option(
+    "--refresh",
+    is_flag=True,
+    default=False,
+    help="Bypass the custom-domain cache and fetch fresh data from the API.",
+)
+@click.option(
+    "--org",
+    default=None,
+    help="Cloudsmith organisation slug for custom-domain discovery.",
+)
+@common_cli_config_options
+@common_cli_output_options
+@common_api_auth_options
+@resolve_credentials
+@click.pass_context
+def install_cmd(
+    ctx,
+    opts,
+    helper: str,
+    bin_dir: str | None,
+    domains: tuple[str, ...],
+    dry_run: bool,
+    no_discover: bool,
+    refresh: bool,
+    org: str | None,
+) -> None:
+    """Install a credential helper launcher and configure the package manager.
+
+    HELPER is the name of the credential helper to install (e.g. ``docker``).
+
+    Examples:
+
+    \b
+        # Install Docker credential helper
+        $ cloudsmith credential-helper install docker
+
+    \b
+        # Install with a custom domain
+        $ cloudsmith credential-helper install docker --domain my.registry.example.com
+
+    \b
+        # Preview without making changes
+        $ cloudsmith credential-helper install docker --dry-run
+
+    \b
+        # Disable automatic custom-domain discovery
+        $ cloudsmith credential-helper install docker --no-discover
+    """
+    installer = _get_installer(helper)
+    org = org or os.environ.get("CLOUDSMITH_ORG", "").strip() or None
+    api_key = opts.credential.api_key if opts.credential else None
+    auth_type = (
+        getattr(opts.credential, "auth_type", "api_key")
+        if opts.credential
+        else "api_key"
+    )
+    try:
+        actions = installer.install(
+            bin_dir=bin_dir,
+            domains=domains,
+            dry_run=dry_run,
+            discover=not no_discover,
+            refresh=refresh,
+            org=org,
+            api_key=api_key,
+            auth_type=auth_type,
+            api_host=opts.api_host,
+        )
+    except OSError as exc:
+        raise click.ClickException(
+            f"Failed to install {helper!r} credential helper: {exc}"
+        )
+
+    use_stderr = utils.should_use_stderr(opts)
+    warnings = [a for a in actions if a.startswith("WARNING")]
+    normal = [a for a in actions if not a.startswith("WARNING")]
+    data = {
+        "helper": helper,
+        "dry_run": dry_run,
+        "actions": normal,
+        "warnings": warnings,
+    }
+    if utils.maybe_print_as_json(opts, data):
+        return
+
+    if dry_run:
+        click.echo("Dry run — no changes will be made:", err=use_stderr)
+    for action in normal:
+        click.echo(f"  {action}" if dry_run else action, err=use_stderr)
+    for warning in warnings:
+        click.secho(f"  {warning}" if dry_run else warning, err=True, fg="yellow")
+
+
+# ---------------------------------------------------------------------------
+# uninstall
+# ---------------------------------------------------------------------------
+
+
+@click.command("uninstall")
+@click.argument("helper")
+@click.option(
+    "--bin-dir", default=None, help="Directory where the launcher binary was installed."
+)
+@click.option(
+    "--dry-run",
+    is_flag=True,
+    default=False,
+    help="Show what would be done without making any changes.",
+)
+@common_cli_config_options
+@common_cli_output_options
+@click.pass_context
+def uninstall_cmd(ctx, opts, helper: str, bin_dir: str | None, dry_run: bool) -> None:
+    """Uninstall a credential helper launcher and remove its config entries.
+
+    HELPER is the name of the credential helper to uninstall (e.g. ``docker``).
+
+    Examples:
+
+    \b
+        # Uninstall Docker credential helper
+        $ cloudsmith credential-helper uninstall docker
+
+    \b
+        # Preview without making changes
+        $ cloudsmith credential-helper uninstall docker --dry-run
+    """
+    installer = _get_installer(helper)
+    try:
+        actions = installer.uninstall(bin_dir=bin_dir, dry_run=dry_run)
+    except OSError as exc:
+        raise click.ClickException(
+            f"Failed to uninstall {helper!r} credential helper: {exc}"
+        )
+
+    use_stderr = utils.should_use_stderr(opts)
+    warnings = [a for a in actions if a.startswith("WARNING")]
+    normal = [a for a in actions if not a.startswith("WARNING")]
+    data = {
+        "helper": helper,
+        "dry_run": dry_run,
+        "actions": normal,
+        "warnings": warnings,
+    }
+    if utils.maybe_print_as_json(opts, data):
+        return
+
+    if dry_run:
+        click.echo("Dry run — no changes will be made:", err=use_stderr)
+    for action in normal:
+        click.echo(f"  {action}" if dry_run else action, err=use_stderr)
+    for warning in warnings:
+        click.secho(f"  {warning}" if dry_run else warning, err=True, fg="yellow")
+
+
+# ---------------------------------------------------------------------------
+# list
+# ---------------------------------------------------------------------------
+
+
+@click.command("list")
+@common_cli_config_options
+@common_cli_output_options
+@click.pass_context
+def list_cmd(ctx, opts) -> None:
+    """List available credential helpers and their installation status.
+
+    Shows which helpers are available, whether their launcher binary is
+    present on PATH, and which registry hosts they are configured for.
+
+    Example:
+
+    \b
+        $ cloudsmith credential-helper list
+    """
+    use_stderr = utils.should_use_stderr(opts)
+
+    data = []
+    for name, cls in sorted(_INSTALLERS.items()):
+        installer = cls()
+        st = installer.status()
+        data.append(
+            {
+                "helper": name,
+                "summary": installer.summary,
+                "launcher": st.get("launcher"),
+                "hosts": st.get("hosts", []),
+            }
+        )
+
+    if utils.maybe_print_as_json(opts, data):
+        return
+
+    for entry in data:
+        name = entry["helper"]
+        launcher = entry["launcher"]
+        hosts = entry["hosts"]
+        summary = entry["summary"]
+
+        click.echo(f"{name}  ({summary})", err=use_stderr)
+        if launcher:
+            click.echo(f"  launcher : {launcher}", err=use_stderr)
+        else:
+            click.echo("  launcher : not installed", err=use_stderr)
+        if hosts:
+            click.echo(f"  hosts    : {', '.join(hosts)}", err=use_stderr)
+        else:
+            click.echo("  hosts    : none configured", err=use_stderr)