cloudsmith-cli 1.20.0__py3-none-any.whl

cloudsmith_cli/cli/commands/help_.py

@@ -0,0 +1,12 @@
+"""Main command/entrypoint."""
+
+import click
+
+from .main import main
+
+
+@main.command(name="help")
+@click.pass_context
+def help_(ctx):
+    """Show this delightful help message and exit."""
+    click.echo(ctx.parent.get_help())

cloudsmith_cli/cli/commands/list_.py

@@ -0,0 +1,317 @@
+"""CLI/Commands - List objects."""
+
+import functools
+from operator import itemgetter
+
+import click
+
+from ...core.api.distros import list_distros
+from ...core.api.packages import get_package_format_names_with_distros, list_packages
+from ...core.pagination import paginate_results
+from .. import command, decorators, utils, validators
+from ..exceptions import handle_api_exceptions
+from ..utils import maybe_spinner
+from . import dependencies, entitlements
+from .main import main
+from .repos import get as get_repos
+
+
+@main.group(cls=command.AliasGroup, name="list", aliases=["ls"])
+@decorators.common_cli_config_options
+@decorators.common_cli_output_options
+@decorators.common_api_auth_options
+@decorators.initialise_api
+@click.pass_context
+def list_(ctx, opts):  # pylint: disable=unused-argument
+    """
+    List distros, packages, repos and entitlements.
+
+    See the help for subcommands for more information on each.
+    """
+
+
+@list_.command(name="dependencies", aliases=["deps"])
+@dependencies.list_dependencies_options
+@functools.wraps(entitlements.list_entitlements)
+@click.pass_context
+def dependencies_(*args, **kwargs):  # pylint: disable=missing-docstring
+    return dependencies.list_dependencies(*args, **kwargs)
+
+
+@list_.command()
+@decorators.common_cli_config_options
+@decorators.common_cli_output_options
+@decorators.common_api_auth_options
+@decorators.initialise_api
+@click.argument(
+    "package-format",
+    default=None,
+    required=False,
+    type=click.Choice(get_package_format_names_with_distros()),
+)
+@click.pass_context
+def distros(ctx, opts, package_format):
+    """List available distributions."""
+    # Use stderr for messages if the output is something else (e.g.  # JSON)
+    use_stderr = utils.should_use_stderr(opts)
+
+    if not use_stderr:
+        click.echo("Getting list of distributions ... ", nl=False, err=use_stderr)
+
+    context_msg = "Failed to get list of distributions!"
+    with handle_api_exceptions(ctx, opts=opts, context_msg=context_msg):
+        with maybe_spinner(opts):
+            distros_ = list_distros(package_format=package_format)
+
+    if not use_stderr:
+        click.secho("OK", fg="green", err=use_stderr)
+
+    if utils.maybe_print_as_json(opts, distros_):
+        return
+
+    headers = ["Distro", "Release", "Format", "Distro / Release (Identifier)"]
+    if package_format:
+        headers.remove("Format")
+
+    rows = []
+    for distro in sorted(distros_, key=itemgetter("slug")):
+        if not distro["versions"]:
+            continue
+
+        for release in sorted(distro["versions"], key=itemgetter("slug")):
+            row = [
+                click.style(distro["name"], fg="cyan"),
+                click.style(release["name"], fg="yellow"),
+                click.style(distro["format"], fg="blue"),
+                "%(distro)s/%(release)s"
+                % {
+                    "distro": click.style(distro["slug"], fg="magenta"),
+                    "release": click.style(release["slug"], fg="green"),
+                },
+            ]
+
+            if package_format:
+                row.pop(2)  # Remove format column
+
+            rows.append(row)
+
+    if distros_:
+        click.echo()
+        utils.pretty_print_table(headers, rows)
+
+    click.echo()
+
+    num_results = sum(
+        1 for distro in distros_ for release in distro["versions"] if release
+    )
+    list_suffix = "distribution release%s" % ("s" if num_results != 1 else "")
+    utils.pretty_print_list_info(num_results=num_results, suffix=list_suffix)
+
+
+@list_.command(name="entitlements", aliases=["ents"])
+@entitlements.list_entitlements_options
+@functools.wraps(entitlements.list_entitlements)
+@click.pass_context
+def entitlements_(*args, **kwargs):  # pylint: disable=missing-docstring
+    return entitlements.list_entitlements(*args, **kwargs)
+
+
+@list_.command(aliases=["pkgs"])
+@decorators.common_cli_config_options
+@decorators.common_cli_output_options
+@decorators.common_cli_list_options
+@decorators.common_api_auth_options
+@decorators.initialise_api
+@click.argument(
+    "owner_repo", metavar="OWNER/REPO", callback=validators.validate_owner_repo
+)
+@click.option(
+    "-q",
+    "--query",
+    help=("A boolean-like search term for querying package attributes."),
+)
+@click.option(
+    "--sort",
+    type=click.Choice(
+        [
+            "date",
+            "-date",
+            "downloads",
+            "-downloads",
+            "format",
+            "-format",
+            "name",
+            "-name",
+            "scan",
+            "-scan",
+            "scan_date",
+            "-scan_date",
+            "size",
+            "-size",
+            "status",
+            "-status",
+            "version",
+            "-version",
+        ]
+    ),
+    help=("Sort packages by field. Prefix with '-' for descending order."),
+)
+@click.pass_context
+def packages(ctx, opts, owner_repo, page, page_size, query, sort, page_all):
+    """
+    List packages for a repository.
+
+    OWNER/REPO: Specify the OWNER namespace (i.e. user or org), and the
+    REPO name to list packages for that namespace and repository. All separated
+    by a slash.
+
+    You can use the search query (-q|--query) to filter packages:
+
+      - By name: 'my-package' (implicit) or 'name:my-package'
+
+      - By filename: 'pkg.ext' (implicit) or 'filename:pkg.ext' (explicit)
+
+      - By version: '1.0.0' (implicit) or 'version:1.0.0' (explicit)
+
+      - By arch: 'x86_64' (implicit) or 'architecture:x86_64' (explicit)
+
+      - By distro: 'el' (implicit) or 'distribution:el' (explicit)
+
+    You can also modify the search terms:
+
+      - '^foo' to anchor to start of term
+
+      - 'foo$' to anchor to end of term
+
+      - 'foo*bar' for fuzzy matching
+
+      - '~foo' for negation of the term (explicit only, e.g. name:~foo)
+
+    Multiple search terms are conjunctive (AND).
+
+    Examples, to find packages named exactly foo, with a zip filename, that are
+    NOT the x86 architecture, use something like this:
+
+    --query 'name:^foo$ filename:.zip$ architecture:~x86'
+
+    You can sort the results using --sort with these fields:
+      - date/-date: Sort by creation date
+      - downloads/-downloads: Sort by download count
+      - format/-format: Sort by package format
+      - name/-name: Sort by package name
+      - scan/-scan: Sort by scan status
+      - scan_date/-scan_date: Sort by last scan date
+      - size/-size: Sort by package size
+      - status/-status: Sort by package status
+      - version/-version: Sort by version
+
+    Prefix any field with '-' for descending order (e.g. -date for newest first).
+    """
+    owner, repo = owner_repo
+
+    # Use stderr for messages if the output is something else (e.g.  # JSON)
+    use_stderr = utils.should_use_stderr(opts)
+
+    if not use_stderr:
+        click.echo("Getting list of packages ... ", nl=False, err=use_stderr)
+
+    context_msg = "Failed to get list of packages!"
+    with handle_api_exceptions(ctx, opts=opts, context_msg=context_msg):
+        with maybe_spinner(opts):
+            packages_, page_info = paginate_results(
+                list_packages,
+                page_all=page_all,
+                page=page,
+                page_size=page_size,
+                owner=owner,
+                repo=repo,
+                query=query,
+                sort=sort,
+            )
+
+    if not use_stderr:
+        click.secho("OK", fg="green", err=use_stderr)
+
+    if utils.maybe_print_as_json(opts, packages_, page_info):
+        return
+
+    headers = ["Name", "Version", "Status", "Owner / Repository (Identifier)"]
+    rows = []
+    for package in sorted(packages_, key=itemgetter("namespace", "slug")):
+        rows.append(
+            [
+                click.style(_get_package_name(package), fg="cyan"),
+                click.style(_get_package_version(package), fg="yellow"),
+                click.style(_get_package_status(package), fg="blue"),
+                "%(owner_slug)s/%(repo_slug)s/%(slug)s"
+                % {
+                    "owner_slug": click.style(package["namespace"], fg="magenta"),
+                    "repo_slug": click.style(package["repository"], fg="magenta"),
+                    "slug": click.style(package["slug"], fg="green"),
+                },
+            ]
+        )
+
+    if packages_:
+        click.echo()
+        utils.pretty_print_table(headers, rows)
+
+    click.echo()
+
+    num_results = len(packages_)
+    list_suffix = "package%s" % ("s" if num_results != 1 else "")
+    utils.pretty_print_list_info(
+        num_results=num_results,
+        page_info=None if page_all else page_info,
+        suffix=f"{list_suffix} retrieved" if page_all else f"{list_suffix} visible",
+        page_all=page_all,
+    )
+
+
+@list_.command()
+@decorators.common_cli_config_options
+@decorators.common_cli_output_options
+@decorators.common_cli_list_options
+@decorators.common_api_auth_options
+@decorators.initialise_api
+@click.argument(
+    "owner_repo",
+    metavar="OWNER/REPO",
+    callback=validators.validate_optional_owner_repo,
+    default="",
+    required=False,
+)
+@click.pass_context
+def repos(ctx, opts, owner_repo, page, page_size, page_all):
+    """
+    List repositories for a namespace (owner).
+
+    OWNER/REPO: Specify the OWNER namespace (i.e user or org) to list the
+    repositories for that namespace.
+
+    If REPO isn't specified, all repositories will be retrieved from the
+    OWNER namespace.
+
+    If OWNER isn't specified it'll default to the currently authenticated user
+    (if any). If you're unauthenticated, no results will be returned.
+    """
+    ctx.forward(get_repos)
+
+
+def _get_package_name(package):
+    """Get the name (or filename) for a package."""
+    return package["name"] or package["filename"]
+
+
+def _get_package_status(package):
+    """Get the status for a package."""
+    status = package["status_str"] or "Unknown"
+    stage = package["stage_str"] or "Unknown"
+    if stage == "Fully Synchronised":
+        return status
+    return f"{status} / {stage}"
+
+
+def _get_package_version(package):
+    """Get the version for a package (if any)."""
+    return package["version"] or "None"

