cloudsmith-cli 1.20.0__py3-none-any.whl

cloudsmith_cli/__init__.py

@@ -0,0 +1,10 @@
+"""Cloudsmith CLI."""
+
+import warnings
+
+import click
+import urllib3
+
+click.disable_unicode_literals_warning = True
+urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)
+warnings.filterwarnings("ignore", category=ResourceWarning)

cloudsmith_cli/__main__.py

@@ -0,0 +1,8 @@
+"""Cloudsmith CLI - Main script."""
+
+from .cli.commands.main import main
+
+if __name__ == "__main__":
+    # Disable false positive for parameters handled by click.
+    # pylint: disable=no-value-for-parameter
+    main()

cloudsmith_cli/cli/__init__.py

@@ -0,0 +1 @@
+"""CLI-specific functionality."""

cloudsmith_cli/cli/command.py

@@ -0,0 +1,160 @@
+"""CLI - Group/Command classes."""
+
+from collections import OrderedDict
+
+import click.exceptions
+from click_didyoumean import DYMGroup
+
+
+def _is_json_output_requested(exception):
+    """Determine if JSON output was requested, checking context and argv."""
+    # Check context if available
+    ctx = getattr(exception, "ctx", None)
+    if ctx and ctx.params:
+        fmt = ctx.params.get("output")
+        if fmt in ("json", "pretty_json"):
+            return True
+
+    # Fallback: check sys.argv for output format flags
+    import sys
+
+    argv = sys.argv
+
+    if "--output-format=json" in argv or "--output-format=pretty_json" in argv:
+        return True
+
+    for idx, arg in enumerate(argv):
+        if arg in ("-F", "--output-format") and idx + 1 < len(argv):
+            if argv[idx + 1] in ("json", "pretty_json"):
+                return True
+
+    return False
+
+
+def _format_click_exception_as_json(exception):
+    """Format a ClickException as a JSON error dict."""
+    return {
+        "detail": exception.format_message(),
+        "meta": {
+            "code": exception.exit_code,
+            "description": "Usage Error",
+        },
+        "help": {
+            "context": "Invalid usage",
+            "hint": "Check your command arguments/flags.",
+        },
+    }
+
+
+class AliasGroup(DYMGroup):
+    """A command group with DYM and alias support."""
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.aliases = OrderedDict()
+        self.inverse = {}
+
+    def resolve_command(self, ctx, args):
+        try:
+            return super().resolve_command(ctx, args)
+        except click.exceptions.UsageError:
+            # Before DYM kicks in, check to see if the command prefix matches
+            # exactly one command, then use that instead.
+            if args:
+                cmd_name = args[0]
+                cmds = self.list_commands(ctx)
+                matched = [cmd for cmd in cmds if cmd.startswith(cmd_name)]
+                if len(matched) == 1 and len(cmd_name) > 1:
+                    args[0] = matched[0]
+                    return super().resolve_command(ctx, args)
+
+            raise
+
+    def list_commands(self, ctx):
+        commands = super().list_commands(ctx)
+
+        if getattr(ctx, "showing_help", False):
+            for k, v in enumerate(commands):
+                try:
+                    commands[k] = f"{v}|{'|'.join(self.aliases[v])}"
+                except KeyError:
+                    pass
+
+            return commands
+
+        for k in self.inverse:
+            commands.append(k)
+
+        return commands
+
+    def get_command(self, ctx, cmd_name):
+        if getattr(ctx, "showing_help", False):
+            if "|" in cmd_name:
+                cmd_name = cmd_name.split("|")[0]
+
+        try:
+            cmd_name = self.inverse[cmd_name]
+        except KeyError:
+            pass
+
+        return super().get_command(ctx, cmd_name)
+
+    def command(self, *args, **kwargs):
+        def decorator(f):
+            # pylint: disable=missing-docstring
+            aliases = kwargs.pop("aliases", [])
+            cmd = super(AliasGroup, self).command(*args, **kwargs)(f)
+
+            if aliases:
+                self.aliases[cmd.name] = aliases
+                for alias in aliases:
+                    self.inverse[alias] = cmd.name
+
+            return cmd
+
+        return decorator
+
+    def group(self, *args, **kwargs):
+        def decorator(f):
+            # pylint: disable=missing-docstring
+            aliases = kwargs.pop("aliases", [])
+            cmd = super(AliasGroup, self).group(*args, **kwargs)(f)
+
+            if aliases:
+                self.aliases[cmd.name] = aliases
+                for alias in aliases:
+                    self.inverse[alias] = cmd.name
+
+            return cmd
+
+        return decorator
+
+    def format_commands(self, ctx, formatter):
+        ctx.showing_help = True
+        return super().format_commands(ctx, formatter)
+
+    def main(self, *args, **kwargs):
+        """Override main to intercept exceptions and format as JSON if requested."""
+        import sys
+
+        original_standalone_mode = kwargs.get("standalone_mode", True)
+        kwargs["standalone_mode"] = False
+
+        try:
+            return super().main(*args, **kwargs)
+        except click.exceptions.Abort:
+            if not original_standalone_mode:
+                raise
+            click.echo("Aborted!", err=True)
+            sys.exit(1)
+        except click.exceptions.ClickException as e:
+            if _is_json_output_requested(e):
+                import json
+
+                click.echo(json.dumps(_format_click_exception_as_json(e), indent=4))
+                sys.exit(e.exit_code)
+
+            if not original_standalone_mode:
+                raise
+            e.show()
+            sys.exit(e.exit_code)

