cloudsmith-cli 1.20.0__py3-none-any.whl

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

cloudsmith_cli/cli/commands/delete.py

@@ -0,0 +1,67 @@
+"""CLI/Commands - Delete packages."""
+
+import click
+
+from ...core.api.packages import delete_package
+from .. import decorators, utils, validators
+from ..exceptions import handle_api_exceptions
+from ..utils import maybe_spinner
+from .main import main
+
+
+@main.command(aliases=["rm"])
+@decorators.common_cli_config_options
+@decorators.common_cli_output_options
+@decorators.common_api_auth_options
+@decorators.initialise_api
+@click.argument(
+    "owner_repo_package",
+    metavar="OWNER/REPO/PACKAGE",
+    callback=validators.validate_owner_repo_package,
+)
+@click.option(
+    "-y",
+    "--yes",
+    default=False,
+    is_flag=True,
+    help="Assume yes as default answer to questions (this is dangerous!)",
+)
+@click.pass_context
+def delete(ctx, opts, owner_repo_package, yes):
+    """
+    Delete a package from a repository.
+
+    - OWNER/REPO/PACKAGE: Specify the OWNER namespace (i.e. user or org), the
+    REPO name where the package is stored, and the PACKAGE name (slug) of the
+    package itself. All separated by a slash.
+
+      Example: 'your-org/awesome-repo/better-pkg'.
+    """
+    owner, repo, slug = owner_repo_package
+
+    delete_args = {
+        "owner": click.style(owner, bold=True),
+        "repo": click.style(repo, bold=True),
+        "package": click.style(slug, bold=True),
+    }
+
+    use_stderr = utils.should_use_stderr(opts)
+
+    prompt = "delete the %(package)s from %(owner)s/%(repo)s" % delete_args
+    if not utils.confirm_operation(prompt, assume_yes=yes, err=use_stderr):
+        return
+
+    click.echo(
+        "Deleting %(package)s from %(owner)s/%(repo)s ... " % delete_args,
+        nl=False,
+        err=use_stderr,
+    )
+
+    context_msg = "Failed to delete the package!"
+    with handle_api_exceptions(ctx, opts=opts, context_msg=context_msg):
+        with maybe_spinner(opts):
+            delete_package(owner=owner, repo=repo, identifier=slug)
+
+    click.secho("OK", fg="green", err=use_stderr)
+
+    utils.maybe_print_status_json(opts, {"slug": slug, "status": "OK"})

cloudsmith_cli/cli/commands/dependencies.py

@@ -0,0 +1,108 @@
+"""CLI/Commands - Dependencies."""
+
+import functools
+
+import click
+
+from ...core.api.packages import get_package_dependencies
+from .. import decorators, utils, validators
+from ..exceptions import handle_api_exceptions
+from ..utils import maybe_spinner
+from .main import main
+
+
+def list_dependencies_options(f):
+    """Options for list dependencies subcommand."""
+
+    @decorators.common_cli_config_options
+    @decorators.common_cli_output_options
+    @decorators.common_api_auth_options
+    @decorators.initialise_api
+    @click.argument(
+        "owner_repo_package",
+        metavar="OWNER/REPO/PACKAGE",
+        callback=validators.validate_owner_repo_package,
+    )
+    @click.pass_context
+    @functools.wraps(f)
+    def wrapper(ctx, *args, **kwargs):
+        # pylint: disable=missing-docstring
+        return ctx.invoke(f, *args, **kwargs)
+
+    return wrapper
+
+
+def list_dependencies(ctx, opts, owner_repo_package):
+    """
+    List direct (non-transitive) dependencies for a package.
+
+    NOTE: These are not guaranteed to be complete, and only represent the *direct* /
+    *non-transitive* dependencies of a package. If packages consistently show
+    no dependencies then it is possible that dependency extraction isn't support
+    for the package format yet.
+
+    - OWNER/REPO/PACKAGE: Specify the OWNER namespace (i.e. user or org), the
+    REPO name where the package is stored, and the PACKAGE name (identifier/slug) of the
+    package itself. All separated by a slash.
+
+    Example: 'your-org/awesome-repo/better-pkg'.
+    """
+    owner, repo, identifier = owner_repo_package
+
+    # Use stderr for messages if the output is something else (e.g.  # JSON)
+    use_stderr = utils.should_use_stderr(opts)
+
+    click.echo(
+        "Getting direct (non-transitive) dependencies of %(package)s in "
+        "%(owner)s/%(repo)s ... "
+        % {
+            "owner": click.style(owner, bold=True),
+            "repo": click.style(repo, bold=True),
+            "package": click.style(identifier, bold=True),
+        },
+        nl=False,
+        err=use_stderr,
+    )
+
+    context_msg = "Failed to get dependencies of package!"
+    with handle_api_exceptions(ctx, opts=opts, context_msg=context_msg):
+        with maybe_spinner(opts):
+            deps, page_info = get_package_dependencies(
+                owner=owner, repo=repo, identifier=identifier
+            )
+
+    click.secho("OK", fg="green", err=use_stderr)
+
+    if utils.maybe_print_as_json(opts, deps, page_info):
+        return
+
+    headers = ["Type", "Name", "Operator", "Version"]
+    rows = []
+    for dep in deps:
+        rows.append(
+            [
+                click.style(dep["dep_type"], fg="cyan"),
+                click.style(dep["name"], fg="yellow"),
+                click.style(dep["operator"], fg="magenta"),
+                click.style(dep["version"] or "", fg="green"),
+            ]
+        )
+
+    if deps:
+        click.echo()
+        utils.pretty_print_table(headers, rows)
+
+    click.echo()
+    num_results = len(deps)
+    list_suffix = "direct dependenc%s" % ("ies" if num_results != 1 else "y")
+    utils.pretty_print_list_info(
+        num_results=num_results, page_info=page_info, suffix=list_suffix
+    )
+
+
+@main.command(name="dependencies", aliases=["deps"])
+@list_dependencies_options
+@functools.wraps(list_dependencies)
+@click.pass_context
+def dependencies_(*args, **kwargs):
+    return list_dependencies(*args, **kwargs)

cloudsmith_cli/cli/commands/docs.py

@@ -0,0 +1,16 @@
+"""CLI/Commands - Launch the help website."""
+
+import click
+
+from ...core.utils import get_help_website
+from .. import decorators
+from .main import main
+
+
+@main.command()
+@decorators.common_cli_config_options
+@click.pass_context
+def docs(ctx, opts):
+    """Launch the help website in your browser."""
+    # pylint: disable=unused-argument
+    click.launch(get_help_website())