feat(ENG-13683): add Maven credential helper via shell plugin

CHANGELOG.md

@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 ## [Unreleased]
 
+### Added
+
+- `cloudsmith domains list` lists the hosts Cloudsmith can authenticate as a versioned JSON document: `{"version": 1, "domains": [{"host": ..., "format": ..., "enabled": ..., "validated": ..., "type": ..., "domain_type": ..., "org": ..., "repository": ..., "primary": ..., "created_at": ...}]}`. The built-in list can be replaced by a `[domains]` section in a trusted `config.ini` — each entry maps a hostname to the format it serves, or to `download`/`upload` — for dedicated and on-premise deployments. `--format` and `--repo` narrow the list to the hosts usable for a package format or repository, most-preferred first.
+- The Cloudsmith organisation is now named by `--org`, with `--organization` and `--oidc-org` accepted as aliases for the same option, and `org`, `organization` or `oidc_org` accepted in `config.ini`. `--oidc-org` named the setting after the first feature that wanted it; it is read by custom-domain discovery as well as OIDC token exchange, so it is now named after what it is. The `CLOUDSMITH_ORG` environment variable is unchanged, and `credential-helper install` no longer has a separate `--org` of its own.
+- `cloudsmith credential-helper install maven --org <org> --repo <repo>` sets up transparent Maven authentication. Maven has no credential-helper protocol, so the CLI installs an `mvn` shim — put the shims directory on `PATH` with `cloudsmith credential-helper shell-init` — that wraps each run in `cloudsmith exec` and injects an ephemeral, mode-0600 `settings.xml` via `mvn -s`, deleted when the run ends, so no token is written to durable configuration. Wrapped runs do not consult `~/.m2/settings.xml`; passing your own `-s/--settings` runs Maven unwrapped, with a warning. Custom download and upload domains are discovered automatically. Publishing is opt-in: `install` prints the `distributionManagement` snippet to add to `pom.xml`, and because Maven matches a `<server>` by id alone, the id that snippet names is supplied only on a deploy — an ordinary build gets a random one, so a `pom.xml` cannot obtain the token by declaring a repository under a guessed id.
+- `cloudsmith exec -- <command>` runs a package-manager command with Cloudsmith credentials provisioned for that single run and cleaned up afterwards — the same machinery the `mvn` shim uses, callable directly (for example in CI, without touching `PATH`). `--org`/`--repo` override the stored binding for one invocation, while `CLOUDSMITH_ORG`/`CLOUDSMITH_REPO` apply only when nothing is stored.
+- `cloudsmith credential-helper shell-init` prints the shell initialisation (bash, zsh and fish) that puts the Cloudsmith shims directory first on `PATH`, for `eval "$(cloudsmith credential-helper shell-init)"` in a shell rc file.
+
+
+### Fixed
+
+- An organisation named only by a `config.ini` in the current directory is no longer used to decide which hosts may receive a credential. That file travels with whatever repository is checked out, so it is now filtered like `api_host`: `--org` and `CLOUDSMITH_ORG` are honoured, a directory-relative `config.ini` is ignored with a warning. A user-level `config.ini` is unaffected.
+- Custom-domain lookups now read every page of results. Only the first page was ever requested, so an organisation with more custom domains than fit on one page lost the rest — and since that list decides which hosts may receive a credential, the Docker helper refused credentials for hosts the organisation owns.
+- API errors now say what went wrong. `ApiException` was constructed without passing anything to `Exception`, so rendering one as a string produced nothing at all — any message built by interpolation stopped dead at the colon, for example `Failed to fetch custom domains for 'acme': ` with no mention of the 401 behind it. It now renders as its status plus the API's detail (or the status description, when the API sends no detail), which fixes that message along with the `credential-helper install`/`uninstall` failures and the Docker auto-discovery warning.
+
 ## [1.21.0] - 2026-08-03
 
 ### Added

cloudsmith_cli/cli/commands/__init__.py

@@ -8,8 +8,10 @@
     delete,
     dependencies,
     docs,
+    domains,
     download,
     entitlements,
+    exec_,
     help_,
     list_,
     login,

cloudsmith_cli/cli/commands/credential_helper/__init__.py

@@ -12,28 +12,45 @@
 from .docker import docker as docker_cmd
 from .generic import generic as generic_cmd
 from .manage import install_cmd, list_cmd, uninstall_cmd
+from .shell import shell_init
 
 
 @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.
+    Use ``install`` to set up a helper and configure the package manager
+    automatically. Docker uses a native credential-helper launcher; Maven has
+    no such protocol, so it uses an ``mvn`` shim plus ``cloudsmith exec`` —
+    activate the shims directory with ``credential-helper shell-init``.
+
+    ``generic`` and ``domains`` emit machine-readable JSON for tools that
+    shell out to the CLI instead of importing it.
 
     Examples:
