Merge branch 'master' into fix/sync-duplicate-name-match

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

Author: const-cloudinary

cloudinary_cli/__init__.py

@@ -1,4 +1,8 @@
 from cloudinary_cli.version import __version__
+from cloudinary_cli.utils.env_config import import_sdk
+
+# Must run before any other `import cloudinary`, so that an invalid CLOUDINARY_URL does not stop the CLI.
+import_sdk()
 
 import cloudinary
 

cloudinary_cli/cli_group.py

@@ -1,4 +1,5 @@
 #!/usr/bin/env python3
+import difflib
 import platform
 import shutil
 
@@ -13,7 +14,21 @@
 CONTEXT_SETTINGS = dict(max_content_width=shutil.get_terminal_size()[0], terminal_width=shutil.get_terminal_size()[0])
 
 
-@click.group(context_settings=CONTEXT_SETTINGS, invoke_without_command=True)
+class SuggestingGroup(click.Group):
+    """Suggests similar command names when the command name is not known."""
+
+    def resolve_command(self, ctx, args):
+        try:
+            return super().resolve_command(ctx, args)
+        except click.UsageError as e:
+            names = [name for name in self.list_commands(ctx) if not self.get_command(ctx, name).hidden]
+            matches = difflib.get_close_matches(args[0], names) if args else []
+            if matches:
+                e.message += f"\nDid you mean: {', '.join(matches)}?"
+            raise
+
+
+@click.group(cls=SuggestingGroup, context_settings=CONTEXT_SETTINGS, invoke_without_command=True)
 @click.help_option()
 @click.version_option(cli_version, prog_name="Cloudinary CLI",
                       message=f"%(prog)s, version %(version)s\n"

cloudinary_cli/core/admin.py

@@ -16,11 +16,12 @@
 \t    cld admin resources max_results=10 -o tags sample
 """)
 @argument("params", nargs=-1)
-@option("-o", "--optional_parameter", multiple=True, nargs=2, help="Pass optional parameters as raw strings.")
+@option("-o", "--optional_parameter", multiple=True, nargs=2,
+        help="Pass an optional parameter as a string, with no parsing. e.g. -o tags a,b")
 @option("-O", "--optional_parameter_parsed", multiple=True, nargs=2,
-        help="Pass optional parameters as interpreted strings.")
+        help="Pass an optional parameter and parse its value as JSON or a boolean. e.g. -O context '{\"alt\": \"cat\"}'")
 @option("-A", "--auto_paginate", is_flag=True, help="Will auto paginate Admin API calls.", default=False)
-@option("-ff", "--filter_fields", multiple=True, help="Filter fields to return when using auto pagination.")
+@option("-ff", "--filter_fields", multiple=True, help="Filter fields to return. Requires -A/--auto_paginate.")
 @option("-F", "--force", is_flag=True,
         help="Skip confirmations for auto pagination and destructive bulk API methods.")
 @option("-ls", "--ls", is_flag=True, help="List all available methods in the Admin API.")

cloudinary_cli/core/provisioning.py

@@ -1,7 +1,10 @@
+import sys
+
 from click import command, argument, option
 import cloudinary.provisioning
 
 from cloudinary_cli.utils.api_utils import handle_api_command
+from cloudinary_cli.utils.env_config import env_config_error
 
 
 @command("provisioning",
@@ -12,13 +15,19 @@
 \te.g. cld provisioning sub_accounts
 """)
 @argument("params", nargs=-1)
-@option("-o", "--optional_parameter", multiple=True, nargs=2, help="Pass optional parameters as raw strings.")
+@option("-o", "--optional_parameter", multiple=True, nargs=2,
+        help="Pass an optional parameter as a string, with no parsing. e.g. -o prefix demo")
 @option("-O", "--optional_parameter_parsed", multiple=True, nargs=2,
-        help="Pass optional parameters as interpreted strings.")
+        help="Pass an optional parameter and parse its value as JSON or a boolean. e.g. -O enabled true")
 @option("-ls", "--ls", is_flag=True, help="List all available methods in the Provisioning API.")
 @option("--save", nargs=1, help="Save output to a file.")
 @option("-d", "--doc", is_flag=True, help="Open the Provisioning API reference in a browser.")
 def provisioning(params, optional_parameter, optional_parameter_parsed, ls, save, doc):