cloudsmith_cli/cli/commands/login.py

@@ -0,0 +1,99 @@
+"""CLI/Commands - Get an API token."""
+
+import click
+import cloudsmith_api
+
+from ...core.api.exceptions import TwoFactorRequiredException
+from ...core.api.user import get_user_token
+from ...core.config import create_config_files, new_config_messaging
+from .. import decorators, utils
+from ..exceptions import handle_api_exceptions
+from ..utils import maybe_spinner
+from .main import main
+
+
+def validate_login(ctx, param, value):
+    """Ensure that login is not blank."""
+    # pylint: disable=unused-argument
+    value = value.strip()
+    if not value:
+        raise click.BadParameter("The value cannot be blank.", param=param)
+    return value
+
+
+@main.command(aliases=["token"])
+@click.option(
+    "-l",
+    "--login",
+    required=True,
+    callback=validate_login,
+    prompt=True,
+    help="Your Cloudsmith login account (email address).",
+)
+@click.password_option("-p", "--password", help="Your Cloudsmith login password.")
+@decorators.common_cli_config_options
+@decorators.common_cli_output_options
+@decorators.initialise_api
+@click.pass_context
+def login(ctx, opts, login, password):  # pylint: disable=redefined-outer-name
+    """Retrieve your API authentication token/key via login."""
+    use_stderr = utils.should_use_stderr(opts)
+    click.echo(
+        "Retrieving API token for %(login)s ... "
+        % {"login": click.style(login, bold=True)},
+        nl=False,
+        err=use_stderr,
+    )
+
+    context_msg = "Failed to retrieve the API token!"
+    try:
+        with handle_api_exceptions(ctx, opts=opts, context_msg=context_msg):
+            with maybe_spinner(opts):
+                api_key = get_user_token(login=login, password=password)
+    except TwoFactorRequiredException as e:
+        click.echo("\r\033[K", nl=False, err=use_stderr)
+        click.echo("Two-factor authentication is required.", err=use_stderr)
+
+        totp_token = click.prompt(
+            "Enter your two-factor authentication code", type=str, err=use_stderr
+        )
+        click.echo(
+            "Verifying two-factor code for %(login)s ... "
+            % {"login": click.style(login, bold=True)},
+            nl=False,
+            err=use_stderr,
+        )
+
+        try:
+            with handle_api_exceptions(ctx, opts=opts, context_msg=context_msg):
+                with maybe_spinner(opts):
+                    api_key = get_user_token(
+                        login=login,
+                        password=password,
+                        totp_token=totp_token,
+                        two_factor_token=e.two_factor_token,
+                    )
+        except cloudsmith_api.rest.ApiException:
+            click.echo("\r\033[K", nl=False, err=use_stderr)
+            click.secho(
+                "Authentication failed: The entered TOTP token is not valid.",
+                fg="red",
+                err=use_stderr,
+            )
+            ctx.exit(1)
+
+    except cloudsmith_api.rest.ApiException as e:
+        click.echo("\r\033[K", nl=False, err=use_stderr)
+        click.secho(f"Authentication failed: {str(e)}", fg="red", err=use_stderr)
+        ctx.exit(1)
+
+    click.secho("OK", fg="green", err=use_stderr)
+
+    if not utils.maybe_print_as_json(opts, {"token": api_key, "login": login}):
+        click.echo(
+            "Your API key/token is: %(token)s"
+            % {"token": click.style(api_key, fg="magenta")}
+        )
+
+    create, has_errors = create_config_files(ctx, opts, api_key=api_key)
+    new_config_messaging(has_errors, opts, create, api_key=api_key)