cloudsmith_cli/cli/commands/__init__.py

@@ -0,0 +1,33 @@
+"""CLI/Commands - Import all commands."""
+
+from . import (
+    auth,
+    check,
+    copy,
+    credential_helper,
+    delete,
+    dependencies,
+    docs,
+    download,
+    entitlements,
+    help_,
+    list_,
+    login,
+    logout,
+    mcp,
+    metadata,
+    metrics,
+    move,
+    policy,
+    push,
+    quarantine,
+    quota,
+    repos,
+    resync,
+    status,
+    tags,
+    tokens,
+    upstream,
+    vulnerabilities,
+    whoami,
+)

cloudsmith_cli/cli/commands/auth.py

@@ -0,0 +1,173 @@
+"""CLI/Commands - Authenticate the user."""
+
+import webbrowser
+
+import click
+
+from .. import decorators, utils, validators
+from ..exceptions import handle_api_exceptions
+from ..saml import create_configured_session, get_idp_url
+from ..webserver import AuthenticationWebRequestHandler, AuthenticationWebServer
+from .main import main
+from .tokens import create, request_api_key
+
+# Authentication server configuration
+AUTH_SERVER_HOST = "127.0.0.1"
+AUTH_SERVER_PORT = 12400
+
+
+def _perform_saml_authentication(
+    opts, owner, enable_token_creation=False, use_stderr=False
+):
+    """Perform SAML authentication via web browser and local web server."""
+    session = create_configured_session(opts)
+    api_host = opts.api_config.host
+
+    idp_url = get_idp_url(api_host, owner, session=session)
+
+    click.echo(
+        f"Opening your organization's SAML IDP URL in your browser: {click.style(idp_url, bold=True)}",
+        err=use_stderr,
+    )
+    click.echo(err=use_stderr)
+    webbrowser.open(idp_url)
+
+    click.echo("Starting webserver to begin authentication ... ", err=use_stderr)
+
+    auth_server = AuthenticationWebServer(
+        (AUTH_SERVER_HOST, AUTH_SERVER_PORT),
+        AuthenticationWebRequestHandler,
+        owner=owner,
+        session=session,
+        debug=opts.debug,
+        refresh_api_on_success=enable_token_creation,
+        api_opts=opts.api_config,
+    )
+
+    auth_server.handle_request()
+
+
+@main.command(aliases=["auth"])
+@click.option(
+    "-o",
+    "--owner",
+    metavar="OWNER",
+    required=True,
+    callback=validators.validate_owner,
+    prompt=True,
+    help="The name of the Cloudsmith organization to authenticate with.",
+)
+@click.option(
+    "-t",
+    "--token",
+    default=False,
+    is_flag=True,
+    help="[DEPRECATED: Use --request-api-key] Retrieve a user API token after successful authentication.",
+)
+@click.option(
+    "-f",
+    "--force",
+    default=False,
+    is_flag=True,
+    help="[DEPRECATED: Use --request-api-key] Force refresh of user API token without prompts.",
+)
+@click.option(
+    "--save-config",
+    default=False,
+    is_flag=True,
+    help="Save the new API key to your configuration files.",
+)
+@click.option(
+    "--json",
+    default=False,
+    is_flag=True,
+    help="[DEPRECATED: Use --output-format json] Output token details in JSON format.",
+)
+@click.option(
+    "--request-api-key",
+    "request_api_key_flag",
+    default=False,
+    is_flag=True,
+    help="Retrieve API token (auto-creates or auto-rotates, no prompts). "
+    "Warning: If token exists, this will rotate it and invalidate the old key.",
+)
+@decorators.common_cli_config_options
+@decorators.common_cli_output_options
+@decorators.initialise_api
+@click.pass_context
+def authenticate(
+    ctx, opts, owner, token, force, save_config, json, request_api_key_flag
+):
+    """Authenticate to Cloudsmith using the org's SAML setup."""
+    # Validate mutual exclusivity
+    if request_api_key_flag and (token or force):
+        raise click.UsageError(
+            "--request-api-key cannot be used with --token or --force. "
+            "Use --request-api-key alone for fully automated token retrieval."
+        )
+
+    # Determine if we should redirect info messages to stderr
+    use_stderr = request_api_key_flag or json or utils.should_use_stderr(opts)
+
+    if token:
+        click.secho(
+            "DEPRECATION WARNING: The `--token` flag is deprecated and will be removed in a future release. "
+            "Please use `--request-api-key` instead.",
+            fg="yellow",
+            err=True,
+        )
+
+    if force:
+        click.secho(
+            "DEPRECATION WARNING: The `--force` flag is deprecated and will be removed in a future release. "
+            "Please use `--request-api-key` instead (force is implied).",
+            fg="yellow",
+            err=True,
+        )
+
+    if json and not utils.should_use_stderr(opts):
+        click.secho(
+            "DEPRECATION WARNING: The `--json` flag is deprecated and will be removed in a future release. "
+            "Please use `--output-format json` instead.",
+            fg="yellow",
+            err=True,
+        )
+
+    owner = owner[0].strip("'[]'")
+
+    click.echo(
+        f"Beginning authentication for the {click.style(owner, bold=True)} org ... ",
+        err=use_stderr,
+    )
+
+    # Determine if we need to refresh API after SSO (required for token operations)
+    enable_token_creation = token or request_api_key_flag
+
+    context_message = "Failed to authenticate via SSO!"
+    with handle_api_exceptions(ctx, opts=opts, context_msg=context_message):
+        _perform_saml_authentication(
+            opts,
+            owner,
+            enable_token_creation=enable_token_creation,
+            use_stderr=use_stderr,
+        )
+
+    if request_api_key_flag:
+        # Non-interactive token retrieval
+        new_token = request_api_key(ctx, opts, save_config=save_config)
+
+        if not new_token:
+            raise click.ClickException(
+                "Failed to retrieve API token. No token was returned."
+            )
+
+        # Check if JSON output is requested
+        if utils.maybe_print_as_json(opts, new_token):
+            return
+
+        # Default: output only the raw token value to stdout
+        click.echo(new_token.key)
+        return
+
+    if token:
+        ctx.invoke(create, opts=opts, save_config=save_config, force=force, json=json)