-        # Install Docker credential helper
+
+    \b
+        # Install the Docker credential helper
         $ cloudsmith credential-helper install docker
 
-        # Test Docker credential helper directly
+    \b
+        # Install the Maven helper for one repository
+        $ cloudsmith credential-helper install maven --org my-org --repo my-repo
+
+    \b
+        # Test the Docker credential helper directly
         $ echo "docker.cloudsmith.io" | cloudsmith credential-helper docker
+
+    \b
+        # Emit a credential as JSON
+        $ cloudsmith credential-helper generic
     """
 
 
 credential_helper.add_command(docker_cmd, name="docker")
 credential_helper.add_command(generic_cmd, name="generic")
+credential_helper.add_command(shell_init, name="shell-init")
 credential_helper.add_command(install_cmd, name="install")
 credential_helper.add_command(uninstall_cmd, name="uninstall")
 credential_helper.add_command(list_cmd, name="list")

cloudsmith_cli/cli/commands/credential_helper/docker.py

@@ -12,14 +12,19 @@
 import click
 
 from ....credential_helpers.docker import execute
-from ...decorators import common_api_auth_options, resolve_credentials
+from ...decorators import (
+    common_api_auth_options,
+    org_from_trusted_source,
+    resolve_credentials,
+)
 
 
 @click.command()
 @click.argument("operation", required=False, default="get")
 @common_api_auth_options
 @resolve_credentials
-def docker(opts, operation):
+@click.pass_context
+def docker(ctx, opts, operation):
     """
     Docker credential helper for Cloudsmith registries.
 
@@ -29,7 +34,11 @@ def docker(opts, operation):
 
     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).
+    (requires an organisation - ``--org``, CLOUDSMITH_ORG, or ``org`` in a
+    user-level ``config.ini`` - and a valid API key/token).  An organisation
+    named only by a ``config.ini`` in the current directory is ignored: it
+    chooses which hosts receive the token, so it is filtered on the same rule
+    as ``api_host``.
 
     Input (stdin):
         Server URL as plain text (e.g. "docker.cloudsmith.io")
@@ -57,6 +66,7 @@ def docker(opts, operation):
         sys.stdin,
         credential=opts.credential,
         api_host=opts.api_host,
+        org=org_from_trusted_source(ctx, opts),
     )
 
     if stdout is not None:

cloudsmith_cli/cli/commands/credential_helper/generic.py

@@ -28,7 +28,8 @@ def generic(opts):
     Resolves a credential through the full provider chain and writes a
     versioned JSON document to stdout.  Takes no arguments: a Cloudsmith token
     is organisation-wide, so the host it will be used against does not change
-    which credential resolves.
+    which credential resolves.  Use ``cloudsmith domains list`` to
+    discover which hosts Cloudsmith can authenticate.
 
     \b
     Output (stdout):

cloudsmith_cli/cli/commands/credential_helper/manage.py

@@ -8,12 +8,13 @@
 
 from __future__ import annotations
 
-import os
 import sys
 
 import click
 
 from ....credential_helpers.docker.installer import DockerInstaller
+from ....credential_helpers.maven.installer import MavenInstaller
+from ....credential_helpers.shellplugin.config import DEFAULT_REGISTRY_ID
 from ... import utils
 from ...decorators import (
     common_api_auth_options,
@@ -28,6 +29,7 @@
 
 _INSTALLERS: dict[str, type] = {
     "docker": DockerInstaller,
+    "maven": MavenInstaller,
 }
 
 
@@ -74,7 +76,8 @@ def _get_installer(name: str):
     "--domain",
     "domains",
     multiple=True,
-    help="Additional registry hostname to configure (repeatable).",
+    help="Registry hostname to configure (repeatable). Docker adds each host; "
+    "maven routes each to its download or upload endpoint.",
 )
 @click.option(
     "--dry-run",
@@ -86,7 +89,7 @@ def _get_installer(name: str):
     "--no-discover",
     is_flag=True,
     default=False,
-    help="Disable automatic discovery of custom Docker domains.",
+    help="Disable automatic discovery of custom domains.",
 )
 @click.option(
     "--refresh",
@@ -95,9 +98,17 @@ def _get_installer(name: str):
     help="Bypass the custom-domain cache and fetch fresh data from the API.",
 )
 @click.option(
-    "--org",
+    "--repo",
     default=None,
-    help="Cloudsmith organisation slug for custom-domain discovery.",
+    envvar="CLOUDSMITH_REPO",
+    help="Cloudsmith repository slug.",
+)
+@click.option(
+    "--registry-id",
+    default=DEFAULT_REGISTRY_ID,
+    show_default=True,
+    help="Id the credentials are registered under in your project config "
+    "(e.g. the Maven settings.xml/pom.xml <server> id).",
 )
 @common_cli_config_options
 @common_cli_output_options