cloudsmith_cli/cli/commands/logout.py

@@ -0,0 +1,151 @@
+# Copyright 2026 Cloudsmith Ltd
+"""CLI/Commands - Log out and clear authentication state."""
+
+import os
+
+import click
+import cloudsmith_api
+
+from ...core import keyring
+from .. import decorators, utils
+from ..config import CredentialsReader
+from .main import main
+
+
+def _clear_credentials(dry_run, use_stderr):
+    """Clear credential files. Returns result dict."""
+    creds_files = CredentialsReader.find_existing_files()
+    if not creds_files:
+        click.echo("No credentials file found.", err=use_stderr)
+        return {"action": "not_found", "files": []}
+
+    if not dry_run:
+        for path in creds_files:
+            CredentialsReader.clear_api_key(path)
+
+    verb = "Would remove" if dry_run else "Removed"
+    for path in creds_files:
+        click.echo(
+            f"{verb} credentials from: " + click.style(path, bold=True),
+            err=use_stderr,
+        )
+    action = "would_remove" if dry_run else "removed"
+    return {"action": action, "files": list(creds_files)}
+
+
+def _clear_keyring(api_host, dry_run, use_stderr):
+    """Clear SSO tokens from keyring. Returns result dict."""
+    if not keyring.should_use_keyring():
+        click.secho(
+            "Keyring is disabled (CLOUDSMITH_NO_KEYRING is set).",
+            fg="yellow",
+            err=use_stderr,
+        )
+        return {"action": "disabled"}
+
+    if not keyring.has_sso_tokens(api_host):
+        click.echo("No SSO tokens found in system keyring.", err=use_stderr)
+        return {"action": "not_found"}
+
+    if dry_run:
+        click.echo("Would remove SSO tokens from system keyring.", err=use_stderr)
+        return {"action": "would_remove"}
+
+    deleted = keyring.delete_sso_tokens(api_host)
+    action = "removed" if deleted else "failed"
+    msg = f"{'Removed' if deleted else 'Failed to remove'} SSO tokens from system keyring."
+    click.secho(msg, fg=None if deleted else "red", err=use_stderr)
+    return {"action": action} if deleted else {"action": action, "message": msg}
+
+
+def _env_api_key_status():
+    """Return structured status for the CLOUDSMITH_API_KEY env var."""
+    is_set = bool(os.environ.get("CLOUDSMITH_API_KEY"))
+    return {
+        "is_set": is_set,
+        "action": "unset CLOUDSMITH_API_KEY" if is_set else "none",
+    }
+
+
+def _collect_warnings(keyring_only, config_only):
+    """Collect advisory warnings based on flags and environment."""
+    warnings = []
+    if config_only:
+        warnings.append("SSO tokens were not modified (--config-only).")
+    if keyring_only:
+        warnings.append("credentials.ini was not modified (--keyring-only).")
+    if os.environ.get("CLOUDSMITH_API_KEY"):
+        warnings.append(
+            "CLOUDSMITH_API_KEY is set in your environment. "
+            "Run: unset CLOUDSMITH_API_KEY"
+        )
+    return warnings
+
+
+@main.command()
+@click.option(
+    "--api-host",
+    envvar="CLOUDSMITH_API_HOST",
+    default=None,
+    help="The API host to clear keyring tokens for.",
+)
+@click.option(
+    "--keyring-only",
+    is_flag=True,
+    default=False,
+    help="Only clear SSO tokens from the system keyring.",
+)
+@click.option(
+    "--config-only",
+    is_flag=True,
+    default=False,
+    help="Only clear credentials from credentials.ini.",
+)
+@click.option(
+    "--dry-run",
+    is_flag=True,
+    default=False,
+    help="Show what would be removed without removing anything.",
+)
+@decorators.common_cli_config_options
+@decorators.common_cli_output_options
+@click.pass_context
+def logout(ctx, opts, api_host, keyring_only, config_only, dry_run):
+    """Clear stored authentication credentials and SSO tokens."""
+    if keyring_only and config_only:
+        raise click.UsageError(
+            "--keyring-only and --config-only are mutually exclusive."
+        )
+
+    if api_host is None:
+        api_host = opts.api_host or cloudsmith_api.Configuration().host
+
+    use_stderr = utils.should_use_stderr(opts)
+
+    credential_file = (
+        _clear_credentials(dry_run, use_stderr)
+        if not keyring_only
+        else {"action": "skipped", "files": []}
+    )
+    keyring_result = (
+        _clear_keyring(api_host, dry_run, use_stderr)
+        if not config_only
+        else {"action": "skipped"}
+    )
+    warnings = _collect_warnings(keyring_only, config_only)
+
+    for warning in warnings:
+        click.secho(f"Note: {warning}", fg="yellow", err=use_stderr)
+
+    utils.maybe_print_as_json(
+        opts,
+        {
+            "api_host": api_host,
+            "dry_run": dry_run,
+            "sources": {
+                "credential_file": credential_file,
+                "keyring": keyring_result,
+                "environment_api_key": _env_api_key_status(),
+            },
+        },
+    )

