feat: add Docker credential helper for Cloudsmith registries

cloudsmith_cli/cli/commands/__init__.py

@@ -4,6 +4,7 @@
     auth,
     check,
     copy,
+    credential_helper,
     delete,
     dependencies,
     docs,

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/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)