cloudinary-cli 1.12.0__tar.gz → 1.14.0__tar.gz

{cloudinary_cli-1.12.0/cloudinary_cli.egg-info → cloudinary_cli-1.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: cloudinary-cli
-Version: 1.12.0
+Version: 1.14.0
 Summary: A command line interface for Cloudinary with full API support
 Home-page: https://github.com/cloudinary/cloudinary-cli
 Author: Cloudinary, Brian Luk
@@ -57,7 +57,7 @@ _**Note:** you can copy and paste your account environment variable from the Acc
     api_secret:     ***************<LAST_4_DIGITS>
     private_cdn:    <True|False>
     ```
-    
+
     If you get an error message when running `cld config`, you may need to add your Python installation to your $PATH. To do so, you can run `PATH="$PATH:/Library/Python/Versions/3.8/bin"` in your terminal, and add `export PATH="$PATH:/Library/Python/Versions/3.8/bin"` to your `/.bash_profile` or `~/.zshrc`.
 
 ## Quickstart
@@ -77,11 +77,38 @@ cld admin          # Lists Admin API methods.
 cld uploader       # Lists Upload API methods.
 ```
 
+## Docker Usage
+
+The Cloudinary CLI is also available as a Docker image, perfect for containerized environments, CI/CD pipelines, or when you prefer not to install Python locally.
+
+### Quick Docker Examples
+
+```sh
+# Check configuration
+docker run --rm -e CLOUDINARY_URL cloudinary/cli config
+
+# Upload files from your local machine
+docker run --rm -e CLOUDINARY_URL \
+  -v /path/to/your/images:/app/images \
+  cloudinary/cli uploader upload /app/images/sample.jpg
+
+# Search for assets
+docker run --rm -e CLOUDINARY_URL \
+  cloudinary/cli search "resource_type:image" --max_results 5
+
+# Interactive mode for multiple commands
+docker run --rm -it -e CLOUDINARY_URL --entrypoint /bin/bash cloudinary/cli
+```
+
+**Docker Image**: `cloudinary/cli` • **Base**: Debian 12 • **Size**: ~175MB • **Multi-arch**: amd64, arm64
+
+For comprehensive Docker usage, examples, and troubleshooting, see [DOCKER.md](DOCKER.md).
+
 ## Upload API
 
 Enables you to run any methods that can be called through the upload API.
 
-You can find documentation for each of the Upload API methods at [https://cloudinary.com/documentation/image_upload_api_reference](https://cloudinary.com/documentation/image_upload_api_reference). 
+You can find documentation for each of the Upload API methods at [https://cloudinary.com/documentation/image_upload_api_reference](https://cloudinary.com/documentation/image_upload_api_reference).
 
 The basic syntax using the Upload API is as follows:
 
@@ -152,7 +179,7 @@ cld [cli options] url [command options] public_id [transformation]
 
 For details, see the [Cloudinary CLI documentation](https://cloudinary.com/documentation/cloudinary_cli#url).
 
-Example: generate a URL that displays the image in your media library that has the public ID of 'sample', with a width of 500 pixels and transformed using the cartoonify effect, then open this URL in a browser. 
+Example: generate a URL that displays the image in your media library that has the public ID of 'sample', with a width of 500 pixels and transformed using the cartoonify effect, then open this URL in a browser.
 
 ```
 cld url -rt image -t upload -o sample w_500,e_cartoonify
@@ -187,9 +214,9 @@ Uploads a folder of assets, maintaining the folder structure.
 cld [cli options] upload_dir [command options] [local_folder]
 ```
 
-For details, see the [Cloudinary CLI documentation](https://cloudinary.com/documentation/cloudinary_cli#upload_dir).  
+For details, see the [Cloudinary CLI documentation](https://cloudinary.com/documentation/cloudinary_cli#upload_dir).
 
-Example: upload the local folder, my_images, and all its contents and sub-folders to your Cloudinary folder my_images_on_cloudinary.  
+Example: upload the local folder, my_images, and all its contents and sub-folders to your Cloudinary folder my_images_on_cloudinary.
 
 ```
 cld upload_dir -f my_images_on_cloudinary my_images
@@ -227,7 +254,7 @@ A configuration is a reference to a specified Cloudinary account or cloud name v
 
 The `config` command displays the current configuration and lets you manage additional configurations.
 
-You can specify the environment variable of additional Cloudinary accounts either explicitly (`-c` option) or as a saved configuration (`-C` option).  
+You can specify the environment variable of additional Cloudinary accounts either explicitly (`-c` option) or as a saved configuration (`-C` option).
 
 For example, using the `-c` option:
 

{cloudinary_cli-1.12.0 → cloudinary_cli-1.14.0}/README.md

@@ -32,7 +32,7 @@ _**Note:** you can copy and paste your account environment variable from the Acc
     api_secret:     ***************<LAST_4_DIGITS>
     private_cdn:    <True|False>
     ```
-    
+
     If you get an error message when running `cld config`, you may need to add your Python installation to your $PATH. To do so, you can run `PATH="$PATH:/Library/Python/Versions/3.8/bin"` in your terminal, and add `export PATH="$PATH:/Library/Python/Versions/3.8/bin"` to your `/.bash_profile` or `~/.zshrc`.
 
 ## Quickstart
@@ -52,11 +52,38 @@ cld admin          # Lists Admin API methods.
 cld uploader       # Lists Upload API methods.
 ```
 
+## Docker Usage
+
+The Cloudinary CLI is also available as a Docker image, perfect for containerized environments, CI/CD pipelines, or when you prefer not to install Python locally.
+
+### Quick Docker Examples
+
+```sh
+# Check configuration
+docker run --rm -e CLOUDINARY_URL cloudinary/cli config
+
+# Upload files from your local machine
+docker run --rm -e CLOUDINARY_URL \
+  -v /path/to/your/images:/app/images \
+  cloudinary/cli uploader upload /app/images/sample.jpg
+
+# Search for assets
+docker run --rm -e CLOUDINARY_URL \
+  cloudinary/cli search "resource_type:image" --max_results 5
+
+# Interactive mode for multiple commands
+docker run --rm -it -e CLOUDINARY_URL --entrypoint /bin/bash cloudinary/cli
+```
+
+**Docker Image**: `cloudinary/cli` • **Base**: Debian 12 • **Size**: ~175MB • **Multi-arch**: amd64, arm64
+
+For comprehensive Docker usage, examples, and troubleshooting, see [DOCKER.md](DOCKER.md).
+
 ## Upload API
 
 Enables you to run any methods that can be called through the upload API.
 
-You can find documentation for each of the Upload API methods at [https://cloudinary.com/documentation/image_upload_api_reference](https://cloudinary.com/documentation/image_upload_api_reference). 
+You can find documentation for each of the Upload API methods at [https://cloudinary.com/documentation/image_upload_api_reference](https://cloudinary.com/documentation/image_upload_api_reference).
 
 The basic syntax using the Upload API is as follows:
 
@@ -127,7 +154,7 @@ cld [cli options] url [command options] public_id [transformation]
 
 For details, see the [Cloudinary CLI documentation](https://cloudinary.com/documentation/cloudinary_cli#url).
 
-Example: generate a URL that displays the image in your media library that has the public ID of 'sample', with a width of 500 pixels and transformed using the cartoonify effect, then open this URL in a browser. 
+Example: generate a URL that displays the image in your media library that has the public ID of 'sample', with a width of 500 pixels and transformed using the cartoonify effect, then open this URL in a browser.
 
 ```
 cld url -rt image -t upload -o sample w_500,e_cartoonify
@@ -162,9 +189,9 @@ Uploads a folder of assets, maintaining the folder structure.
 cld [cli options] upload_dir [command options] [local_folder]
 ```
 
-For details, see the [Cloudinary CLI documentation](https://cloudinary.com/documentation/cloudinary_cli#upload_dir).  
+For details, see the [Cloudinary CLI documentation](https://cloudinary.com/documentation/cloudinary_cli#upload_dir).
 
-Example: upload the local folder, my_images, and all its contents and sub-folders to your Cloudinary folder my_images_on_cloudinary.  
+Example: upload the local folder, my_images, and all its contents and sub-folders to your Cloudinary folder my_images_on_cloudinary.
 
 ```
 cld upload_dir -f my_images_on_cloudinary my_images
@@ -202,7 +229,7 @@ A configuration is a reference to a specified Cloudinary account or cloud name v
 
 The `config` command displays the current configuration and lets you manage additional configurations.
 
-You can specify the environment variable of additional Cloudinary accounts either explicitly (`-c` option) or as a saved configuration (`-C` option).  
+You can specify the environment variable of additional Cloudinary accounts either explicitly (`-c` option) or as a saved configuration (`-C` option).
 
 For example, using the `-c` option:
 

{cloudinary_cli-1.12.0 → cloudinary_cli-1.14.0}/cloudinary_cli/cli_group.py

@@ -14,7 +14,7 @@ from cloudinary_cli.version import __version__ as cli_version
 CONTEXT_SETTINGS = dict(max_content_width=shutil.get_terminal_size()[0], terminal_width=shutil.get_terminal_size()[0])
 
 
-@click.group(context_settings=CONTEXT_SETTINGS)
+@click.group(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"
@@ -24,10 +24,11 @@ CONTEXT_SETTINGS = dict(max_content_width=shutil.get_terminal_size()[0], termina
               help="""Tell the CLI which account to run the command on by specifying an account environment variable."""
               )
 @click.option("-C", "--config_saved",
-              help="""Tell the CLI which account to run the command on by specifying a saved configuration - see 
+              help="""Tell the CLI which account to run the command on by specifying a saved configuration - see
               `config` command.""")
 @click_log.simple_verbosity_option(logger)
-def cli(config, config_saved):
+@click.pass_context
+def cli(ctx, config, config_saved):
     if config:
         refresh_cloudinary_config(config)
     elif config_saved:
@@ -40,4 +41,9 @@ def cli(config, config_saved):
     if not is_valid_cloudinary_config():
         logger.warning("No Cloudinary configuration found.")
 
+    # If no subcommand was invoked, show help and exit with code 0
+    if ctx.invoked_subcommand is None:
+        click.echo(ctx.get_help())
+        ctx.exit(0)
+
     return True

{cloudinary_cli-1.12.0 → cloudinary_cli-1.14.0}/cloudinary_cli/core/__init__.py

@@ -8,7 +8,7 @@ from cloudinary_cli.core.provisioning import provisioning
 from cloudinary_cli.core.utils import url, utils
 from cloudinary_cli.core.overrides import resolve_command
 
-setattr(click.MultiCommand, "resolve_command", resolve_command)
+setattr(click.Group, "resolve_command", resolve_command)
 
 commands = [
     config,

{cloudinary_cli-1.12.0 → cloudinary_cli-1.14.0}/cloudinary_cli/core/overrides.py

@@ -1,14 +1,19 @@
-from click.parser import split_opt
 from click.utils import make_str
 from cloudinary import api, uploader
 from cloudinary.uploader import upload as original_upload
 from cloudinary.utils import cloudinary_url as original_cloudinary_url
+from cloudinary_cli.utils.utils import split_opt
 
 
 # overrides click.MultiCommand.resolve_command
 def resolve_command(self, ctx, args):
     # Patch the `resolve_command` function to enable simple commands (eg. cld resource)
     # Only core commands from API and modules are registered (eg. cld admin)
+
+    # Handle empty args (when CLI is invoked with no arguments)
+    if not args:
+        return None, None, []
+
     cmd_name = make_str(args[0])
     original_cmd_name = cmd_name
 

{cloudinary_cli-1.12.0 → cloudinary_cli-1.14.0}/cloudinary_cli/core/search.py

@@ -6,6 +6,7 @@ from cloudinary_cli.defaults import logger
 from cloudinary_cli.utils.json_utils import write_json_to_file, print_json
 from cloudinary_cli.utils.utils import write_json_list_to_csv, confirm_action, whitelist_keys, \
     normalize_list_params
+from cloudinary_cli.utils.search_utils import parse_aggregate
 
 DEFAULT_MAX_RESULTS = 500
 
@@ -100,7 +101,7 @@ def _perform_search(query, with_field, fields, sort_by, aggregate, max_results,
     if sort_by:
         search.sort_by(*sort_by)
     if aggregate:
-        search.aggregate(aggregate)
+        search.aggregate(parse_aggregate(aggregate))
     if next_cursor:
         search.next_cursor(next_cursor)
     if ttl:

cloudinary_cli-1.14.0/cloudinary_cli/modules/clone.py

@@ -0,0 +1,245 @@
+from click import command, option, style, argument
+from cloudinary_cli.utils.utils import normalize_list_params, print_help_and_exit
+import cloudinary
+from cloudinary.auth_token import _digest
+from cloudinary_cli.utils.utils import run_tasks_concurrently
+from cloudinary_cli.utils.api_utils import upload_file
+from cloudinary_cli.utils.config_utils import get_cloudinary_config, config_to_dict
+from cloudinary_cli.defaults import logger
+from cloudinary_cli.core.search import execute_single_request, handle_auto_pagination
+import time
+import re
+
+DEFAULT_MAX_RESULTS = 500
+ALLOWED_TYPE_VALUES = ("upload", "private", "authenticated")
+
+
+@command("clone",
+         short_help="""Clone assets from one product environment to another.""",
+         help="""
+\b
+Clone assets from one product environment to another with/without tags and/or context (structured metadata is not currently supported).
+Source will be your `CLOUDINARY_URL` environment variable but you also can specify a different source using the `-c/-C` option.
+Format: cld clone <target_environment> <command options>
+`<target_environment>` can be a CLOUDINARY_URL or a saved config (see `config` command)
+Example 1 (Copy all assets including tags and context using CLOUDINARY URL):
+    cld clone cloudinary://<api_key>:<api_secret>@<cloudname> -fi tags,context
+Example 2 (Copy all assets with a specific tag via a search expression using a saved config):
+    cld clone <config_name> -se "tags:<tag_name>"
+""")
+@argument("target")
+@option("-F", "--force", is_flag=True,
+        help="Skip confirmation.")
+@option("-ow", "--overwrite", is_flag=True, default=False,
+        help="Specify whether to overwrite existing assets.")
+@option("-w", "--concurrent_workers", type=int, default=30,
+        help="Specify the number of concurrent network threads.")
+@option("-fi", "--fields", multiple=True,
+        help=("Specify whether to copy tags and/or context. "
+              "Valid options: `tags,context`."))
+@option("-se", "--search_exp", default="",
+        help="Define a search expression to filter the assets to clone.")
+@option("--async", "async_", is_flag=True, default=False,
+        help="Clone the assets asynchronously.")
+@option("-nu", "--notification_url",
+        help="Webhook notification URL.")
+@option("-ue", "--url_expiry", type=int, default=3600,
+        help=("URL expiration duration in seconds. Only relevant if cloning "
+              "restricted assets with an auth_key configured. "
+              "If you do not provide an auth_key, "
+              "a private download URL is generated which may incur additional "
+              "bandwidth costs."))
+def clone(target, force, overwrite, concurrent_workers, fields,
+          search_exp, async_, notification_url, url_expiry):
+    target_config, auth_token = _validate_clone_inputs(target)
+    if not target_config:
+        return False
+
+    source_assets = search_assets(search_exp, force)
+    if not source_assets:
+        return False
+    if not isinstance(source_assets, dict) or not source_assets.get('resources'):
+        logger.error(style(f"No asset(s) found in {cloudinary.config().cloud_name}", fg="red"))
+        return False
+
+    upload_list = _prepare_upload_list(
+        source_assets, target_config, overwrite, async_,
+        notification_url, auth_token, url_expiry, fields
+    )
+
+    logger.info(style(f"Copying {len(upload_list)} asset(s) from "
+                      f"{cloudinary.config().cloud_name} to "
+                      f"{target_config.cloud_name}", fg="blue"))
+
+    run_tasks_concurrently(upload_file, upload_list, concurrent_workers)
+
+    return True
+
+
+def _validate_clone_inputs(target):
+    if not target:
+        print_help_and_exit()
+
+    target_config = get_cloudinary_config(target)
+    if not target_config:
+        logger.error("The specified config does not exist or the "
+                     "CLOUDINARY_URL scheme provided is invalid "
+                     "(expecting to start with 'cloudinary://').")
+        return None, None
+
+    if cloudinary.config().cloud_name == target_config.cloud_name:
+        logger.error("Target environment cannot be the same "
+                     "as source environment.")
+        return None, None
+
+    auth_token = cloudinary.config().auth_token
+    if auth_token:
+        # It is important to validate auth_token if provided as this prevents
+        # customer from having to re-run the command as well as
+        # saving Admin API calls and time.
+        try:
+            cloudinary.utils.generate_auth_token(acl="/image/*")
+        except Exception as e:
+            logger.error(f"{e} - auth_token validation failed. "
+                         "Please double-check your auth_token parameters.")
+            return None, None
+
+    return target_config, auth_token
+
+
+def _prepare_upload_list(source_assets, target_config, overwrite, async_,
+                         notification_url, auth_token, url_expiry, fields):
+    upload_list = []
+    for r in source_assets.get('resources'):
+        updated_options, asset_url = process_metadata(r, overwrite, async_,
+                                                      notification_url,
+                                                      auth_token, url_expiry,
+                                                      normalize_list_params(fields))
+        updated_options.update(config_to_dict(target_config))
+        upload_list.append((asset_url, {**updated_options}))
+    return upload_list
+
+
+def search_assets(search_exp, force):
+    search_exp = _normalize_search_expression(search_exp)
+    if not search_exp:
+        return False
+
+    search = cloudinary.search.Search().expression(search_exp)
+    search.fields(['tags', 'context', 'access_control',
+                   'secure_url', 'display_name', 'format'])
+    search.max_results(DEFAULT_MAX_RESULTS)
+
+    res = execute_single_request(search, fields_to_keep="")
+    res = handle_auto_pagination(res, search, force, fields_to_keep="")
+
+    return res
+
+
+def _normalize_search_expression(search_exp):
+    """
+    Ensures the search expression has a valid 'type' filter.
+
+    - If no expression is given, a default is created.
+    - If 'type' filters exist, they are validated.
+    - If no 'type' filters exist, the default is appended.
+    """
+    default_types_str = " OR ".join(f"type:{t}" for t in ALLOWED_TYPE_VALUES)
+
+    if not search_exp:
+        return default_types_str
+
+    # Use a simple regex to find all 'type' filters
+    found_types = re.findall(r"\btype\s*[:=]\s*(\w+)", search_exp)
+
+    if not found_types:
+        # No 'type' filter found, so append the default
+        return f"{search_exp} AND ({default_types_str})"
+
+    # A 'type' filter was found, so validate it
+    invalid_types = {t for t in found_types if t not in ALLOWED_TYPE_VALUES}
+
+    if invalid_types:
+        error_msg = ", ".join(f"type:{t}" for t in invalid_types)
+        logger.error(
+            f"Unsupported type(s) in search expression: {error_msg}. "
+            f"Only {', '.join(ALLOWED_TYPE_VALUES)} types allowed."
+        )
+        return None
+
+    # All found types are valid, so return the original expression
+    return search_exp
+
+
+def process_metadata(res, overwrite, async_, notification_url, auth_token, url_expiry, copy_fields=None):
+    if copy_fields is None:
+        copy_fields = []
+    asset_url = _get_asset_url(res, auth_token, url_expiry)
+    cloned_options = _build_cloned_options(res, overwrite, async_, notification_url, copy_fields)
+
+    return cloned_options, asset_url
+
+
+def _get_asset_url(res, auth_token, url_expiry):
+    if not (isinstance(res.get('access_control'), list) and
+            len(res.get('access_control')) > 0 and
+            isinstance(res['access_control'][0], dict) and
+            res['access_control'][0].get("access_type") == "token"):
+        return res.get('secure_url')
+
+    reso_type = res.get('resource_type')
+    del_type = res.get('type')
+    pub_id = res.get('public_id')
+    file_format = res.get('format')
+
+    if auth_token:
+        # Raw assets already have the format in the public_id
+        pub_id_format = pub_id if reso_type == "raw" else f"{pub_id}.{file_format}"
+        return cloudinary.utils.cloudinary_url(
+            pub_id_format,
+            type=del_type,
+            resource_type=reso_type,
+            auth_token={"duration": url_expiry},
+            secure=True,
+            sign_url=True
+        )
+
+    # Use private url if no auth_token provided
+    return cloudinary.utils.private_download_url(
+        pub_id,
+        file_format,
+        resource_type=reso_type,
+        type=del_type,
+        expires_at=int(time.time()) + url_expiry
+    )
+
+
+def _build_cloned_options(res, overwrite, async_, notification_url, copy_fields):
+    # 1. Start with mandatory options
+    cloned_options = {
+        'overwrite': overwrite,
+        'async': async_,
+    }
+
+    # 2. Copy fields from source asset. Some are standard, others are from user input.
+    fields_to_copy = {'public_id', 'type', 'resource_type', 'access_control'}.union(copy_fields)
+    cloned_options.update({field: res.get(field) for field in fields_to_copy})
+
+    # 3. Handle fields that are added only if they have a truthy value
+    if res.get('display_name'):
+        cloned_options['display_name'] = res['display_name']
+
+    # This is required to put the asset in the correct asset_folder
+    # when copying from a fixed to DF (dynamic folder) cloud as if
+    # you just pass a `folder` param to a DF cloud, it will append
+    # this to the `public_id` and we don't want this.
+    if res.get('folder'):
+        cloned_options['asset_folder'] = res['folder']
+    elif res.get('asset_folder'):
+        cloned_options['asset_folder'] = res['asset_folder']
+
+    if notification_url:
+        cloned_options['notification_url'] = notification_url
+
+    # 4. Clean up any None values before returning
+    return {k: v for k, v in cloned_options.items() if v is not None}

{cloudinary_cli-1.12.0 → cloudinary_cli-1.14.0}/cloudinary_cli/modules/sync.py

@@ -300,7 +300,7 @@ class SyncDir:
 
     def _local_candidates(self, candidate_path):
         filename, extension = path.splitext(candidate_path)
-        r = re.compile(f"({candidate_path}|{filename} \(\d+\){extension})")
+        r = re.compile(f"({candidate_path}|{filename} \\(\\d+\\){extension})")
         # sort local files by base name (without ext) for accurate results.
         return dict(sorted({f: self.local_files[f]["etag"] for f in filter(r.match, self.local_files.keys())}.items(),
                            key=lambda f: path.splitext(f[0])[0]))

{cloudinary_cli-1.12.0 → cloudinary_cli-1.14.0}/cloudinary_cli/templates/html/video_player

@@ -1,15 +1,14 @@
 <!DOCTYPE html>
 
 <head>
-    <link href="https://unpkg.com/cloudinary-video-player/dist/cld-video-player.min.css" rel="stylesheet">
+    <link rel="stylesheet"
+        href="https://cdn.jsdelivr.net/npm/cloudinary-video-player@latest/dist/cld-video-player.min.css">
 </head>
 
 <body>
-    <link href="https://unpkg.com/cloudinary-video-player/dist/cld-video-player.min.css" rel="stylesheet">
-    <script src="https://unpkg.com/cloudinary-core/cloudinary-core-shrinkwrap.min.js" type="text/javascript"></script>
-    <script src="https://unpkg.com/cloudinary-video-player/dist/cld-video-player.min.js" type="text/javascript"></script>
-    <script src="https://cdnjs.cloudflare.com/ajax/libs/dashjs/2.6.3/dash.all.min.js" type="text/javascript"></script>
-    <script src="https://cdnjs.cloudflare.com/ajax/libs/videojs-contrib-dash/2.9.2/videojs-dash.min.js" type="text/javascript"></script>
+
+    <script
+        src="https://cdn.jsdelivr.net/npm/cloudinary-video-player@latest/dist/cld-video-player.light.min.js"></script>
     
     <video
         style="min-width:100vw;min-height:100vh;max-width:100vw;max-height:100vh"