cloudsmith_cli/cli/commands/main.py

@@ -0,0 +1,73 @@
+"""Main command/entrypoint."""
+
+import click
+
+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
+from .. import command, decorators, utils
+
+CONTEXT_SETTINGS = dict(help_option_names=["-h", "--help"])
+
+
+def print_version(opts):
+    """Print the environment versions."""
+    cli_version = get_cli_version()
+    api_version = get_api_version()
+
+    data = {
+        "cli_version": cli_version,
+        "api_version": api_version,
+    }
+
+    if not utils.maybe_print_as_json(opts, data):
+        click.echo("Versions:")
+        click.secho(
+            "CLI Package Version: %(version)s"
+            % {"version": click.style(cli_version, bold=True)}
+        )
+        click.secho(
+            "API Package Version: %(version)s"
+            % {"version": click.style(api_version, bold=True)}
+        )
+
+
+@click.group(
+    cls=command.AliasGroup,
+    context_settings=CONTEXT_SETTINGS,
+    invoke_without_command=True,
+    help="""\b
+   ________                __               _ __  __       ________    ____
+  / ____/ /___  __  ______/ /________ ___  (_) /_/ /_     / ____/ /   /  _/
+ / /   / / __ \\/ / / / __  / ___/ __ `__ \\/ / __/ __ \\   / /   / /    / /
+/ /___/ / /_/ / /_/ / /_/ (__  ) / / / / / / /_/ / / /  / /___/ /____/ /
+\\____/_/\\____/\\__,_/\\__,_/____/_/ /_/ /_/_/\\__/_/ /_/   \\____/_____/___/
+
+
+The Cloudsmith Command-Line Interface - Be Awesome. Automate Everything.
+    """,
+    epilog="""
+For more help, see the docs: %(help_website)s
+
+For issues/contributing: %(github_website)s
+    """
+    % {"help_website": get_help_website(), "github_website": get_github_website()},
+)
+@click.option(
+    "-V",
+    "--version",
+    help="Show the version numbers for the API and CLI.",
+    is_flag=True,
+    is_eager=True,
+)
+@decorators.common_cli_config_options
+@decorators.common_cli_output_options
+@click.pass_context
+def main(ctx, opts, version):
+    """Handle entrypoint to CLI."""
+    # pylint: disable=unused-argument
+
+    if version:
+        print_version(opts)
+    elif ctx.invoked_subcommand is None:
+        click.echo(ctx.get_help())