+    # -c, -C and the saved default do not replace CLOUDINARY_ACCOUNT_URL, so an invalid one is always an error here.
+    account_url_error = env_config_error("CLOUDINARY_ACCOUNT_URL")
+    if account_url_error:
+        sys.exit(account_url_error)
+
     return handle_api_command(params, optional_parameter, optional_parameter_parsed, ls, save, doc,
                               doc_url="https://cloudinary.com/documentation/provisioning_api",
                               api_instance=cloudinary.provisioning,

cloudinary_cli/core/search.py

@@ -130,8 +130,8 @@ def _perform_search(query, with_field, fields, sort_by, aggregate, max_results,
         logger.info(f"Saved search JSON to '{json}' file")
 
     if csv:
-        write_json_list_to_csv(res[result_field], csv, fields_to_keep)
-        logger.info(f"Saved search to '{csv}.csv' file")
+        csv = write_json_list_to_csv(res[result_field], csv, fields_to_keep)
+        logger.info(f"Saved search to '{csv}' file")
 
 
 def execute_single_request(expression, fields_to_keep, result_field='resources'):

cloudinary_cli/core/uploader.py

@@ -20,9 +20,10 @@
 \t    cld uploader rename flowers secret_flowers -o to_type private
 """)
 @argument("params", nargs=-1)
-@option("-o", "--optional_parameter", multiple=True, nargs=2, help="Pass optional parameters as raw strings.")
+@option("-o", "--optional_parameter", multiple=True, nargs=2,
+        help="Pass an optional parameter as a string, with no parsing. e.g. -o tags a,b")
 @option("-O", "--optional_parameter_parsed", multiple=True, nargs=2,
-        help="Pass optional parameters as interpreted strings.")
+        help="Pass an optional parameter and parse its value as JSON or a boolean. e.g. -O context '{\"alt\": \"cat\"}'")
 @option("-ls", "--ls", is_flag=True, help="List all available methods in the Upload API.")
 @option("--save", nargs=1, help="Save output to a file.")
 @option("-d", "--doc", is_flag=True, help="Open the Upload API reference in a browser.")

cloudinary_cli/core/utils.py

@@ -1,4 +1,5 @@
 from click import command, argument, option, Choice, echo, launch
+import cloudinary
 from cloudinary import utils as cld_utils
 
 from cloudinary_cli.core.overrides import cloudinary_url
@@ -14,9 +15,10 @@
 
 @command("utils", help="Call Cloudinary utility methods.")
 @argument("params", nargs=-1)
-@option("-o", "--optional_parameter", multiple=True, nargs=2, help="Pass optional parameters as raw strings.")
+@option("-o", "--optional_parameter", multiple=True, nargs=2,
+        help="Pass an optional parameter as a string, with no parsing. e.g. -o tags a,b")
 @option("-O", "--optional_parameter_parsed", multiple=True, nargs=2,
-        help="Pass optional parameters as interpreted strings.")
+        help="Pass an optional parameter and parse its value as JSON or a boolean. e.g. -O sign_url true")
 @option("-ls", "--ls", is_flag=True, help="List all available utility methods.")
 def utils(params, optional_parameter, optional_parameter_parsed, ls):
     if ls or len(params) < 1:
@@ -50,8 +52,13 @@ def url(public_id, transformation, resource_type, delivery_type, open_in_browser
     elif delivery_type == "list":
         public_id += ".json"
 
+    # Use HTTPS unless the configuration sets `secure` explicitly.
+    secure = cloudinary.config().secure
+    if secure is None:
+        secure = True
+
     res = cloudinary_url(public_id, resource_type=resource_type,
-                         raw_transformation=transformation, type=delivery_type, sign_url=sign)
+                         raw_transformation=transformation, type=delivery_type, sign_url=sign, secure=secure)
     echo(res)
 
     if open_in_browser:

cloudinary_cli/modules/migrate.py

@@ -17,7 +17,7 @@
 @argument("upload_mapping")
 @argument("file")
 @option("-d", "--delimiter", default="\n", help="The separator used between the URLs. Default: New line")
-@option("-v", "--verbose", is_flag=True)
+@option("-v", "--verbose", is_flag=True, help="Log each migrated URL.")
 def migrate(upload_mapping, file, delimiter, verbose):
     if not os.path.exists(file):
         logger.error(f"Migration file: '{file}' does not exist")

cloudinary_cli/modules/regen_derived.py

@@ -70,6 +70,10 @@ def regen_derived(trans_str, eager_notification_url,
         logger.info("No derived assets are using this transformation.")
         exit()
 
+    if trans_details.get('next_cursor'):
+        logger.warning(f"Only the first {len(derived_resources)} derived assets will be regenerated. "
+                       f"Use -A to regenerate all of them.")
+
     is_named = trans_details.get('named')
     eager_trans = normalise_trans_name(trans_str) if is_named else trans_str
 

cloudinary_cli/modules/sync.py

@@ -41,9 +41,10 @@
         help="Specify folder mode explicitly. By default uses cloud mode configured in your cloud.", hidden=True)
 @option("-st", "--status", type=Choice(['all', 'active', 'pending'], case_sensitive=False),
         help="Specify asset status. Server default: active.", default=None)
-@option("-o", "--optional_parameter", multiple=True, nargs=2, help="Pass optional parameters as raw strings.")
+@option("-o", "--optional_parameter", multiple=True, nargs=2,
+        help="Pass an optional parameter as a string, with no parsing. e.g. -o tags a,b")
 @option("-O", "--optional_parameter_parsed", multiple=True, nargs=2,
-        help="Pass optional parameters as interpreted strings.")
+        help="Pass an optional parameter and parse its value as JSON or a boolean. e.g. -O context '{\"alt\": \"cat\"}'")
 @option("--dry-run", is_flag=True, help="Simulate the sync operation without making any changes.")
 def sync(local_folder, cloudinary_folder, push, pull, include_hidden, concurrent_workers, force, keep_unique,
          deletion_batch_size, folder_mode, status, optional_parameter, optional_parameter_parsed, dry_run):
@@ -226,7 +227,8 @@ def pull(self):
         if not files_to_pull:
             return True
 
-        logger.info(f"Preparing to download {len(files_to_pull)} items from Cloudinary folder ")
+        logger.info(f"Preparing to download {len(files_to_pull)} items "
+                    f"from Cloudinary folder '{self.user_friendly_remote_dir}'")
 
         if self.dry_run:
             logger.info("Dry run mode enabled. The following files would be downloaded:")