@@ -113,18 +124,25 @@ def install_cmd(
     dry_run: bool,
     no_discover: bool,
     refresh: bool,
-    org: str | None,
+    repo: str | None,
+    registry_id: str,
 ) -> None:
     """Install a credential helper launcher and configure the package manager.
 
-    HELPER is the name of the credential helper to install (e.g. ``docker``).
+    HELPER is the name of the credential helper to install (``docker`` or
+    ``maven``). The maven helper binds one repository, so it requires
+    ``--org`` and ``--repo``.
 
     Examples:
 
     \b
         # Install Docker credential helper
         $ cloudsmith credential-helper install docker
 
+    \b
+        # Install the Maven helper for one repository
+        $ cloudsmith credential-helper install maven --org my-org --repo my-repo
+
     \b
         # Install with a custom domain
         $ cloudsmith credential-helper install docker --domain my.registry.example.com
@@ -138,19 +156,44 @@ def install_cmd(
         $ cloudsmith credential-helper install docker --no-discover
     """
     installer = _get_installer(helper)
-    org = org or os.environ.get("CLOUDSMITH_ORG", "").strip() or None
+
+    org = opts.org
+    repo = repo.strip() or None if repo else None
+
+    per_repo = getattr(installer, "requires_repo", False)
+    if per_repo and not (org and repo):
+        click.echo(
+            f"Error: helper {helper!r} requires --org and --repo.",
+            err=True,
+        )
+        sys.exit(1)
+
+    # Shell plugins (per-repo) keep their shims in a fixed dir; --bin-dir only
+    # applies to launcher-based helpers like Docker.
+    if per_repo:
+        if bin_dir:
+            click.echo(
+                f"Warning: --bin-dir is ignored for {helper!r}; its shim lives "
+                "in a fixed shims directory.",
+                err=True,
+            )
+        extra: dict = {"repo": repo, "registry_id": registry_id}
+    else:
+        extra = {"bin_dir": bin_dir}
     try:
         actions = installer.install(
-            bin_dir=bin_dir,
             domains=domains,
             dry_run=dry_run,
             discover=not no_discover,
             refresh=refresh,
-            org=org,
+            org=opts.org,
             credential=opts.credential,
             api_host=opts.api_host,
+            **extra,
         )
-    except OSError as exc:
+    except (OSError, ValueError) as exc:
+        # ValueError: an incomplete trusted [domains] table has no host for a
+        # kind the helper needs, which is a config error to report, not a crash.
         raise click.ClickException(
             f"Failed to install {helper!r} credential helper: {exc}"
         )
@@ -210,9 +253,12 @@ def uninstall_cmd(ctx, opts, helper: str, bin_dir: str | None, dry_run: bool) ->
         $ cloudsmith credential-helper uninstall docker --dry-run
     """
     installer = _get_installer(helper)
+    extra = {} if getattr(installer, "requires_repo", False) else {"bin_dir": bin_dir}
     try:
-        actions = installer.uninstall(bin_dir=bin_dir, dry_run=dry_run)
-    except OSError as exc:
+        actions = installer.uninstall(dry_run=dry_run, **extra)
+    except (OSError, ValueError) as exc:
+        # ValueError: an incomplete trusted [domains] table has no host for a
+        # kind the helper needs, which is a config error to report, not a crash.
         raise click.ClickException(
             f"Failed to uninstall {helper!r} credential helper: {exc}"
         )

cloudsmith_cli/cli/commands/credential_helper/shell.py

@@ -0,0 +1,36 @@
+# Copyright 2026 Cloudsmith Ltd
+"""``cloudsmith credential-helper shell-init`` — print shell init for shims.
+
+Add ``eval "$(cloudsmith credential-helper shell-init)"`` to your shell rc file
+to put the Cloudsmith shims directory ahead of the real package-manager
+binaries on ``$PATH``.
+"""
+
+import click
+
+from ....credential_helpers.shellplugin.shellinit import detect_shell, generate_init
+
+
+@click.command(name="shell-init")
+@click.option(
+    "--shell",
+    "shell_name",
+    type=click.Choice(["bash", "zsh", "fish"]),
+    default=None,
+    help="Target shell. Auto-detected from $SHELL when omitted.",
+)
+def shell_init(shell_name):
+    """Print shell init that puts the Cloudsmith shims dir first on PATH.
+
+    Examples:
+
+    \b
+        # bash / zsh
+        $ eval "$(cloudsmith credential-helper shell-init)"
+
+    \b
+        # fish
+        $ cloudsmith credential-helper shell-init --shell fish | source
+    """
+    shell = shell_name or detect_shell()
+    click.echo(generate_init(shell), nl=False)