cloudsmith_cli/cli/commands/check.py

@@ -0,0 +1,129 @@
+"""CLI/Commands - Get an API token."""
+
+import click
+import cloudsmith_api
+import semver
+
+from ...core.api.rates import get_rate_limits
+from ...core.api.status import get_status
+from ...core.api.version import get_version as get_api_version_info
+from .. import command, decorators, utils
+from ..exceptions import handle_api_exceptions
+from ..utils import maybe_spinner
+from .main import main
+
+
+@main.group(cls=command.AliasGroup)
+@decorators.common_cli_config_options
+@decorators.common_cli_output_options
+@decorators.common_api_auth_options
+@click.pass_context
+def check(ctx, opts):  # pylint: disable=unused-argument
+    """Check rate limits and service status."""
+
+
+@check.command(aliases=["limits"])
+@decorators.common_cli_config_options
+@decorators.common_cli_output_options
+@decorators.initialise_api
+@click.pass_context
+def rates(ctx, opts):
+    """Check current API rate limits."""
+    use_stderr = utils.should_use_stderr(opts)
+    click.echo("Retrieving rate limits ... ", nl=False, err=use_stderr)
+
+    context_msg = "Failed to retrieve status!"
+    with handle_api_exceptions(ctx, opts=opts, context_msg=context_msg):
+        with maybe_spinner(opts):
+            resources_limits = get_rate_limits()
+
+    click.secho("OK", fg="green", err=use_stderr)
+
+    if utils.maybe_print_as_json(opts, resources_limits):
+        return
+
+    headers = ["Resource", "Throttled", "Remaining", "Interval (Seconds)", "Reset"]
+
+    rows = []
+    for resource, limits in resources_limits.items():
+        rows.append(
+            [
+                click.style(resource, fg="cyan"),
+                click.style(
+                    "Yes" if limits.throttled else "No",
+                    fg="red" if limits.throttled else "green",
+                ),
+                "%(remaining)s/%(limit)s"
+                % {
+                    "remaining": click.style(str(limits.remaining), fg="yellow"),
+                    "limit": click.style(str(limits.limit), fg="yellow"),
+                },
+                click.style(str(limits.interval), fg="blue"),
+                click.style(str(limits.reset), fg="magenta"),
+            ]
+        )
+
+    if resources_limits:
+        click.echo()
+        utils.pretty_print_table(headers, rows)
+
+    click.echo()
+
+    num_results = len(resources_limits)
+    list_suffix = "resource%s" % ("s" if num_results != 1 else "")
+    utils.pretty_print_list_info(num_results=num_results, suffix=list_suffix)
+
+
+@check.command()
+@decorators.common_cli_config_options
+@decorators.common_cli_output_options
+@decorators.initialise_api
+@click.pass_context
+def service(ctx, opts):
+    """Check the status of the Cloudsmith service."""
+    use_stderr = utils.should_use_stderr(opts)
+    click.echo("Retrieving service status ... ", nl=False, err=use_stderr)
+
+    context_msg = "Failed to retrieve status!"
+    with handle_api_exceptions(ctx, opts=opts, context_msg=context_msg):
+        with maybe_spinner(opts):
+            status, version = get_status(with_version=True)
+
+    click.secho("OK", fg="green", err=use_stderr)
+
+    config = cloudsmith_api.Configuration()
+
+    data = {
+        "endpoint": config.host,
+        "status": status,
+        "version": version,
+    }
+
+    if utils.maybe_print_as_json(opts, data):
+        return
+
+    click.echo()
+    click.echo(f"The service endpoint is: {click.style(config.host, bold=True)}")
+    click.echo(f"The service status is:   {click.style(status, bold=True)}")
+    click.echo(
+        f"The service version is:  {click.style(version, bold=True)} ",
+        nl=False,
+    )
+
+    api_version = get_api_version_info()
+
+    if semver.Version.parse(version).compare(api_version) > 0:
+        click.secho("(maybe out-of-date)", fg="yellow")
+
+        click.echo()
+        click.secho(
+            f"The API library used by this CLI tool is built against service version: {click.style(api_version, bold=True)}",
+            fg="yellow",
+        )
+    else:
+        click.secho("(up-to-date)", fg="green")
+
+        click.echo()
+        click.secho(
+            "The API library used by this CLI tool seems to be up-to-date.", fg="green"
+        )

