cloudsmith-cli 1.29.0__tar.gz → 1.30.0__tar.gz

{cloudsmith_cli-1.29.0/cloudsmith_cli.egg-info → cloudsmith_cli-1.30.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cloudsmith-cli
-Version: 1.29.0
+Version: 1.30.0
 Summary: Cloudsmith Command-Line Interface (CLI)
 Author-email: Cloudsmith Ltd <support@cloudsmith.io>
 License-Expression: Apache-2.0
@@ -37,13 +37,14 @@ Requires-Dist: mcp==2.3.0
 Requires-Dist: pydantic-settings>=2.14.2
 Requires-Dist: PyJWT[crypto]>=2.13.0
 Requires-Dist: python-toon==0.2.0
-Requires-Dist: requests>=2.18.4
+Requires-Dist: requests>=2.32.5
 Requires-Dist: requests_toolbelt>=1.0.0
 Requires-Dist: rich>=13.0.0
 Requires-Dist: semver>=2.7.9
 Requires-Dist: starlette>=1.3.1
 Requires-Dist: urllib3>=2.5
 Requires-Dist: tomlkit>=0.15.0
+Requires-Dist: sentry-sdk<3,>=2
 Provides-Extra: aws
 Requires-Dist: boto3[crt]>=1.26.0; extra == "aws"
 Provides-Extra: gcp
@@ -102,8 +103,8 @@ The CLI currently supports the following commands (and sub-commands):
   - `entitlements`|`ents`:  List entitlements for a repository.
   - `packages`:             List packages for a repository. (Aliases `repos list`)
   - `repos`:                List repositories for a namespace (owner).
-- `login`|`token`:        Retrieve your API authentication token/key via login.
-- `logout`:               Clear stored authentication credentials and SSO tokens (Keyring, API key from credential file and emit warning when `$CLOUDSMITH_API_KEY` is still set).
+- `login`|`token`:        [DEPRECATED] Retrieve your API authentication token/key via login.
+- `logout`:               Clear stored authentication credentials and SAML tokens (Keyring, API key from credential file and emit warning when `$CLOUDSMITH_API_KEY` is still set).
 - `metadata`:             Manage arbitrary JSON metadata (SBOM, BuildInfo, custom) attached to a package.
   - `add`:                  Attach a new metadata entry to a package.
   - `list`|`ls`:            List metadata entries for a package, or fetch a single entry by slug.
@@ -367,7 +368,7 @@ Both configuration files use the simple INI format, such as:
 api_key=1234567890abcdef1234567890abcdef
 ```
 
-Additionally, the CLI will store SSO access and refresh tokens in the system keyring
+Additionally, the CLI will store SAML access and refresh tokens in the system keyring
 using the [`keyring`](https://github.com/jaraco/keyring) library.
 
 
@@ -378,8 +379,9 @@ See the [default config](https://raw.githubusercontent.com/cloudsmith-io/cloudsm
 You can specify the following configuration options:
 
 - `api_host`: The API host to connect to.
-- `api_proxy`: The API proxy to connect through.
-- `api_ssl_verify`: Whether or not to use SSL verification for requests.
+- `proxy`: The proxy to connect through for all HTTP requests, including API, SAML, upload, download, MCP, update, credential helper, OIDC, and error report connections. Use `--proxy` or `CLOUDSMITH_PROXY` to set it for one command. The config key `api_proxy`, flag `--api-proxy`, and environment variable `CLOUDSMITH_API_PROXY` remain supported for compatibility. In config and environment variables, the new name takes precedence over the alias. Without `proxy`, the CLI uses the `HTTPS_PROXY`, `HTTP_PROXY`, and `NO_PROXY` environment variables. When `proxy` is set, it takes precedence over them.
+- `ssl_verify`: Whether or not to verify SSL certificates for HTTPS requests, including API, SAML, uploads, downloads, and MCP (default: `true`). Use `CLOUDSMITH_SSL_VERIFY=1` to enable verification or `CLOUDSMITH_SSL_VERIFY=0` / `--without-ssl-verify` to disable it. Disabling verification is dangerous; prefer disabling only strict checks where possible. The config key `api_ssl_verify`, flag `--without-api-ssl-verify` / `-S`, and environment variable `CLOUDSMITH_WITHOUT_API_SSL_VERIFY` remain supported for compatibility. Command-line settings override environment variables, which override config; within the same source, the new spelling takes precedence.
+- `ssl_verify_strict`: Whether or not to apply strict X.509 certificate verification (`VERIFY_X509_STRICT`, enabled by default on Python 3.13+). Set to `false` (or use `--without-ssl-verify-strict` / `CLOUDSMITH_SSL_VERIFY_STRICT=0`) if a TLS-intercepting proxy issues certificates that fail these checks. `CLOUDSMITH_SSL_VERIFY_STRICT=1` keeps strict verification enabled (the default). Certificates are still verified.
 - `api_user_agent`: The user agent to use for requests.
 
 ### Credentials (credentials.ini)
@@ -418,29 +420,15 @@ cloudsmith auth --owner example --no-browser
 
 #### Getting Your API Key
 
-You can retrieve your API key using the `cloudsmith login` command:
+Get your API key from the Cloudsmith web app: click your user icon in the top right corner, then click **Personal API Keys**. See [API Key](https://docs.cloudsmith.com/accounts-and-teams/api-key) for more information. If you authenticated with `cloudsmith auth`, you can also use `cloudsmith tokens create` to create an API key.
 
-```
-cloudsmith login
-Login: you@example.com
-Password:
-Repeat for confirmation:
-```
-
-*Note:* Please ensure you use your email for the 'Login' prompt and not your user slug/identifier.
-
-The resulting output looks something like:
-
-```
-Retrieving API token for 'you@example.com' ... OK
-Your API token is: 1234567890abcdef1234567890abcdef
-```
-
-Once you have your API key you can then put this into your `credentials.ini`, use it as an environment variable `export CLOUDSMITH_API_KEY=your_key_here` or pass it to the CLI using the `-k your_key_here` flag.
+Give your API key to the CLI in one of these ways:
 
-For convenience the CLI will ask you if you want to install the default configuration files, complete with your API key, if they don't already exist. Say 'y' or 'yes' to create the configuration files.
+- Set the `CLOUDSMITH_API_KEY` environment variable: `export CLOUDSMITH_API_KEY=your_key_here`.
+- Put the key into your `credentials.ini` file.
+- Pass the key to the CLI with the `-k your_key_here` flag.
 
-If the configuration files already exist, you'll have to manually put the API key into the configuration files, but the CLI will print out their locations.
+*Note:* The `cloudsmith login` command and its `cloudsmith token` alias are deprecated. They retrieve your API key with your email address and password, and they will stop working on November 20, 2026, when Cloudsmith disables username and password login. See the [Cloudsmith changelog](https://cloudsmith.com/changelog). After that, both commands fail with a message that explains how to get an API key instead.
 
 
 ## Uploading Packages

{cloudsmith_cli-1.29.0 → cloudsmith_cli-1.30.0}/README.md

@@ -47,8 +47,8 @@ The CLI currently supports the following commands (and sub-commands):
   - `entitlements`|`ents`:  List entitlements for a repository.
   - `packages`:             List packages for a repository. (Aliases `repos list`)
   - `repos`:                List repositories for a namespace (owner).
-- `login`|`token`:        Retrieve your API authentication token/key via login.
-- `logout`:               Clear stored authentication credentials and SSO tokens (Keyring, API key from credential file and emit warning when `$CLOUDSMITH_API_KEY` is still set).
+- `login`|`token`:        [DEPRECATED] Retrieve your API authentication token/key via login.
+- `logout`:               Clear stored authentication credentials and SAML tokens (Keyring, API key from credential file and emit warning when `$CLOUDSMITH_API_KEY` is still set).
 - `metadata`:             Manage arbitrary JSON metadata (SBOM, BuildInfo, custom) attached to a package.
   - `add`:                  Attach a new metadata entry to a package.
   - `list`|`ls`:            List metadata entries for a package, or fetch a single entry by slug.
@@ -312,7 +312,7 @@ Both configuration files use the simple INI format, such as:
 api_key=1234567890abcdef1234567890abcdef
 ```
 
-Additionally, the CLI will store SSO access and refresh tokens in the system keyring
+Additionally, the CLI will store SAML access and refresh tokens in the system keyring
 using the [`keyring`](https://github.com/jaraco/keyring) library.
 
 
@@ -323,8 +323,9 @@ See the [default config](https://raw.githubusercontent.com/cloudsmith-io/cloudsm
 You can specify the following configuration options:
 
 - `api_host`: The API host to connect to.
-- `api_proxy`: The API proxy to connect through.
-- `api_ssl_verify`: Whether or not to use SSL verification for requests.
+- `proxy`: The proxy to connect through for all HTTP requests, including API, SAML, upload, download, MCP, update, credential helper, OIDC, and error report connections. Use `--proxy` or `CLOUDSMITH_PROXY` to set it for one command. The config key `api_proxy`, flag `--api-proxy`, and environment variable `CLOUDSMITH_API_PROXY` remain supported for compatibility. In config and environment variables, the new name takes precedence over the alias. Without `proxy`, the CLI uses the `HTTPS_PROXY`, `HTTP_PROXY`, and `NO_PROXY` environment variables. When `proxy` is set, it takes precedence over them.
+- `ssl_verify`: Whether or not to verify SSL certificates for HTTPS requests, including API, SAML, uploads, downloads, and MCP (default: `true`). Use `CLOUDSMITH_SSL_VERIFY=1` to enable verification or `CLOUDSMITH_SSL_VERIFY=0` / `--without-ssl-verify` to disable it. Disabling verification is dangerous; prefer disabling only strict checks where possible. The config key `api_ssl_verify`, flag `--without-api-ssl-verify` / `-S`, and environment variable `CLOUDSMITH_WITHOUT_API_SSL_VERIFY` remain supported for compatibility. Command-line settings override environment variables, which override config; within the same source, the new spelling takes precedence.
+- `ssl_verify_strict`: Whether or not to apply strict X.509 certificate verification (`VERIFY_X509_STRICT`, enabled by default on Python 3.13+). Set to `false` (or use `--without-ssl-verify-strict` / `CLOUDSMITH_SSL_VERIFY_STRICT=0`) if a TLS-intercepting proxy issues certificates that fail these checks. `CLOUDSMITH_SSL_VERIFY_STRICT=1` keeps strict verification enabled (the default). Certificates are still verified.
 - `api_user_agent`: The user agent to use for requests.
 
 ### Credentials (credentials.ini)
@@ -363,29 +364,15 @@ cloudsmith auth --owner example --no-browser
 
 #### Getting Your API Key
 
-You can retrieve your API key using the `cloudsmith login` command:
+Get your API key from the Cloudsmith web app: click your user icon in the top right corner, then click **Personal API Keys**. See [API Key](https://docs.cloudsmith.com/accounts-and-teams/api-key) for more information. If you authenticated with `cloudsmith auth`, you can also use `cloudsmith tokens create` to create an API key.
 
-```
-cloudsmith login
-Login: you@example.com
-Password:
-Repeat for confirmation:
-```
-
-*Note:* Please ensure you use your email for the 'Login' prompt and not your user slug/identifier.
-
-The resulting output looks something like:
-
-```
-Retrieving API token for 'you@example.com' ... OK
-Your API token is: 1234567890abcdef1234567890abcdef
-```
-
-Once you have your API key you can then put this into your `credentials.ini`, use it as an environment variable `export CLOUDSMITH_API_KEY=your_key_here` or pass it to the CLI using the `-k your_key_here` flag.
+Give your API key to the CLI in one of these ways:
 
-For convenience the CLI will ask you if you want to install the default configuration files, complete with your API key, if they don't already exist. Say 'y' or 'yes' to create the configuration files.
+- Set the `CLOUDSMITH_API_KEY` environment variable: `export CLOUDSMITH_API_KEY=your_key_here`.
+- Put the key into your `credentials.ini` file.
+- Pass the key to the CLI with the `-k your_key_here` flag.
 
-If the configuration files already exist, you'll have to manually put the API key into the configuration files, but the CLI will print out their locations.
+*Note:* The `cloudsmith login` command and its `cloudsmith token` alias are deprecated. They retrieve your API key with your email address and password, and they will stop working on November 20, 2026, when Cloudsmith disables username and password login. See the [Cloudsmith changelog](https://cloudsmith.com/changelog). After that, both commands fail with a message that explains how to get an API key instead.
 
 
 ## Uploading Packages

{cloudsmith_cli-1.29.0 → cloudsmith_cli-1.30.0}/cloudsmith_cli/cli/command.py

@@ -6,6 +6,8 @@ from collections import OrderedDict
 import click.exceptions
 from click_didyoumean import DYMGroup
 
+from ..core.certificate_errors import describe_certificate_error
+
 
 def _is_json_output_requested(exception):
     """Determine if JSON output was requested, checking context and argv."""
@@ -35,6 +37,19 @@ def _is_json_output_requested(exception):
     return False
 
 
+def _is_debug_requested(args=None):
+    """Determine if --debug was passed (the click context is gone by now).
+
+    ``args`` are the arguments given to ``main``; click falls back to
+    ``sys.argv`` when they are ``None``, so we do the same.
+    """
+    import sys
+
+    if args is None:
+        args = sys.argv[1:]
+    return any(arg in ("-d", "--debug") for arg in args)
+
+
 def _format_click_exception_as_json(exception):
     """Format a ClickException as a JSON error dict."""
     return {
@@ -45,11 +60,19 @@ def _format_click_exception_as_json(exception):
         },
         "help": {
             "context": "Invalid usage",
-            "hint": "Check your command arguments/flags.",
+            "hint": describe_certificate_error(exception)
+            or "Check your command arguments/flags.",
         },
     }
 
 
+def _echo_certificate_hint(exception):
+    """Explain a TLS certificate failure behind ``exception`` on stderr."""
+    hint = describe_certificate_error(exception)
+    if hint:
+        click.echo(f"Hint: {click.style(hint, fg='yellow')}", err=True)
+
+
 class AliasGroup(DYMGroup):
     """A command group with DYM, alias and lazy-subcommand support.
 
@@ -177,4 +200,23 @@ class AliasGroup(DYMGroup):
             if not original_standalone_mode:
                 raise
             e.show()
+            _echo_certificate_hint(e)
             sys.exit(e.exit_code)
+        except Exception as e:  # pylint: disable=broad-exception-caught
+            # Anything reaching here is unexpected: click's own errors and
+            # handled API errors (which exit via ctx.exit) are dealt with
+            # above or never get this far.
+            if not original_standalone_mode:
+                raise
+            main_args = kwargs.get("args", args[0] if args else None)
+            if _is_debug_requested(main_args):
+                import traceback
+
+                click.echo(traceback.format_exc(), err=True, nl=False)
+            from ..core import telemetry
+
+            # Reporting is silent: the user sees the same line either way.
+            telemetry.report_exception(e)
+            click.echo(f"Error: {telemetry.format_exception_summary(e)}", err=True)
+            _echo_certificate_hint(e)
+            sys.exit(1)

{cloudsmith_cli-1.29.0 → cloudsmith_cli-1.30.0}/cloudsmith_cli/cli/commands/auth.py

@@ -12,7 +12,7 @@ from ...core.sso import (
 )
 from .. import decorators, utils, validators
 from ..exceptions import handle_api_exceptions
-from ..saml import create_configured_session, get_idp_url
+from ..saml import get_idp_url
 from ..webserver import AuthenticationWebRequestHandler, AuthenticationWebServer
 from .main import main
 from .tokens import create, request_api_key
@@ -53,7 +53,7 @@ def _create_auth_server(opts, owner, session, enable_token_creation, profile):
 
 
 def _renew_existing_sso_session(opts, profile):
-    """Return a usable existing SSO session, or fall back to browser auth."""
+    """Return a usable existing SAML session, or fall back to browser auth."""
     renewal = renew_sso_session(opts.api_config.host, opts.session, profile=profile)
     if renewal.status in (
         SsoRenewalStatus.RENEWED,
@@ -64,14 +64,15 @@ def _renew_existing_sso_session(opts, profile):
         renewal.error, requests.RequestException
     ):
         raise click.ClickException(
-            "The SSO session has expired and Cloudsmith could not be reached. "
+            "The SAML session has expired and Cloudsmith could not be reached: "
+            f"{renewal.error}\n"
             "Check your connection, then run 'cloudsmith auth' again."
         ) from renewal.error
     return None
 
 
 def _report_active_sso_session(opts, renewal, use_stderr=False):
-    """Report the usable SSO session without exposing its access token."""
+    """Report the usable SAML session without exposing its access token."""
     expires_at = get_access_token_expiry(renewal.access_token)
     data = {
         "authenticated": True,
@@ -84,16 +85,16 @@ def _report_active_sso_session(opts, renewal, use_stderr=False):
         return
 
     if renewal.status == SsoRenewalStatus.RENEWED:
-        click.secho("SSO session renewed.", fg="green", err=use_stderr)
+        click.secho("SAML session renewed.", fg="green", err=use_stderr)
     elif renewal.error:
         click.secho(
-            "The SSO session could not be renewed; the existing access token "
+            "The SAML session could not be renewed; the existing access token "
             "remains active.",
             fg="yellow",
             err=use_stderr,
         )
     else:
-        click.secho("SSO session is active.", fg="green", err=use_stderr)
+        click.secho("SAML session is active.", fg="green", err=use_stderr)
     if expires_at:
         click.echo(
             f"Access token expires at {utils.fmt_datetime(expires_at)}.",
@@ -110,7 +111,7 @@ def _perform_saml_authentication(
     profile=None,
 ):
     """Perform SAML authentication via web browser and local web server."""
-    session = create_configured_session(opts)
+    session = opts.session
     api_host = opts.api_config.host
 
     auth_server, port = _create_auth_server(
@@ -270,10 +271,10 @@ def authenticate(
         err=use_stderr,
     )
 
-    # Determine if we need to refresh API after SSO (required for token operations)
+    # Determine if we need to refresh API after SAML (required for token operations)
     enable_token_creation = token or request_api_key_flag
 
-    context_message = "Failed to authenticate via SSO!"
+    context_message = "Failed to authenticate via SAML!"
     with handle_api_exceptions(ctx, opts=opts, context_msg=context_message):
         _perform_saml_authentication(
             opts,

{cloudsmith_cli-1.29.0 → cloudsmith_cli-1.30.0}/cloudsmith_cli/cli/commands/credential_helper/manage.py

@@ -9,6 +9,7 @@ Provides ``credential-helper install``, ``credential-helper uninstall``, and
 from __future__ import annotations
 
 import sys
+from urllib.parse import urlsplit
 
 import click
 
@@ -78,10 +79,14 @@ def _get_installer(name: str):
 def _terraform_helper_args(ctx, opts, repo: str | None = None) -> tuple[str, ...]:
     """Build the terraformrc ``args`` list from the resolved config.
 
-    Baking ``--org``/``-r``/``-P`` into the block means ``terraform init`` works
+    Baking ``-w``/``-r``/``-P`` into the block means ``terraform init`` works
     with no environment variables and no hand-edited config. Only values
-    actually supplied are written, so an install without ``--org``/``--repo``/
-    ``-P`` leaves ``args = []``.
+    actually supplied are written, so an install without ``-w``/``--repo``/
+    ``-P`` leaves ``args = []``. The API host and proxy are baked in too, so
+    the helper looks up domains on the same API host, through the same proxy,
+    as the install. A proxy URL with credentials is never baked in: Terraform
+    passes ``args`` on the helper's command line, where any local user can read
+    them.
 
     A non-default ``--config-file``/``--credentials-file`` is also baked in: the
     helper is later invoked by ``terraform init`` in a fresh process with none
@@ -91,7 +96,7 @@ def _terraform_helper_args(ctx, opts, repo: str | None = None) -> tuple[str, ...
     """
     args: list[str] = []
     if opts.org:
-        args.extend(["--org", opts.org])
+        args.extend(["-w", opts.org])
     if repo:
         args.extend(["-r", repo])
     profile = ctx.meta.get("profile")
@@ -103,9 +108,32 @@ def _terraform_helper_args(ctx, opts, repo: str | None = None) -> tuple[str, ...
     creds_file = ctx.meta.get("creds_file")
     if creds_file:
         args.extend(["--credentials-file", creds_file])
+    if opts.api_host:
+        args.extend(["--api-host", opts.api_host])
+    if opts.proxy and not _proxy_has_credentials(opts.proxy):
+        args.extend(["--proxy", opts.proxy])
     return tuple(args)
 
 
+def _proxy_has_credentials(proxy: str) -> bool:
+    """Return True if the proxy URL carries a username or password."""
+    parsed = urlsplit(proxy if "://" in proxy else f"//{proxy}")
+    return parsed.username is not None or parsed.password is not None
+
+
+def _terraform_proxy_next_steps(opts) -> list[str]:
+    """Return the post-install guidance when the proxy was not baked in."""
+    if not opts.proxy or not _proxy_has_credentials(opts.proxy):
+        return []
+    return [
+        (
+            "Next steps: the proxy URL contains credentials, so it was not"
+            " written to the Terraform config. export CLOUDSMITH_PROXY=<proxy-url>"
+            " in the environment that runs `terraform init`."
+        ),
+    ]
+
+
 _REPO_FLAGS = ("-r", "--repo", "--repository")
 
 
@@ -141,6 +169,31 @@ def _terraform_next_steps(helper_args: tuple[str, ...]) -> list[str]:
     ]
 
 
+def _terraform_workspace_next_steps(helper_args: tuple[str, ...]) -> list[str]:
+    """Return the post-install guidance when no Workspace is baked in.
+
+    The helper needs a Workspace to match custom domains and to scope the
+    token for a Cloudsmith-owned host.
+    """
+    if "-w" in helper_args:
+        return []
+    rc_path = _terraformrc_path()
+    return [
+        (
+            "Next steps: the Terraform helper needs a Workspace to match custom"
+            " domains and to scope tokens. Provide it in one of these ways:"
+        ),
+        (
+            "  - export CLOUDSMITH_WORKSPACE=<your-workspace> in the environment"
+            " that runs `terraform init`, or"
+        ),
+        (
+            f"  - add it to the args in {rc_path}, e.g."
+            ' args = ["-w", "<your-workspace>", ...].'
+        ),
+    ]
+
+
 # ---------------------------------------------------------------------------
 # install
 # ---------------------------------------------------------------------------
@@ -149,7 +202,10 @@ def _terraform_next_steps(helper_args: tuple[str, ...]) -> list[str]:
 @click.command("install")
 @click.argument("helper")
 @click.option(
-    "--bin-dir", default=None, help="Directory to install the launcher binary."
+    "--bin-dir",
+    default=None,
+    help="Directory to install the launcher binary. "
+    "[default: ~/.cloudsmith/bin, or Terraform's plugin directory]",
 )
 @click.option(
     "--domain",
@@ -231,7 +287,7 @@ def install_cmd(
     \b
         # Terraform: bake the repository into the terraformrc args so
         # `terraform init` needs no CLOUDSMITH_REPO env var
-        $ cloudsmith credential-helper install terraform --org acme --repo my-repo
+        $ cloudsmith credential-helper install terraform -w acme --repo my-repo
     """
     installer = _get_installer(helper)
 
@@ -278,7 +334,11 @@ def install_cmd(
 
     next_steps: list[str] = []
     if helper == "terraform":
-        next_steps = _terraform_next_steps(helper_args)
+        next_steps = (
+            _terraform_workspace_next_steps(helper_args)
+            + _terraform_next_steps(helper_args)
+            + _terraform_proxy_next_steps(opts)
+        )
 
     data = {
         "helper": helper,
@@ -309,7 +369,10 @@ def install_cmd(
 @click.command("uninstall")
 @click.argument("helper")
 @click.option(
-    "--bin-dir", default=None, help="Directory where the launcher binary was installed."
+    "--bin-dir",
+    default=None,
+    help="Directory where the launcher binary was installed. "
+    "[default: ~/.cloudsmith/bin, or Terraform's plugin directory]",
 )
 @click.option(
     "--dry-run",

{cloudsmith_cli-1.29.0 → cloudsmith_cli-1.30.0}/cloudsmith_cli/cli/commands/credential_helper/terraform.py

@@ -46,8 +46,9 @@ def terraform(opts, repo, params):
 
     Provides credentials for all Cloudsmith Terraform registries:
     ``*.cloudsmith.io``, ``*.cloudsmith.com``, and any custom domains
-    configured for the organisation (requires an organisation - ``--org``,
-    CLOUDSMITH_ORG or ``org`` in ``config.ini`` - and a valid API key/token).
+    configured for the Workspace (requires a Workspace - ``-w/--workspace``,
+    CLOUDSMITH_WORKSPACE or ``workspace`` in ``config.ini`` - and a valid API
+    key/token).
 
     Accepts Terraform's calling convention — an optional verb (``get``,
     ``store``, ``forget``) followed by the hostname — so the on-PATH launcher
@@ -76,18 +77,18 @@ def terraform(opts, repo, params):
         0: Token returned, or the host is not a Cloudsmith registry
         1: Cloudsmith host with no credentials available, or an error occurred
 
-    The token is scoped to the repository. On a standard
-    ``*.cloudsmith.io``/``*.cloudsmith.com`` host it is ``{org}/{repo}/{token}``
-    and the organisation is required (``--org``, ``CLOUDSMITH_ORG`` or ``org``
-    in ``config.ini``); a standard host requested without an organisation is a
+    The token is scoped to the repository. On a Cloudsmith-owned host it is
+    ``{workspace}/{repo}/{token}`` and the Workspace is required
+    (``-w/--workspace``, ``CLOUDSMITH_WORKSPACE`` or ``workspace`` in
+    ``config.ini``); a Cloudsmith-owned host requested without a Workspace is a
     non-zero exit. On a custom domain — which is already bound to a single
-    organisation — the org is omitted and the token is ``{repo}/{token}``. The
+    Workspace — the Workspace is omitted and the token is ``{repo}/{token}``. The
     repository is always required (``-r/--repo/--repository`` or
     ``CLOUDSMITH_REPO``): Terraform does not tell a credentials helper which
     repository is being requested. A non-Cloudsmith host still returns ``{}``
     and exit 0. The profile can also be supplied with ``-P/--profile``. The
     launcher forwards Terraform's ``args`` verbatim, so a terraformrc block such
-    as ``credentials_helper "cloudsmith" { args = ["--org=acme",
+    as ``credentials_helper "cloudsmith" { args = ["-w", "acme",
     "--repo=my-repo", "-P", "ci"] }`` reaches this command as those options.
 
     \b
@@ -101,13 +102,13 @@ def terraform(opts, repo, params):
         # Terraform's calling convention (verb + hostname)
         $ cloudsmith credential-helper terraform --repo my-repo get terraform.cloudsmith.io
     \b
-        # Select an org and profile explicitly (no env vars needed)
-        $ cloudsmith credential-helper terraform --org=acme -P ci get terraform.cloudsmith.io
+        # Select a Workspace and profile explicitly (no env vars needed)
+        $ cloudsmith credential-helper terraform -w acme -P ci get terraform.cloudsmith.io
 
     \b
     Environment variables:
         CLOUDSMITH_API_KEY: API key for authentication (optional)
-        CLOUDSMITH_ORG:     Organisation slug (required to scope the token)
+        CLOUDSMITH_WORKSPACE: Workspace slug (required to scope the token)
         CLOUDSMITH_REPO:    Repository slug the registry serves (required)
         CLOUDSMITH_PROFILE: Configuration profile to load (optional)
     """