add --request-api-key flag and deprecation notices for --force and --token command

Author: BartoszBlizniak

CHANGELOG.md

@@ -10,6 +10,13 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 ### Added
 
 - Added `CLOUDSMITH_NO_KEYRING` environment variable to disable keyring usage globally. Set `CLOUDSMITH_NO_KEYRING=1` to skip system keyring operations.
+- Added `--request-api-key` flag to `cloudsmith auth` command for fully automated, non-interactive API token retrieval. Auto-creates a token if none exists, or auto-rotates (with warning) if one already exists. Compatible with `--save-config` and `CLOUDSMITH_NO_KEYRING`.
+
+### Deprecation Notices
+
+- The `--token` flag on `cloudsmith auth` will be deprecated. Use `--request-api-key` instead.
+- The `--force` flag on `cloudsmith auth` will be deprecated. Use `--request-api-key` instead (force behavior is implied).
+- The `--json` flag on `cloudsmith auth` will be deprecated. Use `--output-format json` instead.
 
 ## [1.12.1] - 2026-02-03
 

cloudsmith_cli/cli/commands/auth.py

@@ -9,14 +9,16 @@
 from ..saml import create_configured_session, get_idp_url
 from ..webserver import AuthenticationWebRequestHandler, AuthenticationWebServer
 from .main import main
-from .tokens import create
+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, json=False):
+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
@@ -25,12 +27,12 @@ def _perform_saml_authentication(opts, owner, enable_token_creation=False, json=
 
     click.echo(
         f"Opening your organization's SAML IDP URL in your browser: {click.style(idp_url, bold=True)}",
-        err=json,
+        err=use_stderr,
     )
-    click.echo(err=json)
+    click.echo(err=use_stderr)
     webbrowser.open(idp_url)
 
-    click.echo("Starting webserver to begin authentication ... ", err=json)
+    click.echo("Starting webserver to begin authentication ... ", err=use_stderr)
 
     auth_server = AuthenticationWebServer(
         (AUTH_SERVER_HOST, AUTH_SERVER_PORT),
@@ -60,14 +62,14 @@ def _perform_saml_authentication(opts, owner, enable_token_creation=False, json=
     "--token",
     default=False,
     is_flag=True,
-    help="Retrieve a user API token after successful authentication.",
+    help="[DEPRECATED: Use --request-api-key] Retrieve a user API token after successful authentication.",
 )
 @click.option(
     "-f",
     "--force",
     default=False,
     is_flag=True,
-    help="Force refresh of user API token without prompts.",
+    help="[DEPRECATED: Use --request-api-key] Force refresh of user API token without prompts.",
 )
 @click.option(
     "--save-config",
@@ -81,15 +83,47 @@ def _perform_saml_authentication(opts, owner, enable_token_creation=False, json=
     is_flag=True,
     help="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):
+def authenticate(
+    ctx, opts, owner, token, force, save_config, json, request_api_key_flag
+):
     """Authenticate to Cloudsmith using the org's SAML setup."""
-    json = json or utils.should_use_stderr(opts)
-    # If using json output, we redirect info messages to stderr
-    use_stderr = json
+    # 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(
@@ -106,11 +140,34 @@ def authenticate(ctx, opts, owner, token, force, save_config, json):
         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=token, json=json
+            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/tokens.py

@@ -31,6 +31,77 @@ def handle_duplicate_token_error(exc, ctx, opts, save_config, force, json):
     raise exc
 
 
+def request_api_key(ctx, opts, save_config=False):
+    """
+    Request an API key non-interactively.
+
+    This function creates a new token or rotates an existing one without any prompts.
+    Used by the --request-api-key flag in the auth command.
+
+    Returns the token object on success.
+    Raises ApiException on failure.
+    """
+    context_msg = "Failed to retrieve API token!"
+
+    try:
+        # Don't use handle_api_exceptions here so we can catch and handle
+        # the "already has token" error ourselves
+        with utils.maybe_spinner(opts):
+            new_token = api.create_user_token_saml()
+
+        if save_config:
+            create, has_errors = create_config_files(
+                ctx, opts, api_key=new_token.key, force=True
+            )
+            new_config_messaging(has_errors, opts, create, api_key=new_token.key)
+
+        return new_token
+
+    except exceptions.ApiException as exc:
+        if exc.status == 401:
+            # Unauthorized - re-raise with handler
+            with handle_api_exceptions(ctx, opts=opts, context_msg=context_msg):
+                raise
+
+        if (
+            exc.status == 400
+            and exc.detail
+            and "User has already created an API key" in exc.detail
+        ):
+            # Token exists - rotate it automatically
+            click.echo(
+                "Warning: Rotating existing API token. Your old key will be invalidated.",
+                err=True,
+            )
+
+            # List tokens and select the first one
+            with handle_api_exceptions(ctx, opts=opts, context_msg=context_msg):
+                with utils.maybe_spinner(opts):
+                    api_tokens = api.list_user_tokens()
+
+            if not api_tokens:
+                raise click.ClickException("No existing tokens found to rotate.")
+
+            token_slug = api_tokens[0].slug_perm
+
+            # Refresh the token
+            with handle_api_exceptions(ctx, opts=opts, context_msg=context_msg):
+                with utils.maybe_spinner(opts):
+                    new_token = api.refresh_user_token(token_slug)
+
+            if save_config:
+                create, has_errors = create_config_files(
+                    ctx, opts, api_key=new_token.key, force=True
+                )
+                new_config_messaging(has_errors, opts, create, api_key=new_token.key)
+
+            return new_token
+
+        # Other errors - use the handler
+        with handle_api_exceptions(ctx, opts=opts, context_msg=context_msg):
+            raise
+
+
 @main.group(cls=command.AliasGroup, name="tokens")
 @decorators.common_cli_config_options
 @decorators.common_cli_output_options