cloudsmith_cli/cli/commands/copy.py

@@ -0,0 +1,98 @@
+"""CLI/Commands - List objects."""
+
+import click
+
+from ...core.api.packages import copy_package
+from .. import decorators, utils, validators
+from ..exceptions import handle_api_exceptions
+from ..utils import maybe_spinner
+from .main import main
+from .push import wait_for_package_sync
+
+
+@main.command(aliases=["cp"])
+@decorators.common_cli_config_options
+@decorators.common_cli_output_options
+@decorators.common_package_action_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.argument("destination", metavar="DEST")
+@click.pass_context
+def copy(
+    ctx,
+    opts,
+    owner_repo_package,
+    destination,
+    skip_errors,
+    wait_interval,
+    no_wait_for_sync,
+    sync_attempts,
+):
+    """
+    Copy a package to another repository.
+
+    This requires appropriate permissions for both the source
+    repository/package and the destination 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'.
+
+    - DEST: Specify the DEST (destination) repository to copy the package to.
+    This *must* be in the same namespace as the source repository.
+
+      Example: 'other-repo'
+
+    Full CLI example:
+
+      $ cloudsmith cp your-org/awesome-repo/better-pkg other-repo
+    """
+    owner, source, slug = owner_repo_package
+
+    use_stderr = utils.should_use_stderr(opts)
+
+    click.echo(
+        "Copying %(slug)s package from %(source)s to %(dest)s ... "
+        % {
+            "slug": click.style(slug, bold=True),
+            "source": click.style(source, bold=True),
+            "dest": click.style(destination, bold=True),
+        },
+        nl=False,
+        err=use_stderr,
+    )
+
+    context_msg = "Failed to copy package!"
+    with handle_api_exceptions(
+        ctx, opts=opts, context_msg=context_msg, reraise_on_error=skip_errors
+    ):
+        with maybe_spinner(opts):
+            _, new_slug = copy_package(
+                owner=owner, repo=source, identifier=slug, destination=destination
+            )
+
+    click.secho("OK", fg="green", err=use_stderr)
+
+    if no_wait_for_sync:
+        utils.maybe_print_status_json(opts, {"slug": new_slug, "status": "OK"})
+        return
+
+    wait_for_package_sync(
+        ctx=ctx,
+        opts=opts,
+        owner=owner,
+        repo=destination,
+        slug=new_slug,
+        wait_interval=wait_interval,
+        skip_errors=skip_errors,
+        attempts=sync_attempts,
+    )
+
+    utils.maybe_print_status_json(opts, {"slug": new_slug, "status": "OK"})

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